session-memory-audit

Step 1: Run the audit

bun run ${CLAUDE_PLUGIN_ROOT}/lib/memory-scanner.ts audit

Optional: --age-threshold N (default 60 days for staleness check)

Step 2: Present the summary

Show the health summary first:

Memory Health Report N memories across M projects N critical · N warnings · N info

Step 3: Present findings in two sections

IMPORTANT: Always separate findings into two clearly labeled groups.

Section A: Auto-fixable (deterministic, no AI)

These are safe, mechanical fixes. Present as a numbered table:

#	Action	File	Project	Issue

Where Action is one of:

• DELETE — for expired findings (delete file + remove MEMORY.md entry)
• REMOVE — for broken_link findings (remove dead entry from MEMORY.md)
• INDEX — for orphan findings with frontmatter (add entry to MEMORY.md)
• SYNC — for index_mismatch findings (update MEMORY.md description)

After the table, ask: "Apply all N auto-fixes? (yes/no)"

If yes:

• For DELETE: Remove the file with rm, then edit MEMORY.md to remove the line referencing it
• For REMOVE: Edit MEMORY.md to remove the broken link line
• For INDEX: Read the file's frontmatter, append a new entry to MEMORY.md: - [name](filename.md) — description
• For SYNC: Update the MEMORY.md entry's description to match the file's frontmatter description

Report each fix as it completes.

Section B: AI-assisted (requires analysis)

Present these AFTER auto-fixes are complete (or skipped):

"There are also N findings that require analysis to fix. Would you like to review them? (yes/no)"

If no — show summary and stop. Do NOT proceed with AI-assisted fixes.

If yes — walk through ONE AT A TIME:

For each finding, the ai_action field tells you what to do:

missing_frontmatter:

1. Read the file content
2. Infer the memory type from content (user bio = user, behavioral rule = feedback, project state = project, external pointers = reference)
3. Infer a concise name and description
4. Show the proposed frontmatter to the user
5. If approved, prepend it to the file