Claude Code as a Second Brain: What the Tutorials Skip

Every guide shows you the first 20 minutes. Here is what breaks at month six, from the person who maintains the biggest one.

TL;DR

• Search “claude code second brain” and you get ten tutorials that all show the same setup: drop an Obsidian folder in, add a CLAUDE.md, done. It works, for about a week.

• The hard part is not the setup. It is what a second brain has to do to survive past a few hundred notes: retrieve across notes, stay current, and maintain itself.

• I maintain obsidian-second-brain, a Claude Code skill 3,400+ developers use for exactly this. Here is the part the tutorials skip.

Type “claude code second brain” into Google and you get a wall of how-to posts. They are not wrong. They all show the same thing: put your Obsidian vault in a folder, run Claude Code from it, write a CLAUDE.md, and now the model can read your notes.

That setup is real and it does work. For about a week.

Then you hit the part none of the tutorials cover, because they were written after a weekend, not after a year. I have run this daily for over a year and shipped the tooling for it in the open. This post is month six, not minute one.

The setup everyone shows

Credit where it is due, the basic loop is genuinely good.

Obsidian notes are plain markdown on your disk. Claude Code reads and writes files. Point one at the other and the model can create notes, edit them, and follow a CLAUDE.md instruction file. Cole Medin’s second-brain-starter and a dozen Substack guides all land here, and it is the right place to start.

The problem is that this is a demo, not a system. A demo answers “can Claude read my notes?” A system answers “will this still work when I have 3,000 notes and half of them are stale?”

Those are different questions. The gap between them is where every second brain quietly dies.

Where it breaks

Three things go wrong, and they all show up around the few-hundred-note mark.

Retrieval gets noisy. With 50 notes, Claude reading “everything” is fine. With 2,000, dumping the vault into context is impossible, and naive search pulls ten notes that mention a word but miss the one that answers the question. The tutorial setup has no real retrieval, just “read the files.”

Here is the kind of question that exposes it. Ask your vault “why did we drop the old billing provider?” The answer lives in three notes: the decision, the thing it replaced, and the incident that triggered it. Naive search pulls every note that mentions billing and misses the causal chain entirely. You get ten fragments and no answer.

The vault goes stale. You change jobs. A decision gets reversed. A tool you swore by gets dropped. The old note does not delete itself. Six months in, your second brain confidently cites the version of you from March, and you have no idea which half is current. This is the quiet failure, because it does not look broken. It looks like a confident answer that happens to be wrong.

Nothing maintains it. A real brain prunes, connects, and reconciles. A folder of markdown does none of that on its own. Without maintenance, entropy wins, and the thing you built to reduce your mental load becomes another mess you have to manage.

What a second brain actually has to do

Strip away the hype and a working second brain has four jobs, not one.

Capture with almost no friction, so you actually use it. Retrieve across notes, so it can answer questions whose answer lives in three places at once. Stay current, so it knows what is still true and what got superseded. And maintain itself, so it gets better while you sleep instead of rotting.

The tutorials give you job one and a weak version of job two. Jobs three and four are the entire difference between a note folder and a second brain. They are also the boring, unglamorous work nobody puts in a “build a second brain in 10 minutes” video, because they take longer than 10 minutes.

Own it or rent it

There is a second question the tutorials skip: who holds your memory.

Claude now ships built-in memory, and it is genuinely convenient. But it has three properties I could not live with. It lives on someone else’s server. It lives inside one product. And I cannot open it, read it line by line, and correct a wrong fact.

A file-based second brain is the opposite trade. It is plain markdown on your disk. You can read every fact, fix the wrong ones, and move the whole thing to a different model next year when a better one ships. You give up the one-click convenience and you get ownership that outlives any single vendor. For something meant to hold years of your thinking, that trade is not close.

The part I built

I got tired of my own vault rotting, so I built the missing three jobs and open-sourced them as obsidian-second-brain, a Claude Code skill now starred by 3,400+ developers.

It is 45 slash commands, but they all serve those four jobs. Capture is one keystroke. Retrieval honors freshness and typed relationships between notes instead of blind similarity, so the billing question above returns the causal chain, not ten fragments. Scheduled agents run health checks, reconcile contradictions, and prune stale claims on their own. When a new note contradicts an old one, the old fact gets marked superseded, not silently left to lie.

That last part is the one people underestimate. A second brain that cannot tell you what is no longer true is worse than no second brain, because it launders stale facts as current ones. The maintenance layer exists to keep the vault honest with itself, which is exactly the work a folder of markdown will never do on its own.

This is also where the graph engineering work lives: typed edges in the markdown, so the vault is a real graph the agent can traverse, not just a pile of links. I wrote separately about what a working second brain needs that Karpathy’s LLM Wiki pattern does not, which is the same lesson from a different angle.

The point is not “use my thing.” The point is that the setup you see ranking for this search is the start line, and almost nobody writes about the actual race.

The one line to keep

A second brain is not a folder Claude can read. It is a system that maintains itself. The tutorials give you the folder. The maintenance is the whole job.

If you want to watch that maintenance layer get built in the open, with the benchmark numbers when they land, subscribe. Every post here documents a working build, including this one.

Frequently asked questions

How do I use Claude Code as a second brain? Point Claude Code at a folder of markdown notes (an Obsidian vault works well), add a CLAUDE.md file with your rules, and it can read, write, and structure your notes. That is the starting setup. To make it survive past a few hundred notes you also need real retrieval, freshness tracking, and scheduled maintenance, which plain setup does not include.

Is Obsidian required for a Claude Code second brain? No. Any folder of markdown files works, because Claude Code operates on files, not on Obsidian specifically. Obsidian is a convenient viewer and gives you wikilinks and graph view for free, which is why most setups use it.

Why does my Claude Code second brain get worse over time? Because nothing maintains it. Notes go stale, decisions get reversed, and contradictions pile up. Without a maintenance layer that prunes, reconciles, and marks facts as superseded, the vault slowly fills with outdated claims the model then cites as current.

What is the difference between Claude’s built-in memory and a file-based second brain? Built-in memory lives on a server, inside one product, and you cannot open it and correct a wrong fact. A file-based second brain is plain markdown you own, can read line by line, and can move to any model. You trade convenience for ownership and control.

How many notes can a Claude Code second brain handle? The naive “read all the files” approach breaks around a few hundred notes, when the vault no longer fits in context and simple search gets noisy. With proper retrieval (freshness-aware, relationship-aware) it scales to thousands.

Key takeaways

• Every “claude code second brain” tutorial shows the same 20-minute setup and stops there. The setup is the easy part.

• A second brain has four jobs: capture, retrieve across notes, stay current, and maintain itself. Tutorials cover one and a half of them.

• The setup breaks around a few hundred notes: retrieval gets noisy, the vault goes stale, and nothing prunes or reconciles it.

• Claude’s built-in memory is convenient but sealed. A file-based second brain trades convenience for ownership you can read and correct.

• A second brain is not a folder Claude can read. It is a system that maintains itself, and the maintenance is the whole job.

Further reading

• obsidian-second-brain on GitHub - the open-source Claude Code skill this post describes (MIT, 3,400+ stars).

• What Is Graph Engineering? A Field Guide for Builders - how typed edges turn a vault into a real graph the agent can traverse.

• I Rebuilt Karpathy’s LLM Wiki. Here’s What’s Missing. - the same lesson from the knowledge-wiki angle.

• second-brain-starter by Cole Medin - a good starting-point skill if you want the minimal setup first.

• How to Use Claude Code as a Thinking Partner (Every) - a useful take on the daily-use side.

About the author

Eugeniu Ghelbur is an AI Automation Engineer and the creator of obsidian-second-brain, an open-source Claude Code skill starred by over 3,400 developers on GitHub. He builds production AI systems for marketing and sales workflows, and his personal research covers AI agent memory, AI-first knowledge management, and second brains that maintain themselves. He writes The AI Operator (theaioperator.io), a weekly systems newsletter where every post documents a working build, including this one. The fastest way to reach him is e.ghelbur@gmail.com, and his open-source work lives at github.com/eugeniughelbur.