Obsidian as a Second Brain for Application Repositories

Mon, 13 Apr 2026 00:00:00 +0000

Software projects do not fail because code is invisible. They fail because context is invisible.

A repo may contain source code, but the reasoning behind the code often lives in chats, notebooks, screenshots, or someone’s memory. When that happens, new developers need time to rediscover the project, and AI agents get weak or incomplete context. Obsidian can solve that problem by turning project knowledge into a second brain that is easy to search, link, and maintain.

The second-brain approach works well when you keep important project notes inside the repository and write them in a format that both humans and AI can read. This is especially useful when you want the repo to store not only source code, but also documentation, important decisions, ideas, and development knowledge.

In most projects, markdown is already used for setup guides, README files, or change history. But if all project knowledge lives in disconnected markdown files, the documentation can still become messy. Obsidian helps by turning those markdown notes into a connected system.

Why Obsidian Works Well

Obsidian is a system for creating linked documentation, which fits software development very well. It can also be extended into a knowledge management system or even a lightweight project management workspace through plugins such as Calendar and Timeline.

When you connect notes about architecture, product decisions, APIs, and bugs, you create a map of the project instead of a pile of isolated documents. A developer can open one note and jump to related decisions. An AI agent can do the same if the notes are stored in plain markdown inside the repo.

That turns the repository into an organized knowledge base, not just a place to store code.

Example Folder Structure

Here is a practical structure that works well:

docs/
 overview.md
 architecture.md
 decisions/
 2026-04-13-auth-flow.md
 2026-04-13-database-choice.md
 features/
 payments.md
 search.md
 meetings/
 2026-04-13-planning.md

Each note should answer one question well.

overview.md: what the system is and who it is for.
architecture.md: how the major parts fit together.
decisions/: why a choice was made, including tradeoffs.
features/: what each feature does and how it behaves.
meetings/: what was discussed and what changed.

This pattern becomes best practice when the notes stay close to real work.

Keep notes in markdown inside the repo or in a clearly structured docs folder.
Keep each note focused on one topic, one decision, or one feature when the content has enough detail.
If you update the source code, update the related note in the same pull request when possible.
Link related notes so Obsidian can build a graph of the project knowledge.

Notes should stay concise with a TL;DR mindset. Link only what matters. For example, if a decision affects authentication, link that decision from the architecture note and from the related feature note. That is what makes the vault useful.

How Notes Can Be Linked

This is where Obsidian becomes more powerful than a normal documents folder. Instead of storing notes as isolated files, you can connect them with wiki-style links.

For example:

# architecture

The application uses a token-based login flow described in [[2026-04-13-auth-flow]].

Search is implemented as a separate module. See [[search]] for feature behavior.

The current database decision is documented in [[2026-04-13-database-choice]].

And inside a feature note:

# search

Search supports product lookup, filtering, and ranking.

Related notes:
- [[architecture]]
- [[2026-04-13-database-choice]]
- [[2026-04-13-planning]]

With this approach, a human can jump from architecture to feature behavior to design decisions in seconds. An AI agent can also follow the same trail of linked markdown files and build a much better understanding of the repository.

How Software developer Benefit

For Software developer, the value is speed and clarity.

A new developer can open the repo and quickly understand the product, the architecture, and the important tradeoffs. A senior engineer can review a decision without asking three people for context. A product owner can read the same notes and see why a feature exists.

This reduces repeated explanations. It also reduces the risk of changing something important just because the reason behind it was never written down.

The important habit is to contribute documentation regularly. Short, connected notes are much more useful than long documents that no one updates.

How AI Agents Benefit

Today, developers increasingly work with AI agents, and agents perform much better when the context is structured.

If the repository contains clear markdown notes, an agent can:

summarize the current architecture,
explain why a feature exists,
draft a new implementation plan,
suggest changes that match previous decisions,
and point out missing documentation.

That means the agent is not reading from source code alone. It is also reading the project’s memory, which can reduce wasted tokens and improve the quality of its output.

The Best Rule

Write notes the same way you write code: be specific, keep them small, and update them when reality changes.

If a note is too long, split it. If a decision is obsolete, mark it clearly. If a feature changes, update the related note in the same pull request. That keeps the knowledge base trustworthy.

Obsidian becomes powerful when it is not treated as a personal diary, but as shared project memory.

Conclusion

If your application repository is the body of the project, then Obsidian can be its memory.

That memory helps Software developer move faster, helps AI agents understand the codebase better, and helps the team keep a clear record of how decisions were made. The result is less friction, better collaboration, and a repo that is easier to read long after the original context has faded.

For modern software teams, that is the real value of a second brain.

You can try Obsidian here: https://obsidian.md/help/install

You can get success if you avoid cheap dopamine

Sat, 06 Dec 2025 00:00:00 +0000

In a world overflowing with distractions, our brains are constantly bombarded with “cheap dopamine.” This is the instant gratification we get from endless scrolling on social media, binge-watching TV shows, or eating junk food. It feels good in the moment, but it costs us dearly in the long run. Research indicates that social media usage can activate the brain’s reward system in ways similar to substance addiction (Turel et al., 2014).

Success requires sustained effort, focus, and the ability to delay gratification. This is where “expensive dopamine” comes in. It’s the satisfaction you get after finishing a tough workout, completing a complex project, or learning a new skill. It’s harder to get, but it’s far more rewarding.

What is Cheap Dopamine?

Cheap dopamine is the reward your brain gets with little to no effort. It’s the “hit” you feel when you get a like on Instagram, check a notification, or eat a sugary snack.

The problem isn’t the dopamine itself; it’s the source and the ease. When your brain gets used to high levels of dopamine for no effort, it starts to crave it. Hard work, which releases dopamine more slowly and only after effort, becomes less appealing. This is why it’s so hard to focus on a book after spending an hour on TikTok.

The Cost of Instant Gratification

Reduced Focus: Your attention span shortens as you train your brain to seek constant novelty.
Lack of Motivation: Why work hard for a reward later when you can get a reward right now for free?
Anxiety and Restlessness: The constant need for stimulation makes silence and boredom unbearable.

Expensive Dopamine: The Path to Success

“Expensive dopamine” is the reward system of high achievers. It is earned through:

Deep Work: Spending hours solving a difficult problem.
Physical Exercise: Pushing your body to its limits.
Learning: The struggle of mastering a new concept.
Delayed Gratification: Saving money, building a business, or working on a long-term goal.

The ability to delay gratification is a key predictor of success. The famous “Marshmallow Experiment” demonstrated that children who could wait for a larger reward (two marshmallows) instead of taking a smaller immediate one (one marshmallow) tended to have better life outcomes, including higher academic achievement and better health (Mischel et al., 1972).

When you detach from cheap dopamine, you reset your brain’s baseline. Boredom becomes a tool for creativity, not a state to escape. Difficult tasks become engaging challenges rather than insurmountable obstacles.

How to Detox and Reclaim Your Focus

Digital Detox: Set strict limits on social media and entertainment usage.
Embrace Boredom: Let yourself do nothing for a while. Let your mind wander without reaching for your phone.
Do Hard Things: Intentionally schedule difficult tasks early in the day when your willpower is highest.
Visualize Long-Term Rewards: Keep your eyes on the prize. Remind yourself why you are making these sacrifices.

Success isn’t about luck; it’s about discipline. By choosing expensive dopamine over the cheap kind, you are literally wiring your brain for success.

References

Mischel, W., Ebbesen, E. B., & Raskoff Zeiss, A. (1972). Cognitive and attentional mechanisms in delay of gratification. Journal of Personality and Social Psychology, 21(2), 204–218.
Turel, O., He, Q., Xue, G., Xiao, L., & Bechara, A. (2014). Examination of neural systems sub-serving facebook “addiction”. Psychological reports, 115(3), 675-695.

Productivity on TECHFOR by Suriya Sonphu