Setting Up Claude Code Memory: Persistent Context Across Sessions

2026-03-07

By default, Claude Code starts each session fresh. It doesn't remember what you discussed yesterday, what decisions you made, or what it learned about your codebase. Memory changes that.

What is Claude Code memory?

Memory is a file-based persistence system that lets Claude store and recall information across sessions. When enabled, Claude writes memory files to disk and reads them at the start of each session.

It stores things like:

• Your preferences and working style
• Project context (who's working on what, why)
• Feedback you've given ("don't do X", "keep doing Y")
• Pointers to external resources

Where memory lives

Memory files are stored in:

~/.claude/projects/<project-path>/memory/

Each memory is a markdown file with frontmatter. There's also a MEMORY.md index file that lists all memories — this gets loaded into context at the start of each session.

Memory types

User memories

Information about you — your role, expertise, preferences.

---
name: user-role
description: Thomas is a senior fullstack developer who prefers functional patterns
type: user
---

Senior fullstack developer. Prefers functional programming patterns over OOP.
Deep experience with TypeScript and Python. New to Rust.

Feedback memories

Corrections and confirmations — what to do and what not to do.

---
name: feedback-no-default-exports
description: Always use named exports, never default exports
type: feedback
---

Use named exports, not default exports.

**Why:** Team convention for better refactoring support and IDE autocompletion.
**How to apply:** Every new file should use `export function` or `export const`, never `export default`.

Project memories

Context about ongoing work, decisions, deadlines.

---
name: project-auth-migration
description: Migrating from custom auth to Clerk, deadline May 15
type: project
---

Migrating authentication from custom JWT implementation to Clerk.

**Why:** Security audit flagged session token storage as non-compliant.
**How to apply:** All new auth code should use Clerk SDK. Don't extend the old auth system.

Reference memories

Pointers to external systems and resources.

---
name: ref-linear-project
description: Bug tracking is in Linear project BACKEND
type: reference
---

Backend bugs are tracked in Linear project "BACKEND".
Frontend bugs are in "FRONTEND".
Design specs are in Figma at figma.com/team/our-project.

How to create memories

Explicitly

Just tell Claude to remember something:

"Remember that we always use Zod for validation in this project."

Claude will create the appropriate memory file and add it to the index.

Automatically

Claude Code's auto-memory system watches for moments worth remembering:

• When you correct Claude's approach
• When you share context about your role or the project
• When you confirm a non-obvious approach worked

You can disable this by configuring the memory settings, or use hooks to run custom logic when sessions start.

Tips for effective memory

Keep memories atomic. One fact per file. "Auth uses Clerk and we deploy to Vercel" should be two memories, not one.

Prune regularly. Memories go stale. If a project memory references a migration that's done, delete it. Stale memories cause confusion.

Use feedback memories liberally. Every time you correct Claude and think "I don't want to say this again," that's a feedback memory. These are the highest-value memories because they directly shape behavior.

Don't duplicate CLAUDE.md. If something belongs in CLAUDE.md (coding conventions, build commands), put it there. Memory is for things that aren't derivable from the code — your preferences, project context, external references.

Check what Claude remembers. Ask "what do you remember about this project?" at the start of a session — or use plan mode — to verify memory is working and nothing is stale.

Memory vs CLAUDE.md

Use both. CLAUDE.md is the team playbook. Memory is Claude's personal notes about working with you on this project.