Three Ways to Build a Second Brain — Pick by Who Can Read It

There's a thirty-second test that ends the "which note-taking app" argument. Open a brand-new agent session — empty history, nothing attached — and ask it something that can only be answered by combining three of your own notes. If you had to upload a single file to make that work, you don't have a second brain yet. You have a folder plus a habit of re-explaining yourself.

That test reframes the whole decision. Across the three common setups the features are nearly interchangeable: text goes in, an assistant reads it back. What actually differs is where the bytes sit and which agents can reach them without you in the loop. That's a portability question, not a features question, and it's the only part of this worth arguing about.

The three architectures, on one screen

1. Hosted knowledge — a Claude Project. You create a project, attach files to its knowledge, write standing instructions, and every conversation inside it starts pre-loaded. Fastest path to something useful today, and the instructions box is where most of the quality comes from — name the file to consult before answering and the outputs sharpen immediately. Two limits worth knowing before you commit: the free plan tops out at 5 projects, and retrieval is a paid feature. When a project's knowledge starts pressing against the context limit, Anthropic's help centre says Claude "seamlessly enables RAG mode to expand capacity by up to 10x" — which means past a certain size the model is being handed excerpts it selected, not your whole library. Best for: anyone who wants this working in fifteen minutes, or whose knowledge is one tidy area (a client, a job search) rather than everything.

2. Local Markdown — an Obsidian vault. Obsidian's docs are blunt about what a vault actually is: "A vault is a folder on your local file system where Obsidian stores your notes," and it "stores your notes as Markdown-formatted plain text files in a vault." Nothing proprietary happens to the text — the only Obsidian-specific artefact is the .obsidian folder it creates at the vault root for that vault's hotkeys, themes and community plugins. Because the notes are plain text, other editors and file managers can open and edit them, which is exactly why pointing a coding agent at the same folder just works. Best for: people who already write notes daily and want backlinks, search and a real UI on top. The catch nobody mentions: the notes are portable, but the machine isn't. One laptop, no history, and a plugin gallery large enough to become the project instead of the notes.

3. A git repo of Markdown — ~/brain. The same plain files, minus the app, plus version control. Any agent with file tools reads it directly. In Claude Code you attach it with claude --add-dir ~/brain — the CLI reference describes the flag as adding "additional working directories for Claude to read and edit files" — and you make it permanent by setting permissions.additionalDirectories in settings instead of retyping it every session. For desktop and GUI clients the filesystem MCP server does the same job: the directories it may touch are literally the trailing arguments in its config, and the local-server quickstart is honest about the trade — "the server runs with your user account permissions, so it can perform any file operations you can perform manually." Best for: devs and EMs who already live in git and want the same brain on a laptop, a work machine, and in CI.

Options 2 and 3 aren't rivals, which is the actual punchline: a vault is a folder, so it can be a git repo. Run git init inside it and you've merged them. Once you see that, the real axis has two positions rather than three — knowledge you upload to a vendor, and knowledge that lives in a directory you own.

The layout I'd copy

Five folders, and the first one does more work than the other four:

brain/
├── README.md          # the index: one line per folder, so an agent knows where to look
├── me/
│   ├── context.md     # who I am, what I'm optimising for this year, how to talk to me
│   └── career.md      # scope, evidence, comp data, the stories I retell in every interview
├── projects/          # one file per live thing, named after the thing
├── decisions/         # dated entries: what I chose, what I rejected, why
└── reference/         # things I didn't write — transcripts, docs, saved threads

Lowercase filenames with dashes, one topic per file, .md throughout. Then write the only file that matters on day one:

# Context

- Role & scope: what I'm accountable for, team size, what I actually decide.
- This year: the 2–3 outcomes I'm judged on, with numbers.
- How I work: my tools, my week, what I delegate.
- How to talk to me: direct, no preamble, disagree with me when I'm wrong.
- Stop asking me this: the background I'm tired of retyping into chats.

Dictate it out loud for two minutes and have the agent tidy it into the file. Two minutes of speaking gets you further here than an hour in front of an empty editor.

The gotcha that silently costs you a week

--add-dir grants file access, not configuration. The docs spell it out: most .claude/ configuration is not discovered from those extra directories. So the instructions you carefully leave inside ~/brain about how to use ~/brain may never load at all. Put that routing line in the project you actually launch from, or open the session with it:

Read ~/brain/README.md and ~/brain/me/context.md before answering anything else.

Why career.md is the file that pays

If you're a Brazilian dev or EM going after remote roles in the US or EU, you are retelling the same six stories across dozens of processes — scope, impact, why you left, comp expectations in a currency that isn't yours. Written down once, with real numbers, that file turns every application from a memory exercise into a drafting task. Mine holds promotion evidence I'd otherwise have to reconstruct out of Slack a year later.

Do this today

Make the folder, write me/context.md, git init, push it private. Then run the cold-start test: claude --add-dir ~/brain in a fresh session, and ask the question you normally have to set up first — "based on what's in this folder, what should I spend next week on?" The answer tells you whether you built a second brain or another empty container. All three of these fail the same way, and it is never the tool's fault: people finish the structure and never put anything real inside it.

Sources

• Claude Help Center — What are Projects?
• Obsidian Help — Vaults
• Obsidian Help — How Obsidian stores data
• Claude Code docs — CLI reference
• Model Context Protocol — Connect to local MCP servers