A second brain I run from the command line.

Every Claude session started from zero. I would re-explain the same client and the same approach we had ruled out a month ago, because the model had no memory and, it turned out, neither did I. A good article became a bookmark I never reopened. A call where someone explained the exact thing I was stuck on left nothing behind a week later.

Keeping notes did not fix it. Notes pile into a graveyard you never walk through. I did not want an archive. I wanted what I had already learned to resurface when it could change a brief I was writing, or a decision I was about to repeat badly. The archive existing was never the point.

The structure I run today is the third attempt. Day one I built it the textbook way: PARA, Zettelkasten, MOCs. It looked principled and worked badly. I kept stalling on where each note belonged, and that hesitation is fatal, because capture has to be frictionless or it does not happen. Four days in, I tore it out and renumbered everything, 00 to 05.

The numbers turn “where does this go?” into a glance. Raw captures land in 00 and stay rough. The further right a thing sits, the more I have processed it, from a loose source summary to an idea I have actually made my own to something I am using on a live project.

Tasks taught me the same lesson harder. I had Kanban boards, the default move, and they drifted constantly: the board claimed one status, the note claimed another, and keeping the two honest became its own chore. So I deleted the boards. Now the note is the truth: one native checkbox per task, and the folder it sits in has to agree with that checkbox. Nothing is left to fall out of sync.

Here is the shape it settled into.

second-brain
├── 00-inbox/              # Raw captures, unprocessed
├── 01-projects/           # Active work (.paused/ for paused)
│   └── {project-name}/
├── 02-personal/           # Personal notes by domain (career, finance, ...)
├── 03-research/           # Source summaries and references
│   └── {domain}/
├── 04-knowledge/          # Refined, atomic ideas
│   └── {domain}/
├── 05-resources/          # Reusable artefacts (shared/ is cross-domain)
│   ├── {domain}/
│   └── shared/
├── archive/               # Processed inbox and completed projects
├── design/                # Local Design Canvas app for visual artefacts
├── system/                # Architecture, workflows, tools, learnings
├── tasks/                 # Promoted task notes by status
│   ├── 00-todo/
│   ├── 01-doing/
│   ├── 02-waiting/
│   └── 03-done/
└── templates/             # Note templates and scaffold folders

A few rules stop this from collapsing back into one big folder called notes. Research, knowledge, and resources are domain-first: nothing loose at the root, everything under ai/, branding/, career/ and the like. The domains are not symmetric between research and knowledge, which bothered me until I stopped fighting it. I research plenty I never synthesise, and I hold opinions I have never read anywhere. Whichever side I am writing to picks the domain.

The rest bends where a project earns it. A few keep their own indexed subfolders because that is genuinely easier to navigate. The system/ folder holds the vault’s own documentation (architecture, workflows, and a running log of things I learned the hard way), so the rules live inside what they govern.

Around six hundred notes in, the obvious approach broke. You cannot pour a vault into a model’s context and ask it to think. So the agents never touch the raw files; they go through a CLI that does the work and hands back only the answer.

obsidian search query="speed control" limit=10
obsidian property:set name="status" value="done" file="edu-014"
obsidian move path="tasks/00-todo/edu-014.md" to="tasks/03-done"

Reading a note, flipping a property, moving a file so its wikilinks update everywhere it is referenced: each is one call that returns one result. The model spends its context on the problem, not on Markdown it will throw away. It is also what lets an agent edit a six-hundred-note vault without leaving a trail of dead links behind it.

Notes do not move themselves. A capture lands in 00-inbox raw. /research turns a URL or a video transcript into a source note with metadata. /knowledge:extract pulls the ideas worth keeping into my own words, filed under the right domain. Three steps, each one I trigger.

/inbox              triage raw captures into research, knowledge, or a project
/research           a URL or transcript becomes a source note with metadata
/knowledge:extract  source notes become atomic ideas in my own words
/save               end a session: language pass, clean commits, log learnings
/absorb             fold session learnings into permanent commands and docs

The part I am most deliberate about is the end of a session. /save reviews the language, commits the work in clean chunks, and appends what I learned to system/LEARNINGS.md. /absorb takes those scattered notes and folds them into the permanent commands and docs, so the vault gets better at being itself.

I could put all of this on a schedule. I keep it manual instead: every change is something I ran, sitting in git, where I can read it and undo it.

Three decisions kept it usable past a few hundred notes. None of them are clever, and each one cost me something.

1. Capture stays raw. 00-inbox has no structure and no rules. I write and move on. The cost is an inbox I have to triage by hand, with nothing forcing me to. I would rather pay that than add friction to the one step that has to have none.
2. Research and knowledge never share a folder. A summary sits in 03-research until I have formed my own take on it; only then does an idea graduate to 04-knowledge. It is an extra step every single time, and I keep it on purpose, because a summary I parroted and an idea I own are not the same thing and the vault should not pretend they are.
3. It works with whatever model I am using. The commands and skills live once in .agents/. Each tool keeps its own config folder (.claude/, .codex/, .opencode/), but the commands and skills inside them are symlinks back to .agents/. I write a command once and Claude Code, Cursor, Codex, and opencode all read the same one. I did not want to rebuild my second brain every time I switched tools.

The vault stopped being a notebook a while ago. It tracks a competitive Pokémon project and runs the private admin of my life I would rather not think about twice. The layers and commands do not care what they are holding.

For client work it does the job I first built it for. Open a project and the research that fed it, every decision I made and why, and whatever tasks are still open all come back in one query. I brief myself in a minute instead of rebuilding the context from memory, badly.

It runs on around sixty commands and a handful of skills, each one grown from a real need. There was never a roadmap. A command exists because I hit the same chore twice and refused to do it by hand a third time.

I could run a fully automated version of this, with agents ingesting sources and rewriting the vault while I sleep. But I keep it manual, because the vault was never really the point.

Building it by hand is how I learned how commands and skills actually behave, and the same patterns now plan my days and review my pull requests on a client monorepo. I built the vault to stop losing what I learned. What I did not expect was that building it would be the most useful thing it taught me.