/memory-cleanup

name: memory-cleanup
user-invocable: true
tags: [memory, maintenance, meta, dream]
model: sonnet
model-preference: sonnet
model-preference-codex: gpt-5.4-mini
model-preference-cursor: claude-sonnet-4-6
args-schema:
  - flag: --dry-run
    description: "Produce complete-body proposal in .orchestrator/pending-dream.md, no mutations."
  - flag: --apply-pending
    description: "Consume .orchestrator/pending-dream.md (atomic apply)."
description: >
  Use this skill when performing manual memory consolidation (Dream-equivalent). Reviews, consolidates, and prunes memory files
  under ~/.claude/projects/*/memory/. Run after major refactors, every 5+ sessions, or when memory
  quality degrades (broken links, stale references, contradictions, MEMORY.md > 200 lines).
  Invoke with /memory-cleanup.

Memory Cleanup — Manual Dream Process

Implements the 4-phase memory consolidation process modelled after Claude Code's Auto Dream feature. Run after major refactors, framework migrations, or every 5+ sessions in a repo.

The memory system lives at `~/.claude/projects/<encoded-cwd>/memory/` and consists of:

• `MEMORY.md` — index file (must stay under 200 lines; lines after 200 are truncated by the harness).
• Topic files — one Markdown file per memory entry with YAML frontmatter (`name`, `description`, `metadata.type`).

The four memory types are `user`, `feedback`, `project`, `reference` (see global `auto memory` instructions for semantics). This skill never invents new types.

Argument Handling (Phase 0)

This skill accepts two optional flags. Default (no flag) runs the interactive 4-phase consolidation defined below.

| Flag | Behavior | |---|---| | `--dry-run` | Run Phases 1-3 read-only; instead of mutating MEMORY.md / topic files, write a complete-body MEMORY.md proposal (single fenced block — never a unified-diff) to `.orchestrator/pending-dream.md` (atomic). Exit 0. <!-- path-check: example --> | | `--apply-pending` | Read `.orchestrator/pending-dream.md`; refuse if older than 14 days (`stale`) or if MEMORY.md changed since the producing --dry-run (`stale-index`, #788); apply diff; delete pending file; print `auto-dream applied: -<X> lines, +<Y> entries`. Exit 0. <!-- path-check: example --> |

Flags are mutually exclusive — passing both is an error. Absence of both = legacy interactive mode (Phases 1-4 below).

**`--dry-run` flow:**

• Read MEMORY.md and topic files (read-only).
• Produce the same internal plan the interactive mode would (merges, prunes, rewrites).
• **Serialisation contract (#717 — load-bearing, read before writing the proposal):** `applyPendingDream()` in `scripts/lib/auto-dream.mjs` consumes ONLY the FIRST fenced code block in the sidecar body and writes it VERBATIM as the complete new MEMORY.md. It does NOT parse or apply git-style diff hunks. Therefore the proposal MUST ALWAYS be the complete new MEMORY.md body, in EXACTLY ONE fenced ` ```markdown ` block — never git-style unified-diff hunks (`--- `/`+++ `/`@@ … @@` lines), and never multiple fences for MEMORY.md itself. Any topic-file (non-MEMORY.md) change needed by the plan CANNOT be carried inside that single fence — instead, append it AFTER the fence as a separate, clearly-delimited machine-readable section per topic file, using the heading `### Topic-file change: <path>` followed by plain-language instruction text (not a diff). These sections are for a human to apply by hand; `applyPendingDream()` never reads past the first fence. If a `### Topic-file change:` section needs to show illustrative code, use 4-space-indented code text, never a fenced ``` block — `countFencedBlocks()` counts every fence in the raw sidecar body (not just MEMORY.md's), so a second fence anywhere in the document trips the >1-fence unsupported-format guard and blocks the whole apply.
• Call `writePendingDream({ repoRoot, diff, sourceSession, memoryLinesBefore, proposedLinesAfter })` from `scripts/lib/auto-dream.mjs`, passing the single-fence MEMORY.md body (plus any `### Topic-file change:` sections) as `diff`.
• Print one-line status: `pending-dream written: <N> lines proposed` (or `no consolidation needed (MEMORY.md is healthy)` when the plan is empty).
• Exit 0 in both branches.

**`--apply-pending` flow:**

• Call `applyPendingDream({ repoRoot, memoryDir })` from `scripts/lib/auto-dream.mjs`.
• Behavior matrix on the helper return:
• `applied: true` → print `auto-dream applied: -<linesBefore-linesAfter> lines, +<entries> consolidated entries` and exit 0.
• `applied: false, reason: 'missing'` → print `no pending dream to apply` and exit 1.
• `applied: false, reason: 'stale'` → print `pending dream is stale (>14d), re-run --dry-run` and exit 1.
• `applied: false, reason: 'stale-index'` (#788) → print `MEMORY.md changed since the producing --dry-run; re-run --dry-run.` and exit 1. The sidecar is preserved and MEMORY.md is left untouched (MEMORY.md's mtime is newer than the sidecar's `generated_at`, so applying the frozen dry-run snapshot would clobber the interim edits).
• `applied: false, reason: 'unsupported-format'` → print `auto-dream NOT applied: pending-dream.md contains git-style diff hunks this applier cannot consume. MEMORY.md left untouched, sidecar preserved. Re-run /memory-cleanup --dry-run to regenerate a complete-body proposal.` and exit 1.
• The sidecar file is deleted on successful apply; staleness (`stale` / `stale-index`), missing sidecar, or unsupported-format never deletes anything.

Both flag-driven flows delegate atomicity and staleness enforcement to `scripts/lib/auto-dream.mjs`. The interactive Phases 1-4 below remain unchanged.

Phase 1: Orient

Understand the current memory state before making changes.

1. List all files in the memory directory:

   ls -la ~/.claude/projects/*/memory/ 2>/dev/null | grep "$(basename "$(pwd)")"

Or directly list the project's memory dir (the path is in the `auto memory` system instructions).

2. Read `MEMORY.md` (the index file) — note its li