Memory Optimize

Plugin: kochetkov-ma/claude-brewcode

Memory Optimizer

Optimizes Claude Code auto-memory files in 4 interactive steps: removes duplicates, migrates rules to proper config files, compresses remaining entries, validates the result. Typical reduction: 30–50% token count in memory files.

Auto-memory stores context across sessions in ~/.claude/projects/**/memory/MEMORY.md. Enable: CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 · Disable: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Benefits: faster context loading · no duplicate rules · cleaner instructions · lower API cost

Usage:

/memory-optimize          # no args — starts 4-step interactive workflow

_Skill text is written for LLM consumption and optimized for token efficiency._

---

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

1. Glob all memory files: ~/.claude/projects/**/memory/*.md 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_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 using Edit tool if approved

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

Goal: Identify remaining memory 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 via Edit
• If target file doesn't exist, create it

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 (Edit tool) 3. Check for orphaned memory files (files in ~/.claude/projects/**/memory/ 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 ~/.claude/projects/.../memory/}

---

**Part of brewdoc:** [brewcode](https://github.com/kochetkov-ma/claude-brewcode) — docs tools: memory optimization, auto-sync, Claude installation docs, Markdown to PDF.
Install: `claude plugin marketplace add https://github.com/kochetkov-ma/claude-brewcode && claude plugin install brewdoc@claude-brewcode`

Memory Optimizer

Optimize Claude Code memory files through a 4-step interactive workflow: remove duplicates, migrate rules to proper config files, compress remaining entries, and validate the result. Typical savings: 30-50% on token count in memory files, meaning faster context loading and lower API cost.

Quick Start

1. Install:

   npx skills add kochetkov-ma/claude-brewcode

2. Use via slash command:

   /memory-optimize

Or via natural language prompt:

   Optimize my Claude memory files
   Clean up memory duplicates

The skill scans all memory files under ~/.claude/projects/, cross-references them against your CLAUDE.md and rules files, then walks you through each optimization step with approval prompts before making changes.

Why Use This

• Token savings -- 30-50% fewer tokens in memory context means lower cost and more room for actual work
• Interactive -- approve each step, skip steps you don't want; nothing changes without your confirmation
• Safe -- shows before/after preview before making changes; content is only deleted when it provably exists elsewhere
• Smart migration -- moves rules to proper config files (CLAUDE.md, .claude/rules/, ~/.claude/rules/) so they load reliably instead of depending on memory

What It Does

Step 1: Remove Duplicates

Finds memory entries that already exist in CLAUDE.md or rules files. Shows a table of what is redundant, asks for approval before deleting.

Example:

Found 4 duplicate/redundant entries (35% of memory):
| Entry | Memory File | Already In | Action |
|-------|-------------|------------|--------|
| "Use grepai first" | MEMORY.md:5 | rules/grepai-first.md | DELETE |
| "Constructor injection" | MEMORY.md:12 | CLAUDE.md:## DI | DELETE |
| "No System.out" | MEMORY.md:18 | rules/best-practice.md:7 | DELETE |
| "Edit bottom-up" | MEMORY.md:23 | rules/avoid.md:8 | DELETE |

Options: "Yes, delete all" / "Review each" / "Skip this step"

Step 2: Migrate to Rules/CLAUDE.md

Identifies remaining entries that belong in persistent config files rather than memory. Uses a decision tree to categorize each entry:

• Global rule (all projects) --> ~/.claude/rules/
• Project rule (this project) --> .claude/rules/
• Architectural decision --> project CLAUDE.md
• Reusable fact/pattern --> keep in memory
• Session context --> delete (ephemeral)

Shows a migration plan with target files and token savings, asks for approval before moving anything.

Step 3: Compress

Converts remaining entries to token-efficient formats: prose to table rows, multiple entries to a single table, verbose descriptions to imperative one-liners.

Before:

## Plugin Development (2026-01-15)
When developing plugins, remember to update BOTH plugin.json and marketplace.json
files on version bump, otherwise autocomplete will break because versions won't match.

After:

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

Shows 2-3 specific before/after samples with token savings, asks for approval.

Step 4: Validate (Automatic)

Runs automatically after the previous steps. Checks for:

• Broken file path references in memory files
• Contradictions between memory and CLAUDE.md
• Malformed markdown
• Orphaned memory files (files with no MEMORY.md reference)

Reports any issues found and offers to fix them.

Where Information Goes

Part of Brewdoc

This skill is extracted from brewdoc -- a documentation tools plugin for Claude Code with memory optimization, auto-sync, Claude installation docs, and Markdown to PDF.

claude plugin marketplace add https://github.com/kochetkov-ma/claude-brewcode
claude plugin install brewdoc@claude-brewcode

License

MIT

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