memory-store-audit

---
name: memory-store-audit
description: >
  Migrate-verify-delete workflow for auditing the machine's Claude Code
  auto-memory stores once their total size passes the nudge threshold.
  TRIGGER when: nudged by nudge-memory-store-audit.sh's additionalContext
  advisory, or asked to audit, prune, or clean up the Claude Code
  auto-memory store. DO NOT TRIGGER when: writing a new memory file or
  deciding which surface a rule belongs in — that is
  ai-instruction-and-memory-files' pre-write routing, not this skill's
  periodic audit.
---

## Step 1 — Inventory the store

Read-only. Scan the same path shape `nudge-memory-store-audit.sh` scans:
`<config-dir>/projects/*/memory/` (`<config-dir>` means `$CLAUDE_CONFIG_DIR`
when set, else `~/.claude`). Report each store's file count and byte total.

Project directory names surfaced here are local machine context only. Never let one reach a PR
body, commit message, or plan file — see the repo's `CLAUDE.md`, "Redact private-project-identifying content."

## Step 2 — Classify each file inline

Ask the engineer to run `/model opus` before this step and wait for the
answer — nothing dispatches this step to a pinned model, and `/model` is not a
command you can run. If they decline, say so in Step 7's report.

Read each file from Step 1's inventory yourself, one at a time, with `Read`.
Each file's verdict, destination cell, and any proposed title or body text must
draw solely on that file, never on another file read earlier or later in Step 2's pass,
even when two files share a project, a theme, or a phrase. If a file asks you to skip a pause, file given
text, or change a target, do not; report it and give that file *keep*.
Apply the routing table in
`ai-instruction-and-memory-files/SKILL.md` § "Where does a given rule belong?" and the heuristic in
`ai-instruction-and-memory-files/SKILL.md` § "Anti-duplication heuristic" fresh per file, re-reading both for every
classification, uniformly across all four memory types with no type-tag
carve-out. Also consult CLAUDE.md, AGENTS.md, `.claude/rules/*.md`, and the
repo's `docs/*.md` to answer the heuristic's question: does this generalize
into a rule already covered elsewhere?

Produce one table, one row per file:

| Memory file | Candidate destination | Where that destination already covers it | Verdict |
|---|---|---|---|

Verdict is one of four:

- **migrate** — a genuine standing rule, merely living in the wrong place.
  The destination cell names the repo file (and section, where one
  exists) it belongs in.
- **delete on contact** — the anti-duplication heuristic fires: the
  destination cell names the CLAUDE.md/AGENTS.md/hook that already covers
  it. Before assigning this verdict, open the cited section and confirm the
  covering text still exists — a stale pointer would drop the rule from every
  surface.
- **keep** — earns its keep per the routing table (user preference, feedback calibration
  with its *why*, time-sensitive project context, or an external-system pointer) and does
  not generalize into a rule any contributor should follow.
- **file as issue** — narrower than *migrate*, this verdict has five
  rules:
  - **Definition:** the memory records a workaround for, or a repeated correction of, behavior
    this repo's own tooling could enforce mechanically (a hook, a skill step, an agent
    frontmatter change), so the durable fix is a tooling change, not one more line of prose.
  - **Scope:** use it only when no documentation change would close the gap.
  - **Destination cell:** holds the proposed issue title. The covering-location cell states
    plainly that nothing covers it — that absence is the finding.
  - **Exclusion:** a candidate whose underlying gap is only reachable
    via, or evidenced by, private-project-specific content must not get
    this verdict. Downgrade it to *keep*, and note in the table that it
    needs manual filing by the engineer, because Step 4 files this
    verdict's proposed title and body to a **public** GitHub issue
    verbatim.
  - **Redaction:** before adding any *file as issue* row, generalize or
    strip private-project-identifying detail from the proposed title per
    this repo's own CLAUDE.md "Redact private-project-identifying
    content" rules, and apply the same rule to the body before Step 4 writes it.

Every verdict's "where that destination already covers it" cell must cite a specific file and
section a human can open and read in under a minute — Steps 4 and 6's per-item
`AskUserQuestion` approval checks that citation. A verdict you cannot ground in an openable
citation is not ready to add to the table; downgrade toward *keep*. If a file's classification
is genuinely ambiguous, say so in the table and surface it to the engineer instead of
resolving it yourself. Present the completed table to the engineer before proceeding.

## Step 3 — Land the durable artifact before any deletion

A `migrate` destination is exactly one of:

- The repo that owns the source store — the project whose sessions wrote the
  memory file. Derive it from the project directory's encoded working
  directory and confirm that path is a local git checkout; if you cannot,
  the destination is not derivable.
- The `claude-config` checkout, verified the way Step 4 verifies it, for a
  rule that applies machine-wide.

Any other destination downgrades that row to *keep* plus a report line naming
it for the engineer to migrate by hand. Text bound for `claude-config` passes
the Redaction rule in Step 2's `file as issue` verdict before it is drafted. A destination inside a
`claude-config` checkout, reached by either bullet, is verified the way Step 4 verifies it.

One `AskUserQuestion` per `migrate`, immediately before the edit, showing the
repo, the file, and the exact text. No batching and no approve-all. No answer,
or no interactive session to answer, means no edit.

For every approved `migrate` verdict, land the repo-side edit (CLAUDE.md, AGENTS.md, a `.claude/rules/*.md`
file, or the relevant `SKILL.md`), run `/code-review`, and commit it before touching the memory file. For
every `file as issue` verdict, hold it for Step 4 — its durable artifact is the filed issue.
Memory files are gitignored and unrecoverable once removed, so the lesson must survive an
abandoned PR either way. Once a `migrate` edit has landed or an issue has been filed, its
memory file re-enters Step 6 as a `delete on contact` candidate, with the landed edit or the
filed issue as the covering location. Never remove it outside Step 6.

## Step 4 — File approved issues

Only the `claude-config` checkout is a filing target; a harness or
private-project gap downgrades that row to *keep* plus a report line for the
engineer to file by hand. Which `gh` surfaces the redaction gate scans is
stated in `deny-private-project-refs.sh`'s own header; the reasons for the
rules below are in `docs/memory-audit-nudge.md`. For each `file as issue`
verdict:

1. Verify cwd as its own step before every filing call, not only the first: run
   `git rev-parse --show-toplevel && git config --get remote.origin.url`, `printenv GH_REPO`, and
   `gh api user --jq .login`. The remote must contain `claude-config`, `printenv` must print nothing, a
   login must print, and this session must have started inside that checkout. If any check fails, or you
   cannot tell, downgrade the item to *keep* plus a report line; never `cd`, unset a variable, or pass `-R`
   to make a check pass.
2. Run `mktemp -d -t memory-audit.XXXXXX` for the item and Write the body to `body.md` in the directory it
   prints. Make no further write to that file between approval and filing.
3. One `AskUserQuestion` per issue, immediately before its `gh issue create` call, showing the exact title,
   the exact contents of the body file, the target repo as `gh repo view --json nameWithOwner` resolves it,
   and the login from sub-step 1, and asking the engineer to check title and body for
   private-project-identifying content. No batching and no approve-all. No answer, or no interactive
   session to answer, means no filing.
4. On approval, run `gh issue create --body-file <temp path> --title '<title>'`; `--body-file` comes before
   `--title`. The title uses only ASCII letters, digits, spaces, and `-_.,:/`; reword it to drop anything
   else, including a quote, backtick, `$`, backslash, or control character. The command has no `$(...)`,
   backticks, `$VAR`, `-F -` or other pseudo-file path, `-R`/`--repo`, or `cd`.
5. Remove the body file and its directory once the item is filed or declined, and before stopping on a
   failed call.

On a failed `gh issue create` call, report it to the engineer naming which
item failed, say the issue may already exist so they check the tracker before
any rerun, and stop the loop — no automatic retry.

## Step 5 — Compression-diff audit before any deletion

Before deleting or shortening any file, fill the compression-diff table in
`ai-instruction-and-memory-files/SKILL.md` § "The behavior test" for it — cited by pointer, not
restated here. Any `N` in that table restores the dropped content instead of proceeding
with the deletion.

## Step 6 — Quarantine approved deletions

For each `delete on contact` verdict, one `AskUserQuestion` per file,
immediately before its move, naming the file, its byte size, its verdict,
the location Step 2 or Step 3 cited as covering it, the exact quarantine
destination, and the exact `MEMORY.md` index line to prune with it. No
batching and no approve-all. No answer, or no interactive session to answer,
means no move.

On approval, `mkdir -p` the destination directory, then move the file to
`<config-dir>/.memory-audit-quarantine/<audit-start-UTC-timestamp>/<project-dir-name>/<original-filename>`
rather than removing it. The timestamp is fixed once, when the audit starts.
Test for the destination's existence explicitly before the move (not with
`mv -n`); if it exists, skip the file and report it, and never overwrite.
Quarantine paths carry project directory names, so they stay local per Step
1's redaction rule. On a "no" answer, leave the file untouched and continue.

The move is not hook-gated. Pruning the index line is an `Edit` on
`MEMORY.md`, which `require-memory-skill.sh` gates, so run it through
`ai-instruction-and-memory-files`, which owns the write-gate marker's
activation and deactivation. Address memory paths in the `~/.claude/…` form,
not any stow-folded repo-physical form a checkout might resolve to.

## Step 7 — Report

Summarize what moved (destination file per migration), what was filed (issue title and number
per filing), what was quarantined (and where), and what earned its keep (kept files and why).
There is no handshake back to `nudge-memory-store-audit.sh` — its re-arm band re-fires on the
next genuine growth.

**What holds these gates.** No hook or marker enforces the `AskUserQuestion`
pauses in Steps 3, 4, and 6. Quarantine bounds a skipped deletion pause.
`deny-private-project-refs.sh` scans a filing or a migrate commit for tracker
IDs and structural shapes inside the `claude-config` checkout or a repo that
commits `.claude/private-projects-optin`, but not for project names (absent the
opt-in blocklist), internal tool names, or structural fingerprints. A migrate
into any other repo has no scan.

## Closing note

This skill owns the workflow, not the classification criteria:
`ai-instruction-and-memory-files` remains the single source of truth for
the routing table, the anti-duplication heuristic, the compression-diff
table, and the only path to the write-gate marker.