Auto Memory: How Claude Remembers Across Sessions
Claude Code's context window resets between sessions — but auto memory persists what matters to disk. This article explains the ~/.claude/projects/ directory structure, the four memory types, MEMORY.md as the index, and how to instruct Claude to remember or forget anything.
Quick Reference
- →Memory files live in ~/.claude/projects/{encoded-project-path}/memory/
- →MEMORY.md is the index — always loaded at session start
- →Four types: user (who you are), feedback (how to work with you), project (context), reference (where to look)
- →Claude auto-saves memories when it learns something worth persisting
- →Trigger a save explicitly: 'remember that...' or 'from now on...'
- →Trigger a forget: 'forget that...' removes the relevant memory file
- →Memory files are plain Markdown — you can read, edit, and delete them directly
- →MEMORY.md is capped at ~200 lines — keep entries concise
In this article
The Problem Memory Solves
Every Claude Code session starts fresh. The context window is empty except for the automatic load sequence (system prompt, env info, CLAUDE.md files). Without a memory system, you would need to re-explain your role, preferences, and project context every session. For engineers who use Claude Code daily, that repetition is the difference between a tool that feels like a collaborator and one that feels like a stranger.
Auto memory solves this by persisting selected context to disk between sessions. When a new session starts, the MEMORY.md index is loaded and relevant memory files are made available. Claude starts the session already knowing that you prefer TypeScript strict mode, that the staging database is read-only, and that the team decided to avoid Redux.
The Memory Directory Structure
The directory name is the project path with slashes replaced by hyphens. Each project's memory is completely isolated — Claude Code doesn't cross-contaminate memories from one project into another session. User-level memories (preferences that apply everywhere) are stored in ~/.claude/CLAUDE.md, not in the project memory directory.
Every memory file is a Markdown file with YAML frontmatter. You can open them in any editor, edit them directly, add new ones manually, or delete ones that are no longer accurate. Claude doesn't own these files — you do.
The Four Memory Types
Auto memory uses four types, each with a different purpose and a different trigger for when Claude should save it:
| Type | What it stores | When it's saved |
|---|---|---|
| user | Your role, expertise level, preferences, working style | When Claude learns something about who you are |
| feedback | How to approach work — what to do and what to avoid | When you correct Claude's behavior OR confirm an approach worked |
| project | Ongoing work, decisions, constraints, deadlines | When Claude learns a non-obvious fact about the project |
| reference | Where to find information in external systems | When Claude learns the location of a resource (Linear board, Slack channel, dashboard) |
The best feedback memories include the reason behind the rule. 'Don't mock the database' is a rule. 'Don't mock the database — we got burned when mocked tests passed but the prod migration failed' is a rule Claude can apply intelligently to edge cases.
MEMORY.md: The Index That Always Loads
MEMORY.md is the single file that is always loaded at session start. It is an index, not a content file — each entry is a one-line pointer to a memory file, with a short description that helps Claude decide whether that memory is relevant to the current task.
Lines after 200 in MEMORY.md are truncated — they don't make it into context. Keep each index entry to one concise line. If you accumulate too many memories, archive or delete outdated ones rather than letting the index grow past 200 entries.
How to Instruct Claude to Remember or Forget
Claude saves memories automatically when it learns something worth persisting. But you can also trigger saves and deletions explicitly.
Trigger a save
Say 'remember that...' or 'from now on...' — Claude will create a memory file immediately. For example: 'Remember that our API uses cursor-based pagination, not offset.' or 'From now on, never use default exports in this project.'
Trigger a forget
Say 'forget that...' — Claude will find and remove the relevant memory file. For example: 'Forget that I said no default exports — we changed that convention last week.'
Edit manually
Open any file in ~/.claude/projects/{project}/memory/ with a text editor and modify it directly. This is the best way to correct a memory that Claude saved inaccurately.
Ask Claude to review memories
Ask Claude: 'What do you remember about this project?' It will read MEMORY.md and summarize what's stored. Good for auditing stale or incorrect memories.
A memory that names a function, file, or config key is a claim about what existed when the memory was written. Before acting on a memory, Claude (and you) should verify it is still accurate — file structures change, functions get renamed, decisions get reversed. If a memory conflicts with what Claude observes in the current codebase, trust the observation and update the memory.
What Not to Store in Memory
Auto memory is valuable precisely because it is selective. Storing too much makes the index noisy and the session start slower. The following belong in the codebase or git history, not in memory files:
- ▸Code patterns, conventions, and architecture — store in CLAUDE.md, not memory
- ▸Git history and who-changed-what — git log is authoritative and always current
- ▸Debugging solutions and fix recipes — the fix is in the code; the commit message has context
- ▸Anything already documented in CLAUDE.md files — no duplication
- ▸Ephemeral task details that only matter for the current session
- ▸PR lists, activity summaries, or progress snapshots — git log has this
Best Practices
Do
- ✓Explicitly save important feedback after Claude makes a mistake you don't want repeated
- ✓Include 'why' in feedback memories — rules without reasons get misapplied at edge cases
- ✓Audit your memory files periodically — stale memories mislead as much as wrong code
- ✓Keep MEMORY.md index entries under one line and under 200 entries total
- ✓Store project context (key decisions, constraints) that is not obvious from reading the code
Don’t
- ✗Don't store code architecture or conventions in memory — those belong in CLAUDE.md
- ✗Don't store git history or change logs — git log is the authoritative source
- ✗Don't let the memory index grow past 200 entries — older, less-relevant memories should be archived
- ✗Don't trust a memory that names a specific file or function without verifying it still exists
Key Takeaways
- ✓Memory files live in ~/.claude/projects/{project}/memory/ — isolated per project
- ✓MEMORY.md is the always-loaded index that points to individual memory files
- ✓Four types: user (who you are), feedback (how to work), project (context), reference (where to look)
- ✓Trigger saves with 'remember that...' and deletions with 'forget that...'
- ✓Memory files are plain Markdown — edit and delete them directly to correct stale information
Video on this topic
Claude Code Auto Memory: Never Re-Explain Your Project Again
tiktok