memory-hygiene

Audit and optimize Claude Code's persistent memory system — axioms, phase templates, MEMORY.md, lessons, memory files, and ADRs — using a research-backed tiered architecture with promotion/demotion lifecycle and agency-aware staleness detection. v3.4 fixes the cross-plugin lookup of session-handoff's label_audit.py, which silently found nothing on a plugin install. v3.3 added a label-table integrity audit and a peer workflow for auditing a project's docs/ directory against a canonical 7-bucket taxonomy.

The Problem

Claude Code's memory system has two failure modes that compound over time:

1. Truncation: MEMORY.md exceeding ~200 lines is silently truncated — context lost without warning.
2. Lost in the Middle: Even within the context window, LLMs show >30% accuracy degradation for information in the middle of long contexts (Liu et al. 2023). A critical lesson at line 617 of a 1400-line file is effectively invisible.

This means bulk-loading large files into context is counterproductive — it wastes tokens AND buries the important rules. The solution is a tiered architecture:

T0:   Axioms    (≤12 items, always loaded)     — Universal + Role behavioral overrides
T0:   CLAUDE.md (~70 lines, always loaded)     — workflow rules, retrieval strategy
T1:   MEMORY.md (~40-80 lines, always loaded)  — index pointers
T1.5: .claude/rules/ (auto on file match)      — phase-specific rules with paths: globs
T2:   Topic files (~50 lines each, on demand)  — per-topic context
T3:   Archives  (unlimited, grep only)         — lessons, handoffs, sessions

v3.0 adds phase templates (~/.claude/templates/phase_*.md) — reusable rule sets that auto-activate when you touch matching files. Rules that are only relevant during specific project phases (data sourcing, deliverables, code review) don't waste attention in every session — they load precisely when needed.

Without regular maintenance, the system also accumulates: duplicate lesson numbers, orphaned memory files, stale references to renamed code, ADR numbering conflicts, and lessons that should be promoted to axioms but remain buried in archives.

Quick Start

You: my lessons file is 1400 lines and critical rules keep getting ignored

Claude: [Reads axioms.md, CLAUDE.md, MEMORY.md, lessons, topic files, ADRs]
        [Checks tiered loading, axioms health, staleness, duplicates]
        [Produces structured audit report grouped by severity]

        ## Memory Hygiene Audit

        ### Critical
        - axioms.md missing — no behavioral overrides loaded at session start
        - CLAUDE.md says "read lessons.md" (bulk-load anti-pattern)

        ### Axioms
        - 6 lessons in T3 qualify for axioms promotion (override default behavior)
        - CLAUDE.md retrieval strategy: needs update (grep, not bulk-read)

        ### Tiering
        - 3 items at wrong tier (lesson #68 at line 617 → promote to T0)
        - lessons.md: 1,406 lines (archive only, never bulk-read)

        ### Staleness
        - 2 memory files reference functions that no longer exist

        ### Duplicates
        - Global lessons: 5 number collisions

        ### Recommendations
        - Create axioms.md with 15-20 behavioral overrides from lessons.md
        - Update CLAUDE.md checklist: load axioms.md, grep lessons.md
        - Merge 5 lesson pairs, suffix 5 number collisions

        Want me to proceed with all fixes?

You: yes, go ahead

Claude: [Creates axioms.md, updates CLAUDE.md, fixes duplicates, verifies]
        Done. axioms.md: 52 lines (18 behavioral overrides). CLAUDE.md: updated
        to grep-not-read strategy. No duplicate lesson numbers remain.

Installation

Claude Code:

# Plugin install (recommended)
/plugin marketplace add wan-huiyan/memory-hygiene
/plugin install memory-hygiene@wan-huiyan-memory-hygiene

# Git clone (always works)
git clone https://github.com/wan-huiyan/memory-hygiene.git ~/.claude/skills/memory-hygiene

Cursor (2.4+):

# Per-project rule (most reliable)
mkdir -p .cursor/rules
# Copy SKILL.md content into .cursor/rules/memory-hygiene.mdc with alwaysApply: true

# Manual global install
git clone https://github.com/wan-huiyan/memory-hygiene.git ~/.cursor/skills/memory-hygiene

Also available bundled: memory-hygiene is included in the claude-ecosystem-hygiene marketplace alongside ecosystem-audit (full-coverage ecosystem audit) and skill-trigger-eval-subprocess-blindness (skill-creator diagnostic). This repo remains the canonical source — installing from either location gives you the same skill.

What You Get

• Axiom management — classifies each axiom as Universal/Role/Phase, enforces 12-item Cowan cap, flags demotion and merge candidates
• Phase template system — audits ~/.claude/templates/ and .claude/rules/, creates missing templates, migrates Phase axioms to path-scoped rules
• Promotion/demotion lifecycle — two-incident rule for promotion (Google SRE), three demotion triggers (dormant/caught by tooling/subsumable)
• Agency-aware staleness — detects user work pattern from user_role.md; measures staleness across project portfolio (not just current project) for consultants/agency workers
• CLAUDE.md retrieval strategy audit — flags "read lessons.md" as an anti-pattern, recommends grep-based retrieval
• Tiered loading audit — checks content lives at the right tier (T0/T1/T1.5/T2/T3)
• Structured audit report grouped by severity (critical / axioms / phase templates / tiering / staleness / duplicates / ADR best practices)
• MEMORY.md slimming — extracts inline content to topic files, rewrites as a ~40-80 line index
• Staleness detection — finds broken references, relative dates, codebase contradictions, conflicting lessons
• Session compression — flags old verbose session files for compression, suggests archive splits
• Lesson deduplication — finds number collisions within and across files, merges overlapping content
• ADR best practices — numbering, bidirectional links, Confirmation sections, index file, gap stubs
• Cross-project scope review — suggests promoting frequently-reused project lessons to global (with user approval)
• Writing quality gate — three-question check before creating new memory files
• docs/ taxonomy audit (v3.3) — classifies every file in a project's docs/ against a 7-bucket canonical taxonomy (decisions, runbooks, analysis, references, reviews, handoffs, deliverables); detects loose files, duplicate folders (handoff/ + handoffs/), stale candidates, and non-doc artifacts. Produces a human-reviewable audit report. Never auto-moves — --migrate pass generates a feature branch with git mv commands plus link-rewrite for PR review.

How It Works

What It Audits

The Tiered Architecture

Axiom Classification (three categories)

Promotion/Demotion Lifecycle

lessons.md (T3, grep only)
    ↓ Fires in 2+ sessions without being queried (two-incident rule)
axioms.md (T0, ≤12 items)  ←── Promotion criteria: default wrong + silent failure + recent
    ↓ Dormant 20+ sessions OR caught by tooling OR subsumable
    ├── DEMOTE → back to lessons.md (T3)
    └── PHASE  → ~/.claude/templates/phase_*.md → .claude/rules/ (T1.5)

Capacity enforcement: Hard cap of 12 items (Cowan 2001: 3-4 chunks × 3 items/chunk). Every new promotion past 12 requires a demotion or merge.

Agency-aware staleness: For consultants/agency workers who cycle through projects, staleness is measured across the user's portfolio (calendar time), not within one project (session count). A rule dormant in THIS project may fire immediately in the next client engagement.

Phase Templates

Global templates at ~/.claude/templates/ — reusable across all client projects:

New project setup:

# Option A: Path-scoped (automatic)
cp ~/.claude/templates/phase_*.md new-project/.claude/rules/
# Edit paths: in each file to match project structure

# Option B: @import (manual swap)
# In project CLAUDE.md:
@~/.claude/templates/phase_data_sourcing.md

Comparison

Limitations

• Does not validate the content quality of memories or lessons — only structural issues and staleness
• Does not automatically determine whether a cross-file duplicate should live in global vs project (asks the user)
• Does not renumber all lessons sequentially (that would break external references) — only fixes collisions
• Axioms promotion candidates are flagged but require user approval — never auto-promotes
• Stale memory files are flagged but never auto-deleted — user must confirm
• Codebase contradiction detection requires package.json/requirements.txt or similar manifests

File Format Conventions

• axioms.md: Short behavioral overrides grouped by theme. Each rule references the source lesson number. Target ~50 lines.
• MEMORY.md: No frontmatter. One-line index entries under semantic sections. Target ~40 lines.
• Memory files: YAML frontmatter with name, description, type (user/feedback/project/reference)
• Lessons: ### N. Title with **Pattern:** and **Rule:** sections
• ADRs: NNNN-kebab-case.md with # ADR-NNNN: Title, Status/Context/Decision sections

Inspired By

Academic foundations (v3.0)

The tiered architecture, phase templates, and promotion/demotion lifecycle are grounded in:

• Liu et al. (2024) "Lost in the Middle" — ~20pp accuracy drop for mid-context info (TACL, Stanford/Meta AI). Motivates small T0.
• EMNLP 2025 "Context Length Alone Hurts" — Performance degrades even with perfect retrieval. Confirms the problem persists in 2025.
• Chroma (2025) "Context Rot" — 18 production models all degrade with context length. Breaking point is unpredictable.
• Cowan (2001) "The Magical Number 4" — Working memory is ~4 chunks → 12-item axiom cap (3 items × 4 chunks).
• Sweller (1988) Cognitive Load Theory — Extraneous load competes with task-relevant processing.
• Lewis et al. (2020) RAG — Selective retrieval outperforms preloading. T3 grep = lightweight RAG.
• Lunney & Lueder (2017) Google SRE Postmortems — Two-incident rule for runbook promotion; "would it recur silently?" demotion test.
• Fiedler et al. (2018) Intentional Forgetting — Demotion = removing retrieval cues, not deletion.
• Markus (2001) "Toward a Theory of Knowledge Reuse" — Push vs pull: pure push risks overload. Pull surfaces knowledge at moment of need.
• Nygard (2011) ADRs — "No one reads large documents."

AI agent memory systems (v2.0)

• OpenViking (ByteDance) — L0/L1/L2 tiered context loading, filesystem paradigm, auto-compression
• MADR 4.0 — Confirmation section, structured pros/cons, YAML frontmatter, status lifecycle
• claude-memory-skill — Three-question quality gate, codebase contradiction detection
• Cog — Hot/warm/glacier memory tiers, /housekeeping and /reflect skills
• Cursor Memory Bank — Stability-axis organization pattern
• MemOS (Jul 2025) — Three-tier memory hierarchy formalization
• Zep/Graphiti (Jan 2025) — Temporal knowledge graph, contradiction invalidation

See docs/research-best-practices.md for the full research synthesis and docs/openviking-assessment.md for the detailed OpenViking comparison.

Version History

License

MIT