agentleFS
chuckplayerchuckplayer/claude-agent-pack/skills/memory-audit/SKILL.md

memory-audit

Skill8 starsChanged 35 days agoMITView on GitHub

Runs a memory hygiene pass on the project memory/ directory. Reviews all active memory files against the current codebase and archives or supersedes stale entries. Use before major feature work or when memory files feel out of date. Trigger this when someone says: clean up memory, audit memory files, memory is out of date, stale decisions, memory hygiene, are our memory files current, check if decisions are still valid. Do NOT use when searching for a specific memory entry — use /memory-query instead.

15 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 4 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 12 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run a memory hygiene pass on the project's memory/ directory.

    line 8
  2. Very specific:

    If memory/ does not exist in the current project, report that and stop.

    line 10
  3. Very specific:

    Use Glob("memory//*.md") to discover all memory files.

    line 14
  4. Distinctive:

    Do not delete files — history is preserved by archiving, not deletion.

    line 31
  5. Distinctive:

    After reviewing active files, look for unrecorded decisions.

    line 39
  6. Very specific:

    If the user identifies gaps, offer to create new memory entries for them using the templates in docs/MEMORY-WRITING.md.

    line 43
  7. Distinctive:

    If no changes were needed, say so

    line 52
  8. Distinctive:

    Run the conformance check over the corpus, including any file this pass just edited:

    line 56
  9. Very specific:

    Missing the memory/ directory entirely: If memory/ does not exist, report that clearly and stop.

    line 74

“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Memory Audit

Run a memory hygiene pass on the project's memory/ directory.

If memory/ does not exist in the current project, report that and stop.

1. Review active files for staleness

  1. Use Glob("memory/**/*.md") to discover all memory files.
  2. Skip files with status: superseded or status: archived — these are history only.
  3. For each active file, check whether it still accurately describes the codebase as it exists today:
    • Does it reference a service, module, or dependency that no longer exists?
    • Has the technology it covers been removed or replaced?
    • Does a more recent decision supersede it?
  4. For stale files, edit the fenced lowercase frontmatter in place:

    • Context no longer applies → set status: archived
    • Superseded by a newer decision → set status: superseded and populate superseded-by: with the newer filename
    • The issue was fixed → set status: resolved and add a resolved: YYYY-MM-DD key

    Write lowercase keys inside the --- fence and nothing else. docs/MEMORY-WRITING.md is the authority on the dialect. This step previously instructed the bold unfenced dialect retired on 2026-09-02, which would have made this hygiene skill the thing that broke the dialect on every future pass. Change only the keys named above; leave the rest of the frontmatter and the whole body alone.

  5. Do not delete files — history is preserved by archiving, not deletion.

1a. Check the repo map for drift

If memory/architecture/repo-map.md exists, read its verified-at-commit stamp and run git diff --name-only <that-sha>..HEAD. If mapped directories have changed, added, or been removed since the stamp, do not archive the map — it is meant to be refreshed, not retired. Instead, flag it in the report and recommend running /repo-map refresh. Only archive the map if the project structure it describes has been entirely replaced.

2. Check for gaps in decision coverage

After reviewing active files, look for unrecorded decisions. Ask the user:

"Are there major architectural decisions, known issues, or pattern choices that have been made but aren't recorded in memory? For example: a technology that was evaluated and rejected, a workaround for a platform constraint, or a deliberate deviation from the conventions."

If the user identifies gaps, offer to create new memory entries for them using the templates in docs/MEMORY-WRITING.md.

3. Report

Output a summary:

  • Total active files reviewed
  • Files archived (with reason)
  • Files superseded (with reason and superseded-by)
  • Gaps identified and whether new entries were created
  • If no changes were needed, say so

4. Lint the dialect

Run the conformance check over the corpus, including any file this pass just edited:

bash scripts/lint-memory.sh

Exit 0 conforms, 1 is a finding, 2 means the checker's own self-test failed and its verdict is worthless. Fix any finding before reporting the pass complete — a hygiene pass that leaves the corpus non-conforming has not finished. Findings name the file and the rule; docs/MEMORY-WRITING.md is the authority on the dialect.

If scripts/lint-memory.sh is not present in the project, report this step as not applicable and continue. The script is newer than some checkouts. A missing checker is a stated gap — do not describe it as a pass, and do not hand-roll a substitute check.

Gotchas

  • Archiving too aggressively: A memory file that references a pattern no longer in use may still be valid if it explains why that pattern was abandoned. Read for intent before archiving — "we removed X because Y" is still useful context even if X is gone.
  • Missing the memory/ directory entirely: If memory/ does not exist, report that clearly and stop. Do not create the directory — use /setup-project to scaffold the full project structure.
  • Confusing superseded with archived: Superseded means a newer decision replaced this one — the newer file must be cited in superseded-by:. Archived means the content no longer applies at all (e.g., references a removed module). Resolved means the issue it records was fixed. These are different statuses with different meanings.
  • Inviting the user to create too many new entries at once: Step 2 asks about gaps, but memory files are only useful when they capture non-obvious decisions. Do not turn this into a documentation sprint. Focus on decisions that would surprise a new contributor.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.