CLAUDE.md: Your Project's Memory

Claude starts every session fresh

Claude doesn't remember yesterday's session. Without help, you'd re-explain your test command, your folder conventions and that one gotcha every time. **CLAUDE.md** fixes this: it's a markdown file of instructions that Claude Code loads at the start of every session.

Where CLAUDE.md files live

Files in your working directory and every directory above it load at launch. They're combined, not overridden, and the closest file is read last. A CLAUDE.md in a subdirectory loads on demand, when Claude starts working with files there.

/init: a starter in seconds

/init

/init explores your repo and writes a starter CLAUDE.md with build commands, test commands and the structure it discovered. If one already exists, it suggests improvements instead of overwriting. It can also migrate rules from other tools' files, like .cursorrules.

What to put in it

The best CLAUDE.md files are short and specific. Include things Claude can't easily discover, or would get wrong:

# Shop API

## Commands
- Test: `pnpm test` (single file: `pnpm test -- path/to/file`)
- Typecheck: `pnpm tsc --noEmit`. Run it before saying you're done.

## Conventions
- Money is integer cents everywhere. Never use floats for currency.
- New endpoints go in `src/routes/` and need a test in `tests/routes/`.

## Gotchas
- `legacy/` is generated. Don't edit it; change `schema/` and run `pnpm gen`.
- Staging uses a different Stripe account; keys are in 1Password, not .env.

What to leave out: long architecture essays (Claude can read the code), instructions for rare tasks (make them skills, Unit 4), and rules that must never be broken. CLAUDE.md is guidance Claude follows, not enforcement. Hard rules belong in hooks and permissions (Units 3 and 7).

Imports

Pull other files in with @path syntax:

See @README.md for an overview and @docs/api-conventions.md for API rules.

Imports keep files organized, but the imported content still loads, so they don't save context.

Auto memory: Claude takes its own notes

Besides the CLAUDE.md you write, Claude Code keeps auto memory: notes Claude writes for itself as it learns your preferences and project facts. It's stored per repository under ~/.claude/projects/<project>/memory/, with a MEMORY.md index that loads at session start.

• Say "remember that…" and Claude saves it to auto memory.
• Say "add this to CLAUDE.md" and it goes in the shared file instead.
• Run /memory to see every memory file, open them, or turn auto memory on and off.

Check your understanding