What CLAUDE.md Actually Does: Persistent Project Memory Explained
Every time you start a fresh conversation with Claude Code, it knows nothing about your project except what it can see in the files themselves.
//
Search across all documentation pages
Every time you start a fresh conversation with Claude Code, it knows nothing about your project except what it can see in the files themselves.
It does not remember that you asked it yesterday to always use a particular testing library, or that your team never commits directly to main.
CLAUDE.md exists to close that gap.
It is a plain markdown file, checked into your repository, that Claude Code reads automatically so the conventions, structure, and rules of your project persist across sessions instead of evaporating the moment a conversation ends.
/init bootstrap./init, writing rules that actually get followed, nested CLAUDE.md scope inheritance.At its simplest, CLAUDE.md is just a markdown file named CLAUDE.md at the root of your project.
Claude Code looks for it automatically and loads its contents as context before it starts working on your request.
Think of it as the project's onboarding document, except the reader is an AI coding agent instead of a new hire.
A useful analogy is a new engineer's first week.
A good onboarding doc tells them which package manager to use, where the tests live, and which patterns the team has standardized on, so they do not have to guess or ask on every single task.
CLAUDE.md plays that same role for Claude Code, except it gets re-read at the start of every session rather than being read once and half-forgotten.
The file typically covers things like the project's tech stack, folder structure, coding conventions, testing approach, and any hard rules ("never edit generated files directly," "always run the linter before finishing").
A minimal example might look like this:
# Project: Order Service
- Language: TypeScript, strict mode.
- Tests live in `__tests__/`, mirroring the source folder structure.
- Never modify files under `generated/` - they are rebuilt by `npm run codegen`.
- Use the existing `logger` utility instead of `console.log`.Nothing here is exotic. It is the same information you would put in a README for a human, just addressed to an agent that reads it fresh every time.
The mechanic that makes CLAUDE.md different from a one-off prompt is when it gets read.
A prompt only exists for the conversation it was typed in. CLAUDE.md gets loaded automatically at the start of a new session, before you have typed anything, which is what makes it "persistent" rather than "remembered."
Claude Code is not actually retaining memory between sessions in the way a human would.
Each new conversation is still a blank slate in terms of prior chat history.
What changes is that the blank slate now includes the contents of CLAUDE.md as part of its starting context, so the agent behaves as if it already knows the project's conventions.
This has a few practical consequences worth internalizing:
That last point matters. CLAUDE.md is guidance the agent reads and reasons over, not a permissions system.
If a rule genuinely must never be violated, back it up with something enforced outside the model, like a CI check or a pre-commit hook, in addition to stating it in CLAUDE.md.
As a project grows, CLAUDE.md tends to grow with it, and that growth needs active management rather than passive accumulation.
A file that starts as ten focused lines can quietly become two hundred lines of half-relevant history if nobody prunes it.
Because CLAUDE.md consumes context budget on every single session, an oversized or poorly organized file has a real cost: it can crowd out room for the actual files and conversation the agent needs to reason about your current task.
This is why concrete, current rules beat exhaustive ones - a shorter file with accurate, specific guidance outperforms a long file padded with generalities or outdated notes.
Teams working across multiple parts of a large codebase often move from a single root CLAUDE.md to a nested structure, where a backend folder and a frontend folder each carry their own CLAUDE.md with rules specific to that area, layered on top of the shared root file.
This keeps each file focused and relevant to the work actually happening in that subtree, rather than forcing every session to load rules for parts of the codebase it is not touching.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| Single root CLAUDE.md | Simple, one place to look, easy to keep in sync | Can grow unwieldy on large, multi-domain codebases | Small to mid-size projects, single-team repos |
| Nested CLAUDE.md files | Rules stay scoped and relevant to the subtree being worked on | More files to keep consistent, requires understanding scope inheritance | Large monorepos, multi-package projects |
| No CLAUDE.md | Zero maintenance | Every session re-explains conventions from scratch, inconsistent results | Throwaway scripts, one-off experiments |
CLAUDE.md also interacts with how a session evolves over time. As a conversation runs long and its context window fills up, tools like /compact and /clear come into play to manage that budget - but CLAUDE.md itself is reloaded fresh at the start of each new session regardless, which is exactly what makes it a durable anchor rather than something that decays as a conversation progresses.
A file named CLAUDE.md, typically at the root of the project. Nested versions of the same file name can also live in subfolders to layer on additional, more specific rules.
No. It removes the need to repeat stable project context (conventions, structure, rules) in every prompt, but task-specific instructions for what you want done right now still belong in the prompt itself.
It is loaded at the start of each new session. There is no persistent chat memory carried between sessions - CLAUDE.md is what makes the effect feel persistent.
Yes. Because the agent treats CLAUDE.md as trustworthy project context, a stale rule (referencing a library you removed, a folder that moved) can steer it toward outdated or incorrect behavior. Treat it as living documentation that needs upkeep.
It consumes part of the context window on every session, which leaves less room for file reads and conversation before the window fills up. It is not "slow" in a literal sense, but it is a real budget cost worth minimizing.
A README is written for human contributors browsing the repo. CLAUDE.md is written to be loaded automatically as agent context on every session - it can and often does overlap with README content, but its audience and delivery mechanism are different.
No. The /init slash command bootstraps a starter CLAUDE.md by inspecting a fresh repo, which you then edit and refine for your project's actual needs.
Claude Code still works, but every session starts from whatever it can infer from the files it happens to read - there is no standing project memory, so conventions and rules need to be restated or rediscovered each time.
It can, in the sense that both are just context competing for the agent's attention. A specific, explicit prompt instruction for the current task generally takes precedence over general project rules, but genuinely contradictory guidance should be resolved by fixing the file, not relying on the model to guess correctly every time.
No. It is a plain markdown file describing project conventions, so it applies equally to any language or stack - the content is whatever your project actually needs documented.
Yes. Since it lives in the repository like any other file, committing it means the whole team shares the same project memory, and changes to it go through the same review process as code changes.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.
Reviewed by Chris St. John·Last updated Jul 16, 2026