Last week I published Verified Memory Vault — a free Obsidian vault that gives Claude Code, Codex or Gemini CLI persistent memory through a plain CLAUDE.md boot file and an append-only MEMORY.md. It works. But after running it for a few weeks, something became obvious:
Memory systems don't fail loudly. They rot silently.
Nobody deletes your agent's brain in one dramatic afternoon. Instead:
- A note gets renamed and three
[[wikilinks]]die — nobody notices for weeks. - Someone (you, or the agent during a "cleanup") rewrites a memory line without its date. That line is now unauditable: you can no longer tell what the agent knew when it made that decision last Tuesday.
- The inbox folder grows to 40 unsorted files because capturing is easy and sorting is work. The agent reads the junk into its context every session.
- And then there is the dramatic version anyway: an over-eager cleanup command runs
git rmover half ofMEMORY.md, the commit goes through, and the knowledge is gone. This is not hypothetical — it is the documented way agent setups die.
A folder structure that can't detect any of this isn't a memory system. It's a landfill with good intentions.
Two scripts, zero dependencies
So the vault ships with two small Python tools. No pip install, no Node, no plugins — if you have Python 3, you're done.
1. memory_check.py — the honest report
python3 tools/memory_check.py
It scores the vault's health out of 100 across four dimensions:
-
Protocol violations — undated lines in
MEMORY.md, missing daily notes for active days -
Dead links — every
[[wikilink]]gets resolved against actual filenames -
Inbox pressure — how much uncaptured junk has piled up in
00_Inbox -
Bloat —
MEMORY.mdgrowing without consolidation
The output is a score, a list of concrete problems with file names, and an exit code (0 healthy, 1 degraded). That exit code matters more than it sounds: you can wire the check into CI, a cron job, or the end of your agent's session loop, so the system audits itself instead of relying on you remembering to care.
Here's what a degraded run looks like:
memory_check: 80/100 (DEGRADED)
[links] DEAD: [[weekly-review]] -> no such note (referenced in 01_Daily/2026-08-21.md)
[protocol] MEMORY.md line 14: entry without date prefix
exit code: 1
Eighty points sounds fine until you realize each deduction is a fact your agent will misremember or miss.
2. memory_guard.py — the seatbelt
If you keep the vault in git (you should), this becomes a pre-commit hook:
ln -s ../../tools/memory_guard.py .git/hooks/pre-commit
From then on, any commit that deletes a large share of MEMORY.md gets refused:
memory_guard: REFUSED
MEMORY.md: 31 of 44 lines deleted (70%)
Mass deletion of the memory file looks like an accident.
If it really is intentional, split it into smaller commits
with an explicit reason in the message.
The guard doesn't make deletion impossible — it makes it deliberate. Legitimate restructuring still works; you just can't lose six weeks of agent memory to one fat-fingered command anymore.
Why not just use a vector database?
You can, and for some workloads you should. But most agents' persistent memory needs are smaller than the industry pretends: dozens of durable facts, not millions. Plain Markdown wins at that scale because
- it's auditable — the agent's memory is readable in ten minutes by a human,
- it's diffable — every change to what your agent "believes" is in git history,
- it's portable — no lock-in, no export problem, works with Claude Code, Codex, Gemini CLI or anything else that reads a boot file,
and now, with these two tools, it's checkable — which plain text normally isn't.
Get it
The vault is free, licensed CC BY 4.0 (use it commercially, attribution only), and sets up in about ten minutes: download, open as an Obsidian vault, point your agent at CLAUDE.md.
Download Verified Memory Vault v0.9 (ZIP)
Source and updates: github.com/secondbrainstarter/verified-memory-vault
If you want a starter system for your own notes rather than your agent's, the companion project Second Brain Starter uses the same philosophy — three folders, no plugin zoo, working in ten minutes.
Question, feedback or an idea? Write to geld.hamster@gmx.net — every mail is read.
