Agent Memory Vault

A ready-to-use Obsidian vault template that gives your AI agents shared, persistent memory: Claude Code, Codex, Cursor, or any agent that can read a folder of markdown. Every agent you run reads from and writes back to the same vault, so your context survives across sessions and across agents.

What this is

Every new agent session starts from zero, and every agent keeps its own memory silo: what Claude Code learns about you, Codex never sees. This template fixes both problems. One folder of plain markdown becomes the shared brain that all your agents read rules from and write memory back to. Switching agents stops being a context-loss event.

What's inside

agent-memory-vault/
├── AGENTS.md                        ← the rules file every agent reads on session start
├── CLAUDE.md                        ← one-line pointer for Claude Code
├── 00-Rules/                        ← what agents must remember forever (human-gated)
│   ├── _index.md
│   ├── _principles/                 ← graduated cross-cutting principles
│   └── who-i-am.md
├── 01-Projects/                     ← one folder per project, no mixing
│   └── example-project/
│       ├── _memory/                 ← project truth (overview + decisions)
│       ├── _feedback/               ← project correction loop
│       └── doc-001-example.md
├── 02-Sources/                      ← web clips, papers, transcripts
├── 03-Maps/                         ← Canvas / Excalidraw visuals
├── 04-Feedback/
│   └── graduation-queue.md          ← the single human-gated promotion path
├── _templates/                      ← Templater templates (project note, deliverable, feedback)
├── docs/                            ← plugin setup guides (Web Clipper, Templater, Obsidian Git)
├── prompts/                         ← maintenance loops (weekly lint, feedback compaction) + nightly distill architecture
└── scripts/                         ← check-vault.sh (secret scan, link check)

The 5 folders

Folder	Role	Who writes
00-Rules/	What you want AI agents to remember forever: voice, bio, graduated principles	Human only. Agents propose via the graduation queue, never write directly
01-Projects/	One folder per project. Working docs + _memory/ (project truth) + _feedback/ (correction loop)	Agents write directly: drafts, memory, feedback. You review naturally
02-Sources/	Web articles, screenshots, transcripts, papers, anything clipped from outside	You (via Web Clipper) + agents when they find relevant research
03-Maps/	Visual files: Obsidian Canvas or Excalidraw	Agents, when a diagram clarifies real work. No decorative files
04-Feedback/	graduation-queue.md: cross-cutting rule candidates awaiting human review	Agents add "watching (new)" rows and bump counts. Only you approve

The same spine running in the author's live vault (plus a few folders added on top):

Quickstart

1. Get the files:
   • Hit "Use this template" on GitHub, create your own repo, and clone that. This is the primary path.
   • Not using git? Download the ZIP from GitHub and unzip it.
   • Plain git clone of this repo also works, with one caveat: cloning keeps this repo's git history and origin remote, so run rm -rf .git before following the Obsidian Git guide.
2. Rename the folder to whatever you want your vault called, then open it in Obsidian (obsidian.md, free): "Open folder as vault."
3. Edit the bracketed placeholders in AGENTS.md and 00-Rules/who-i-am.md. Rename 01-Projects/example-project/ to your first real project, and delete the sample row in 04-Feedback/graduation-queue.md.
4. Validate any time (and always before a git push): run bash scripts/check-vault.sh. It scans for secret patterns, broken relative links, duplicate filenames, and unquoted placeholder dates.

Done. Open Claude Code (or any agent) in your vault directory and start working.

Read order (what every agent does on session start)

1. AGENTS.md (or CLAUDE.md, whichever the agent reads).
2. 00-Rules/: every file, including graduated principles in _principles/.
3. The active project's feedback: _feedback/compacted.md first, then raw feedback files from the last 7 days. Never other projects' feedback; lane separation matters.
4. The active project's _memory/: current decisions, facts, playbooks.
5. 02-Sources/: only when a specific reference is needed.

Don't read everything. Read what's relevant.

Using the vault from a coding project

The vault does not have to be your working directory. A Claude Code session running in ~/projects/my-app connects with one pointer line added to that project's CLAUDE.md:

Also read ~/vault/AGENTS.md. That is the shared memory vault: follow its rules, and write project feedback and memory there.

The agent then reads the vault rules on session start and writes feedback and memory back into the vault, all while working in the code repo.

The graduation rule, short version

Project-specific rules get written directly to that project's _memory/<project>-decisions.md, with no human gate. Wrong writes there are cheap to edit, but not harmless: a false fact sitting in a project overview gets treated as truth by every later session, so correct wrong memory the moment it's spotted. Cross-cutting candidates (evidence in 2+ distinct projects) go into 04-Feedback/graduation-queue.md as "watching (new)" rows, and only a human flipping the row to "approved" lets a rule graduate into 00-Rules/_principles/. Agents never write directly to _principles/: the queue is the gate.

A note on maintenance maturity

You do not need every tool in this pack on day one. The right ramp:

• Day 1: folder structure + AGENTS.md.
• Week 1: start writing project feedback files when agents make mistakes.
• After ~10 feedback files in a project: turn on the two manual loops. They are different jobs:
  • Weekly lint (prompts/weekly-lint.md): vault hygiene questions asked across the whole vault (stale rules, conflicting decisions, missing connections).
  • Feedback compaction (prompts/compact-feedback.md): per project, once that project has ~10 raw feedback files, squash them into its compacted.md.
• Multiple active projects + many sessions per week: nightly distill (prompts/nightly-distill.md), the optional pro pattern. It ships as a reference architecture you build yourself, not as working code.
• Promotion of any global rule (into 00-Rules/_principles/) always goes through the graduation queue, no matter how mature you are.

Most readers will live happily at "folders + AGENTS.md + occasional feedback file" for months. That is fine. Pro tooling exists for when the volume justifies it.

What a vault looks like after months of humans and agents writing into the same graph:

FAQ

"I have 0 markdown files. Where do I start?" Start with 1 file: 00-Rules/who-i-am.md. Write 5-10 sentences about you, your projects, what you're building, your voice. That one file removes the biggest source of generic output: the agent not knowing who it's working for. Everything else can wait.

"Not technical. Can I do this without a CLI agent?" Partly. Paste your AGENTS.md content as the first message in any chat-based AI (ChatGPT, Claude.ai, Gemini, whatever) and you get the rules half: your voice, context, and constraints travel with you. You don't get the read/write memory loop, because a chat window can't open your project files or write feedback back into the vault. For the full effect you need an agent that can read and write files.

"What if my projects don't fit the 5-folder structure?" The 5 folders are a template, not a law. The categories matter, the names don't: rules / project work (with per-project _memory/ and _feedback/) / stuff saved from outside / visual material / the graduation queue. Stay consistent within whatever names you pick.

"How is this different from Notion + Notion AI?" Local files (plain markdown you own), multi-agent (works with every agent, including whatever ships next year), and you can see what the AI remembers: vault files are plain text you can open and edit.

"How is this different from a long CLAUDE.md, or memory tools like mem0 / Letta / an MCP memory server?" A single CLAUDE.md doesn't scale past one project: everything piles into one file, and there is no correction loop turning your rejections into durable rules. DB-backed memory systems have the opposite problem: they are agent-specific and opaque. The memory sits in a database you can't open in an editor, so you can't see or fix what the AI believes about you. This vault is plain markdown, portable across agents, and the graduation queue keeps a human in control of what becomes a permanent rule. Agent-specific memory systems lock you in. The vault belongs to you.

"Won't AI agents pollute my vault with junk?" The structure defends itself in three ways: explicit write rules in AGENTS.md (the 00-Rules/ and graduation-queue gates do most of the work), reviewing every write, and the maintenance loops (weekly lint, feedback compaction, and the nightly distill architecture if you build it). Stay disciplined for the first 30 days. After that, the structure is self-enforcing.

"What about privacy / sensitive notes?" Don't put secrets in the vault. API keys, passwords, and real client data go in a password manager or .env file, never here. Keep sensitive personal notes in a separate vault with no AI access.

"How do I know if my vault is working?" You stop re-explaining yourself, agents stop repeating the same mistakes, and you delete fewer agent outputs. If you're 4 weeks in and none of these are happening, your AGENTS.md is underspecified. Audit it, add rules, make the read order louder.

"Will this still work in 2 years when there are 10 new agents?" Yes, that's the point. Markdown doesn't go obsolete. New agent comes out → change the entry point file → point it at the same vault → your knowledge migrates instantly. This is the case AGAINST agent-specific memory systems. They lock you in. The vault belongs to you.

Credit

Core idea (LLM + markdown wiki instead of fancy RAG) comes from Andrej Karpathy's April 2026 gist "llm-wiki: A pattern for building personal knowledge bases using LLMs."

→ https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

Nightly distill architecture: the 3-stage Distiller → Cartographer → Evictor pattern is adapted from PEEK (Gu, Zhang, Khattab, Madden; MIT/Stanford; arXiv 2605.19932, May 2026). PEEK introduced the separation-of-stages principle that prevents single-prompt approaches from collapsing memory updates into noise.

→ https://arxiv.org/abs/2605.19932

This pack assembles both into a practical setup for solopreneurs running multiple AI agents in parallel, plus original additions:

• Project-scoped _feedback/ folder (agent self-correction loop)
• The graduation queue (single human-gated promotion path into global rules)
• Multi-agent workflow (Claude Code + Codex + others sharing one vault)
• Nightly distill reference architecture (vault routing, privacy gate, distill prompts) built on top of PEEK's architectural pattern; you build the wrapper yourself
• The 5-bucket spine (00-Rules / 01-Projects / 02-Sources / 03-Maps / 04-Feedback) tuned for solopreneurs juggling multiple projects and agents, not single-purpose research workflows

License

MIT. See LICENSE.