Memory

Memory is a memory optimization skill (recipe notes) that interactively trims and reorganizes CLAUDE.md and MEMORY.md files. Through 4 sequential steps, it removes duplicates, migrates entries to proper locations, compresses what remains, and validates the result.

/brewdoc:memory

Why optimize memory

Claude Code memory files accumulate entries over time. Some of them duplicate rules already recorded in CLAUDE.md or .claude/rules/. Other entries are too verbose and waste tokens on every session load.

The Memory optimizer addresses these problems while keeping all useful knowledge in its proper place.

4 optimization steps

Remove duplicatesStep 1
The Explore agent cross-references all memory files against CLAUDE.md and .claude/rules/*.md. It finds entries that already exist in rules or conflict with CLAUDE.md (CLAUDE.md takes priority). It shows a duplicates table and asks for confirmation: “Remove all”, “Review each”, or “Skip”.
Migrate to rules/CLAUDE.mdStep 2
Remaining entries are classified by target location. Global rules are moved to ~/.claude/rules/, project rules to .claude/rules/, architectural decisions to the project CLAUDE.md. Facts and patterns useful across sessions stay in memory.
CompressStep 3
Remaining entries are compressed for token savings: prose is converted to table rows, related entries are merged, verbose descriptions are replaced with imperative one-liners, example lists are reduced to a pattern plus one example. A preview with estimated savings is shown.
Validate and clean upStep 4
The reviewer agent checks the final state: broken file references, conflicts with CLAUDE.md, invalid markdown. Broken references are fixed automatically. Orphaned memory files (not referenced from MEMORY.md) are detected and proposed for deletion.

Memory directory detection

The skill automatically determines where memory files are stored:

Checks .claude/settings.json for the autoMemoryDirectory field
If the field is set, uses <git-root>/<autoMemoryDirectory>
If not set, uses the legacy path ~/.claude/projects/<hash>/memory/

Analysis context

Before starting optimization, all related files are loaded:

Source	What is loaded
Memory directory	All `*.md` files
Global instructions	`~/.claude/CLAUDE.md`
Project instructions	`CLAUDE.md` (if it exists)
Global rules	`~/.claude/rules/*.md`
Project rules	`.claude/rules/*.md`

Example: before and after

Before optimization

## Memory - my-project

When working with the database, always use the connection pool
from `src/db/pool.ts`. Never create direct connections because
they leak resources and cause timeout issues in production.

Always use grepai for code search before using Glob or Grep tools.

The project uses ESLint with the Airbnb config. Make sure to run
`npm run lint` before committing any changes to ensure code quality.

Use grepai_search MCP tool for code exploration.

Architecture: microservices with API Gateway pattern.

After optimization

## Memory - my-project

| Rule | Context |
|------|---------|
| DB: connection pool from `src/db/pool.ts` | Direct connections forbidden (resource leak) |
| Architecture: microservices + API Gateway | -- |

Removed (duplicate): “Use grepai for code search” — already in .claude/rules/grepai-first.md

Removed (duplicate): “Use grepai_search MCP tool” — duplicates the previous rule

Migrated to .claude/rules/lint.md: “ESLint Airbnb config, npm run lint before commit”

Summary report

After all 4 steps are complete, a report is generated:

Metric	Before	After	Saved
Total entries	X	Y	Z
Duplicates	X	0	—
Migrated	—	—	X
Estimated tokens	~X	~Y	~Z (~P%)

Interactive process

Each step requires user confirmation. You can skip any step, review changes one by one, or apply them all at once. The skill does not delete data without approval.