Brewdoc:Memory

Memory Optimizer

Optimizes Claude Code memory files through 4 interactive steps.

No `context: fork` — must run in main conversation to spawn agents.

Phase 0: Load Context

0. Determine memory directory (`$MEMORY_DIR`):

   CUSTOM_DIR=$(cat .claude/settings.json 2>/dev/null | jq -r '.autoMemoryDirectory // empty')
   if [ -n "$CUSTOM_DIR" ]; then
     MEMORY_DIR="$(git rev-parse --show-toplevel)/$CUSTOM_DIR"
   else
     MEMORY_DIR=~/.claude/projects/<hash>/memory
   fi

Read .claude/settings.json (if exists) → extract autoMemoryDirectory. If set → resolve as <git-root>/<autoMemoryDirectory>. If not set → use legacy ~/.claude/projects/<hash>/memory/ glob pattern.

1. Glob all memory files: $MEMORY_DIR/*.md (or ~/.claude/projects/**/memory/*.md for legacy) 2. Read ~/.claude/CLAUDE.md and project CLAUDE.md (if exists) 3. Glob .claude/rules/*.md — read all project rules 4. Read ~/.claude/rules/*.md — read all global rules

Build context map:

memory_dir: $MEMORY_DIR
memory_files: [paths]
claude_md_sections: [sections]
rules_files: [paths with content]

Step 1: Analysis — Remove Duplicates (Interactive)

Goal: Find memory entries that duplicate content already in CLAUDE.md or rules.

1. Spawn Explore agent to cross-reference all loaded files 2. Identify entries where:

• Same rule already in CLAUDE.md
• Same pattern already in a rules file
• Contradicts CLAUDE.md (CLAUDE.md wins)

3. Show analysis:

   Found X duplicate/redundant entries (Y% of memory):
   | Entry | Memory File | Already In | Action |
   |-------|-------------|------------|--------|
   | "Use grepai first" | MEMORY.md:5 | rules/grepai-first.md | DELETE |
   ...

4. AskUserQuestion: "Delete X duplicate entries (Y% of memory)? This is safe — content exists elsewhere." Options: "Yes, delete all" / "Review each" / "Skip this step" 5. Apply deletion via Edit if approved

Step 2: Migration — Move to Rules/CLAUDE.md (Interactive)

Goal: Identify remaining entries better suited to persistent config files.

Decision tree (per entry):

• Applies to ALL projects + IS a rule/constraint → ~/.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 → KEEP in memory

1. Show categorization:

   X entries suitable for migration:
   | Entry | Current Location | Target | Reduction |
   |-------|-----------------|--------|-----------|
   | "Always use BD_PLUGIN_ROOT" | MEMORY.md:12 | .claude/rules/brewdoc.md | 15 tokens |
   ...
   Total: X entries → ~Y tokens saved

2. AskUserQuestion: "Migrate X entries to rules/CLAUDE.md?" Options: "Yes, migrate all" / "Review each" / "Skip this step" 3. If approved: create/append to target rule files via Edit, remove migrated entries from memory, create target file if missing

Step 3: Compression (Interactive)

Goal: Compress remaining entries using LLM-efficient formatting.

Compression techniques:

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

1. Show compression preview:

   Compression opportunities found:
   | Before | After | Savings |
   |--------|-------|---------|
   | "When you need to... always use..." | "Use X for Y" | 8 tokens |
   ...
   Total: ~Y% token reduction (~Z tokens)

Show 2-3 specific before/after samples. 2. AskUserQuestion: "Compress remaining memory? (~Y% reduction)" Options: "Yes, compress all" / "Skip compression" 3. Apply compression via Edit (bottom-up order to preserve line numbers)

Step 4: Validation (Automatic)

Goal: Verify final state and clean orphaned references.

1. Spawn reviewer agent to verify:

• No broken file path references in memory files
• No contradictions between memory and CLAUDE.md
• Memory files are well-formed markdown

2. Clean broken references via Edit 3. Check for orphaned memory files (in $MEMORY_DIR with no MEMORY.md reference) 4. Report orphaned files and ask to delete

Final Report:

## Memory Optimization Complete

### Summary
| Metric | Before | After | Saved |
|--------|--------|-------|-------|
| Total entries | X | Y | Z |
| Duplicate entries | X | 0 | — |
| Migrated entries | — | — | X |
| Token estimate | ~X | ~Y | ~Z (~P%) |

### Changes Made
- Step 1: Deleted X duplicate entries
- Step 2: Migrated X entries to rules/CLAUDE.md
- Step 3: Compressed X entries (Y% reduction)
- Step 4: Fixed X broken references, removed X orphaned files

### Final Memory Structure
{directory listing of $MEMORY_DIR}

Memory Optimizer

Optimizes Claude Code memory files through a 4-step interactive workflow -- removes duplicates, migrates entries to persistent config, compresses remaining content, and validates the final state.

Quick Start

/brewdoc:memory

No arguments. The skill detects your memory directory automatically and guides you through each step interactively.

How It Works

The skill loads all memory files, CLAUDE.md configs, and rules files into a context map. It then walks you through four steps: deduplication, migration, compression, and validation. Each step shows a preview of proposed changes and asks for your approval before modifying anything.

The 4 Steps

Examples

Good Usage

After many sessions with accumulated memory. Memory files grow over time as Claude saves patterns and facts. Running the optimizer consolidates and trims the bloat.

# Memory has grown to 200+ lines across multiple files
/brewdoc:memory
# Result: 40% token reduction, 12 duplicates removed, 8 entries migrated to rules

Before a project handoff. Clean memory ensures the next person (or session) gets a concise, non-redundant context.

# Preparing project for another developer
/brewdoc:memory
# Result: memory files are compact, all reusable rules live in .claude/rules/

When memory contradicts CLAUDE.md. Over time, memory entries may drift from the authoritative config. The optimizer detects contradictions and resolves them (CLAUDE.md always wins).

Common Mistakes

Running on a fresh project with minimal memory. If you only have a few entries, there is nothing to optimize. Wait until memory has grown meaningfully.

Skipping all steps every run. If you skip deduplication, migration, and compression, the skill does nothing useful. Engage with at least one step for meaningful results.

Running after every single session. The optimizer is most effective after 10+ sessions of accumulated memory. Running it daily on a lightly-used project wastes time.

What Gets Optimized

Removed: Entries duplicating existing rules or CLAUDE.md content, contradictions (CLAUDE.md wins), broken file references.

Migrated: Rules/constraints moved to .claude/rules/, architectural decisions moved to CLAUDE.md.

Compressed: Prose rewritten as table rows, related entries merged into tables, verbose descriptions replaced with imperative one-liners.

Output

The skill produces a summary report at the end:

## Memory Optimization Complete

### Summary
| Metric         | Before | After | Saved      |
|----------------|--------|-------|------------|
| Total entries  | 45     | 28    | 17         |
| Duplicates     | 12     | 0     | --         |
| Migrated       | --     | --    | 8          |
| Token estimate | ~1200  | ~720  | ~480 (40%) |

### Changes Made
- Step 1: Deleted 12 duplicate entries
- Step 2: Migrated 8 entries to rules/CLAUDE.md
- Step 3: Compressed 5 entries (25% reduction)
- Step 4: Fixed 1 broken reference, removed 0 orphaned files

Files modified: memory files in $MEMORY_DIR, and optionally .claude/rules/*.md or CLAUDE.md (migration targets).

Tips

• Run after 10+ sessions when memory has accumulated enough content to benefit from optimization.
• Say "review each" on your first run to understand what the skill considers duplicate or migratable. After that, "delete all" / "migrate all" is safe.
• Check the migration targets after Step 2 -- the skill creates or appends to rules files, so verify the new rules fit your project structure.
• Memory directory auto-detection reads .claude/settings.json for a custom autoMemoryDirectory. If unset, it falls back to the legacy ~/.claude/projects/<hash>/memory/ path.

Documentation

Full docs: memory

Memory Guide

Decision Tree: Where Does This Information Belong?

Is this information?
├── A rule/constraint (should always apply)
│   ├── Applies to ALL projects → ~/.claude/rules/{topic}.md
│   └── Applies to THIS project only → .claude/rules/{topic}.md
├── An architectural decision (project-specific)
│   └── → project CLAUDE.md (## Architecture or ## Decisions section)
├── A reusable pattern/fact (sessions may forget)
│   └── → MEMORY.md (or topic file linked from MEMORY.md)
└── Session-specific context (current task state)
    └── → DO NOT save (ephemeral, delete if found)

File Location Map

Compression Patterns

Duplicate Detection

An entry IS a duplicate if: 1. Same rule appears in CLAUDE.md (exact or paraphrase) 2. Same pattern in a rules file 3. References a pattern that's been generalized in CLAUDE.md

An entry is NOT a duplicate if: 1. More specific than the CLAUDE.md version (add detail, not replace) 2. Context-specific exception to a general rule 3. Recent discovery not yet in CLAUDE.md

Compression Examples

Before:

## Plugin Development (2026-01-15)
When developing Claude Code plugins, you should always remember to update BOTH plugin.json and marketplace.json files when bumping the version number, otherwise autocomplete functionality will break because the versions won't match.

After:

## Plugin Dev
| Rule | Why |
|------|-----|
| Update BOTH plugin.json + marketplace.json on version bump | Autocomplete breaks on mismatch |

Bottom-Up Editing

Always apply edits in descending line number order: 1. Sort all changes by line number (descending) 2. Apply from last line to first 3. This preserves line numbers for subsequent edits