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:
[[wikilinks]]
die — nobody notices for weeks.git rm
over half of MEMORY.md
, the commit goes through, and the knowledge is gone. This is not hypothetical — it is A folder structure that can't detect any of this isn't a memory system. It's a landfill with good intentions.
So the vault ships with two small Python tools. No pip install, no Node, no plugins — if you have Python 3, you're done.
memory_check.py
— the honest report
python3 tools/memory_check.py
It scores the vault's health out of 100 across four dimensions:
MEMORY.md
, missing daily notes for active days[[wikilink]]
gets resolved against actual filenames00_Inbox
MEMORY.md
growing without consolidationThe 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.
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.
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
and now, with these two tools, it's checkable — which plain text normally isn't.
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.