memory-audit

# Memory audit

A periodic self-check on the memory system itself, not a lookup of any one
memory. Two things drift silently if nobody checks them: the index can fall
out of sync with the files it's supposed to point at, and the same friction
can get rediscovered and re-recorded multiple times instead of being fixed
once (structurally, as a skill/hook) or consolidated.

## Step 1 -- index integrity

Every `<type>_<slug>.md` file in the memory directory should have exactly
one bullet in `MEMORY.md` linking to it.

```sh
cd ~/.claude/projects/-home-lancer1977-projects/memory/
comm -23 <(find . -maxdepth 1 -name '*.md' -not -name MEMORY.md -printf '%f\n' | sort) \
         <(grep -oE '\]\([a-zA-Z0-9_.-]+\.md\)' MEMORY.md | tr -d '()[]' | sort -u)
```

**Use `find`, not `ls`, for the real-file side.** In this environment `ls` is
aliased to `eza -a --icons=always`, which prepends an icon glyph to every
filename — that silently broke this exact comparison on first use (every
real file looked "orphaned" and every indexed link looked "dead" because
neither side's strings matched anymore). `find -printf '%f\n'` bypasses the
alias entirely; don't swap it back for `ls` even if it looks equivalent.

Anything the first command prints is an **orphaned memory** — written but not
indexed, at real risk of being forgotten (this happened to
`feedback_dev_means_staging_tier.md` on 2026-08-17, found and fixed by this
exact check). Also check the reverse — an index line whose target file
doesn't exist — with the comparison flipped (`comm -13`).

`MEMORY.md` truncates after 200 lines in context; if the file is approaching
that, flag it as needing consolidation (merge/retire stale entries) rather
than letting new entries silently fall off the loaded window.

## Step 2 -- friction sweep

Grep memory bodies (not just descriptions) for language that signals a
recurring pain point rather than a one-off note:

```sh
grep -lriE 'confus|convoluted|ambiguous|mismatch|contradict|duplicat|burned [0-9]+|repeatedly|again\b|rediscover' *.md | grep -v MEMORY.md
```

Read the hits. Group by theme, not by file. A theme worth acting on shows up
**independently in two or more memories** written at different times about
different projects — that's a structural gap, not a one-off. A theme that
only appears once is probably already handled by the memory itself; don't
manufacture a skill for it.

## Step 3 -- contradiction check

Within a theme cluster from Step 2, check whether the memories actually agree.
Two feedback memories giving opposite instructions on the same situation is
worse than either being silent — surface it to the user rather than picking
one side.

## Step 4 -- name the candidate, don't just build it

For each theme that clears Step 2's bar, state: what the friction is
concretely, which memories evidence it (cite them), and what form fixes it
structurally (a glossary/reference skill, a hook that enforces a check, a
consolidation of overlapping memories, or a fix to an existing skill's
missing step). Then hand the list to the user as real options — per this
environment's elicitation-first convention, a picker of what to build next,
not a unilateral build.

## When *not* to run this

Don't run a full sweep just to answer a specific factual question — that's
ordinary memory recall. This is for explicit "look back and find patterns"
requests, or a periodic hygiene pass the user asks for.