Claude Code Memory: Auto-Memory vs CLAUDE.md Explained
Claude Code uses two distinct memory layers: ephemeral conversation memory that resets when a session ends, and persistent CLAUDE.md files that are loaded automatically at every session start. Understanding the difference determines whether your project context survives between sessions — or disappears the moment you close the terminal. For real-world CLAUDE.md examples, see How to Write Effective CLAUDE.md Files.
The Two Memory Types
Conversation Memory (Ephemeral)
Everything Claude learns during a session — the shape of your codebase, coding preferences you mentioned, debugging context — lives in the active context window. When you type /exit or close the terminal, that memory is gone. The next session starts fresh.
This ephemeral layer is powerful for within-session work. Claude can hold up to 200K tokens of context, enough to reason across large codebases. But it does not persist.
CLAUDE.md (Persistent)
CLAUDE.md files are Markdown documents that Claude Code reads automatically when a session starts. They inject persistent context into every conversation — before you type your first prompt. Think of them as a briefing document Claude always reads before getting to work.
Claude Code looks for CLAUDE.md in several locations, in order of precedence:
~/.claude/CLAUDE.md— global user preferences applied to all projects<project-root>/CLAUDE.md— project-level context<subdirectory>/CLAUDE.md— directory-specific context (useful in monorepos)
All discovered files are concatenated and injected at session start. Lower-level files do not override higher-level ones; they supplement them.
How Claude Code Reads CLAUDE.md at Session Start
When you run claude in a directory, the startup sequence is:
- Claude Code walks up the directory tree, collecting all CLAUDE.md files it finds.
- It also reads the global
~/.claude/CLAUDE.md. - All collected content is prepended to the system prompt as persistent context.
- Your first user message follows.
This happens before any tool calls. The result is that Claude enters the session already knowing your project's conventions, constraints, and preferences.
Auto-Memory: How Claude Code Writes Back to CLAUDE.md
Auto-memory is Claude Code's ability to update your CLAUDE.md files during a session. When Claude discovers something worth remembering — a project convention you clarify, a dependency constraint, a recurring preference — it can write that information back to CLAUDE.md so future sessions inherit it.
Auto-memory writes happen through the standard file-editing tools. Claude will either:
- Propose a specific addition to CLAUDE.md and ask for approval, or
- Write it automatically if you have granted broad file-edit permissions.
To encourage auto-memory, you can add an explicit instruction in your CLAUDE.md:
## Memory Policy
When you discover a project convention, preference, or constraint during this session
that is not already documented here, add it to the "Project Notes" section below.
This turns CLAUDE.md into a living document that improves across sessions.
What to Put in CLAUDE.md vs. Leave in Conversation
Put in CLAUDE.md:
- Project tech stack and versions (
Next.js 15, React 19, TypeScript strict mode) - Code style rules that differ from defaults (tab width, import order, naming conventions)
- Architecture decisions that affect how Claude should reason (
all API routes live in /app/api/,state management via Zustand, not Redux) - Constraints Claude should never violate (
never commit directly to main,never modify /legacy/) - Frequently used commands (
npm run dev,npm run typecheck,npx prisma db push) - Context about non-obvious file relationships
Leave in conversation:
- One-off debugging context for the current session
- Temporary task framing ("today we're migrating the auth module")
- Exploratory questions that don't represent settled decisions
- Large code dumps you want Claude to analyze once
A well-maintained CLAUDE.md surfaces the 5% of project knowledge that applies to 80% of Claude's decisions.
Per-Directory CLAUDE.md for Monorepos
In a monorepo, a single root CLAUDE.md is often too coarse. You can place CLAUDE.md files in individual packages:
/monorepo
├── CLAUDE.md # Root: shared conventions, repo-wide tooling
├── packages/
│ ├── api/
│ │ └── CLAUDE.md # API-specific: DB schema, route conventions
│ └── web/
│ └── CLAUDE.md # Frontend-specific: component patterns, CSS approach
When you run Claude Code inside /packages/api/, it reads all three files. When you run it from the root, it reads the root file plus any subdirectory files it finds relevant.
This layering lets teams maintain targeted context per service without contaminating unrelated packages.
Memory Limits and What Gets Forgotten
CLAUDE.md files are injected into the context window, so they count against the 200K token limit. Practical limits:
- Keep each CLAUDE.md under 2,000 tokens (roughly 1,500 words) to leave headroom for actual work.
- Remove outdated entries. Stale entries are worse than no entries — they actively mislead Claude.
- For very large projects, split context across directory-level CLAUDE.md files rather than cramming everything into the root.
What gets forgotten regardless of CLAUDE.md:
- The actual code Claude read during a previous session (it re-reads files each session)
- Intermediate reasoning steps and debugging traces
- Any context from a parallel session running in a different terminal
Practical Example: CLAUDE.md for a Next.js Project
Here is a well-structured CLAUDE.md for a Next.js 15 application:
# Project: Acme SaaS
## Stack
- Next.js 15 (App Router), React 19, TypeScript (strict), Tailwind CSS 4
- Database: PostgreSQL via Prisma ORM (schema at /prisma/schema.prisma)
- Auth: NextAuth v5 (config at /app/api/auth/[...nextauth]/route.ts)
- State: Zustand for client state, React Query for server state
- Payments: Stripe (webhook handler at /app/api/stripe/webhook/route.ts)
## Conventions
- Components: PascalCase, colocated with their tests (`Button.tsx` + `Button.test.tsx`)
- API routes: return `{ data, error }` shape always
- Environment variables: validated by Zod at startup (see /lib/env.ts)
- Database: never use raw SQL — always Prisma client
- Branch naming: `feat/`, `fix/`, `chore/` prefixes
## Critical Constraints
- Never modify /legacy/ directory (deprecated, do not touch)
- Never commit API keys or secrets — use .env.local only
- All DB migrations must be reviewed before running in production
## Common Commands
- `npm run dev` — start dev server (port 3000)
- `npm run typecheck` — TypeScript type check (run before commits)
- `npx prisma studio` — open DB browser
- `npm run test` — run Vitest suite
## Project Notes
(Claude: add discovered conventions here for future sessions)
This CLAUDE.md gives Claude everything needed to contribute effectively from session one, without lengthy orientation prompts.
FAQ
Q: Can I have multiple CLAUDE.md files in the same directory? No. Claude Code reads one CLAUDE.md per directory. Use clear sections within a single file to organize different topic areas.
Q: Does CLAUDE.md content count as tokens I pay for? Yes. CLAUDE.md content is injected into each session's context window and billed as input tokens. Keep files concise to manage costs.
Q: Can I prevent Claude from modifying CLAUDE.md automatically?
Yes. Set restrictive file-write permissions in your .claude/settings.json to require approval for writes to CLAUDE.md, or simply do not include auto-memory instructions in your file.
Q: What happens if CLAUDE.md has conflicting instructions with my prompt? CLAUDE.md is part of the system context. In practice, explicit instructions in your message will override passive CLAUDE.md context, but CLAUDE.md establishes strong defaults. Keep CLAUDE.md focused on stable conventions, not dynamic session guidance.
Q: Is there a way to disable CLAUDE.md loading?
You can pass --no-claude-md at startup if you want a clean session without project context. Useful for isolated experiments. For all available startup flags, see the Claude Code CLI Commands reference.
Sources
- Anthropic Claude Code documentation — Memory and Context
- Claude Code settings reference
- CLAUDE.md best practices — Anthropic
→ Get Claude Code Power Prompts 300 — $29
300 production-ready prompts covering memory management, CLAUDE.md templates, and session workflows — everything you need to get consistent results from Claude Code across projects.