Learn how to use CLAUDE.md files and Claude Code's auto memory feature to persist project instructions, coding standards and personal preferences across sessions.
Ever opened a new Claude Code session and had to re-explain the same project rules all over again? Maybe you told it "always use pnpm, not npm" last week. Today, it forgot. You type it again. Next week, same thing.
That gets old fast. The good news is Claude Code has two built-in systems that carry knowledge from one session to the next. You do not need to repeat yourself every time.
This guide breaks down both systems, when to use each one, and how to set them up properly.
| CLAUDE.md Files | Auto Memory | |
|---|---|---|
| Who writes it | You | Claude |
| What it stores | Instructions and rules | Patterns and learnings |
| Scope | Project, user, or org | Per repository |
| Loaded at start | Always (full file) | First 200 lines or 25KB of MEMORY.md |
| Best for | Standards, conventions, workflows | Build commands, debugging insights, preferences |
Think of CLAUDE.md as the rulebook you write. Auto memory is Claude's own notepad it fills in as it learns from you.
Add things you would otherwise re-type every session:
npm test, make lint)Do not dump everything in here. If something only applies to one folder, or is a multi-step workflow, use path-scoped rules or skills instead.
| Scope | Location | Who sees it |
|---|---|---|
| Organization-wide | /etc/claude-code/CLAUDE.md (Linux) | All users on the machine |
| Project (shared) | ./CLAUDE.md or ./.claude/CLAUDE.md | Everyone via version control |
| Personal (all projects) | ~/.claude/CLAUDE.md | Just you |
| Personal (one project) | ./CLAUDE.local.md | Just you, not committed |
More specific locations take priority over broader ones. Both CLAUDE.md and CLAUDE.local.md load at the same level, with the local file appended after.
Run /init inside your project to auto-generate a starter CLAUDE.md:
claude /initClaude scans your codebase and fills in build commands, test steps, and conventions it finds. You refine from there.
For an interactive setup that asks follow-up questions and shows a preview before writing files:
CLAUDE_CODE_NEW_INIT=1 claude /initKeep files under 200 lines. Longer files eat up context and Claude follows them less reliably.
Be specific:
# Good
Use 2-space indentation.
Run `npm test` before committing.
API handlers live in `src/api/handlers/`.
# Bad
Format code properly.
Test your changes.
Keep files organized.Use markdown headers and bullets to group related rules. Claude scans structure the same way humans do.
You can pull in other files from your CLAUDE.md using @ syntax:
See @README for project overview and @package.json for available scripts.
# Git workflow
@docs/git-instructions.mdImported files load at session start, so they count toward your context. Use imports for organization, not to get around the size limit.
For larger projects, split instructions into topic files under .claude/rules/:
your-project/
├── .claude/
│ ├── CLAUDE.md
│ └── rules/
│ ├── code-style.md
│ ├── testing.md
│ └── security.mdRules can load only when Claude works with matching files. Add YAML frontmatter at the top of any rules file:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation commentsSupported glob patterns:
| Pattern | Matches |
|---|---|
**/*.ts | All TypeScript files anywhere |
src/**/* | Everything under src/ |
*.md | Markdown files in project root |
src/components/*.tsx | React components in a specific folder |
Multiple patterns with brace expansion:
---
paths:
- "src/**/*.{ts,tsx}"
- "tests/**/*.test.ts"
---Claude reads CLAUDE.md, not AGENTS.md. If your repo already has an AGENTS.md for other tools, import it so both tools stay in sync:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.Or use a symlink (Linux/macOS):
ln -s AGENTS.md CLAUDE.mdAuto memory lets Claude take its own notes as it works. It saves things like build commands it had to figure out, debugging patterns, code style preferences it picked up from your corrections.
You do not write anything. Claude decides what is worth saving.
Auto memory is on by default. Toggle it with /memory inside a session, or set it in your project settings:
{
"autoMemoryEnabled": false
}Via environment variable:
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1Requires Claude Code v2.1.59 or later. Check with claude --version.
~/.claude/projects/<project>/memory/
├── MEMORY.md # Index loaded every session
├── debugging.md # Detailed debugging notes
├── api-conventions.md # API decisions
└── ...The <project> path comes from the git repository root, so all worktrees share one memory directory. Auto memory is local to your machine and not synced.
Only the first 200 lines (or 25KB) of MEMORY.md loads at session start. Claude keeps this file short and moves detailed notes into topic files. Topic files like debugging.md are read on demand, not at startup.
Run /memory in any session to:
Auto memory files are plain markdown. You can edit or delete them any time.
/memory and check that your file is listed. If it is not listed, Claude cannot see it.For instructions that must run at a specific moment (before every commit, after every file edit), use hooks instead. Hooks execute as shell commands at fixed lifecycle events and always run regardless of what Claude decides.
Use path-scoped rules so instructions only load when relevant files are open. Trim anything that does not apply to every single session.
Project-root CLAUDE.md reloads after /compact. Nested CLAUDE.md files in subdirectories do not reload automatically. They come back the next time Claude reads a file in that subdirectory.
If an instruction vanished, it was either in the conversation only, or in a nested file that has not reloaded yet. Add it to your root CLAUDE.md to make it stick.
1. What is the difference between CLAUDE.md and auto memory?
CLAUDE.md is written by you and contains explicit rules. Auto memory is written by Claude and contains things it learns from working with you.
2. Does CLAUDE.md work like a system prompt?
No. It is delivered as a user message after the system prompt. Claude reads and tries to follow it, but it is not strictly enforced. Specific, concrete instructions work much better than vague ones.
3. How many lines should my CLAUDE.md be?
Stay under 200 lines per file. Longer files consume more context and Claude follows them less reliably.
4. Can I have multiple CLAUDE.md files in the same project?
Yes. Claude loads CLAUDE.md files from parent directories all the way up to the root, plus any files in subdirectories when Claude reads files there. More specific paths take precedence.
5. Will auto memory be shared with my team?
No. Auto memory is stored locally on your machine under ~/.claude/projects/ and is not committed to version control.
6. How do I make Claude remember something specific?
Just tell it during a session: "always use pnpm, not npm" or "remember that API tests need a local Redis instance." Claude saves it to auto memory. To put it in CLAUDE.md instead, say "add this to CLAUDE.md."
7. What happens to auto memory across git worktrees?
All worktrees and subdirectories of the same git repository share one auto memory directory.
8. Can I use path-scoped rules in auto memory?
No. Path-scoped rules only apply to .claude/rules/ files that you create. Auto memory does not support path scoping.
9. How do I stop a specific CLAUDE.md from loading in a monorepo?
Use the claudeMdExcludes setting in .claude/settings.local.json:
{
"claudeMdExcludes": [
"**/other-team/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}10. Can organization admins enforce instructions that users cannot override?
Yes. Place a CLAUDE.md at the managed policy location (for example /etc/claude-code/CLAUDE.md on Linux) and deploy it via MDM or Ansible. This file cannot be excluded by individual settings.
A practical guide to Claude Code's most useful everyday workflows, from exploring codebases and fixing bugs to running parallel sessions, resuming conversations, and piping Claude into scripts.
A practical guide to Claude Code best practices covering context management, prompt writing, CLAUDE.md setup, parallel sessions, and how to avoid the most common mistakes developers make.
Learn how Claude Code works as a terminal-based agentic assistant. Covers the agentic loop, built-in tools, session management, context windows, and safety features for developers.
Learn how prompt caching works in large language models, why it reduces API costs and latency, and how to design your prompts and system state to take full advantage of it.
A clear breakdown of everything new in Claude Opus 4.8, including fast mode, mid-conversation system messages, lower prompt cache minimum, refusal stop details, and behavior improvements.
