Persistent Project Memory with CLAUDE.md

1. The problem CLAUDE.md solves

Every Claude Code session begins with a blank slate. Without persistent memory, you would have to re-explain your project to Claude Code at the start of every session: “This is a TypeScript monorepo. We use pnpm. Tests run with Vitest. Don’t use the legacy src/utils/old-helpers.ts module because it’s being deprecated.” That repeated briefing is friction, and friction compounds across dozens of sessions.

CLAUDE.md is the solution. It is a Markdown file that Claude Code automatically reads at the start of every session, before it looks at anything else in your project. Whatever you put in CLAUDE.md becomes part of Claude Code’s working context from the very first message. It is not a one-time setup — it is a standing briefing that runs every time you open Claude Code in that project.

The power of this is significant. A well-maintained CLAUDE.md can be the difference between Claude Code that feels like it knows your project and Claude Code that feels like a new hire who keeps forgetting things you told it last week. The limitation of this is also significant: everything in CLAUDE.md costs tokens, every session, even for trivial tasks. This constraint should shape every decision you make about what to include.

2. What belongs in CLAUDE.md

Think of CLAUDE.md as a briefing document for an expert engineer who just joined your team. You would not tell a senior engineer how JavaScript syntax works — they already know. You would tell them the things that are specific to your project and not obvious from reading the code.

Project overview — one or two sentences about what this project does and who uses it. Not a marketing pitch, a functional description. “A REST API for the internal HR system, deployed on AWS ECS, used by the people ops team.”

Stack and tooling — the technologies that might not be obvious from file extensions alone. Runtime version, package manager, test framework, build system, any unusual dependencies. “Node 20, pnpm 9, Vitest for unit tests, Playwright for E2E, Prisma for database access, deployed with Docker Compose.”

Key commands — the commands Claude Code will actually need to run. Don’t list every npm script; list the ones that are part of the development loop. pnpm test, pnpm build, pnpm dev, pnpm db:migrate. Claude Code runs these commands often; having them in CLAUDE.md means it never has to discover them by reading package.json.

Coding conventions — project-specific patterns that deviate from generic best practices. “We use named exports only, never default exports.” “All async functions must be wrapped in our tryCatch utility from src/utils/error.ts.” “React components go in src/components/{Name}/{Name}.tsx with an index.ts barrel.”

Known gotchas — the landmines a new developer would step on. “The config object is frozen at startup; don’t try to mutate it at runtime.” “The legacy payment module in src/payments/v1 is read-only; all new payment features go in src/payments/v2.” “Integration tests require a running Docker Compose stack; they will fail silently if Docker is not running.”

What NOT to include: Things Claude Code can discover itself. It can read your directory structure, your package.json, your tsconfig. It can find your test files by looking for .test.ts files. Duplicating this information in CLAUDE.md is waste — it spends tokens on facts that are already available in the codebase and creates a second source of truth that can get out of sync.

3. The three-level hierarchy

CLAUDE.md is not a single file — it is a three-level hierarchy that lets you have general preferences, project-specific instructions, and directory-specific rules all coexist without conflict.

Global CLAUDE.md lives at ~/.claude/CLAUDE.md (your home directory’s .claude folder). It is loaded for every Claude Code session, regardless of which project you are in. This is the right place for preferences that apply everywhere: your preferred coding style, general conventions you always want Claude Code to follow, tools you always want it to use or avoid. Keep this file short — everything here costs tokens on every session, including sessions where these instructions are irrelevant.

Project CLAUDE.md lives at the root of your git repository. It is loaded when you run Claude Code from anywhere inside that project. This is the primary CLAUDE.md for most users — the one that contains project-specific stack, commands, conventions, and gotchas described above.

Folder-level CLAUDE.md files can live in any subdirectory. When Claude Code reads files in that directory, the local CLAUDE.md is added to its context. This is useful for large monorepos where different packages have different conventions. A packages/mobile/CLAUDE.md might specify React Native–specific patterns, while packages/api/CLAUDE.md specifies database access conventions, neither of which are relevant outside their respective directories.

4. Keeping CLAUDE.md current

A stale CLAUDE.md is worse than no CLAUDE.md. Instructions that describe code that no longer exists, commands that have changed names, or conventions that were superseded actively mislead Claude Code. The cost is not just wrong output — it is confident wrong output, because Claude Code trusts your CLAUDE.md more than contradictory evidence in the codebase.

The discipline that works: treat CLAUDE.md as a living document you update whenever the underlying reality changes. When you rename a command, update CLAUDE.md. When you deprecate a module and add a replacement, update CLAUDE.md. When you adopt a new testing convention, update CLAUDE.md. This takes thirty seconds and prevents hours of confusion.

A useful prompt to run periodically to keep CLAUDE.md accurate:

Read CLAUDE.md and then read the actual project structure and package.json. 
Identify anything in CLAUDE.md that is no longer accurate and suggest updates.

This turns Claude Code into a maintenance tool for its own context file, which is a tidy recursive use of the system.

5. Bootstrapping CLAUDE.md for an existing project

If you are adding CLAUDE.md to an existing project that has never had one, the fastest path is to ask Claude Code to draft it for you:

Read this project's structure, package.json, and any existing README. 
Then draft a CLAUDE.md that includes: a one-sentence description of the project, 
the key dev commands, the stack, any obvious conventions from the existing code, 
and placeholder sections for gotchas and deprecated paths that I can fill in manually.

Review the draft carefully before accepting. Claude Code can correctly identify the stack and commands from existing files, but it cannot know which modules are deprecated, which conventions are enforced but not visible in code, or what the team-specific landmines are. Those sections need your input.

cd ~/projects/your-repo
claude

Read this project's package.json, any README files, and the top-level directory structure. 
Draft a CLAUDE.md with: a one-sentence project description, the key dev commands, 
the tech stack, any conventions visible from the code, and placeholder sections for 
gotchas and deprecated paths I will fill in.

Write this CLAUDE.md to the project root.

What command do I run to start the development server?

Read CLAUDE.md and compare it against the actual package.json and project structure. 
List anything in CLAUDE.md that is no longer accurate.