auto-memory

Auto Memory Management

Use persistent auto memory to retain project knowledge across Claude Code sessions. The memory directory (~/.claude/projects/<path>/memory/) stores a concise index file (MEMORY.md) and detailed topic files, creating a structured knowledge base that grows with the project.

Core Architecture

~/.claude/projects/<project-path>/memory/
├── MEMORY.md          # Always loaded into system prompt (~200 lines max)
├── architecture.md    # Topic file: system architecture decisions
├── patterns.md        # Topic file: code patterns and conventions
├── debugging.md       # Topic file: debugging insights
├── workflows.md       # Topic file: development workflows
└── known-issues.md    # Topic file: bug tracking

Two-Tier Design

1. MEMORY.md (always in context): Concise index with key facts, quick reference tables, and links to topic files. Lines after 200 are truncated — keep it tight.
2. Topic files (consulted as needed): Detailed reference organized by domain. No size limit, but keep each file focused on one topic.

What to Save

Save These

• Stable patterns confirmed across multiple interactions (naming conventions, file organization, coding style)
• Architectural decisions and their rationale
• Important file paths and project structure
• User preferences for workflow, tools, and communication style
• Solutions to recurring problems and debugging insights
• Critical gotchas that cause repeated mistakes
• Explicit user requests ("always use bun", "never auto-commit") — save immediately, no need to wait for confirmation across sessions

Do NOT Save

• Session-specific context (current task details, in-progress work, temporary state)
• Unverified information — verify against project docs before writing
• Duplicates of CLAUDE.md — memory supplements project instructions, never contradicts them
• Speculative conclusions from reading a single file
• Rapidly changing values (exact line numbers, temporary feature flags)

Setting Up Auto Memory

Step 1: Create the Memory Directory

The directory is created automatically by Claude Code, but to initialize manually:

mkdir -p ~/.claude/projects/<project-path>/memory/

The <project-path> typically mirrors the working directory with slashes replaced by dashes (e.g., /workspaces/my-app becomes -workspaces-my-app).

Step 2: Create MEMORY.md

Start with a minimal index and expand as patterns emerge. Include:

• Project overview: Key architectural facts (2-3 bullet points)
• Quick reference: Counts, paths, conventions that come up repeatedly
• Critical gotchas: Hard-won lessons that prevent repeated mistakes
• Topic file index: Table linking to detailed files with "when to consult" guidance

See examples/MEMORY.md for a starter template.

Step 3: Create Topic Files as Needed

Create topic files only when a domain accumulates enough detail to warrant its own file. Common topic files:

See examples/topic-file.md for the recommended structure.

Organization Principles

Semantic Over Chronological

Organize by topic, not by date. "Architecture decisions" is better than "Session notes 2026-02-15". When new information arrives, integrate it into the appropriate topic rather than appending chronologically.

Concise Index, Detailed Topics

MEMORY.md answers "what do I need to know right now?" Topic files answer "what are all the details about X?" Keep the index scannable — use bullet points, tables, and bold for key terms.

Topic File Index Table

Always include a table in MEMORY.md linking to topic files with guidance on when to consult each:

## Topic Files

| File | When to consult |
|------|----------------|
| `architecture.md` | Working on system design, component changes |
| `patterns.md` | Writing new code, reviewing conventions |
| `debugging.md` | Investigating bugs, error messages |

One Topic Per File

Each file covers one domain. If a file grows beyond ~5,000 words or covers multiple unrelated topics, split it. A file named misc.md or notes.md is a sign of poor organization.

Maintenance

When to Update

• After discovering a mistake that could recur
• When a pattern is confirmed across 2+ interactions
• When the user explicitly asks to remember something
• After resolving a tricky bug worth documenting
• When project structure changes significantly

When to Remove or Edit

• When stored information becomes outdated (version bumps, removed features)
• When a gotcha is fixed and no longer relevant
• When the user asks to forget something
• When MEMORY.md exceeds ~200 lines — prune or move detail to topic files

Avoiding Drift

Periodically review memory files against the actual project state. Stale entries (wrong counts, outdated paths, fixed bugs still listed as open) erode trust in the memory system. Mark fixed issues as fixed rather than deleting them — the history of what went wrong is itself valuable.

Additional Resources

Reference Files

For detailed patterns, anti-patterns, and advanced techniques:

• references/patterns.md — Writing style guide, MEMORY.md structure patterns, topic file patterns, common anti-patterns

Example Files

Working examples ready to adapt:

• examples/MEMORY.md — Starter MEMORY.md template
• examples/topic-file.md — Topic file template with recommended structure