The Memory System

Right now, your Claude Code setup has two kinds of knowledge:

1. CLAUDE.md — your preferences, behaviour rules, work domain. Loaded every session.
2. Skills — structured instructions for specific tasks. Loaded when invoked.

Both are things you wrote in advance. They're static. Claude reads them but doesn't add to them.

Here's what's missing: the things that emerge during work. A decision you made last Tuesday about how to structure a project. Feedback you gave Claude about how you prefer error messages formatted. A reference URL you'll need again in three weeks. The name of a colleague Claude should know about.

Without memory, this knowledge evaporates when the session ends. Next session, you explain it again. And again.

Memory changes this. It gives Claude a place to store and retrieve information across sessions — things you tell it to remember, patterns it notices about your work, project context that accumulates over time.

Here's how the whole system flows:

  Session start
  ─────────────

  MEMORY.md (index)  ──────▶  Claude reads titles
  lightweight, ~20 lines           knows what memories exist

  ─────────────────────────────────────────────────────────

  During conversation
  ────────────────────

  You say: "Remember that I     Claude creates:
   prefer tables over bullets"    ┌─────────────────────┐
                                  │ feedback_tables.md  │
                                  │ type: feedback      │
                                  │ "prefer tables..."  │
                                  └──────────┬──────────┘
                                             │
                                             ▼
                                  updates MEMORY.md index

  ─────────────────────────────────────────────────────────

  Next session
  ────────────

  You ask for a comparison   ──▶  Claude checks MEMORY.md
                                  finds: feedback_tables.md
                                  reads it, uses a table

  Four types: user · feedback · project · reference

Claude Code has a built-in memory system using simple files stored alongside each project. It's on by default — Claude automatically saves useful notes for itself (build commands, debugging insights, your preferences) as you work. You can also tell it to remember specific things.

Memory is a folder of plain text files, each containing one piece of information. Claude reads a table of contents of these files at the start of every session (lightweight — just the list, not every file's content). When it needs specific information, it reads the relevant file.

When you tell Claude to remember something, it creates a new memory file and adds it to the index. When you tell it to forget something, it removes it.

That's the core mechanism. The setup prompt configures all of this for you. Here's what it creates and how it works.

The folder structure

Claude Code's auto-memory uses a project-scoped memory directory. It stores memories in:

~/.claude/projects/[your-project-path]/memory/

The main file is MEMORY.md — an index that lists all your memories with short descriptions. Claude reads this file at session start. Individual memories are stored as separate files in the same directory.

Memory types

Claude's auto-memory is free-form — Claude decides what to save and how to organise it. But we recommend sorting memories into four types, which helps keep things findable as your memory grows:

Creating memories

In any Claude Code session, you can say:

Remember that I prefer tables over bullet lists for comparison content.

Claude creates a memory file with this information, categorises it (this would be a "feedback" type), and adds it to the MEMORY.md index. Next session, Claude knows this.

You can also be more explicit:

Remember: our deployment pipeline requires approval from the platform team
for any changes to the auth service. This was decided after the February incident.

Claude stores this as a project memory with the context about why.

Retrieving memories

Claude automatically checks relevant memories when they might be useful. But you can also ask directly:

What do you remember about our deployment process?

Claude searches its memory and returns what it finds.

Forgetting

Forget what you know about the old deployment process — we changed it last week.

Claude finds the relevant memory and removes it.

The MEMORY.md file is the table of contents for Claude's memory. It's loaded into every conversation, so it needs to stay concise. Here's what a healthy MEMORY.md looks like:

# Memory

## User
- [User role and context](memory/user_role.md): Freelance content writer, works with small businesses
- [Communication preferences](memory/user_communication.md): Concise suggestions, no filler, show trade-offs

## Feedback
- [Editing approach](memory/feedback_editing.md): Fix the specific thing I ask about, don't rewrite whole paragraphs
- [Response style](memory/feedback_style.md): No trailing summaries, no "Great question!"

## Projects
- [GreenLeaf proposal](memory/project_greenleaf.md): Due March 20, casual tone, eco-friendly brand
- [Blog migration](memory/project_blog.md): Moving to new WordPress theme, don't touch pre-January posts

## Reference
- [Client brand files](memory/reference_brands.md): GreenLeaf guidelines in shared Google Drive
- [Invoice template](memory/reference_invoicing.md): Zoho template at ~/Documents/invoice-template.docx

Each line is a pointer to a detailed memory file. Claude reads the index to know what memories exist, then reads specific files when they're relevant to the current task. This keeps token cost low — the index is typically 200-400 tokens, and individual memories are only loaded when needed.

Memory grows over time. Without maintenance, it becomes cluttered with outdated information — old project decisions, completed tasks, feedback that's already been incorporated into your CLAUDE.md.

A few habits to keep it useful:

Review quarterly. Skim through your MEMORY.md and ask: is this still true? Is this still relevant? Remove anything that's outdated.

Move stable patterns to CLAUDE.md. If a feedback memory has been useful for months ("always use British English"), it belongs in your CLAUDE.md where it's loaded directly, not in memory where it has to be searched.

Keep the index under 200 lines. After 200 lines, the token cost of loading the index starts to add up. If you're approaching that, it's time to clean up.

Date your project memories. Projects change. Date them so you know when to clean them out.

Let's be clear about the boundaries:

Memory is for the things that aren't written down anywhere else. The decisions, preferences, context, and corrections that would otherwise exist only in your head — and that Claude needs to know to work well with you.

Let's quantify it:

• MEMORY.md index (loaded every session): ~200-400 tokens depending on how many memories you have
• Individual memory files (loaded on demand): ~50-150 tokens each, only when relevant
• Typical session: index + 1-2 relevant memories = ~400-700 tokens

Compare this to the alternative: manually re-explaining context every session, which easily costs 500-1,000 tokens and often requires multiple rounds of clarification.

Memory pays for itself from the first session where Claude remembers something you would have had to re-explain.

Claude now has a memory that persists. Your preferences, your project context, your feedback — it all carries forward. Combined with the CLAUDE.md (how to behave), skills (how to perform tasks), and hooks (what to automate), your Claude Code setup is starting to feel less like a tool and more like a colleague who's been with you for a while.

One major piece left: agents. Module 9 gives Claude a team.