---
name: memory-tidy
description: Keep memory small enough to stay useful - report which caps are over, propose merges, split bloated notes, archive what is finished, and connect orphans. Use when memory-doctor or the session brief reports a cap, when memory feels noisy, or on a periodic review.
---

# memory-tidy — forgetting, on purpose

Promotion without forgetting just makes a bigger pile. `identity/` is read in
full on every session, so its size is not a matter of taste: a note nobody can
read in one pass stops being read at all, and then the judgement it holds stops
applying.

So the layers have caps, and reaching one is the signal to consolidate. The cap
is the mechanism — not a tidiness rule, and not a number to raise when it gets
inconvenient. It already works: `memory/identity/decision-policy.md` has held to "40
entries, 3 lines each, a forty-first arrives by merging or dropping one" and it
is the one part of the harness that has never bloated. What the number cannot
tell you is which entries still earn their place — for that, step 1 also asks
which ones nobody has cited.

## What this may do on its own

| Action | Do it |
|---|---|
| **Archive** a finished or superseded note | Without asking. Reversible, and it stays in the graph |
| **Add a missing link** between two notes | Without asking |
| **Merge** two notes, or rewrite one | Propose it. Show what would be lost |
| Change anything in **`identity/`** | Propose it. Always |
| **Delete** | Don't. Archive instead — a deleted note takes its observations and its inbound links with it, and they break silently on the other side |

Report everything done without asking, one line each.

## Steps

### 1. Measure

```bash
node "${CLAUDE_PLUGIN_ROOT}/engine/cli.mjs" doctor
```

| Cap | Limit | Why that one |
|---|---|---|
| `identity/` notes | 8 | Read in full, every session |
| One `identity/` note | 120 lines | The same. `decision-policy.md` is exempt |
| `decision-policy.md` entries | 40, 3 lines each | Counted across every section, not per section |
| `episodes/` notes | 60 | Past this, promotion has stopped happening |

A cap is a prompt to consolidate, never a licence to delete.

Then ask which policy entries are dead weight:

```bash
node "${CLAUDE_PLUGIN_ROOT}/engine/cli.mjs" axes
```

It lists the entries — `## Always ask` excepted — that no note in
`memory/notes/` or `_ai/comms/` has cited by `P-NN` in the last 90 days. It says
nothing until 90 days have passed since the policy's `axes_since`, because an
empty record would otherwise read as "nothing is used". These are candidates for
moving down to `notes/`, not a verdict: an entry can be rarely reached and still
right. Propose each one with what it would cost to lose.

### 2. Find what is actually wrong

| Problem | Signal | Fix |
|---|---|---|
| Bloated note | Over 300 lines, several subjects | Split by subject; keep the axes, move the cases out |
| Duplicates | Two notes on one subject | Merge, then `supersedes` the loser (do not delete it) |
| Stale | Refers to work that finished, decisions since overturned | Archive, or mark `status: superseded` and give the replacement a `supersedes [[old]]` relation — the link runs one way, from the new note |
| Orphan | No inbound link, in no index | Link it, or ask whether it is still wanted |
| Contradiction | Two notes disagree on a fact | **Surface it. Do not pick one silently** — ask which is true |
| Un-promoted | `episodes/` full of `status: open` checkpoints | Run `memory-reflect` first; this skill is the wrong tool |

### 3. Consolidate, in this order

1. **Archive** what is plainly finished. Cheapest, reversible, often enough on
   its own.
2. **Merge** duplicates — propose each one.
3. **Split** what is over its cap — propose each one.
4. **Re-measure.** If a cap is still over after the first three, the layer has
   a real excess and the owner has to choose what goes.

Never renumber or rename to tidy up. It breaks every link into a note and buys
nothing a reader can see.

### 4. Record what it cost

When a merge drops something, say what. A consolidation that quietly loses a
rule is worse than the bloat it fixed.

Add anything that has now gone wrong **twice** to `memory/README.md`'s
`## Known failure modes`. That section tends to become the most valuable thing
in the store, and it only grows if someone puts things in it.

## Report

```
memory: 3 archived, 1 link added — identity 9/8 still over

  → identity/preferences.md is 140 lines (cap 120)
    Proposal: move the six worked examples to notes/, keep the four axes.
    Lost: nothing — the examples keep their own note.

  → identity/ holds 9 notes (cap 8)
    Proposal: merge tone.md into about-me.md; they are two paragraphs each.
```

Proposals first, with what each one costs. The owner decides which rule
survives — that is not a judgement to make on their behalf.