Building a shared second brain that Claude reads and writes

Six months ago I got tired of introducing myself to my own AI assistant. Every session started the same way: re-explain the architecture, re-list the repos, re-state the decisions I'd already made and the mistakes I'd already learned from. The model was brilliant and amnesiac, and I was its full-time memory. So I built it a memory it could read and write — a plain folder of markdown files that both of us edit. Not a vector database, not a SaaS "memory layer." Files. Here's what I've learned about making that work when a human and a fleet of agents are all writing to the same brain, because the writing part is where it gets interesting.

Why files, and why both of us write to them

Start with the constraint that makes this hard: the assistant's context resets every session, and mine doesn't. If the memory only I can edit, it's documentation, and documentation rots because updating it is a separate chore. If it's a memory only the assistant can edit, I can't correct it when it's wrong, and I can't read it when I'm the one who needs the reminder. A shared brain has to be first-class for both of us or it decays.

Plain markdown files win here for an unglamorous reason: everything already speaks them. I can grep them, diff them, edit them in any editor, and put them under version control. The assistant can read them, append to them, and link them together with no special tooling. The format is boring, and boring is exactly what you want for something that has to survive years and a dozen tool changes.

The two hooks that kill cold-start

A pile of notes isn't a memory until the right ones show up at the right time. Two mechanisms do that work, and you can build both.

The first is a small index note that loads at the start of every session — the map of what's stored where. One line per major note: a title, a link, and a one-sentence hook. The assistant reads that first and knows the shape of everything it could pull, without pulling all of it. That single file is the difference between "cold model" and "model that knows which drawer to open."

The second is a retrieval step that fires on each message and surfaces the handful of notes relevant to what I just asked. Ask about scheduling and the scheduling gotchas appear; ask about a client's data and the governance decisions appear. The assistant consults them before it asks me a question I've already answered in writing. The rule I enforce: if the answer might already be in the brain, check the brain before asking the human. That one rule reclaimed more of my time than any prompt-engineering trick.

One fact per file, and a little frontmatter

Keep the atoms small. Each memory is one fact or one tightly-scoped note, not a sprawling document, because small notes are easier to retrieve, dedupe, and retire. Give each one a scrap of frontmatter — a name, a one-line description that's used to judge relevance during recall, and a type so you can tell a durable fact from a personal preference from a pointer to an external resource. That description field earns its keep: it's what a retrieval step reads to decide whether this note matters right now, so write it like a hook, not a title.

Then link generously. When one note references another, wire them together with [[wikilinks]]. Over a few months the brain stops being a list and becomes a graph — and the assistant can walk from a decision to the gotcha that caused it to the best practice that came out of it.

The part nobody warns you about: coexistence

Here's the failure mode I hit early, and it's the whole reason this post exists. When more than one writer touches the same brain — you, plus an assistant, plus the background agents you'll inevitably add — the naive "let the AI update the notes" approach turns into the AI quietly rewriting your notes. I watched an agent "tidy up" a section I'd hand-written and lose a nuance I cared about. It wasn't malicious. It was just doing what I'd have done to my own draft. That's the problem: an agent editing shared memory like it's its own scratchpad will step on the humans.

The fix is a short contract that every writer — human or agent — follows:

• Append, don't rewrite. Add to the bottom of the relevant section. Never delete the human's text without being told to.
• Date and attribute. Prefix entries with the date, and tag agent-written lines so authorship is never ambiguous. When something's wrong later, you can see who wrote it and when.
• Search before you create. Look for an existing note on the topic and update that, rather than spawning a near-duplicate. Duplication is how a brain becomes a junk drawer.
• Secrets by reference only. Never write a token or password into the brain — write where it lives ("in the password manager," "env var X"). The brain is readable by a lot of eyes and processes; treat it that way.

None of these are clever. All of them are load-bearing. The contract is what lets my hand-written notes and a machine's appended memories sit in the same file without either corrupting the other.

Trust the brain, but verify before you act on it

One more discipline, and it's a governance one. A recalled memory reflects what was true when it was written, not necessarily now. If a note tells the assistant "the flag is called X" or "that logic lives in file Y," the right move is to confirm X and Y still exist before acting on them — the brain is a strong prior, not a live source of truth. I treat recalled notes as background context the assistant considers, never as instructions it obeys. That distinction matters more as you add agents: a memory store that agents blindly execute is a prompt-injection surface waiting to happen. A memory store they consult and verify is just a very good set of notes.

What it actually buys you

The obvious win is that I stopped re-priming every session — the cold-start tax is gone, and that alone paid for the build. The bigger win snuck up on me: the brain compounds. Every gotcha I hit once is caught the next time. Every decision I make is there to contradict me when I drift from it three weeks later. The assistant got measurably more useful not because the model got smarter, but because it stopped operating on a blank slate every morning.

If you're leaning on an AI assistant for real work, this is the highest-leverage thing you can build around it — and you can start with a single folder and one index file today. Write down the decisions, the gotchas, and the "how does this actually work" facts as you go, and give the assistant permission to do the same under a contract that protects your own notes. If you've built something like this and solved the multi-writer problem differently, I'd genuinely love to compare notes. As always, I'm here to help!