memory-clean

name	memory-clean
description	Use when the user asks to audit memory or find stale or duplicate memories.

Audit memory for structural rot and staleness, report with evidence, fix only on user confirmation.

Scope

Audits and fixes existing memory files. Does not create new memories from session signals (that is memory-update). Does not redact PII or credentials (that is memory-sanitize, which memory-clean will recommend when it detects suspected credentials at critical severity).

Path resolution

Scripts live under this skill's own scripts/ directory. Resolve the skill root from $HOME (the conventional install path is $HOME/.claude/claude/skills/memory-clean/):

SKILL_SCRIPTS="${MEMORY_CLEAN_SKILL_SCRIPTS:-$HOME/.claude/claude/skills/memory-clean/scripts}"
MEMORY_DIR=$("$SKILL_SCRIPTS/resolve-paths.sh" memory_dir)
SESSION_HISTORY_GLOB=$("$SKILL_SCRIPTS/resolve-paths.sh" session_history_glob)

Set MEMORY_CLEAN_SKILL_SCRIPTS to override when the skill is installed outside $HOME/.claude. Abort on non-zero exit from the resolver. Overrides via MEMORY_DIR / SESSION_HISTORY_GLOB env vars.

Workflow

1. Resolve paths (above)

2. Snapshot before any fix

cp -r "$MEMORY_DIR" /tmp/memory-snapshot-$(date +%s)

3. Run structural audit

./scripts/audit-memory.sh "$MEMORY_DIR" "$SESSION_HISTORY_GLOB" > /tmp/memory-audit-$(date +%s).json

The script emits JSON with these arrays:

Field	What it detects
orphans	Files in dir with no MEMORY.md entry
dangling	MEMORY.md entries pointing to missing files
near_duplicates	File pairs with >70% content overlap
structural	Missing frontmatter, missing Why:/How to apply:, index line > 150 chars, MEMORY.md > 200 lines, type-mismatch, fix-recipe content
staleness	Memories whose stated rule conflicts with recent session evidence

Read references/AUDIT-CHECKLIST.md for full detection rules per category. Staleness is the one category whose detection is an algorithm rather than a check: read references/STALENESS-RULES.md for the session cross-referencing procedure, the negative signals that look like staleness but are not, and the historical-anchor phrases that suppress a past-date flag.

4. Render report grouped by severity

CRITICAL (N)
  [cred-scan] feedback_no-html-comments.md — suspected credential on line 7
  → Recommend: run memory-sanitize first

WARN (N)
  [near-dup] feedback_consistent-config.md ↔ feedback_no-html-comments.md (82% overlap)
  [stale] feedback_bump-minor-versions.md — rule contradicted in 4 recent sessions
    Evidence: turns uuid-aaa, uuid-bbb, uuid-ccc, uuid-ddd

INFO (N)
  [orphan] user_role_data_scientist.md — not in MEMORY.md index
  [index-long] project_auth-rewrite.md — index entry is 163 chars (limit 150)

For staleness items, always show the specific turn IDs and a snippet of the contradicting evidence.

5. Wait for confirmation per group

Present each fix group with a diff preview. Wait for explicit user confirmation before applying.

6. Apply confirmed fixes

• Orphan: append entry to MEMORY.md.
• Dangling: remove line from MEMORY.md.
• Near-duplicate: present merged draft; write merged file + remove the superseded one; update MEMORY.md.
• Structural: targeted in-place edit via Edit tool.
• Stale: present options: update the rule, archive the file, or delete it.

7. Re-run audit; confirm zero critical issues

./scripts/audit-memory.sh "$MEMORY_DIR" "$SESSION_HISTORY_GLOB"

Report residual warn/info items; leave them for the user to act on separately if desired.

Anti-patterns (never do)

• Delete a file without showing the user its content first.
• Attempt credential redaction (surface critical flag, recommend memory-sanitize).