Skip to content

Memory & CLAUDE.md

Give Claude durable project context that persists across sessions.

Beginner9 min read

Claude Code starts every session with a blank slate — no memory of your last conversation. CLAUDE.md files are how you give Claude permanent context about your project so you never have to repeat yourself.

How memory works

Claude Code has two memory systems that load at the start of every session. First, CLAUDE.md files: plain Markdown files you write containing instructions, conventions, and project facts. Second, auto memory: notes Claude writes to itself based on corrections and preferences it picks up during your sessions. Both end up in Claude's context window before you type your first message.

Context, not enforcement
CLAUDE.md is guidance, not a hard rule. Claude reads it and tries to follow it, but there is no guarantee of strict compliance — especially for vague instructions. For behavior that must always happen (like running a linter before every commit), use a hook instead.

Where memory lives

Claude loads CLAUDE.md files from several locations. They are all concatenated together — none override the others. Here is the load order from broadest to most specific:

  • Managed policy (org-wide, cannot be excluded) — macOS: /Library/Application Support/ClaudeCode/CLAUDE.md | Linux: /etc/claude-code/CLAUDE.md | Windows: C:\Program Files\ClaudeCode\CLAUDE.md
  • User (~/.claude/CLAUDE.md) — your personal preferences, applies to every project
  • Project (./CLAUDE.md or ./.claude/CLAUDE.md) — team-shared, checked into source control
  • Local (./CLAUDE.local.md) — your personal project-specific notes; add to .gitignore so it stays off source control
Run /init to get started fast
The /init command analyzes your codebase and generates a starter CLAUDE.md with build commands, test instructions, and conventions it discovers. If a CLAUDE.md already exists, it suggests improvements instead of overwriting.

Write an effective CLAUDE.md

Think of CLAUDE.md as the onboarding doc you wish every new teammate had read. Write down what you would otherwise re-explain in chat. Keep entries concrete and verifiable — 'Use 2-space indentation' works far better than 'Format code nicely.' Target under 200 lines; longer files consume more context and Claude follows them less reliably.

markdown
# My Project

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Tests: `npm test` (always run before committing)

## Conventions
- Use 2-space indentation, single quotes in JS/TS
- API handlers live in `src/api/handlers/`
- New components go in `src/components/`, one file per component
- Never push directly to `main`

## Architecture
- Auth is handled by the `auth` service — do not duplicate logic elsewhere
- All DB queries go through the repository layer in `src/db/`

You can also pull in other files using @path imports. Put an @path reference anywhere in your CLAUDE.md and Claude will expand that file into context at load time:

markdown
# Project Instructions

See @README.md for the full project overview.
Available npm scripts: @package.json

# Git workflow
@docs/git-workflow.md

Quick-add with #

The fastest way to save something is the # shortcut. Start any message with # and Claude saves that note to memory for you — choosing which CLAUDE.md (or auto-memory) file it belongs in. You can also just tell Claude in plain English: 'add this to CLAUDE.md' and it will edit the file for you. To browse everything that has been loaded or saved, run /memory in any session.

bash
# always use pnpm, not npm
# the staging API is at https://api-staging.example.com

What to leave out

Not everything belongs in CLAUDE.md. Overloading it makes Claude less likely to follow any of it.

  • Multi-step procedures for a specific workflow — put those in a skill file instead (they load on demand, not every session)
  • Instructions that only apply to one subdirectory — use a nested CLAUDE.md in that directory so it loads only when relevant
  • Personal preferences in a shared project file — use CLAUDE.local.md (gitignored) or ~/.claude/CLAUDE.md
  • Anything over ~200 lines total — trim, split, or move detail into imported files
Conflicting instructions
If two CLAUDE.md files give different guidance for the same behavior, Claude may pick one arbitrarily. Review your files periodically and remove outdated or contradictory entries.
Key takeaways
CLAUDE.md files give Claude permanent context across sessions — write what you would otherwise retype each time. Use the project file for team standards, ~/.claude/CLAUDE.md for personal preferences, and CLAUDE.local.md for private notes. The # shortcut saves a note instantly. Keep files under 200 lines and make every rule concrete. Full reference: code.claude.com/docs/en/memory.