This chapter teaches you how to save context between sessions so Claude never starts from scratch. The difference between an assistant that forgets everything and a real dev partner. Reading time: 7 minutes.
The problem
Every new conversation with Claude Code starts from scratch. It re-reads CLAUDE.md (the general conventions), but it doesn't know:
- Which architectural decisions you made yesterday
- Which bugs you ran into and how you solved them
- Which patterns work well in your specific project
- Where you are in your roadmap
- Which choices were dropped and why
Concrete result: Claude can repeat the same mistakes, suggest approaches that contradict previous sessions, and waste time rediscovering context.
The solution: the MEMORY.md file
Claude Code maintains a persistent memory file that survives between sessions. Don't confuse it with CLAUDE.md:
CLAUDE.md | MEMORY.md |
|---|---|
| General, permanent conventions | Specific learnings that evolve |
| "We use Supabase for the DB" | "The redirect() bug in try/catch was solved on 02/28" |
| Rarely changes | Updated after every productive session |
| You create it at the start of the project | Claude updates it progressively |
How it works
Automatic memory (default)
Claude Code ships with a native auto-memory system. It automatically maintains a MEMORY.md file in ~/.claude/projects/ (not at the project root). Claude updates it on its own when it judges a learning worth saving.
Nothing to configure, it's active from the very first session.
Manual update
You can also trigger an explicit update at the end of a session:
"Update the project memory with the decisions and learnings from this session."
Claude adds the new info without duplicating what's already there.
In practice: Claude automatically saves confirmed patterns, resolved errors, and important decisions. You can ask it to "update the memory" to force a save, but it does it spontaneously too.
What MEMORY.md contains
Anthropic's official system is minimal: a single MEMORY.md file acting as an index. You're free to structure it however you want. Here are the 4 sections I personally use.
Personal convention, not an Anthropic rule: the taxonomy below (user /
feedback / project / reference) is my own way of organizing memory. Anthropic
only mandates a MEMORY.md file as the entry point. You can ignore this
structure entirely and write your memory as free prose if that works better
for you.
1. Confirmed patterns
The technical patterns that work well and should be reused:
## Confirmed patterns
- Server Actions with Zod validation: standard pattern for all mutations
- Forms: react-hook-form + zodResolver + shadcn/ui components
- AI streaming: useChat + POST api route with sdk.messages.stream()
- Rate limiting: check rateLimit() before every AI call
2. Architectural decisions
The choices made and the reasoning behind them (so you don't second-guess them):
## Decisions
- Weekly streak (not daily): freelancers don't have time to publish every day
- Scoring on 4 axes (not 5): reduces UX complexity without losing accuracy
- No push notifications: too costly to maintain for the project's size
3. Common errors and solutions
The bugs you ran into and their fixes (so you don't redo them):
## Resolved errors
- redirect() inside try/catch → Next.js throws a NEXT_REDIRECT, you have to catch it specifically
- supabase db reset destroys all data → always use migration up
- cookies() must be called with await in Next.js 15+
4. Progress status
Where the project stands and what the next priorities are:
## Progress
- Authentication: ✅ done
- Dashboard: ✅ done
- Content generation: ✅ done
- Stripe payment: 🟡 in progress
- Analytics: ⏳ to do
The concrete impact
Without memory, every session: Claude starts from scratch and wastes 5-10 minutes rediscovering context. It might suggest a daily streak when you decided weekly yesterday. It redoes the same bug you already fixed (redirect inside try/catch). It doesn't know which features are done and which are still left.
With memory, every session: Claude knows exactly where you are ("I see Stripe payment is in progress. Should we keep going?"). It reuses confirmed patterns without you having to re-spec them. It proactively avoids errors it's already encountered and stays consistent with past decisions.
Best practices
When to update
- After every productive session (2+ features shipped)
- After a tough bug is solved (so you don't redo it)
- After an important architectural decision (to justify it)
- No need if the session was just a small fix or a cosmetic tweak
What NOT to put in
- Temporary session details ("today I fixed a bug in...") too volatile
- Code or file snippets, code changes, memory should stay stable
- Unverified opinions, wait until you've confirmed a pattern across 2-3 uses before writing it down
Ideal size and the "index" pattern
MEMORY.md should stay under 200 lines (beyond that, Claude truncates). Target: 20-30 lines in "index" mode.
The index pattern: instead of putting every detail in MEMORY.md, turn it into a table of contents pointing to dedicated files per project:
memory/
├── MEMORY.md ← Index (~25 lines)
├── my-saas.md ← SaaS project details
├── client-poc.md ← Client POC details
└── side-project.md ← Side project details
MEMORY.md becomes a simple directory:
# Active projects
## My SaaS
- Path: /Users/me/code/my-saas
- Port: 3000
- Status: Phase 2 in progress
- Details: see my-saas.md
## Client POC
- Path: /Users/me/code/client-poc
- Port: 3001
- Status: Delivered
- Details: see client-poc.md
Claude loads the index every session (light, fast) and only reads the detail files when it needs them. Same logic as .claude/rules/ for CLAUDE.md.
Takeaway: "Update the project memory" is the phrase to say at the end of every productive session. 30 seconds that guarantee tomorrow, Claude picks up exactly where it left off.