Obsidian Second Brain with Claude Code: My Agent-Readable Vault Setup

Everyone talks about building a “second brain.” Most people mean folders in Notion, backlinks in Obsidian, or a dashboard they open twice a month.

I mean something more literal: a knowledge base that an AI agent can read, search, cross-reference, and update while I work. My projects, diary notes, tasks, research, drafts, finances, code decisions, all living in markdown. Claude Code can enter that vault, understand the rules, and do useful work without me re-explaining my life every morning.

Why normal second brains fail

Classic second brain advice optimizes for human browsing. Nice folders. Tags. Pretty graph view. Maybe a PARA structure if you are disciplined.

That works until the system grows. Then you stop remembering where things are, search becomes noisy, and the graph view turns into wallpaper. The vault becomes a digital storage unit. Technically full of useful things. Practically dead.

An AI-readable second brain has a different job. It should answer questions like:

• What am I working on right now?
• What decisions did I already make about this project?
• What source material should be saved for later?
• What should be updated after this voice note?
• Which facts are durable enough to move into a project overview?

That is why the structure matters. Not because folders are beautiful. Because agents need deterministic places to read and write.

My vault architecture

The core structure is simple:

projects/
  second-brain/
    overview.md
    tasks.md
    ideas.md
    ai-docs/
  public-site/
    overview.md
    tasks.md
    ai-docs/
personal/
  diary/
  finances/
work/
  ton_foundation/
AGENTS.md

Every active project has the same primitives:

• overview.md — durable facts and current strategy.
• tasks.md — concrete next actions.
• ideas.md — backlog, not commitments.
• ai-docs/ — generated briefs, audits, transcripts, research notes.

This looks basic. That is the point. Claude Code does not need a beautiful taxonomy. It needs predictable paths.

Agent instructions are the operating system

The most important file in the whole vault is not a note. It is AGENTS.md.

It tells the agent how the vault works: where raw voice notes go, which files are source of truth, how to extract tasks, where credentials must not be stored, when to use GBrain, and how to write in my voice through dania.zip.

This is the pattern that changed everything for me:

When receiving a long request:
- Save raw text into the right project ai-docs folder
- Add tags and project links below it
- Extract TODOs into tasks.md
- Move durable project facts into overview.md
- Never edit raw human notes directly

Without rules, the agent is a smart intern with no map. With rules, it becomes a librarian who knows where every shelf is.

The voice note pipeline

The input layer matters more than the storage layer. If capturing a thought is annoying, the system dies.

My default flow:

1. I record a Telegram voice note while walking.
2. The agent transcribes it.
3. Claude Code reads the vault instructions.
4. It saves raw text into the right project folder.
5. It extracts tasks and project facts.
6. It links the note to related projects.

This is where Obsidian becomes useful. Not because I open Obsidian and lovingly maintain notes. Because markdown files are easy for agents to edit, diff, search, and version.

The voice note stays pristine. AI-generated synthesis lives next to it. That boundary matters. Raw human input should not be rewritten just because an LLM wanted to be helpful.

GBrain vs Obsidian

I use two memory layers now:

GBrain is not replacing markdown. It is the briefing layer on top of it. Before a planning session, the agent can query GBrain and recover the latest decisions. Then it writes the durable update back into the relevant project files.

That loop is the real second brain: retrieval, synthesis, action, and durable storage.

What Claude Code actually does inside the vault

Most people imagine “AI + notes” as a chatbot over a folder. Useful, but too passive.

Claude Code can do more because it has file access and shell access. In my vault it can:

• find related notes with ripgrep;
• read project overview/tasks before answering;
• create an ai-doc with a timestamped summary;
• update project tasks after a long planning request;
• save a distilled insight into GBrain;
• cross-link new notes to old decisions;
• refuse to put credentials into markdown.

The difference is agency. I do not want a search box. I want an assistant that can cleanly move context from “random thought” to “project memory” to “next action”.

The minimum setup

If I had to rebuild from zero, I would not start with plugins. I would start with five files:

Then I would add Claude Code. Then GBrain. Then automation. In that order.

Mistakes I made

Too many clever folders. If the agent needs to infer where something belongs, the structure is too clever. Use boring names.

Letting AI edit raw notes. Bad idea. You lose provenance. Keep raw text, add AI synthesis below or next to it.

Mixing credentials with memory. Credentials belong in env vars, secret managers, or local private files. Not overview notes. Not GBrain.

Writing long rules nobody will read. Agents have context limits too. Put the highest-priority rules near the top and keep files short.

Treating search as the product. Search is table stakes. The product is a workflow that turns messy input into structured project state.

How to make your vault agent-readable

Here is the checklist I would use for any Obsidian + Claude Code setup:

• Every active project has overview.md and tasks.md.
• Raw human notes are never overwritten.
• AI-generated docs have date + source + project links.
• Credentials are referenced by location, never pasted.
• Long-term decisions move from chat logs into project overviews.
• Repeatable workflows become explicit instructions.
• Search/retrieval results are summarized before action.

Do this and the vault becomes legible to an agent. Skip it and you get another folder full of markdown that nobody wants to open.

Why this is better than another SaaS

I do not want my second brain trapped behind a product roadmap. Markdown files are boring, portable, diffable, and easy to back up. If Obsidian disappears, the vault still works. If Claude Code changes, another agent can read the same files.

The moat is not the app. The moat is the accumulated context and the operating rules around it.

That is also why this setup compounds. Every project note, task, decision, and voice memo makes the next agent session better. Not because the model “remembers” me magically. Because I wrote the memory down in a format it can use.

What I would build next

The next step is not more folders. It is better feedback loops:

• weekly project review from tasks + ai-docs;
• weekly synthesis from raw notes and GBrain decisions;
• automatic stale-task detection;
• source packs for projects and talks;
• clear public/private boundaries for anything the agent touches.

The second brain stops being a note system at that point. It becomes the coordination layer for work and memory.

If you want to build the Claude Code side first, start with my Claude Code setup. If your agent starts forgetting context mid-session, read the compaction guide. And if you want to package your own voice into the system, read dania.zip.