Every Claude Code session starts from zero. That's the deal — you open a terminal, the model reads your repo, and whatever you worked out together last Tuesday is gone. You re-explain the architecture. You re-explain why you rejected the obvious approach. You re-explain it again next week.
For about a year I solved this the way most people do: I didn't. I scrolled back through old chats when I needed something, found it maybe half the time, and re-derived the rest. The re-deriving was the expensive part. Not the typing — the fact that Claude would confidently propose the thing I'd already tried and discarded, and I'd have to remember why I'd discarded it before I could say no.
So I built a second brain. It's an Obsidian vault at ~/Brain, backed by a private git repo, and it's the long-term memory for every agent I run. Around 370 notes now. This post is about why it's shaped the way it is — the rules that make it work, and the ones I got wrong first.
Why files, and not chat history
The obvious alternative is to lean on the chat platform. Most of them now have some form of memory: the assistant notices something worth keeping and stores it for you. It's genuinely useful. It's also not what I needed, for three reasons.
It isn't mine. Chat memory lives inside one product. My work runs through Claude Code in a terminal, Claude on the web, and an agent on a VM in my house. A memory that only one of those can read isn't memory, it's a cache. The vault is a folder of Markdown files — every one of those clients can read it, and so can grep, and so can I on a plane.
I can't review what I can't see. Hosted memory decides what's worth remembering and shows you a summary. I want to open the file. I want to see the diff when an agent edits it, and I want git log to tell me who wrote what and when. Three writers touch my vault — me, Claude, and the agent on the VM — and git is the only reason I trust any of it. When something in there is wrong, I can find the commit that made it wrong.
Retrieval isn't the hard part; structure is. This is the one that took me longest to accept. The value of the vault isn't that it can find things — a good search over your chat history can do that too. The value is that writing a note forces a decision to be stated. "We chose X over Y because Z, on this date." That sentence doesn't exist in your chat history. It exists in the gap between four messages, and no retrieval system reconstructs it faithfully. The file makes it real.
There's a fourth reason that's less principled and more practical: Obsidian is where I already think. The vault isn't an agent artifact I visit for maintenance. It's the same place I write reading notes and plan my week, and agents happen to write there too. If it had been a separate agent-only store, I'd have stopped opening it inside a month.
Compartments, and why they never cross
The vault has one compartment per working context — current work, past engagements, my own company, personal life — plus _shared/.
The rule is strict: a session mounted at one compartment uses only that compartment, and there are no wikilinks between compartments. Not "prefer not to." None.
This started as caution and turned out to be the single best structural decision in the whole thing. Two reasons, and the second one surprised me.
The first is the obvious one. Different working contexts carry different confidentiality obligations, and those obligations don't expire when the engagement does. If a session working in one context can reach material from another, I've built exactly the leak I'd tell a junior engineer to avoid. Isolation by folder is crude, but crude and enforceable beats elegant and aspirational: when I open a session against one compartment, there is no mechanism by which anything outside it arrives.
The second reason is that it makes the notes better. A note that can link anywhere drifts toward being about everything. When the only links available are inside one compartment, the note has to stand on its own in that context — it has to say what it means in that context's own terms, without leaning on a definition that lives three folders away. It's the same discipline as a module with a narrow public API. Constrain the edges and the middle gets clearer.
So then: what about the knowledge that genuinely is general? A caching pattern doesn't belong to anyone. That's what _shared/ is for — career material, house conventions, templates, tooling recipes, and a small zettelkasten of timeless concepts. It's the only bridge, and crossing it costs something on purpose. To promote a lesson into _shared/, you have to strip it of the specifics that tied it to one context. Which is exactly the work that turns "the sync job raced" into something reusable. The friction is the feature.
The line about what goes in
This is the rule I've rewritten the most, and the interesting part isn't the current wording — it's why the first version failed.
Version one was a flat prohibition: no specifics, ever. Generic patterns only.
It reads responsibly. It doesn't work, and the reason is worth understanding if you're writing rules for yourself or for an agent. A note stripped of every specific isn't a cautious note, it's an unusable one. "The upstream service in that domain behaved unexpectedly" is not knowledge, it's a riddle — I'd read it back six weeks later with no idea what it pointed at. And a rule whose output is worthless doesn't get followed carefully. It gets followed sloppily, or quietly abandoned, and then you have a rule nobody enforces plus the comfortable illusion that something is being enforced. That's strictly worse than no rule.
So I stopped writing prohibitions and wrote a rewrite instruction instead:
Keep the insight, drop the identifier.
The difference is the whole thing. A prohibition tells you not to write something and leaves you with nothing. A rewrite instruction tells you what to write instead — and the rewritten note is almost always the better note, because the general form outlives the instance. "That job failed on Tuesday for that account" is a support ticket. "Jobs in this shape fail when the upstream assumes an ordering it doesn't control" is knowledge, and it's what I'd actually want six months later.
That's why this version holds where the ban didn't. It isn't discipline against my own interest. Following it makes the vault sharper, so there's nothing to fight.
Then the hard boundaries — the categories where the answer is no regardless of how useful the note would be:
- Patient or customer PHI and PII. Names, dates of birth, contact details, records, or screen captures that display them. No exceptions and no "anonymised enough."
- Artifacts I didn't author. Decks, PDFs, specs, source. My own notes are mine to keep; someone else's file isn't mine to hold, however convenient it would be.
- Live credentials and infra identifiers. Tokens, connection strings, account IDs, internal hostnames. Note where a thing lives, never what it is.
- Security detail. That a class of issue exists, and which ticket tracks it. That's the entire note. Mechanics never go in a personal store.
- Third-party personal data. Other people's pay, health, hiring assessments, reviews. Mine are fine. Theirs aren't mine to keep.
The load-bearing design decision is that all of this applies at write time, not at review time. A knowledge store has no undo — anything committed stays in the history whether or not you delete the file later, so "I'll clean it up during triage" was never a real plan. The filter has to run before the note exists. Which is precisely why it's phrased as a rewrite instruction rather than a checklist: it's cheap enough to apply mid-sentence, and a check that's expensive to run is a check that doesn't get run.
The write rules that actually do the work
Structure is cheap to design and expensive to maintain. Three rules carry most of the weight.
Decisions get dated files
decisions/YYYY-MM-DD-slug.md. One decision, one file, date in the filename.
This is the highest-value convention in the vault and it's almost embarrassingly simple. The date in the filename means chronology survives without a database — I can see what I believed in March and what changed by July. Superseding a decision doesn't mean editing history, it means writing a new dated file that references the old one. The old belief stays visible, which matters, because "why did we stop doing it that way" is a question I ask far more often than "what do we do."
And it gives agents a target. When I say "we're going with the queue instead of polling," the response isn't a nod — it's a proposed filename. That's a much better contract than "I'll remember that."
00-inbox/ is a parking lot, not a default
This is the rule I got wrong for months, and it's the one I'd push hardest on anyone building the same thing.
The intuitive design is a capture inbox: everything lands there, you triage weekly, notes flow to their real homes. Every productivity system ever built works this way. Mine did too.
What actually happens is that the inbox becomes the system. Filing is deferred work, deferred work accumulates, and by Friday there are forty notes whose context I've lost. Triage stops being filing and becomes archaeology — reading my own note from Tuesday and trying to reconstruct which conversation produced it and whether it's still true. I did that sweep maybe three times before I quietly stopped, and then the inbox was just a place notes went to die. The system had a compost heap at its center.
So I inverted it. Durable knowledge gets filed straight to its compartment, at the moment it's produced. The agent proposes the exact destination path, I confirm, it writes there — correct folder, proper tags, committed and pushed. 00-inbox/ is now used only when I explicitly say "park this," meaning I've decided it needs thinking I don't want to do right now. That's a real category and it deserves a folder. It just isn't the default one.
The proof is the count. My inbox has three files in it. Under the old model it never had fewer than thirty.
There's a corollary I had to add later: agent error notes and tooling status don't go in the inbox either. They were flooding it with things I'd never chosen to park, which put me right back to ignoring the folder. They go to the agent's own outbox now. The inbox only ever holds things I decided to defer — which is the only way I'll keep trusting it enough to look.
File it as you produce it
Related to the above but broader, and it's aimed at the agent rather than the folder: don't stockpile.
The failure mode is a session that does good work for two hours and then offers, at the end, to write up what it learned. By then the write-up is a summary of a summary. The specific reason we rejected the second approach — the thing that would have been most valuable to future-me — got compressed out three steps back, because at the time it seemed like a detail.
Now the instruction is: when something durable is produced, propose the destination immediately, and file it on confirmation. Mid-session, while the reasoning is still in context. It interrupts flow a little. It's worth it, because notes written at the moment of the decision contain the why, and notes written at the end of a session contain the what. The what is recoverable from the code. The why never is.
Everything ends with a commit and a push, in the same breath as the write. Unpushed is not saved. I lost a set of local-only repos in a machine migration last year and I've been unpleasant about this ever since.
What it's bad at
The honest section, because I've read enough second-brain posts that end at the victory lap.
Compartmentalisation blocks real synthesis. This is the cost I actually feel, not a hypothetical one. Some of the most useful things I know are patterns I've now run into in several different places — the same architectural mistake, the same organisational failure, wearing different clothes each time. The vault structurally cannot show me that. Each instance sits in a sealed folder, and no agent will ever surface the third one and tell me it's the same shape as the first. _shared/ is the escape hatch, but it only works if I notice the pattern and promote it by hand. The noticing is exactly the part I wanted help with. I don't have a fix that doesn't compromise the isolation, so I pay it.
Confirmation-gating every write puts me back in the loop I was trying to leave. Agents propose a destination and wait for my yes. That's the right default — I'm not letting an agent write unsupervised into something I'm accountable for, and the write-time filter only works if a human runs it. But it means the vault grows only as fast as I approve things, and on a busy day I approve nothing. The memory system has a bottleneck, and the bottleneck is me.
Nothing ever gets deleted. Notes accumulate and none of them decay. There's no process that flags a decision from eight months ago that's been quietly false since March. Superseding is manual, so stale notes just sit there looking as authoritative as fresh ones, and an agent retrieving them can't tell the difference. This is the failure mode most likely to actually bite me — confidently wrong recall is worse than no recall, and I've been lucky rather than careful so far.
It only pays off if you already live in your notes. The vault works for me because Obsidian was already where I thought. If I'd built this as a dedicated agent-memory store, I'd have stopped opening it in a month and it'd now be a stale folder that lies to my agents. Adopt this pattern into a habit you have, not a habit you're planning to acquire.
What I'd change
If I rebuilt it tomorrow: add decay. Some notion of freshness on every note — last verified, confidence, a nudge when a decision file has gone six months untouched in an area that's obviously moved. Not automatic deletion. Just a signal, so retrieval can weight recent knowledge over confident old knowledge instead of treating both as equally true.
And I'd want a review loop that isn't me. Something that periodically reads a compartment and asks: what in here contradicts something else in here? Compartment isolation makes that tractable — the search space is one folder — and contradiction is a much easier thing to detect than obsolescence. I haven't built it. It's the next thing.
The actual payoff
The thing I didn't anticipate is that the vault changed how sessions start, not how they end.
I used to open a session and spend the first ten minutes rebuilding context out loud — here's the system, here's what we tried, here's why the obvious approach doesn't work here. Now the session opens against a compartment and that context is already on disk. The first message can be the actual question.
And the compounding is real, in the specific sense that the answer to "did we already discuss this?" is now a file path instead of a shrug. That question used to cost me twenty minutes of scrolling and usually ended in re-deriving. It costs a search now.
None of that came from Obsidian. Obsidian is a Markdown editor. It came from four rules — one folder per context and no links between them, keep the insight and drop the identifier, decisions get dated files, and file it the moment it's produced. The tool is interchangeable. The rules aren't.