CLAUDE.md and memory

Every conversation starts from nothing. That’s the design — Claude sees this thread and not last week’s — and it’s fine until you notice you’ve explained the same five facts about your project for the fourth time this month. What tool you use to run it. Which folder is generated and shouldn’t be edited. That one file full of real customer data that nobody touches. Re-typing that is not a small tax; it’s the same tax, forever.

CLAUDE.md is the fix, and it is deliberately unglamorous: a plain text file sitting in your project that Claude reads at the start of every conversation, so those standing facts are simply there from the first message. It’s the place for things that are true about the project regardless of what you’re asking today — the stack, the conventions, the commands, the do-not-touch list.

The one discipline that matters is keep it short and specific. Because it’s re-read on every single conversation, anything vague or bloated is a cost you pay over and over — and a long file of generic advice crowds out the four lines that actually matter. The natural way to grow one is reactive rather than up-front: when you catch yourself correcting the same thing a second time, write it down so there isn’t a third.

You do not need a terminal for any of this. In Claude Desktop the easiest start is to ask in the chat — “set up a CLAUDE.md for this project” — and Claude reads what’s there and drafts a first version you can edit in the file pane like any other text file. The /init command below does the same thing if you’d rather type it.

Three places, and they stack

The CLAUDE.md in your project’s top folder is the common case, not the only one. The same file works in three locations, and the difference between them is who and when it applies to:

• Project — CLAUDE.md at the top of the repository. About this project: how to run it, its conventions, the do-not-touch list. It’s committed, so every teammate’s Claude reads the same one.
• Personal — CLAUDE.md in your home folder, at ~/.claude/CLAUDE.md. Not tied to any project; it applies to every project you open, on your machine only. This is the place for how you like to work — “explain your reasoning before big changes”, “define jargon when you use it”, “keep answers short”. Nobody else sees it.
• Nested — a CLAUDE.md deeper inside a large project, picked up when Claude is working on files in that part of the tree. Most people never need it; it’s for big mixed codebases where one corner has different rules.

The part worth knowing is that they don’t override each other, they combine. Working in a project, Claude reads your personal file and the project file and any nested one that applies, all at once — so your standing “keep it concise” rides along on top of the project’s “plain HTML, don’t touch messages.json”. General preferences at home, project facts in the repo, and they layer cleanly.

The rule for choosing: would every teammate want this? Project. Is it about how you personally work, everywhere? Personal. Does it only matter inside one corner of a huge repo? Nested. When in doubt, project-level is the safe default — you can always move a line to your personal file later.

Memory is the other half, and the guide below is there because people reliably mix the two up. The split is about ownership: CLAUDE.md is a file you write and commit, so it travels with the project and every teammate’s Claude reads the same one. Memory is notes Claude keeps privately about how you personally tend to work, built up quietly over time and never shared. Project facts belong in the first; personal habits belong in the second. The team consequence of that split is the interesting part — a new joiner who clones the repository has a Claude that already knows the project, which is why standing context is really a team operating guide question as much as a personal one.