memory-doctor
Keep an LLM agent's long-term memory healthy — the cure for context rot. Use when a memory store exists and the user wants to check or tidy it ("记忆体检", "整理记忆", "memory health", "memory cleanup", "dedup memory", "fix MEMORY.md index"), or whenever memory has grown long, contradictory, or its index drifted. Runs a read-only health report and safe, reversible repairs. Supports the Claude Code auto-memory format (frontmatter + [[links]] + MEMORY.md) and the mneme format (.mneme cells). Zero dependencies, zero LLM in v0.1.
memory-doctor — keep agent memory healthy
Memory skills write memory; almost none maintain it. Over time a store grows long, contradicts itself, sprouts dead links, and its index drifts — the agent then burns tokens parsing stale history instead of acting. That is context rot. This skill governs an existing store; it does not produce memory.
Producers write, memory-doctor keeps it alive. Complements memory skills, doesn't replace them. Source & issues: https://github.com/casperkwok/memory-doctor
When to use
- A memory store exists (a
MEMORY.md+*.mdnotes, or a*.mnemefile) and the user wants to check or clean it: "记忆体检 / 整理记忆 / memory health / cleanup / dedup / fix the index". - Memory has clearly grown long, repetitive, or the index no longer matches the files.
How to run (zero deps, Python ≥ 3.9)
# read-only — safe anytime; print the health card first
python scripts/curate.py report --dir <memory-dir>
# auto-memory only: preview then apply the index reconciliation (snapshots first)
python scripts/curate.py lint --dir <memory-dir>
python scripts/curate.py lint --dir <memory-dir> --fix
# revert the last write
python scripts/curate.py undo --dir <memory-dir>
The format is auto-detected (*.mneme present → mneme, else auto-memory); override with
--format auto-memory|mneme.
What the report checks
- dead links, stale notes, oversized files, lexical duplicate candidates, and a freshness score (per-type exponential decay).
- auto-memory: index drift (MEMORY.md vs files) and orphans (no inbound link, unindexed).
- mneme: history cells (superseded/retired/proposed) excluded from active health, and
supersede back-link symmetry; freshness uses each cell's
seendate.
What it fixes (v0.1 — deterministic & reversible only)
- Index reconciliation (auto-memory): add missing
MEMORY.mdentries, drop dangling ones, preserving your hand-written hooks. A full-directory snapshot is taken first;undoreverts. - mneme's spine is derived, so there is no index to reconcile — use
report.
Semantic fixes that need a model — true duplicate merge, contradiction reconcile, oversized compaction — are flagged in v0.1 and resolved in v0.2 (no embeddings; manual-apply, snapshot-backed). Never auto-edit memory content on the user's behalf without confirmation.
Safety
Every write snapshots the whole directory to .memory-doctor/snapshots/<ts>/ and logs to
.memory-doctor/changelog.md; undo restores it. v0.1 only ever rewrites the index file.
Optional: a read-only health nudge
hooks/health_nudge.py (in the repo) can be wired to a Claude Code SessionStart hook to print
a one-line nudge when health drops. It is read-only and never edits anything. Opt-in.
Related skills
- Downloads
- 779All time
- Security audit
- Review
- Last updated
- 5mo ago
- Current version
- v0.1.2
- License
- MIT-0
