Claude Code forgets everything between sessions, and every fix people reach for — bigger context windows, RAG pipelines, vector databases — solves the wrong problem. After running agent projects that span weeks and dozens of sessions, I've landed on an unfashionable conclusion: persistent memory for a coding agent is a plain-markdown-files problem, and it was solved by the humblest tool on your machine. Obsidian works as Claude Code's long-term memory not because it's clever, but because it's a folder of .md files with links — the one format the agent reads natively, you can audit at a glance, and nothing can lock you out of.
But before the vault setup, I want to show you the memory system I actually run in production, because it taught me what agent memory needs to be — and most Obsidian-for-AI guides get that part wrong.
What a working agent memory actually looks like
My main project carries a memory directory that Claude Code maintains across every session. It has exactly two layers:
An index file — MEMORY.md, currently around 8 KB — where every project workstream gets one line: what it was, its status, and a link to a deeper file. Lines like "sitemap audit — all 8 sitemaps verified complete, 62 duplicate-tag groups merged" or "prompt library — all 854 prompts fully built." One line each. Twenty-two workstreams.
Topic files — one markdown file per workstream, holding the detail: the gotchas, the credentials location, the exact commands that worked, the failure that cost an afternoon. The index points; the topic file explains.
That two-layer shape is the entire trick, and it's the same principle Anthropic pushes as progressive disclosure: the agent loads the cheap index always, and pulls the expensive detail only when the task needs it. A session that starts on SEO work reads one line about the translation pipeline and moves on. A session that starts on translations opens that file and instantly knows things I'd otherwise re-explain for ten minutes — which locale keys exist, which script does the work, which step silently fails.
Here's the measure of whether this works: I've had Claude Code open a fresh session on a project untouched for weeks and correctly warn me about a caching gotcha it learned three sessions earlier — because a past session wrote it down where future sessions look. That's the whole game. Not smarter models. Better files.
The second kind of memory nobody writes about: state manifests
Notes are memory for facts. Multi-session projects need memory for state — and this is the part I never see in Obsidian tutorials.
Last month I ran a project rewriting 84 blog posts with agent workers, spread across seven batches and many sessions over several weeks. The thing that made it survivable was a single JSON manifest on disk — a status file marking every post DONE or PENDING, updated as work completed. Any session, any crash, any week-long pause: the next session read the manifest and knew exactly where the job stood. No session ever re-did finished work or lost track of remaining work, because the truth lived in a file, not in anyone's context window.
The distinction matters because the two memory types have different rules. Fact memory (notes, decisions, gotchas) should be prose — human-readable, linkable, editable. State memory (what's done, what's pending, what was touched) should be machine-checkable — JSON or checklists that a script can verify, because an agent's prose recollection of "I think I finished those" is exactly the thing you must never trust. When the same principle shows up in agent handoffs between sessions, it's worth doing deliberately — the handoff pattern for multi-session Claude Code work formalizes it.
An Obsidian vault handles the first type beautifully. Pair it with plain manifest files for the second and you have the full memory stack.
Where Obsidian earns its place
You could run the index-plus-topics pattern in bare folders — I effectively do on some projects. What the vault adds:
Links become structure. Obsidian's [[double bracket]] links turn a pile of notes into a graph, and that graph is parseable by Claude Code as plain text. When your "JWT strategy" note links to your "rate limiting" note which links to a production incident note, the agent can walk that chain the same way you would — instead of pattern-matching across disconnected files.
Everything stays yours. The vault is a normal directory of markdown. No proprietary format, no sync dependency, no API between your agent and its memory. If Obsidian vanished tomorrow, your memory system wouldn't notice. Compare that with vector-database memory, where your agent's knowledge is embeddings you can neither read nor correct.
You can audit memory by reading it. This one is underrated. Agent memory goes stale — decisions get reversed, gotchas get fixed — and stale memory is worse than no memory, because the agent trusts it. A vault you skim weekly gets corrected. An embedding store never does.
The setup that survives contact with real work
Keep it small. My structure, which consolidated down from something more elaborate:
vault/
├── daily/ # what happened, decisions made, open questions
├── projects/ # one folder per project, index.md each
├── decisions/ # one file per decision that will matter in 6 months
├── research/ # findings that outlive the session that found them
├── templates/ # note skeletons
└── CLAUDE.md # the conventions file — see below
The CLAUDE.md in the vault root is what turns Claude Code from a visitor into a maintainer. Mine describes conventions, not procedures:
# Vault Conventions
- Every note: YAML frontmatter, at least one tag, H2/H3 headings only
- Daily notes: /daily/YYYY-MM-DD.md — "Worked on / Decisions / Open questions"
- Projects: /projects/<name>/index.md holds status + key decisions
- Decisions: /decisions/YYYY-MM-DD-topic.md — context, options, choice, consequences
- Before creating a note, check whether one already exists
- Links are bidirectional: if A links B, B links back
- The index stays one line per item. Detail goes in the linked file.
Twenty lines, not two hundred. I learned that threshold the hard way in a different file: my instruction files accumulated rules for months until they contradicted each other — I eventually found the same rule stated nine different ways in one agent definition, two versions of it irreconcilable. The full autopsy is in what auditing my own prompts for Opus 5 turned up, and the lesson transfers directly to memory files: every rule you add is a rule that can drift, so add rules only when the agent actually gets something wrong.
Then the loop that makes it compound: end sessions by having Claude update the relevant notes — one command, thirty seconds — and start sessions by pointing it at the index. Research tasks get a standing instruction to write findings into research/ instead of dumping them into chat where they die with the session.
What this costs, honestly
The maintenance is real: a few minutes per working day, and a weekly skim to kill stale entries. Skip it for two weeks and the vault quietly rots — I've done it, and re-trusting a rotten vault takes longer than maintaining a live one.
The other honest caveat: memory files ride in your context budget. An index that stays index-sized costs almost nothing; a vault where "index" files bloated into essays taxes every single message. If your sessions feel shorter after adding memory, measure before blaming the model — my token management breakdown covers how to see exactly what your memory layer costs per turn.
And if you're deciding between this and heavier machinery: vector-RAG memory earns its complexity at team scale or across truly huge corpora — for a solo developer or small team, markdown files get you most of the value at a fraction of the moving parts. Andrej Karpathy's take on markdown-first knowledge bases pushed my thinking here; I unpacked it in the Obsidian RAG knowledge-base breakdown, and if you want the wider taxonomy of options, I ranked all of them in six levels of Claude Code memory systems.
Start with one file tonight
Don't build the whole system this week. Create the vault, write a ten-line conventions file, and have Claude Code write today's daily note. Then work normally for two weeks and let the structure grow only where re-explaining something annoys you — that annoyance is the requirements document.
The compounding is the point. Every session that writes one honest note makes every future session start further ahead. Six months in, opening Claude Code on a project stops feeling like briefing a new hire and starts feeling like resuming a conversation with a colleague who kept minutes.
Building durable AI workflows — memory systems, multi-session pipelines, agents that pick up where they left off — is exactly what I teach in my structured courses. If you'd rather follow a guided path than assemble this from blog posts, browse the AI School catalog and start with the workflow course that matches where you are.
