lint-memory

Health check for the Claude memory system — finds orphans, dead links, contradictions, stale entries, and missing cross-references

SKILL.md

GitHub

/lint-memory

Memory health check. Finds problems, auto-fixes safe ones, flags the rest.

What It Checks

  1. Dead links — entries in MEMORY.md pointing to missing files
  2. Orphan files — .md files in the memory directory not listed in MEMORY.md
  3. Contradictions — same fact stated differently across files (e.g., two project statuses for same project)
  4. Stale project memories — project status not updated in 30+ days
  5. Missing cross-links — two memories that reference the same topic but don't link each other

Scope

Default: {agency-root}/memory/ (global) + {agency-root}/projects/{agency-root-slug}/memory/ (per-conversation). The per-conversation slug is the agency root path with / and . replaced by - (e.g. /home/ada/.claude → -home-ada--claude) — derive it, never hardcode it. Override: /lint-memory [path] to lint a specific directory.

Within a target directory, "in scope" excludes control/handoff filenames and managed/log directories — defined once in scripts/memory_scope.py (EXCLUDE_NAMES — next-session.md, decisions.md, heartbeat.md, .canary.md, etc.; EXCLUDE_DIRS — sessions/, qa/, tasks/, inter-spawn-tasks/, agents/, outputs/) — rather than restated inline here or duplicated per-script.

Steps

Step 1 — Read Indexes

Read MEMORY.md in each target directory. Parse all [Title](file.md) links.

Step 2 — Check Dead Links

For each link in MEMORY.md: verify the file exists. Auto-fix: remove entries for files that are missing (git history is the log).

Step 3 — Check Orphans

List all .md files in the directory (excluding MEMORY.md, wiki-schema.md itself). Flag files present on disk but absent from MEMORY.md. Do NOT auto-delete orphans — present them for user review.

Step 4 — Check Contradictions

For each memory file: extract key facts (project names, statuses, URLs, preferences). Compare across files. Flag cases where the same entity appears with conflicting values. Present contradictions for user resolution — never auto-resolve.

Step 5 — Check Staleness

For project-type memories: check the file's last modification date (git log or stat). Flag project memories not updated in 30+ days.

Step 6 — Check Cross-Links

For memory files that share 2+ topic keywords (e.g., both mention "Acme Corp"): Check if they contain See also: links to each other. Suggest (but do not auto-add) missing cross-links.

Step 7 — Report + Apply Safe Fixes

Output format:

MEMORY LINT — {date}

✅ {n} entries checked
❌ Dead links ({n}): [list] → auto-removed
⚠️  Orphan files ({n}): [list] → needs your review
⚠️  Contradictions ({n}): [list] → needs resolution
⚠️  Stale project memories ({n}): [list]
💡 Suggested cross-links ({n}): [list]

Auto-applied: {n} fixes
Action needed: {n} items