A Second Brain Your AI Agent Can Read

Background

There are so many details we need to remember in life. Recently I've been
working on a legacy project that was written years ago with no maintainers left.
I've had to continuously dig through thousands of lines of my own notes just to
remember how a particular piece of the application works. Sifting through notes
to find one detail takes time I'd rather spend architecting and building.

AI agents change that. They make it much easier to store and retrieve
information you wrote down days, months, or years ago.

What is Obsidian

Obsidian is a note-taking app that stores everything as
plain markdown files. It lets you organize and structure your notes in a
flexible way, and because the files are plain text on disk, anything that can
read a directory can read your notes, including an AI agent.

For projects, I use Obsidian as my personal documentation: how a system works,
why a decision was made, what the process flows are. Think of it as a second
brain. Everything lives in one place.

The part that makes it work with an agent isn't the app, it's the linking.
Obsidian lets you create bidirectional links between notes with
[[Note Name]]. That turns your vault from a pile of files into a graph you can
hand an agent a single entry point to.

How I structure my files

Obsidian is flexible enough that there are a dozen reasonable ways to set this
up. Here's mine, but you can adapt it to whatever fits your style.

I keep two folders. MOC stands for Map of Content, and holds one file per
topic named <Topic Name> - MOC. Permanent Notes holds everything else. Every
time I create a note related to a topic, I link it in both directions:
[[<Permanent note name>]] in the MOC, and [[<Topic Name> - MOC]] in the
note.

The following files are examples:

vault/
├── MOC/
│   └── Legacy Payments API - MOC.md
└── Permanent Notes/
    ├── Payments API - Endpoints.md
    ├── Payments API - Webhook Retry Logic.md
    ├── Payments API - Settlement Flow.md
    └── Payments API - Architecture Decisions.md

And the MOC itself stays deliberately thin:

# Legacy Payments API - MOC

Legacy service handling card settlement.

## Reference

- [[Payments API - Endpoints]]
- [[Payments API - Webhook Retry Logic]]

## Design

- [[Payments API - Settlement Flow]]
- [[Payments API - Architecture Decisions]]

This is the whole trick. Instead of pointing an agent at a folder and hoping it
reads the right things, you point it at one file that tells it exactly which
notes matter and how they relate. You control the context window instead of
letting the file system decide it for you.

Connecting your agent to the vault

There's no plugin or integration to set up here. Because Obsidian notes are just
markdown files on disk, any agent that can read your file system can read your
vault.

My workflow is simple: I open Claude at the vault root and tell it to read a
specific MOC file.

Read MOC/Legacy Payments API - MOC.md and the notes it links to.

Or paste the full path in directly if you'd rather not think about where you
launched from.

The reason to open at the root rather than inside MOC/ is that the links point
outward. Your MOC lives in one folder and every note it references lives in
another, so an agent scoped to MOC/ has to reach outside its working directory
to follow them. Depending on your setup that means approving access every time.

Using an agent with the MOC

When I start researching a topic, I create the MOC first and give the agent the
path to it.

On the legacy project, that meant creating Legacy Payments API - MOC, then
working through the codebase asking Claude to document the API endpoints, the
business logic, and the process flows — with each one landing as its own
permanent note and each one linked back to the MOC. I wrote my architecture
documents into the vault too, so I can reference them later instead of
reconstructing the reasoning from scratch.

Once the MOC has some substance, it becomes the entry point for everything else.
When I need a plan for a new feature, the prompt is roughly:

Read MOC/Legacy Payments API - MOC.md and every note it links to. Then write
an implementation plan for adding partial refunds to the settlement flow. Flag
anything in the existing notes that contradicts the change.

Tips to work efficiently

Two things went wrong for me before this settled into something useful.

Agents write far too much. Ask for documentation on a service and you'll get
a small book. It becomes too dense for a human to actually read. The more text
the agent has to go through, the more likely it is to hallucinate something that
isn't in there.

The fix is the most important habit when working with AI agents: proofread what
the agent wrote before you save it. It's tempting to trust Claude to write notes
and then never look at them, but a proofreading pass lets you cut the sections
you'll never need. Every paragraph you delete now is context the agent doesn't
have to process later.

Notes drift out of sync. New information surfaces in conversation and never
makes it into the vault, so the next time you read the note it's wrong. Keeping
notes short is what makes them maintainable. If you can scan the section headers
of a note in ten seconds, you'll actually update it. Long notes are far less
likely to get updated.

What doesn't belong in the vault

The instinct when an agent is doing the writing is to let it document
everything, because it's free. But every line it writes is a line you have to
proofread and a line it has to read on every future run.

The thing to cut first is code detail. You don't need a note listing every
parameter on every method, or a walkthrough of what each function does line by
line. That information is already documented by the code itself.

Keep the vault at the level the code can't tell you. Why the retry logic backs
off the way it does. What the endpoints are actually doing at a high level. The
reasoning behind an architecture decision nobody wrote down at the time. That's
the stuff you can't reconstruct from source.

Two more things I've learned to leave out.

The first is the agent's own reasoning. When Claude works through a problem it'll
often narrate how it got there, what it ruled out, what it checked, and why it
landed where it did. That's useful to read in the moment, but it becomes noise
in a document.

The second is anything that has an authoritative source somewhere else — framework
docs, library references, the ticket describing the requirement, the Slack thread
where a decision got made. Copying those into the vault creates a second copy
that starts going stale immediately. Link to them instead.

The main idea is to keep your notes concise and at a high level to stop the AI
agent from hallucinating.

A decent test: if the information already lives somewhere authoritative — the
repo, the ticket, the docs — you don't need to duplicate it. Write down the part
that only exists in your head.

Summary

Documentation is hard to write and harder to keep current, and on a legacy
project with no maintainers that gap is where all your time goes. Pairing an
agent with Obsidian doesn't remove the work. You still proofread and keep things
in sync. What it changes is the kind of work. Instead of scanning your notes to
find information, you're scanning them to verify it, and that's a much
simpler job.

Let me know how it works for you.

Comments

[Alex Shev]

A second brain for agents needs more than storage. It needs provenance, freshness, ownership, and a way to distinguish facts from summaries and preferences. Otherwise the agent can retrieve a note correctly and still apply it in the wrong context.

[Mikhail]

"Every paragraph you delete now is context the agent doesn't have to process later" is the whole argument in one line, and it holds up even outside note-taking. I ran a paired experiment recently comparing a lean, intent-filtered context call against a maximal one that pulled everything (source + symbols + git + memory) for an AI coding agent — the maximal version cost ~5x more tokens for statistically the same recall. More context wasn't more correct, it was just more expensive to be equally right.

The "notes drift out of sync" point maps onto something I keep running into on the retrieval side too: a stale or shadowed source can produce an answer that looks exactly as confident as a correct one. Same failure shape as what alexshev is pointing at below (provenance/freshness) — whether it's a markdown note or a symbol lookup, the agent has no way to tell "this is current" from "this used to be true" unless something upstream flags it.

Good discipline either way: proofread before it compounds, and keep the source of truth in one place instead of a copy that can quietly go stale.