CLAUDE.md memory files

Each session starts with a blank memory; CLAUDE.md is how Claude learns your build commands and conventions every time.

Every session starts fresh: Claude does not remember yesterday's conversation. To give it lasting knowledge, write a CLAUDE.md file. It is plain markdown that Claude Code loads at the start of every session.

Where it can live:

./CLAUDE.md (or ./.claude/CLAUDE.md) in the project: shared with the team through git.
./CLAUDE.local.md: your personal notes for this project; add it to .gitignore.
~/.claude/CLAUDE.md: your preferences for every project.
A managed file your company may deploy.

Files in parent folders of where you start load too, and a CLAUDE.md in a subfolder loads when Claude works on files there. They add up rather than replace each other.

Run /init to have Claude draft one from your codebase, then edit it. Good content is what Claude cannot guess by reading the code: the exact test and build commands, code style that differs from defaults, branch and PR conventions, required environment variables and known gotchas. Leave out what the code already shows, long tutorials and anything that changes weekly. Aim for under 200 lines; long files cost context on every message and important rules get lost.

Useful extras:

@path/to/file inside CLAUDE.md imports another file.
.claude/rules/*.md files can carry a paths: list in frontmatter so they load only when Claude touches matching files.
If the repo already has an AGENTS.md (used by other coding agents) and no CLAUDE.md, recent versions read it.
Auto memory: Claude also saves its own notes, such as corrections you gave it, per repository. /memory shows and edits all of these and can turn auto memory off.

CLAUDE.md is guidance, not enforcement. For "must always happen" rules, use permissions or hooks.

Example

# Project notes for Claude

## Commands
- Install: `pnpm install` (never npm)
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Typecheck before finishing: `pnpm tsc --noEmit`

## Conventions
- API handlers live in src/api/<resource>.ts and return Result<T, ApiError>
- Use the logger in src/lib/log.ts, not console.log
- Branches: feat/<ticket>-<slug>; PR titles start with the ticket id

## Gotchas
- Integration tests need Redis running locally (docker compose up redis)

@docs/architecture.md

Remember

CLAUDE.md loads every session; project, local, user and managed locations stack
Put commands, non-obvious conventions and gotchas in it; keep it short
/init drafts it, /memory edits it; it guides but does not enforce

Watch out for

Pasting the whole style guide and architecture docs into CLAUDE.md, so the file is so long that key rules get ignored.

Check yourself

Which line belongs in CLAUDE.md?
You want personal notes for one repo that teammates should not see. Where?

Official docs: code.claude.com/docs/en/memory

Example

Remember

Watch out for

Check yourself

Builds on

Unlocks