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:

When to use

• A memory store exists (a MEMORY.md + .md notes, or a .mneme file) 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 seen date.

What it fixes (v0.1 — deterministic & reversible only)

• Index reconciliation (auto-memory): add missing MEMORY.md entries, drop dangling ones,

preserving your hand-written hooks. A full-directory snapshot is taken first; undo reverts.

• 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// 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.