/consolidate

name: consolidate
description: >
  Consolidates project memory across harness and .memory/ with theme clustering,
  practical-expiry prune, ground-truth verify, and an adversarial second pass.
  Use when the user runs /memory:consolidate, asks to tidy/dedupe/prune memory,
  or reports redundant or stale memories. Also covers active writing during work.
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Agent
  - Bash(ls:*)
  - Bash(find:*)
  - Bash(wc:*)
  - Bash(diff:*)
  - Bash(cmp:*)
  - Bash(md5:*)
  - Bash(shasum:*)
  - Bash(rm:*)
  - Bash(cp:*)
  - Bash(mkdir:*)
  - Bash(stat:*)
  - Bash(head:*)
  - Bash(sort:*)
  - Bash(comm:*)
  - Bash(python3:*)
  - Bash(mktemp:*)

Memory — Active Write & Consolidate

The project's memory lives in two locations that must stay **identical for safe (public) files** (idempotent):

1. **`~/.claude/projects/<escaped-cwd>/memory/`** — harness, loaded by Claude Code, written first 2. **`.memory/`** — canonical, git-tracked, written second — **safe files only**

Resolve the harness path: `~/.claude/projects/<cwd-with-/→->/memory/` (probe both space-handling forms: `/→-`+` →-` and `/→-`+space-kept).

Private files (user preferences, credentials, PII) live in **harness only**. They must never appear as files or index lines under `.memory/`.

Active Write

When you encounter a decision, preference, lesson, or anything worth remembering, write it **immediately** — do not wait for /memory:consolidate.

Before writing

1. **Search existing memories first** (Grep/Read harness `*.md` by theme keywords). If one already covers the topic, **edit that file** instead of creating a near-duplicate. 2. Refuse pure operation logs: if you cannot state a durable **Why** and a reusable **How to apply**, do not write a memory. Put timelines in git/commits/docs, not memory. 3. Prefer one decision per file. Two independent decisions → two files; the same decision learned twice → one file.

Privacy check

`.memory/` is a **public GitHub repo**. Private = secrets/PII/credentials **or user preferences / personal workflow habits**. Safe technical content → both locations. Private → harness only; harness index line ends with `(harness only)`.

How to write

1. Write file to harness `.../memory/<filename>.md` 2. If **safe** → write identical file to `.memory/<filename>.md`. If **private** → do **not** write to `.memory/`; if `.memory/<filename>.md` already exists, **delete it**. 3. Update indexes:

• **Harness `MEMORY.md`**: include every file (private lines marked `(harness only)`)
• **`.memory/MEMORY.md`**: **safe lines only** — never copy `(harness only)` lines into the public index

File naming: `<type>_<kebab-slug>.md` (type: feedback, project, reference)

Format:

---
name: <kebab-slug>
description: <one-line hook distinguishing this from similar files>
type: feedback | project | reference
---

<the fact>

**Why:** <why this decision exists>

**How to apply:** <actionable rules>

**Related:** [[other-memory]] [[another-memory]]

Memory is decision log, not operation log

Every memory file answers two questions only:

• **Why** — why this decision or rule exists
• **How to apply** — what to do next time

Remove all operation history (version numbers, dates-as-timeline, "first X then Y"). That lives in `git log`. Keep only the durable rationale and actionable rules.

MEMORY.md index format

Each line: one concise sentence, no version numbers, no date ranges, no timeline descriptions. One line per surviving file. Prefer ≤50 lines for scanability; if more files exist, **keep every entry** and group by theme — never drop entries to hit 50.

Good: `feedback_git_commit_hook_needed.md — git PreToolUse hook intercepts git add/commit, redirects to /git:commit; allows chain + GIT_SKILL_FALLBACK=1 escape` Bad: `feedback_git_commit_hook_needed.md — git PreToolUse hook intercepts git add/commit; v0.5.3 command position anchoring + two exceptions + 26 regression tests`

Red lines

• Never drop `[[name]]` cross-links when rewriting — preserve all from the original unless the target is intentionally deleted and the reference is removed in the same pass
• Never delete a file referenced by `[[name]]` in another memory file unless the reference is also removed
• **`rm` only under the harness memory directory or `.memory/`** — never elsewhere
• Never publish private content to `.memory/` (file body or index line)

---

Consolidate (/memory:consolidate)

User-invoked only. No auto-consolidation. Default failure mode of a weak run is **cosmetic tidy while leaving thematic redundancy and factually dead notes**. This procedure is fail-closed against that.

Work order: harness first, then sync to `.memory/`.

CRITICAL: Mutation freeze until planning artifacts exist

**Do not Write, Edit, or `rm` any memory file** until all three artifacts exist in this conversation:

1. **Inventory** — complete name list of harness `*.md` and `.memory/*.md` (including both `MEMORY.md`) 2. **Cluster map** — every non-index file appears in exactly one theme cluster 3. **Staleness table** — every non-index file has a rubric verdict (step 4)

After ground-truth probes (step 5), also hold a **ground-truth table** with tool-observed paths (`path → found|missing|updated`) before applying claim fixes. Fabricating these tables without Read/Grep/`find`/`ls` is a failed run.

CRITICAL: Machine validator (cannot self-attest past this)

Write inventory / cluster / staleness / report to temp files, then run:

# Pre-mutation (lift freeze only if exit 0)
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/validate-consolidate.py" \
  --inventory /tmp/mem-inventory.txt \
  --cluster /tmp/mem-cluster.txt \
  --staleness /tmp/mem-staleness.txt \
  --check=cluster,staleness

# Post-sync before claiming done (exit 0 required)
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/validate-consolidate.py" \
  --inventory /tmp/mem-inventory.txt \
  --cluster /tmp/mem-clus