The Brain Vault is an accessibility system I built for my ADHD. It's a local-first Obsidian vault that works as an external layer for context and priorities, structured so an AI agent can navigate it and act on real context. A notes app is built for retrieval: where did I put that? This is built for connection and action: what does an agent need to know right now to act on real context?
I started building it around March 2026, writing the instructions for the agents that would build it. The seed was about 1,300 ChatGPT chats covering December 2023 through March 2026, and I was clear from the beginning: the purpose was not to create a chat archive, but a map of my brain that I could continue to update intuitively. The important part of those chats was what I said, not the input from ChatGPT.
Today the vault holds 1,765 documents — 869 synthesized and 822 raw imports — with 7,075 links in the synthesized layer, a median of five per document. Fifty concept pillars map to eleven domains. Seventeen agent playbooks define named routines. It's shipped, for its one user, and in continuous use.
This is the build log: what I was doing, what I saw, how the pieces came together, what broke, and what changed.
Two layers, on purpose
The architecture puts raw conversations and extracted conclusions in separate layers, and that separation does real work.
The raw layer holds imported source material and is never edited. The synthesized layer — concept pillars, notes, timelines — is written on top and links back to the raw items it came from. When I run importance scoring (PageRank on the link graph), it only counts the synthesized layer. The raw layer exists to be cited, not to be navigated.
This maps directly to an ADHD failure mode: finished work evaporates from memory. A completed-work ledger holds what shipped; the raw layer holds what happened; the synthesized layer is where the agent looks to understand what matters. Anything that ships gets a ledger line the same day.
Triage before extraction
Early on, I built an import pipeline that does signal triage before any extraction work happens.
A batch comes in — let's say a few hundred items — and the pipeline splits it into one file per item, then removes near-duplicates at a 0.80 similarity threshold. Every decision is logged. Then each item gets a signal-strength score. Only the items that clear the threshold make it into the raw layer; the rest are archived out.
The rule I wrote for the agents building this: the purpose is a map of my brain, not a chat archive. If something doesn't carry signal, it doesn't go in.
Dates with confidence
Ninety-six percent of documents in the vault carry structured frontmatter metadata. Where a document has a date, that date is in the frontmatter. Where it doesn't, the system infers one and states the confidence level.
Undated material gets an inferred date and a label — not a guess dressed as fact. The same pattern runs through the whole vault: anything that isn't measured is labelled as an estimate or an inference, in the sentence.
PageRank, ported twice and cross-checked
Importance scoring in the vault uses PageRank on the link graph of the synthesized layer. I wrote a standard-library Python script to build the graph and rank the documents; the same scores drive a 3D visualization plugin I call Cosmos.
Cosmos maps domains to stars, concept pillars to planets, and evidence notes to moons. The plugin is built and tested — 31 tests, including a real-vault integration run — but not shipped. One feedback round is still open.
The dense analytical graph is never rendered directly. Cosmos renders a sparse version of it, because the full graph would be unreadable.
I ran PageRank twice: once in the scoring script, once in a verification pass. The scores matched.
Seventeen playbooks instead of vibes
The vault has seventeen agent playbooks. Each one defines a named routine: imports, interlinking, health checks, weekly review. A routing layer tells an agent where to start and which sources are stale.
A routing layer tells an agent where to start, because working memory won't hold the entry point.
That's the same principle as LEGION's agent-first README in 2025: write the brief for the agent first. If I can't hold the entry point in my head, neither can the agent unless I write it down.
The playbooks are procedures, not vibes. They say what to check, what to update, where to write the result, and when to ask before changing something.
Operating documents
The vault keeps a set of live operating documents that answer ADHD-specific needs:
- A priorities document, capped at five active items, because working memory won't hold more.
- Operating assumptions held as confidence-scored hypotheses, so I can see what I think is true and how sure I am.
- An energy map for scheduling against actual focus capacity.
- An accomplishment ledger, built as a deliberate counterweight to undercounting my own output.
Since August 2026, I write my own entries and an agent files them. My method: I add bullets first for coverage, then fill in the details on a second pass.
What broke
The nebula that never rendered. In Cosmos, the visualization plugin, I wanted a nebula effect in the background. Scene fog was washing the additive sprites to black. No test caught it; I found it by looking at the render.
The fix was straightforward once I saw it, but the lesson was that some rendering bugs only show up when you look at the output, not when the tests pass.
Five fix rounds in one day, and the record drifted. The feedback document for Cosmos says four rounds; the coding session had five. Three rounds happened in chat and were never written down. The record drifted because I didn't log them as they happened.
That's a process failure, not a technical one. The fix is to log every round the moment it closes, not later when I'm writing it up.
An earlier headline number was wrong. An earlier summary I wrote said the vault held about 1,850 documents and 56 pillars. The measured counts are 1,765 documents and 50 pillars. I had rounded up from an estimate that turned out high.
I don't round up anymore. The number is what the measurement says, or it's labelled as an estimate.
The habits that keep it working
A weekly check-in with written wins. Anything shipped gets a ledger line the same day. The priorities cap at five, and I don't let that slip.
The stack is Obsidian for the vault, Syncthing for device-to-device sync with no cloud, and Claude Code as the maintenance agent. The playbooks route the work; the routing layer keeps the agent from getting lost; the two-layer architecture keeps raw material separate from conclusions.
It's an accessibility tool. A highly effective one.