Memory and Persistence in Claude Code: The Complete Guide (CLAUDE.md, MCP Memory, Sessions)

The biggest problem when you work with Claude Code daily is that every conversation starts from scratch. Claude doesn’t remember what you told it yesterday. It doesn’t know you prefer tabs over spaces, that your project uses Vitest instead of Jest, or that utils/auth.ts is a bug nest that shouldn’t be touched.

Unless you configure persistence correctly.

Claude Code offers four complementary persistence mechanisms, and most devs only use one (or none). This guide covers all four, explains when to use each, and gives you a decision tree so you never have to wonder again.

The 4 Persistence Mechanisms

1. CLAUDE.md: Permanent Instructions

The most basic and most powerful mechanism. The CLAUDE.md file at your project root is read by Claude Code at the start of every conversation. Everything in it is treated as a permanent instruction.

What to put in it:

Project conventions (stack, style, patterns)
Rules you never want to repeat (“always use server components”, “no any in TypeScript”)
Custom commands and their usage
Minimal business context for the project

What NOT to put in it:

Info that changes often (current tasks, active bugs)
Instructions that are too long (Claude has a token budget for context)
Sensitive data (the file is in the repo)

2. Memory Files: The Persistent Brain

Beyond CLAUDE.md, you can configure a file-based memory system. Claude Code can read and write to a dedicated folder (.claude/memory/ or equivalent) to store information that evolves over time.

Use cases:

User profile (who you are, your preferences, your level)
Accumulated feedback (“don’t do X anymore”, “keep doing Y”)
Project context (architectural decisions, contacts, deadlines)
External references (Notion links, dashboards, repos)

Advantage: Memories survive between conversations and get richer over time.

3. MCP Memory: The Knowledge Graph

MCP Memory is an MCP server that stores information as a knowledge graph. Unlike flat files, it enables relationships between entities and structured queries.

When to use it:

When you have many linked entities (people, projects, decisions)
When you want to query memory by relationship (“who decided X?”, “which projects are linked to Y?”)
When you work in a team and memory needs to be shared

When to skip it:

For a solo builder with simple needs, memory files are enough
If you don’t want to manage an additional MCP server

4. Session Storage: Conversation Context

During a conversation, Claude Code maintains a context that includes everything that happened: your messages, its responses, tool results. This context is automatic but ephemeral: it disappears when the conversation ends.

How to optimize it:

Use tasks (TodoWrite) to keep track in long conversations
Use plan mode for complex tasks (the plan persists within the conversation)
Be aware that context gets compressed as it approaches the limit

The Decision Tree

To know which mechanism to use, ask yourself:

Does this info need to survive between conversations?

No -> Session storage (automatic)
Yes -> Continue

Does this info rarely change?

Yes -> CLAUDE.md
No -> Continue

Does this info have complex relationships with other info?

Yes -> MCP Memory
No -> Memory files

The Most Common Mistakes

1. Putting Everything in CLAUDE.md

CLAUDE.md is read every conversation. If you put 500 lines of instructions in it, you consume tokens needlessly and dilute the important instructions. Keep CLAUDE.md for critical, invariant rules.

2. Never Cleaning Memory

Memory files and MCP Memory accumulate information. If you never clean up, you end up with outdated info that misleads Claude. Do a monthly cleanup.

3. Ignoring the CLAUDE.md Hierarchy

Claude Code reads CLAUDE.md at multiple levels: global (~/.claude/CLAUDE.md), project (root), and subdirectories. Use this hierarchy: global rules in the global file, project rules in the project file, specific rules in subdirectories.

4. Storing Secrets in Memory

Memory files are plaintext on disk. Never store tokens, passwords, or API keys in memory. Use environment variables.

My Recommended Config

For a solo builder:

Global CLAUDE.md: who you are, universal preferences, formatting rules
Project CLAUDE.md: stack, conventions, custom commands, business context
Memory files: detailed profile, feedback, contacts, external references
MCP Memory: optional, add if you manage many interconnected entities
Session: let Claude handle it, use tasks for long conversations

This guide is based on daily use of all 4 persistence mechanisms in Claude Code on production projects.