This chapter teaches you how to save context between sessions so Claude never starts from scratch. That's what makes 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 make the same mistakes again, suggest approaches that contradict previous sessions, and waste time rediscovering context.
The solution: the MEMORY.md file
Claude Code can maintain a persistent memory file that survives between sessions. It's different from 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 now 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.
You don't have to configure anything, 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
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 to do
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 - It 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). Ideal: 20-30 lines in "index" mode.
The index pattern: instead of putting every detail in MEMORY.md, you 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.