memory-quality-auditor

Memory Quality Auditor

Audit the memory system as a unified retrieval layer (STM/MTM/LTM files + index + spawn citation outcomes).

Scope

• Retrieval drift signals
• stale memory ratio
• evidence injection coverage
• citation usage/groundedness continuity

Workflow

1. Read memory artifacts and latest eval reports.
2. Compute quality metrics and threshold status.
3. Emit remediation backlog with TDD checks.
4. Record findings in memory and optional evolution recommendation.

Iron Laws

1. ALWAYS establish a baseline metric snapshot before auditing — drift is only meaningful relative to a prior measurement; auditing without a baseline produces absolute numbers that cannot identify regression.
2. NEVER close a memory finding without re-running the affected retrieval query — closing without verification creates false improvement metrics and masks persistent degradation.
3. ALWAYS include citation-groundedness checks in every audit run — uncited memory injections are the primary source of hallucination in agent spawns; skipping this check leaves the highest-risk failure mode undetected.
4. NEVER audit only the STM tier — degradation often originates in MTM/LTM promotion corruption; all three tiers must be sampled in every full audit cycle.
5. ALWAYS emit TDD-ready remediation items with a failing-test condition and expected metric threshold — vague findings ("memory quality is low") cannot be actioned by any agent.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Auditing without a baseline	Cannot distinguish regression from steady-state; all findings are ambiguous	Snapshot current metrics at session start; compute delta against the previous run
Closing findings without re-check	Produces false-positive resolution; degradation persists silently behind green metrics	Re-run the specific retrieval query after each remediation; close only on confirmed green metric
Skipping citation groundedness	Citation failures are the leading cause of agent hallucination; missing this check omits the highest-severity defect class	Include citation_coverage and grounded_ratio metrics in every audit report
Full-mode audit on every spawn	Full audit is expensive; running it unconditionally inflates cost and slows workflows	Use --mode summary for routine checks; reserve --mode full for scheduled or triggered audits
Auditing STM only	MTM/LTM corruption is invisible in STM-only scans; stale LTM entries contaminate future sessions	Sample all three tiers: STM (current session), MTM (last 10 sessions), LTM (permanent summaries)

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern → .claude/context/memory/learnings.md
• Issue found → .claude/context/memory/issues.md
• Decision made → .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.