How Claude Code Remembers Things Between Sessions Using CLAUDE.md and Auto Memory

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.

---

The Two Memory Systems

	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.

---

CLAUDE.md Files

What belongs in CLAUDE.md

Add things you would otherwise re-type every session:

• Build and test commands (npm test, make lint)
• Coding conventions (indentation, naming patterns)
• Project structure and architecture notes
• "Always do X" or "never do Y" rules

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.

Where to put your CLAUDE.md

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.

Quick setup

Run /init inside your project to auto-generate a starter CLAUDE.md:

claude /init

Claude 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 /init

Writing instructions that actually work

Keep 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.

Importing other files

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.md

Imported files load at session start, so they count toward your context. Use imports for organization, not to get around the size limit.

Directory structure for rules

For larger projects, split instructions into topic files under .claude/rules/:

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

Path-specific rules

Rules 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 comments

Supported 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"
---

Using AGENTS.md from other tools

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.md

---

Auto Memory

Auto 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.

Enable or disable

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=1

Requires Claude Code v2.1.59 or later. Check with claude --version.

Where files are stored

~/.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.

What gets loaded

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.

Viewing and editing memory

Run /memory in any session to:

• See all CLAUDE.md and rules files loaded
• Toggle auto memory on or off
• Browse and open auto memory files

Auto memory files are plain markdown. You can edit or delete them any time.

---

Troubleshooting

Claude is not following my CLAUDE.md

1. Run /memory and check that your file is listed. If it is not listed, Claude cannot see it.
2. Check the file location matches where you launched Claude from.
3. Make instructions more specific (see examples above).
4. Look for conflicting instructions across multiple CLAUDE.md files.

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.

My CLAUDE.md is too large

Use path-scoped rules so instructions only load when relevant files are open. Trim anything that does not apply to every single session.

Instructions disappeared after /compact

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.

---

Q&A

1. What is the difference between CLAUDE.md and auto memory?
A: 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?
A: 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?
A: 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?
A: 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?
A: 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?
A: 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?
A: All worktrees and subdirectories of the same git repository share one auto memory directory.

8. Can I use path-scoped rules in auto memory?
A: 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?
A: 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?
A: 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.

References

• How Claude Remembers Your Project