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.
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.
Summary
- Core Idea: CLAUDE.md is a project-memory file that gives Claude Code persistent knowledge of your project's conventions, structure, and rules across sessions.
- Why It Matters: Without it, every session starts from zero, and you end up repeating the same instructions in prompt after prompt.
- Key Concepts: project memory, session persistence, conventions vs instructions, nested scope, the
/initbootstrap. - When to Use: Any project you return to more than once, any team repo with shared conventions, and any codebase with rules a generic coding agent would not guess on its own.
- Limitations / Trade-offs: CLAUDE.md is only as useful as what you put in it - vague guidance gets skimmed past, and a stale file can actively mislead Claude Code if it drifts from the real codebase.
- Related Topics: bootstrapping with
/init, writing rules that actually get followed, nested CLAUDE.md scope inheritance.
Foundations
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.
Mechanics & Interactions
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:
- CLAUDE.md content competes for space in the context window alongside your prompts, file reads, and tool output, so it is not free - a bloated file has a real cost.
- Because it is a normal file in your repo, it is versioned, diffable, and reviewable through the same pull-request process as any other change.
- It can be layered: a root CLAUDE.md sets project-wide rules, and nested CLAUDE.md files in subfolders add more specific rules that apply only within that scope.
- It is descriptive, not enforced - Claude Code follows it because the instructions are in its context, not because of any hard technical guardrail preventing deviation.
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.
Advanced Considerations & Applications
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.
Common Misconceptions
- "CLAUDE.md means Claude remembers our past conversations." - It does not. Each session is still independent; CLAUDE.md just ensures the same background information is present every time, which produces memory-like behavior without actual cross-session recall.
- "Longer is always better." - A bloated CLAUDE.md costs context budget on every session and buries the rules that matter. Concise and specific beats exhaustive.
- "It's enforced like a permission system." - CLAUDE.md is context the agent reads and reasons over, not a hard technical guardrail. Critical rules still need enforcement outside the model, such as CI checks.
- "One CLAUDE.md has to cover the whole codebase equally." - Nested CLAUDE.md files let different parts of a large project carry their own scoped rules layered on top of the root file.
- "It's optional documentation, so accuracy doesn't matter much." - A stale or inaccurate CLAUDE.md actively misleads the agent, since it is trusted as current project context by default.
FAQs
What file name and location does Claude Code actually look for?
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.
Does CLAUDE.md replace writing good prompts?
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.
Is CLAUDE.md read once per project, or once per session?
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.
What kind of content belongs in CLAUDE.md?
- Tech stack and key dependencies
- Folder structure and where things live
- Coding conventions and naming patterns
- Testing approach and how to run tests
- Hard rules ("never do X," "always do Y before finishing")
Can CLAUDE.md make Claude Code do something objectively wrong if the file is out of date?
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.
Does a large CLAUDE.md file slow Claude Code down?
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.
How is CLAUDE.md different from a regular README?
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.
Do I have to write CLAUDE.md by hand?
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.
What happens if a project has no CLAUDE.md at all?
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.
Can CLAUDE.md conflict with what I ask in a prompt?
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.
Is CLAUDE.md specific to one programming language?
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.
Should CLAUDE.md be committed to version control?
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.
Related
- Bootstrapping a New Project with /init - the fastest way to generate a starting CLAUDE.md automatically.
- Writing a CLAUDE.md File That Actually Gets Followed - how to structure rules so Claude Code actually obeys them.
- Nested CLAUDE.md Files and How Scope Inheritance Works - layering project memory across subfolders.
- Context Management Basics - the starting point for this whole section.
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.