memory — clean up memory files

Caution

Memory files accumulate silently. Entries duplicate rules already in CLAUDE.md, verbose prose inflates every session load, and contradictions pile up unnoticed. Claude reads the full memory on every startup — deadweight entries cost real tokens every time.

Tip

One command, four interactive steps. Each step shows exactly what it proposes and waits for your approval. Nothing is deleted without confirmation. Run it anytime memory feels noisy.

Quick reference

FieldValue
Command/brewdoc:memory
Argumentsnone — runs a 4-step interactive workflow
Modelopus
ToolsRead, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion

When to use

  • Memory files have grown over weeks and feel cluttered
  • Claude auto-selects wrong rules because of conflicting memory entries
  • You added new .claude/rules/ files and want to remove redundant memory entries
  • Session startup feels slow and you want to reduce context load
  • You want to move project-specific constraints from memory into proper rules files

Examples

# Run the full 4-step interactive flow
/brewdoc:memory

The skill auto-detects your memory directory, loads all related files, then walks through each step.

# Natural language also works
"optimize my memory"
"clean up claude memory files"
"brewdoc:memory"

After Step 4, the skill prints a summary report:

## Memory Optimization Complete

| Metric         | Before | After | Saved      |
|----------------|--------|-------|------------|
| Total entries  | 42     | 18    | 24         |
| Duplicates     | 11     | 0     | —          |
| Migrated       | —      | —     | 8          |
| Estimated tokens | ~1 800 | ~620 | ~1 180 (~65%) |

Flow

  1. Load context

    The skill reads your memory directory (from autoMemoryDirectory in .claude/settings.json, or the legacy ~/.claude/projects/<hash>/memory/ path), then loads ~/.claude/CLAUDE.md, project CLAUDE.md, and all rules files — both global and project-level. This full context map drives all four analysis steps.

  2. Step 1 — Remove duplicates

    An Explore agent cross-references every memory entry against CLAUDE.md and .claude/rules/*.md. Entries that already exist in rules, or that contradict CLAUDE.md (CLAUDE.md wins), are shown in a table. You choose: “Delete all”, “Review each”, or “Skip”.

  3. Step 2 — Migrate to rules / CLAUDE.md

    Remaining entries are categorised by target: global rules go to ~/.claude/rules/, project rules to .claude/rules/, architectural decisions to project CLAUDE.md, cross-session facts stay in memory. A table with estimated token savings is shown before any migration is applied.

  4. Step 3 — Compress

    What remains is compressed for LLM efficiency: prose becomes table rows, related entries merge, verbose descriptions shrink to imperative one-liners, example lists reduce to a pattern plus one example. A before/after preview with estimated savings is shown. You confirm or skip.

  5. Step 4 — Validate and clean up

    A reviewer agent checks the final state: broken file references, conflicts with CLAUDE.md, malformed markdown. Broken references are fixed automatically. Orphaned memory files — files in the memory directory not referenced from MEMORY.md — are detected and proposed for deletion.

Internals

Memory directory detection

The skill resolves $MEMORY_DIR in this order:

  1. Read .claude/settings.json → extract autoMemoryDirectory
  2. If set: <git-root>/<autoMemoryDirectory>
  3. If not set: glob &#126;/.claude/projects/**/memory/*.md (legacy path)

Context map built before Step 1

SourceWhat is loaded
Memory directoryAll *.md files
Global instructions&#126;/.claude/CLAUDE.md
Project instructionsCLAUDE.md (if present)
Global rules&#126;/.claude/rules/*.md
Project rules.claude/rules/*.md

Migration decision tree (per entry)

  • Applies to all projects + is a rule/constraint → &#126;/.claude/rules/
  • Applies to this project only + is a rule → .claude/rules/
  • Is an architectural decision → project CLAUDE.md
  • Is a fact/pattern reusable across sessions → stays in memory

Compression techniques

  • Prose → table row
  • Multiple related entries → single table
  • Verbose description → imperative one-liner
  • List of examples → pattern + one example

Edits are applied bottom-up (descending line number order) to preserve line numbers during multi-edit operations.

No context: fork — the skill must run in the main conversation to spawn Explore and reviewer agents.

🔄

Auto-sync

Keep docs in sync automatically — the other core brewdoc skill.

📄

My-claude

Generate Claude Code installation docs for your project.

🔗

GitHub source

Source code and full SKILL.md for the memory optimizer.

🚀

Brewdoc overview

All brewdoc skills in one place.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.