Did Claude make the same mistake today that you corrected last week? Here's
how its memory works between two sessions, where it's stored, how to fix it,
and what belongs in CLAUDE.md instead.
The problem
Every new conversation with Claude Code starts from zero. It rereads CLAUDE.md (your conventions), but without memory it doesn't know:
- What decisions you made yesterday and why
- What corrections you've already given it ("no, not like that")
- Who you are, how you like to work
- Where you are on your roadmap
The result: it brings back an approach you ruled out last week, or repeats the mistake you just corrected.
How auto memory works
Notes Claude writes itself, for itself, while you work: a correction you gave it, a decision, something about you. They're stored outside your repo, one note per file, with an index reread at the start of every session. On by default locally, nothing to configure.
Claude doesn't write everything down. It skips what it can find again by reading the code or the git history (the architecture, file paths, the details of a fix), and what your CLAUDE.md already says. It doesn't save every session either: only what seems useful for a future conversation. When it does, you see "Saved 2 memories" or "Recalled 2 memories" go by.
Where it's stored
Not in your project. In your home folder:
~/.claude/projects/<your-project>/memory/
├── MEMORY.md ← the index, loaded every session
├── feedback-no-push-without-approval.md
├── project-weekly-streak.md
└── reference-supabase-dashboard.md
One folder per git repo: all worktrees and subfolders of the same repo share the same memory. It stays on your machine, it doesn't follow you to another computer or to the cloud.
Two levels:
MEMORY.mdis an index: one line per memory, with a link to its file. Claude Code loads it at the start of every session, up to the first 200 lines or 25 KB.- One file per memory, with a frontmatter (the block between
---at the top of the file). Claude only opens it when the topic comes back up.
Here's the format I find in my own files:
---
name: feedback-no-push-without-approval
description: Never push to main without explicit approval
metadata:
type: feedback
modified: 2026-09-12T16:19:02.230Z
---
Correction from September 12: Claude pushed a fix straight to main.
Rule: always ask before a git push, even for a one-line fix.
The official docs don't lock down this whole format. They guarantee two things: the memory's type is recorded in a type field in the frontmatter, and Claude Code adds a modified timestamp on every write (since v2.1.214), so Claude knows whether the information is fresh.
And the matching line in MEMORY.md:
- [No push without approval](feedback-no-push-without-approval.md): always ask before git push
The 4 types of memories
| Type | What it contains | Example |
|---|---|---|
user | Who you are, your level, your preferences | "Solo founder, prefers short answers, Next.js stack" |
feedback | The corrections you made, and the approaches you approve | "Never put redirect() inside a try/catch" |
project | A project's decisions and status, what the code doesn't say | "Weekly streak, not daily: freelancers don't publish every day" |
reference | Where to find what outside the project (dashboards, tickets) | "Prod logs are in project X's Vercel dashboard" |
Steering memory
Asking for an update
Claude saves on its own, but you can force it at the end of a session:
"Update the project memory with the decisions and learnings from this session."
Same logic when you correct Claude: "Remember this for next time" is enough, it files it in auto memory. Reread what it wrote, especially in the first few weeks.
Reviewing and fixing with /memory
/memory lists your CLAUDE.md files, turns auto memory on or off, and opens the memory folder in your editor. Do it every now and then: a wrong or outdated memory is worse than no memory, because Claude will apply it with confidence.
You can also open the ~/.claude/projects/<your-project>/memory/ folder directly. They're regular markdown files, edit or delete them as you like.
Turning memory off
The toggle in /memory saves the autoMemoryEnabled setting in ~/.claude/settings.json. For a single project, set "autoMemoryEnabled": false in the project's settings. The environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 also turns it off. Useful for a demo or a client project where you don't want to keep anything.
Memory, CLAUDE.md or rules?
Claude finds instructions in three places. They don't play the same role.
| Where | Who writes it | What goes in it | Loaded when |
|---|---|---|---|
CLAUDE.md | You (or Claude when you ask) | Stable conventions: stack, structure, team rules | Every session |
.claude/rules/*.md | You | Rules for a specific domain, with paths: to target folders | Every session, or only on the files targeted by paths: |
| Auto memory | Claude, mostly | What was learned along the way: corrections, decisions, status | The index every session, the details on demand |
The test: a stable rule that applies to the whole team goes in CLAUDE.md. If it only concerns SQL migrations, make it a rule. What Claude learns along the way stays in memory.
An important rule that's been sitting in memory for weeks deserves to move up into CLAUDE.md. Just ask Claude: "Add this rule to the project's CLAUDE.md." The memory file is personal and not versioned: your colleagues don't benefit from it.
Subagents don't load your main conversation's memory. Only a fork (a copy of your conversation) inherits it.
No CLAUDE.md but an AGENTS.md? Since v2.1.277 (September 18, 2026), Claude
Code reads the AGENTS.md file (the format shared by other AI coding tools)
when the project has no CLAUDE.md. See chapter
3.
What not to put in it
- Short-lived session details ("today I fixed a bug in...")
- Code or file excerpts: code changes, memory should stay stable
- An opinion you haven't checked yet. Wait until you've confirmed a pattern over 2 or 3 uses
- Never secrets (API keys, passwords), memory is a plain text file
What it costs
MEMORY.md is part of the project context Claude Code sends with every message, right after the system prompt and alongside CLAUDE.md. Thanks to the cache, that block is read back for almost nothing as long as you don't take too long a break. But it's reread on every turn, and it takes up room in your context.
Hence the rule: a short index. One line per memory, 20 to 50 lines in total, the details in the files. Past 200 lines or 25 KB, the end isn't loaded. Claude Code actually warns Claude when the index gets close to the limit, so it can shorten it. Clean up with /memory.
Chapter 19 explains how context and cache show up on your bill.
Question
Your MEMORY.md is 320 lines long (under 25 KB). What does Claude Code load at the start of a session?
Pick an answer to see the explanation.
Key takeaways
- Auto memory runs by default, in
~/.claude/projects/<your-project>/memory/, without leaving your machine. Your colleagues don't see it: a team rule goes inCLAUDE.md. MEMORY.mdis only an index. Past 200 lines or 25 KB, the end gets dropped, so aim for 20 to 50 lines.- At the end of a productive session: "Update the project memory". And
/memoryevery now and then to review and fix.