A repo file only knows about its repo. The hard-won knowledge that matters most crosses projects: the same problem, the same mechanism, the same stack, in a different codebase. That is what a vault is for, and it is the ceiling a README cannot get past.
Every session with an AI coding agent starts from nothing. The agent does not remember that the last session found a gotcha in the database’s grant model, or that a design decision was made and why, or that a pattern for polling a push-less API was worked out three projects ago. The usual answer is a README or an instructions file in the repo. That helps, up to the ceiling.
What it is
Plain Markdown files in a git repository. One note per idea, with wiki-style links between them and a single index file with one line per note. Notes are typed: features built, reusable patterns, decisions with reasoning, learnings distilled from sources.
Why not a database or a vector index. The value of a second brain is atomic notes, links and traversal. Markdown with links gives all three for free, and a coding agent can read, grep and edit files natively. Git gives history and, more importantly, reachability from cloud sessions that cannot see a local disk. A search index goes on top later if grep stops being good enough, which at a few dozen notes it has not.
Getting it read
A vault nobody reads is a diary. Three layers make it get read.
Awareness is mechanical. A session-start hook pulls the repo and injects the index into context. One line per note is tiny, and tens of lines cost nothing. Once those lines are in context, a session designing an integration connects “centralized polling with poke broadcast, for push-less APIs” on its own.
Obligation is a standing rule. Before proposing an approach to any non-trivial build, design or debug task, scan the index, and if any note plausibly relates, read it and apply it before designing from scratch. And say which notes were applied, so stale ones get noticed.
Retrieval quality is writing. Each index line is written for a stranger searching by problem. Symptom, mechanism, stack. Not the title.
Getting it written
The failure mode of every instructions file is that it is written once and never updated, and a stale architecture document is worse than none. Two rituals keep the vault alive.
Save mid-session, not at wrap-up. The moment a decision or gotcha is settled, it goes in, because a long session’s context gets summarized and the decision made an hour ago is exactly what gets lost.
Check before writing. If a new note contradicts an old one, stop and ask: did I change my mind, or is the new information wrong? On a change of mind, the old note is updated in place with a dated line saying what it previously said and why it changed. Never two notes disagreeing. Git keeps the old version.
The junk drawer problem
A vault accumulates. Near-duplicates, one-way links, index lines that no longer describe the note. So it audits itself: a script that checks links both ways and flags thin hooks, run in CI, and a periodic gardening pass that merges duplicates and prunes.
What it changed
The agent now starts a new project already knowing the setup gotchas from the last three, knows which design directions were rejected and why, and can be told “save that” and put it somewhere the next session will find. It is not memory in any deep sense. It is a shared notebook with a librarian’s habits, and that turns out to be most of what was missing.