curate-agent-memory

Files (3)

• SKILL.md
• memory_audit.py · scripts/
• test_memory_audit.py · scripts/

SKILL.md (first lines)

# 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>"`:

  ```bash
  {{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`; any other `FAILED <reason>` means git could not read the repository, so 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

```bash
{{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. 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) are candidates only; the script cannot tell whether a passage states the same rule.

## 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):

| Outcome | When |
|---|---|
| Keep | A personal preference, identity detail, or fact about the user's work that nothing else records. |
| Delete: obsolete | It describes something that no longer exists or no longer applies. |
| Delete: already covered | Its destination already states the same rule. Cite the passage; similar wording is not enough. |
| Merge | It overlaps other memories; name the survivor and show the merged text. |
| Move to global instructions | A rule the user wants in every repository. |
| Move to repository guidance | A convention for everyone working in this repository (`CLAUDE.md`, coding guidelines, contributor docs). |
| Move to a skill | A rule about how a specific skill must behave; the destination is a file `skill-source` prints (below). |
| Record as a review finding | A correction to an automated reviewer's findings rather than a preference. Use `flag-review-finding` when it is available. |

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:

```bash
{{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:

  ```bash
  {{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:

  ```bash
  {{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 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.

From EJRyan89/coding-agent-skills, MIT.

More from EJRyan89/coding-agent-skills