Auto memory

CLAUDE.md tells the agent about your project. But what about you? Your preferences, your feedback, the corrections you've given across dozens of sessions — where does that go?

That's what auto memory is for. It's Claude's built-in persistence layer across conversations.

Where memory lives

Every time Claude remembers something about you or your project, it writes to a specific directory:

~/.claude/
  projects/
    {project-hash}/
      memory/
        MEMORY.md              # Index file (max 200 lines)
        user_role.md           # Who you are
        feedback_preferences.md  # How you like things done
        project_identity.md    # What this project is
        reference_blog.md      # External system pointers

The {project-hash} is derived from your project path. Each project gets its own memory space. Memories don't leak between projects.

MEMORY.md is the index — it lists all memory files with a one-line description of each. This is what Claude reads at the start of a session to decide which memories are relevant. It has a hard limit of 200 lines.

Memory types

Each memory file has a type that determines when it's loaded:

Here's what a real memory file looks like:

# Feedback: Preferences
 
- Communication style: direct, no fluff, no emojis
- Code: functional components, named exports for utilities
- Content tone: first person ("I"), address reader as "you"
- Never use third person when writing about the user
- Prefer Tailwind over CSS modules

Short, specific, actionable. Each line is something Claude can directly apply.

When memory is useful

Memory shines for things that are true about you across sessions but aren't part of the codebase:

• Your role: "I'm a senior React Native engineer" — so Claude calibrates complexity accordingly
• Your corrections: "I told you last week to stop using class components" — so it doesn't repeat the mistake
• Sprint context: "We're focused on the payment flow this week" — so Claude prioritizes relevant work
• External references: "Bug tracking is in Linear project X" — so Claude can reference the right system

These are things the agent can't learn from reading your code. They're personal or temporal. That's exactly where memory belongs.

When memory is NOT useful

This is where people go wrong. They try to put everything in memory, and it becomes a dump.

Things that should NOT be memories:

• Code patterns — the agent reads the code. It can see your patterns.
• Git history — the agent has git log. It can see what changed.
• Debugging solutions — the fix is in the code. The test proves it works.
• Architecture decisions — these belong in CLAUDE.md where every session loads them.
• Import rules — CLAUDE.md. Every time.

I've seen setups with 50+ memory files. That's a red flag. If you need that many memories, you're putting structure in memory that should be in CLAUDE.md or your codebase itself.

The key distinction: CLAUDE.md vs memory

This is the most important thing to understand about configuration in Claude Code:

| | CLAUDE.md | Auto Memory | |---|---|---| | Loaded | Every session, always | When relevant to the conversation | | Scope | Project-wide | Personal or temporal | | Content | Commands, structure, boundaries, anti-patterns | Role, preferences, corrections, sprint context | | Lifespan | As long as the project exists | As long as it's relevant | | Shared | Checked into git, shared with team | Local to your machine |

If you're unsure where something goes, ask: "Would a teammate need this?" If yes, CLAUDE.md. If it's just about you, memory.

Session persistence: the power-user version

Auto memory is the default persistence mechanism. But advanced setups go further.

Claude Code supports hooks — scripts that run at specific lifecycle events. Three of them are relevant to persistence:

{
  "SessionStart": [
    { "command": "cat .claude/session-state.json" }
  ],
  "PreCompact": [
    { "command": ".claude/scripts/save-session.sh" }
  ],
  "SessionStop": [
    { "command": ".claude/scripts/save-session.sh" }
  ]
}

This pattern saves structured session state before the context window gets compacted and when the session ends. On the next session start, that state gets loaded back in.

It's the power-user version of memory — automatic, structured, and it survives context compaction. We'll cover hooks in detail in Chapter 5. For now, know that this exists and that auto memory is the foundation it builds on.

Practical guidelines

Keep your memory system lean. Here's what I recommend:

1. Start with zero memories. Let them accumulate naturally through corrections and feedback.
2. Review quarterly. Open your MEMORY.md. Delete anything that's no longer true or relevant.
3. Watch for drift. If memory says "we use REST" but you migrated to TRPC, the agent gets conflicting signals.
4. Keep MEMORY.md under 100 lines. The 200-line limit is a ceiling, not a target.

Memory is a supporting tool. CLAUDE.md and your codebase do the heavy lifting. Memory fills in the gaps — who you are, how you like things done, what you've already corrected. Keep it small, keep it accurate, and let the code speak for itself.