Auto Memory Curation

# Example check for a link target
ls ~/.claude/projects/<project>/memory/<file>.md 2>/dev/null

4. Collect broken links (target file does not exist).
5. Flag any links pointing to files outside the memory directory (potential path drift).

Step 3: Staleness detection

For each memory file, scan for path references — lines containing ~/, /var/home/, /home/, or /opt/. For each path found:

ls <path> 2>/dev/null || echo "MISSING"

Collect all references where the path no longer exists on disk. These are stale entries. Note the line number and the full line text.

Also flag date-stamped entries older than 90 days where the surrounding context suggests they are time-sensitive (e.g., lines containing "current", "active", "running", "status").

Step 4: Deduplication

For each pair of topic files, compare content blocks (paragraphs and list items). Flag blocks that:

• Are identical across two files
• Say the same thing with minor wording variation (check for >80% word overlap on sentences over 10 words)

Note: do not flag intentional cross-references — only flag duplicated knowledge that adds no value by being in both places.

Step 5: Size enforcement

For each topic file (non-index files):

• Warn if line count exceeds 500
• Report the top 3 largest sections (by heading) within oversized files to help the user decide what to trim or split

Step 6: Conflict detection

Read the active CLAUDE.md files:

cat ~/.claude/CLAUDE.md 2>/dev/null
cat ~/CLAUDE.md 2>/dev/null

Scan memory files for entries that directly contradict instructions in CLAUDE.md. Examples of contradictions:

• Memory says "use npm" when CLAUDE.md says "always use Bun"
• Memory says "install on host" when CLAUDE.md says "use distrobox"
• Memory contains a hardcoded path like /home/yish when CLAUDE.md says use $HOME or /var/home/yish

Collect all conflicting entries with file, line number, memory text, and the CLAUDE.md instruction it conflicts with.

Step 7: Session-based suggestions

Scan recent session data for patterns that should be persisted but aren't in any memory file:

find ~/.claude/projects/*/sessions/ -name "*.jsonl" -newer $(date -d '7 days ago' +%Y-%m-%d) 2>/dev/null | head -10

Look for:

• Repeated bash commands that suggest a stable workflow not yet documented
• Tool configurations or paths referenced multiple times
• User preferences stated explicitly ("always do X", "never do Y", "I prefer Z")

Suggest these as new memory entries (do not auto-add — present as suggestions only).

Step 8: Present proposed changes

Before touching any file, output the full change plan:

MEMORY CURATION REPORT
======================

Index files audited: <N>
Topic files audited: <N>
Total lines scanned: <N>

BROKEN LINKS (<N>)
  ~/.claude/projects/.../memory/MEMORY.md:12 — [topic-file.md](topic-file.md) [NOT FOUND]

STALE PATHS (<N>)
  ~/.claude/projects/.../memory/system-context.md:34 — ~/old-project/ [NOT FOUND]

DUPLICATED ENTRIES (<N>)
  Same content in system-context.md:45 and agent-patterns.md:12:
    "<duplicated text>"

SIZE WARNINGS (<N>)
  agent-patterns.md: 612 lines (limit: 500)
    Largest sections: "FSM Patterns" (210 lines), "Multi-Agent" (180 lines)

CONFLICTS WITH CLAUDE.md (<N>)
  system-context.md:78 — "use npm install" conflicts with CLAUDE.md: "Always use Bun (not Node)"

SUGGESTED NEW ENTRIES (<N>)
  Pattern seen 3x in sessions: <description>
  Suggest adding to: <target file>

PROPOSED ACTIONS
  1. Remove broken link at MEMORY.md:12
  2. Remove stale path reference at system-context.md:34
  3. Remove duplicate at agent-patterns.md:12 (keep system-context.md:45 as primary)
  4. Flag agent-patterns.md for manual trimming (612 lines)
  5. Fix conflict at system-context.md:78

Proceed with actions 1-3 and 5? (Skipping 4 — manual trim required)
[Waiting for confirmation]

Step 9: Apply confirmed changes

Only after the user confirms, apply the non-destructive changes (removals of specific lines, not whole-file rewrites). Use Edit for targeted line removals. Never delete an entire file.

After applying, output a final summary:

Actions taken:
  Removed N stale entries
  Deduplicated M entries
  Fixed K broken links
  Flagged L conflicts for review

Memory files are now within size and quality targets.
Run the health check mode for a quick re-check.

Health Check (Quick, Read-Only)

A lightweight, read-only health check. Runs fast — no writes, no confirmations needed. Use before important sessions or as a periodic sanity check. For remediation, run the full curation above.

Current Memory Status

!`wc -l ~/.claude/projects/*/memory/MEMORY.md 2>/dev/null | tail -1`

!`ls ~/.claude/projects/*/memory/*.md 2>/dev/null | wc -l` topic files found

!`wc -l ~/shared-memory/core/*.md 2>/dev/null | tail -1`

Health Checks

Run each check in sequence. Collect all findings before reporting.

Check 1: MEMORY.md line count

Read each MEMORY.md index file and count its lines.

• OK: 0–150 lines
• WARN: 151–200 lines — approaching limit, consider trimming
• ERROR: 201+ lines — exceeds 200-line budget; run full curation

wc -l ~/.claude/projects/*/memory/MEMORY.md ~/shared-memory/core/MEMORY.md 2>/dev/null

Check 2: Broken links in MEMORY.md

Extract all markdown links [text](file.md) from each MEMORY.md. For each link, verify the target file exists relative to the index file's directory. Report any missing targets as broken links.

Pattern to match: \[.+?\]\((.+?\.md)\)

For each match, check:

ls <resolved-path> 2>/dev/null || echo "BROKEN"

Check 3: Stale paths in topic files

Scan all topic files (*.md in memory directories, excluding MEMORY.md) for lines containing path references:

• Lines with ~/, /var/home/, /home/yish, /opt/, /etc/

For each path extracted, verify it exists:

ls <path> 2>/dev/null || echo "MISSING"

Flag paths that do not exist as stale. Note: skip paths that are clearly illustrative examples (inside fenced code blocks used as templates).

Check 4: Large topic files

Count lines in all non-index topic files:

wc -l ~/.claude/projects/*/memory/*.md ~/shared-memory/core/*.md 2>/dev/null | grep -v MEMORY.md | sort -rn | head -10

• OK: 0–500 lines
• WARN: 501+ lines — flag for trimming

Check 5: Last modified dates

Check when each memory file was last modified:

find ~/.claude/projects/*/memory/ ~/shared-memory/core/ -name "*.md" -exec stat --format="%Y %n" {} \; 2>/dev/null | sort -n

Convert timestamps. Flag any file not modified in the last 30 days with WARN. Files untouched for 90+ days get ERROR — they may be stale enough to mislead the agent.

Output: Summary Table

After all checks, render a summary table:

MEMORY HEALTH REPORT — <date>
==============================

File                                          Lines   Last Modified   Issues
----------------------------------------------------------------------
MEMORY.md (project)                           <N>     <date>          <status>
system-context.md                             <N>     <date>          <status>
agent-patterns.md                             <N>     <date>          <status>
project-state.md                              <N>     <date>          <status>
secrets-management.md                         <N>     <date>          <status>
shared-memory/core/MEMORY.md                  <N>     <date>          <status>
...

SUMMARY
  OK:     <N> files
  WARN:   <N> files
  ERROR:  <N> files

FINDINGS
  Broken links:    <N>  (list file:line — target)
  Stale paths:     <N>  (list file:line — path)
  Oversized files: <N>  (list file — line count)
  Stale files:     <N>  (list file — days since modified)

STATUS: <HEALTHY | NEEDS ATTENTION | ACTION REQUIRED>

HEALTHY: no errors, 0–2 warnings. NEEDS ATTENTION: 3+ warnings or 1 error. ACTION REQUIRED: 2+ errors.

If status is NEEDS ATTENTION or ACTION REQUIRED, append:

Recommended next step: run /auto-memory-curation (full mode) to resolve findings.