Claude Code has two ways of “remembering” things across sessions. They sound similar but serve very different purposes, and knowing which to use prevents the most common setup mistakes.
The one-line version
- CLAUDE.md is a file you write and commit — project facts, shared with the team.
- Memory is notes Claude keeps privately — patterns it learned about how you work.
CLAUDE.md — the team’s shared brain
A CLAUDE.md file sits in your project root (or in .claude/). Claude reads it at the start of every conversation. It’s where you put:
- Your stack and build commands (
npm test,cargo build) - Conventions (“prefer plain CSS over Tailwind”, “never edit /vendor”)
- Architecture notes (“the API layer is in src/server, the UI in src/components”)
# CLAUDE.md
This is a Next.js app. Run `npm test` before every commit.
Prefer plain CSS over Tailwind. Never edit files in /vendor.You author it. You commit it. Your whole team benefits. When a new person clones the repo, their Claude already knows the project.
Memory — Claude’s private notebook
Memory is what Claude writes for itself — things it picks up about your preferences over time:
- “This user prefers concise answers”
- “Always use bun, not npm, in this project”
- “When they say ‘deploy’, they mean the staging environment”
You can ask Claude to remember something (“always use single quotes”), and it saves that to memory. But you can also just work normally, and it learns.
Claude authors it. It’s private to your machine. It’s not committed anywhere.
Side by side
| CLAUDE.md | Memory | |
|---|---|---|
| Who writes it | You | Claude |
| Who reads it | Claude (every session) | Claude (every session) |
| Shared with team | Yes (committed to repo) | No (local to your machine) |
| What it holds | Project facts, conventions, rules | Personal preferences, learned patterns |
| Where it lives | Project root or .claude/ | ~/.claude/projects/<project>/memory/ |
| How to update | Edit the file | Ask Claude, or it learns over time |
What goes where
Put it in CLAUDE.md when:
- It’s a project fact anyone working here should know
- It’s a convention or rule the whole team follows
- You’d put it in a README if there were no AI
Put it in memory when:
- It’s personal — your style, your shortcuts, your preferences
- It’s something Claude noticed that you’d rather not write down formally
- It’s specific to how you work, not how the project works
The most common mistake
People put personal preferences in CLAUDE.md (“I like short answers”) and project facts in memory (“use npm run build”). Flip those. CLAUDE.md is the team document; memory is your personal notebook. Keep them clean and both systems work much better.