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.

Claude Code has a built-in memory mechanism using project-scoped files. It's simpler than you might expect.

Memory is a folder of markdown files, each containing one piece of information. Claude reads an index 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. Let's set it up.

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

There are four types of memory, each for a different kind of information:

User memories — facts about you that help Claude tailor its behaviour.

"Priya is a freelance content writer. Prefers concise suggestions with trade-offs."

"Main tools: Google Docs, Canva, and WordPress."

Feedback memories — corrections you've given Claude that should persist.

"Don't rewrite my entire paragraph when I ask for a tweak — just fix the specific thing."

"Stop summarising what you just did at the end of every response."

Project memories — context about ongoing work.

"Client proposal for GreenLeaf is due March 20. They want a casual, friendly tone."

"Blog migration to new WordPress theme — don't touch any posts from before January."

Reference memories — pointers to external resources.

"Brand guidelines for GreenLeaf are in the shared Google Drive folder."

"Invoicing is done through Zoho — template is in ~/Documents/invoice-template.docx."

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 role and context: Freelance content writer, works with small businesses
• Communication preferences: Concise suggestions, no filler, show trade-offs

• Editing approach: Fix the specific thing I ask about, don't rewrite whole paragraphs
• Response style: No trailing summaries, no "Great question!"

• GreenLeaf proposal: Due March 20, casual tone, eco-friendly brand
• Blog migration: Moving to new WordPress theme, don't touch pre-January posts

• Client brand files: GreenLeaf guidelines in shared Google Drive
• Invoice template: 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. "Merge freeze begins March 5" is useful in February, confusing in June. Date them so you know when to clean them out.

Let's be clear about the boundaries:

Memory is not a database. Don't store large amounts of structured data. That's what files are for.

Memory is not version control. Don't use it to track code changes or file modifications. Git does that better.

Memory is not a task list. Don't store to-dos in memory. Claude Code has task tracking for that.

Memory is not documentation. Don't duplicate information that exists in your codebase. If it's in the code, Claude can read the code directly.

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.

For most people, the basic memory system above is plenty. But if you want to go further, there's a more powerful approach: a knowledge graph.

A knowledge graph connects memories to each other. Instead of isolated facts ("Ronit prefers British English" and "Auth rewrite is compliance-driven"), a knowledge graph creates relationships ("The auth rewrite affects the deployment process, which requires platform team approval").

Setting this up requires some technical infrastructure:

• A Python script that manages memory entries as structured data
• A search mechanism that can find relevant memories by topic (not just by file name)
• A summarisation layer that can condense old sessions into key learnings

This is the setup we use ourselves. It's powerful — Claude can draw on a rich web of interconnected knowledge to make better decisions and avoid repeating mistakes.

The honest assessment: A full knowledge graph is overkill for most users. The basic memory system handles 90% of use cases. If you find yourself thinking "I wish Claude could connect these two pieces of context," that's when to consider upgrading. Until then, the flat file system is simpler and works well.

If you ran the one-shot setup prompt, you were offered the knowledge graph as an optional add-on at the end. If you skipped it then, you can always add it later — just ask Claude Code to set up a memory search script in ~/.claude/scripts/memory/. It requires Python, but the setup is straightforward.

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.