The Memory System

Why Memory Matters

Every time you start a new Claude Code session, it begins with a blank slate. Without memory, you spend the first few minutes of every conversation re-explaining who you are, what you're working on, and how you like things done.

The memory system fixes this. It gives Claude Code a structured way to remember you, your projects, and your preferences across sessions. Think of it as building a relationship with your tool instead of meeting a stranger every time.

The Two Memory Systems

Claude Code has two complementary memory systems. Understanding both is the key to a great experience.

1. CLAUDE.md (You Write It)

CLAUDE.md files are instructions you write for Claude. They tell it about your project, your preferences, and your rules.

All CLAUDE.md files load automatically at session start. Subdirectory CLAUDE.md files load lazily when Claude reads files in that directory.

2. Auto Memory (Claude Writes It)

Auto memory is Claude writing notes to itself. When it discovers something important: your preferred build command, a debugging insight, an architecture decision: it saves it for next time. This is on by default.

Auto memory is what makes Claude get better over time without you doing anything. It notices patterns, saves corrections, and builds context automatically.

What About Config?

Config files (.claude/settings.json) are separate from memory. They control technical settings: which tools are allowed, model preferences, permissions. Memory is knowledge. Config is plumbing.

Organizing Your Memory (Recommended Pattern)

Auto memory creates topic files organically. But if you want more structure, especially for teams or complex setups, here's a four-category pattern that works well in practice:

1. User Memory

Who you are and what you care about.

• Your role (frontend developer, PM, full-stack engineer)
• Your goals ("I'm building a SaaS product", "I'm learning React")
• Your preferences: coding style, communication style, tools you use
• Your team context: who you work with, what they own

A user_role.md file might say: "Senior PM at an EdTech company. Manages 3 squads. Prefers bullet points over paragraphs. Hates em dashes."

2. Feedback Memory

Corrections you've given Claude Code over time.

• "Don't suppress lint rules as a fix, rethink the solution"
• "Always use relative paths, never absolute paths with usernames"
• "Her name is Viveca, not Viveka"

This is the most powerful category. Every correction you make gets saved, and Claude Code stops making that mistake. Auto memory captures many of these automatically, but explicit feedback files give you more control.

3. Project Memory

What you're actively working on.

• Project names, tech stacks, and current status
• Key decisions and their rationale
• Architecture notes and patterns specific to each project
• Links to relevant repos, boards, or documents

A project_heimdall.md file, for example, tracks an ad server replacement project: its version, test count, team members, and related design documents.

4. Reference Memory

Where to find things in external systems.

• API endpoints and credential locations (never the actual secrets)
• Folder structures and file conventions
• Tool configurations: CI/CD, deployment, monitoring
• Team ownership maps

This prevents Claude Code from guessing where things live. Instead of searching your codebase every time, it knows exactly where to look.

How Memory is Structured

Memory lives in ~/.claude/projects/<project>/memory/ for each git repo:

Each topic file is a small Markdown file with frontmatter (name, description, type) and focused content. Keep them short. One topic per file.

MEMORY.md acts as a table of contents. Claude reads it at the start of every session, then loads individual topic files when they're relevant. If you use the four-category pattern, you might have files like user_role.md, feedback_no_em_dashes.md, project_heimdall.md, or reference_api_endpoints.md.

The /memory Command

The /memory command is your dashboard for everything memory-related. Run it to:

• See all loaded context: every CLAUDE.md, CLAUDE.local.md, and rules file currently active
• Toggle auto memory on or off for the current project
• Browse memory files: get a link to open the memory folder
• Open files in your editor: quickly edit any memory file

You don't need to run /memory to use memory. It loads automatically. This command is for when you want to inspect, toggle, or edit what's there.

What NOT to Save

Not everything belongs in memory:

• Code patterns and syntax: Claude Code already knows how to write code. Saving "how to write a React hook" is wasted space.
• Git history: It can read your git log directly. No need to duplicate it.
• Debugging solutions: One-off fixes that rarely repeat. Save the lesson, not the fix.
• Temporary context: If it won't matter next week, don't save it.

The rule of thumb: save things that change how Claude Code behaves, not things it can look up on its own.

The Compound Effect

Memory builds over time, and the returns accelerate.

Week 1: Sessions start faster. Claude Code knows your name, your projects, and your preferred coding style. You stop repeating "I'm working on Project X using Next.js."

Month 1: Claude Code stops making mistakes you've corrected before. It remembers that your teammate's name is spelled a specific way, that you never want any types in TypeScript, that you prefer colons over em dashes.

Month 3: Claude Code starts anticipating what you need. It knows which files to check first, which patterns your codebase uses, which team members own which systems. It feels less like a tool and more like a colleague who's been on your team for a while.

Getting Started Checklist

The simplest start: just use Claude Code. Auto memory is on by default. After a few sessions, run /memory to see what it's captured.

Want to go further? Build on top of auto memory:

• Run /memory to see what's already been saved automatically
• Write a CLAUDE.md in your project with your tech stack and coding rules
• Create a CLAUDE.local.md for personal preferences you don't want in Git
• Add a ~/.claude/CLAUDE.md with your role and global preferences
• After a correction, ask Claude to save it as a feedback memory
• Review your MEMORY.md index periodically and prune stale entries

You don't need to build the whole system at once. Auto memory handles the basics. The structured approach adds precision on top. The best memory systems are grown, not designed upfront.