memory-hygiene

Memory Hygiene v3.5 — Audit & Cleanup

This skill audits Claude Code's persistent knowledge stores (axioms, MEMORY.md — both auto-memory and in-repo, memory topic files, lessons, phase templates, ADRs, and the project docs/ taxonomy) for structural problems that degrade future session quality. It produces a structured report, gets user approval, then executes fixes.

v3.5 adds mechanism-claim integrity (§1k). §1i catches a fabricated label; §1k catches a fabricated cause. On 2026-08-07 a memory recorded a PR that deleted 5,081 lines of four sessions' merged work and blamed "a branch cut before those merges and never rebased" — measured afterwards, the branch's parent WAS the newest commit on main and a rebase would have been a no-op. The memory was internally coherent, well written, about a real incident, and routed every reader to a check that PASSES. §1k flags incident memories that assert a cause with no way to re-derive it, catches the mechanism restated in description: and the MEMORY.md line (what recall matches on), and reports groups of memories about the same incident whose causes conflict.

v3.4 fixes the cross-plugin script lookup in §1i. The label_audit.py call reached for ~/.claude/skills/session-handoff/scripts/ only. On a plugin install that path does not exist — the script lives under ~/.claude/plugins/cache/<marketplace>/session-handoff/<version>/scripts/ — so the sub-check resolved to nothing, logged "not installed", and the audit still reported clean. §1i now resolves the script across all three install roots and reports a miss as a skipped check.

v3.3 adds label-table integrity audit (§1i) and project docs/ taxonomy audit (§1j). The 7-bucket taxonomy that session-handoff dispatches to is now defined here as source-of-truth — previously session-handoff referenced "memory-hygiene v3.1" for this but the definition lived nowhere. §1i catches fabricated code→label tables in lessons.md / feedback_*.md / reference_*.md that bypass the author-side gate session-handoff runs in its Phase 0.

v3.2 adds in-repo MEMORY.md detection (§1a2) — the A/B counterfactual harness (n=3, 2026-04-21) showed that in-repo MEMORY.md files (e.g., project-root MEMORY.md or docs/MEMORY.md) survive a CLAUDE_CONFIG_DIR clean env and drive measurable success on tasks that the ~/.claude/projects/*/memory/MEMORY.md auto-memory file cannot. v3.1's §1a scanned only the auto-memory MEMORY.md, making the in-repo counterpart invisible to memory hygiene. v3.2 scans both and reports them as separate tiers in the audit output (T1 auto-memory and T1-repo).

v3.1 added feedback lifecycle detection (§1c2) — classifying each feedback_*.md file as Incorporated / Pending / Dormant / Superseded based on whether its rule has been promoted to axioms/lessons/templates — and emits a feedback_incorporation_rate metric for downstream consumers like ecosystem-audit.

v3.0 added phase template management, three-category axiom classification (Universal/Role/Phase), capacity ceiling enforcement, agency-aware staleness detection, and path-scoped rule auditing. Backed by research from cognitive science (Cowan 2001), LLM research (Liu et al. 2024 TACL, EMNLP 2025, Chroma Context Rot 2025), KM theory (Markus 2001), and SRE practice (Google SRE post-mortem framework). Full sources in ~/Documents/memory_hygiene_guide.md.