Curate agent memory

Memory is for facts about the user and their work that nothing else records. Rules that belong to a repository, a skill, or the user's global instructions drift out of sync when they live only in memory. This skill finds those, proposes where each belongs, and changes nothing without approval.

Step 1: Resolve the memory directory

Everything later deletes or rewrites files, so the target must be the store Claude Code actually uses.

• Repository: the argument, else the current Git repository root. Worktrees of one repository share a single store.

• Memory directory: use --memory-dir when given. Otherwise resolve it. The command below resolves it for the current repository; when the user named another repository, add --repo "<repository>":

  {{PYTHON}} -B "${CLAUDE_SKILL_DIR}/scripts/memory_audit.py" resolve

  It prints REPO <root>, the repository to use from here on; then MEMORY_DIR <path>, SOURCE <where it came from>, EXISTS yes or EXISTS no, and REFUSED <reason> when the later steps would refuse that directory, or NO_MEMORY_DIR when no usable directory resolves; a CANDIDATE <dir> line for each other memory directory it found when no usable one resolved; and a NOTE line for each caveat, such as the --settings launch flag it cannot see. FAILED not inside a Git repository means you must pass --repo; a FAILED line naming CLAUDE_CONFIG_DIR, USERPROFILE, or HOME as not an absolute path means the user must set that variable as the line says; any other FAILED <reason> means git could not read the repository, or a settings file it names could not be read. Either way, show it and stop.

• On NO_MEMORY_DIR, EXISTS no, or REFUSED, show the reason and notes, list the CANDIDATE lines, and ask the user to choose or supply --memory-dir. Never guess.
• Show the user the resolved directory and its source, and get explicit confirmation before continuing.

Step 2: Run the mechanical audit

{{PYTHON}} -B "${CLAUDE_SKILL_DIR}/scripts/memory_audit.py" audit --memory-dir "<memory dir>" --repo "<repository>"

It prints REPORT <path>, a new JSON file in the system temporary directory; read that file. FAILED <reason> means it wrote no report; show the reason, which may name a variable to set, as in Step 1. A FAILED <memory dir> ... line means the later steps would refuse the directory too, so go back to Step 1 before changing anything. Its overlaps (up to three passages in the repository's or the user's guidance per memory, with overlaps_omitted counting any more it left out) are candidates only; the script cannot tell whether a passage states the same rule. Each cited path gives "exists": true or false for a path that is there or is not; "exists": null with an "unreadable" reason means the path could not be examined, which is no evidence that it is gone: report it as unreadable, and never take the memory for obsolete on it.

Step 3: Verify and classify every memory

Read every memory file in full, in one turn as parallel calls, and every overlapping passage in context. Memories are point-in-time notes, so check any claim about code, paths, or configuration by searching the current files with Grep before relying on it.

Assign each memory exactly one outcome, with a one-line reason and evidence (file:line for anything that exists elsewhere):

For a move to a skill, find the file to edit. Add --repo "<repository>" as in Step 1, or pass --file "<path>" in place of the name to check a source file the user names:

{{PYTHON}} -B "${CLAUDE_SKILL_DIR}/scripts/memory_audit.py" skill-source "<skill>"

It prints SKILL_FILE <path> for each source of the skill: the checkout the deployer installed it from, and a project skill in the repository. Never edit a deployed copy under a skills directory: the deployer then stops updating that skill, and the next audit never sees the rule. A NOTE line names a file it passed over. When it ends with FAILED <reason>, show the reason; the outcome is Keep unless the user names a source file that --file accepts.

A memory whose rule is not yet at its destination is never simply deleted. Its outcome is the move, and the memory is deleted only after the destination change is applied. If the user declines the move, keep the memory. Record nothing about deferrals; the next run checks again.

Fix mechanical problems from Step 2 as part of the relevant outcome: repair or remove broken links, and bring an index that is over or near its load limit back under it by merging or moving entries. Memories missing from the index, entries whose file is gone, and duplicate entries form one "Rebuild index" group rather than per-memory outcomes. Show each unreadable entry with its reason; it is the user's to resolve.

Step 4: Get approval by group

Present the proposal grouped by outcome, headed by the memory directory it applies to, one line per memory: file, outcome, reason, evidence. For every move, show the exact text that would be added and where.

Ask which groups to apply with a multi-select AskUserQuestion, one option per non-empty group. Offer to review a group item by item when the user wants to exclude individual memories. Apply nothing that was not approved.

Step 5: Apply the approved changes

• Change destination files first with Edit, reading each before changing it and keeping its existing style and structure. Never replace a whole existing file.

• Only then delete or rewrite the memories those changes cover. When rewriting one, keep its frontmatter name and description accurate: the index is built from them. Delete approved memories by file name, never with another command:

  {{PYTHON}} -B "${CLAUDE_SKILL_DIR}/scripts/memory_audit.py" delete --memory-dir "<memory dir>" "<file>.md" ...

  It prints DELETED <file> for each file it deletes. A lone FAILED <memory dir> ... line, here or from reindex, means the directory holds no MEMORY.md or lies inside a skills directory, so it changed nothing; show it and go back to Step 1. FAILED <file>: <reason> lines with no DELETED line mean it refused those names and deleted nothing; show the reasons and fix the list. A FAILED line after DELETED lines means the deletion stopped part way: the DELETED files are gone and the rest remain, so show the reason and rerun with the remaining files.

• For review findings, invoke flag-review-finding through the Skill tool with the memory's substance; delete the memory the same way once the finding is recorded.

• When any memory changed or the "Rebuild index" group was approved, rebuild MEMORY.md last instead of editing it by hand:

  {{PYTHON}} -B "${CLAUDE_SKILL_DIR}/scripts/memory_audit.py" reindex --memory-dir "<memory dir>" --write

  It writes the index from the memory files and prints WROTE <path>, or UNCHANGED; WOULD_WRITE <path> means --write was left off, so run it again as shown. It first prints one INDEX_LINE <file> per entry of the index, in its order, which needs no report; report its DROPPED, ADDED, and UNREADABLE lines; an UNREADABLE entry is the user's to resolve. OVER_LIMIT (it still writes the index) or NEAR_LIMIT means the index still needs merging or moving entries. A last FAILED <reason> means it could not read a memory or write the index; show the reason.

• Do not commit, push, or open pull requests; report which repository files changed so the user can review them, and that a change to a skill's source reaches the deployed skill at its next deployment.

Step 6: Re-audit and report

Rerun Step 2. Report what changed per outcome, any destination files edited, and anything the audit still flags. Everything left should be a memory you deliberately kept.