cleanup

ctx:cleanup — Memory Reconciliation

Reconcile Claude Code's built-in MEMORY.md system with the ctx knowledge graph. Detect duplicates, stale nodes, conflicts, and bloat across both systems, then resolve them with user approval.

Arguments

• $1 — Project name (optional, auto-detected from git)
• --global — Include all projects, not just the current one

Execution Flow

This is a phased command — run each phase in order, presenting findings to the user between phases.

Phase 1: Inventory

Gather the complete state of both memory systems.

Actions:

1. Detect the current project name from git (basename $(git rev-parse --show-toplevel))
2. Run the analysis script to dump both systems:

   sh "${CLAUDE_SKILL_DIR}/scripts/analyze-sync.sh" "$PROJECT"
   

3. Read the MEMORY.md file for this project from ~/.claude/projects/ (search for directory matching project name)
4. Read any supplemental memory files (*.md besides MEMORY.md in the same directory)
5. Query ctx for all project-scoped nodes:

   ctx list --tag "project:$PROJECT" --format json
   

6. Query ctx for global nodes (no project tag or project:global):

   ctx list --tag "project:global" --format json
   

If --global was passed, also inventory all other projects:

• List all directories in ~/.claude/projects/*/memory/
• List all unique project:* tags in ctx via ctx tags

Save the inventory mentally — it feeds all subsequent phases.

Phase 2: Analysis

Analyze the inventory for seven categories of issues. For each issue found, record: the issue type, affected items (node IDs / MEMORY.md line numbers), severity (high/medium/low), and recommended action.

Issue categories (consult references/sync-strategies.md for detailed detection patterns):

1. Cross-system duplicates — Same knowledge in both MEMORY.md and ctx

   • Compare MEMORY.md content against pinned/working ctx nodes
   • Flag when semantically identical content exists in both
   • Severity: medium

2. Intra-ctx duplicates — Two+ ctx nodes with near-identical content

   • Compare node contents within the same project tag
   • Flag pairs with >80% content overlap
   • Severity: medium

3. Stale working nodes — tier:working nodes from completed tasks

   • Check creation date: working nodes older than 7 days are likely stale
   • Check content: completed sprints, resolved bugs, finished implementations
   • Severity: high (these auto-load every session, wasting tokens)

4. Pinned tier bloat — Too many pinned nodes consuming context budget

   • Count pinned nodes and total tokens
   • Flag if >20 nodes or >1,500 tokens
   • Identify pinned nodes that could be reference instead
   • Severity: medium

5. Conflicts — Contradictory information across systems

   • Compare related content in MEMORY.md vs ctx
   • Flag version numbers, rules, or conventions that disagree
   • Severity: high

6. Orphaned content — Knowledge for projects that no longer exist or are inactive

   • Cross-reference project tags against actual project directories
   • Flag nodes for projects with no matching directory
   • Severity: low

7. Missing structure — Nodes without tier tags, without project tags, or with empty content

   • Query for nodes missing expected tags
   • Severity: low

Phase 3: Report

Present findings to the user in a structured report. Group by severity (high first).

Report format:

## Memory Sync Report — [project]

### Token Budget
- MEMORY.md: ~X tokens (Y lines)
- ctx pinned: X tokens (Y nodes)
- ctx working: X tokens (Y nodes)
- Total auto-loaded: X tokens

### Issues Found

#### HIGH: Stale Working Nodes (N found)
| Node ID | Content Preview | Created | Recommendation |
|---------|----------------|---------|----------------|
| 01KK... | Sprint complete... | Mar 15 | -> tier:reference |

#### MEDIUM: Cross-System Duplicates (N found)
| MEMORY.md Line | ctx Node | Content | Recommendation |
|---------------|----------|---------|----------------|
| L5-7 | 01KH... | Release rules | Remove from MEMORY.md |

... (all categories)

### Summary
- X issues found (Y high, Z medium, W low)
- Estimated token savings: ~N tokens

MANDATORY: After presenting the report, MUST use the AskUserQuestion tool (not plain text) to ask how to proceed. Use this exact configuration:

• question: "How would you like to proceed with the N issues found?"
• header: "Remediation"
• options:
  1. label: "Auto-fix all (Recommended)", description: "Apply all recommendations automatically"
  2. label: "Review each", description: "Walk through issues one by one for approval"
  3. label: "Fix high-severity only", description: "Auto-fix HIGH issues, skip medium and low"
  4. label: "Skip", description: "Just show the report, don't change anything"

Do NOT proceed to Phase 4 without this user response. Do NOT present these options as text — use the AskUserQuestion tool.

Phase 4: Remediation

Execute approved fixes. For each fix, use the appropriate mechanism:

ctx node actions:

• Demote tier: ctx tag <id> tier:reference && ctx untag <id> tier:working
• Archive: ctx tag <id> tier:off-context && ctx untag <id> tier:working
• Delete: ctx delete <id> (only for true duplicates or empty nodes)
• Supersede: Emit <ctx:supersede old="ID1" new="ID2"/> when one node replaces another
• Add missing tags: ctx tag <id> project:name or ctx tag <id> tier:reference

MEMORY.md actions:

• Remove duplicate lines: Edit the MEMORY.md file to remove lines that duplicate ctx content
• Add missing content: Write new entries to MEMORY.md for project conventions not in ctx
• Update stale content: Edit outdated information in MEMORY.md

Cross-system actions:

• Migrate to ctx: Remove from MEMORY.md, store in ctx with proper type/tags
• Migrate to MEMORY.md: Archive ctx node, add concise version to MEMORY.md
• Consolidate duplicates: Supersede in ctx, clean MEMORY.md reference

After each batch of fixes, show a summary of what changed.

Phase 5: Verification

After remediation:

1. Run ctx status to show the new state
2. Read the updated MEMORY.md
3. Show before/after comparison:
   • Total auto-loaded tokens: before -> after
   • Node counts by tier: before -> after
   • MEMORY.md line count: before -> after
4. Flag any remaining issues

Sync Maintenance Advice

After cleanup, advise the user on keeping systems in sync:

1. The using-ctx skill already handles this — it instructs the agent to cross-check before writing to either system. If the user feels drift is happening, the skill instructions may need strengthening.

2. Periodic cleanup — Run /ctx:cleanup quarterly or when starting major new work.

3. Hook option — For persistent drift, a PostToolUse hook on MEMORY.md writes can enforce cross-checking. See references/sync-strategies.md for the hook design. Only recommend this if the user reports ongoing issues after multiple cleanups.

Additional Resources

Reference Files

• references/sync-strategies.md — Detailed sync strategies, division of labor rules, issue detection patterns, token budget guidelines, and hook-based sync design

Scripts

• scripts/analyze-sync.sh — Dumps both memory systems for comparison (run with project name argument)