How Claude Code Memory Works: CLAUDE.md and Auto Memory

73% of engineering teams now use AI coding tools daily, up from 41% a year earlier, according to the February 2026 Pragmatic Engineer survey of 15,000 developers. Yet most developers re-explain the same project context every time they open a new Claude Code session. Build commands, naming conventions, deployment steps, preferred test frameworks: all of it gets re-stated, session after session.

The problem is not Claude Code itself. Each session genuinely does start with a fresh context window. The problem is that most developers have not configured the two systems that carry knowledge across those sessions.

Claude Code memory is a dual system. CLAUDE.md files provide persistent project instructions that you write and maintain. Auto memory stores notes that Claude writes based on your corrections and preferences. Both are loaded into the context window at the start of every conversation. Together, they give Claude the context it needs to behave consistently without you repeating yourself.

This distinction matters because Claude Code memory is entirely separate from Claude.ai's Projects memory. Claude.ai builds a memory wiki inside a project that updates on a nightly cycle. Claude Code reads flat markdown files from disk. The two systems share no data, no mechanism, and no storage. If you have worked with Claude.ai Projects memory, set those expectations aside.

A CLAUDE.md file is a plain markdown file that gives Claude persistent instructions for your project. You write it, you maintain it, and Claude reads it at the start of every session. Think of it as the project README that only Claude sees.

CLAUDE.md files can live in several locations, each with a different scope. Claude loads them in order from broadest to most specific:

1. Managed policy at /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) or /etc/claude-code/CLAUDE.md (Linux). IT deploys this for organization-wide standards. It cannot be excluded by individual settings.
2. User instructions at ~/.claude/CLAUDE.md. Your personal preferences across all projects, like code style or preferred tools.
3. Project instructions at ./CLAUDE.md or ./.claude/CLAUDE.md. Team-shared standards committed to version control: architecture decisions, build commands, naming conventions.
4. Local instructions at ./CLAUDE.local.md. Your personal overrides for this specific project. Add it to .gitignore so it stays on your machine.

Claude walks up the directory tree from your current working directory, loading every CLAUDE.md and CLAUDE.local.md it finds along the way. If you run Claude Code in foo/bar/, it reads foo/bar/CLAUDE.md, then foo/CLAUDE.md, all the way to the root. All discovered files are concatenated into context, not overridden. Content from the filesystem root appears first, your working directory last. Within each directory, CLAUDE.local.md is appended after CLAUDE.md, so your personal notes are the last thing Claude reads at that level.

CLAUDE.md files in subdirectories below your working directory load on demand when Claude reads files in those directories. This keeps the initial context lean.

What to put in CLAUDE.md

Target under 200 lines. Longer files consume more tokens and reduce how consistently Claude follows the instructions. Include facts Claude should know in every session:

• Build and test commands (npm test, make lint, cargo build --release)
• Code style rules ("Use 2-space indentation", "Never use default exports")
• Project architecture ("API handlers live in src/api/handlers/")
• Common workflows ("Run npm run migrate before testing database changes")
• Naming conventions ("Components use PascalCase, utilities use camelCase")

Keep instructions specific enough to verify. "Format code properly" is too vague. "Use 2-space indentation and single quotes for strings" gives Claude something concrete to follow.

Importing other files

CLAUDE.md files support @path/to/file imports. Reference your README, package.json, or workflow docs, and Claude expands them inline at launch:

See @README for project overview and @package.json for available commands.

# Git workflow
- @docs/git-instructions.md

Relative paths resolve from the file containing the import. Imports nest up to four levels deep. To mention a path without importing it, wrap it in backticks: `@README` stays literal.

If your repo already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it instead of duplicating content:

@AGENTS.md

## Claude Code specific
Use plan mode for changes under src/billing/.

Auto memory is the second half of Claude Code's persistent context system. Instead of you writing instructions, Claude writes notes for itself based on patterns it observes during your sessions.

When you correct Claude's behavior ("no, always use pnpm here, not npm"), fix a mistake it keeps making, or confirm an approach that worked, Claude evaluates whether that information would help in future conversations. If it decides yes, it saves a note to disk. You will see "Writing memory" appear in the Claude Code interface when this happens.

Auto memory stores files at ~/.claude/projects/<project>/memory/. The <project> path is derived from your git repository, so all worktrees and subdirectories within the same repo share one memory directory. The directory contains:

• MEMORY.md: a concise index file loaded at the start of every session
• Topic files like debugging.md or api-conventions.md: detailed notes Claude creates as needed

The first 200 lines of MEMORY.md, or the first 25KB (whichever limit hits first), load into context at session start. Content beyond that threshold is not loaded automatically. This is why Claude keeps MEMORY.md as an index with short entries, moving longer notes into separate topic files that it reads on demand during the session.

What auto memory typically saves

Claude organizes its notes into four categories:

• User preferences: your role, tools you prefer, how you like explanations structured
• Feedback: corrections you have made ("don't mock the database in integration tests")
• Project context: architectural decisions, deployment quirks, team conventions not evident from code
• References: pointers to external systems ("bugs tracked in Linear project INGEST")

Claude does not save something every session. It writes a note only when it judges the information would be useful in a future conversation that has no other way to discover it.

Reviewing and editing auto memory

Run /memory in any session to browse what Claude has saved, toggle auto memory on or off, or open the memory folder directly. Everything is plain markdown you can edit or delete at any time. If Claude saved something wrong or outdated, just delete the file or fix the entry.

To disable auto memory entirely, set autoMemoryEnabled: false in your project settings or set the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Auto memory requires Claude Code v2.1.59 or later.

Give your agents a workspace that persists between sessions

Fast.io workspaces let agents and humans share files, search by meaning, and hand off work through one API. Versioning and audit trails keep every artifact traceable.

Start 14-Day Trial

The fastest way to start is with the /init command. Run it inside a Claude Code session, and Claude analyzes your codebase to generate a starting CLAUDE.md with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting.

For a more interactive setup, set CLAUDE_CODE_NEW_INIT=1 before running /init. This enables a multi-phase flow where Claude asks which artifacts to create (CLAUDE.md files, skills, hooks), explores your codebase with a subagent, asks follow-up questions, and presents a proposal before writing anything.

After /init, add what code cannot reveal

The generated CLAUDE.md captures what Claude can discover from source files. Add the knowledge it cannot infer:

• Environment-specific setup ("Requires Redis running on localhost:6379 for tests")
• Team conventions not evident from code ("PR descriptions must reference a Jira ticket")
• Historical decisions ("We chose Postgres over Mongo because of transaction guarantees")
• Known pitfalls ("The payment service timeout is 5 seconds; do not increase it")

These are the instructions that prevent Claude from making the same mistake your new hire would make on day one.

Personal preferences with CLAUDE.local.md

Create a CLAUDE.local.md at your project root for preferences that should not be committed to version control: sandbox URLs, test data paths, preferred debugging approach. Add CLAUDE.local.md to .gitignore so it stays local.

If you work across multiple git worktrees, a gitignored CLAUDE.local.md only exists in the worktree where you created it. Import a file from your home directory instead:

# Individual Preferences
- @~/.claude/my-project-instructions.md

This keeps your personal instructions consistent across all worktrees of the same repo.

Long Claude Code sessions eventually trigger context compaction, where Claude summarizes older messages to free up space in the context window. Understanding what survives this process matters for reliable memory behavior.

Project-root CLAUDE.md survives compaction. After compaction, Claude re-reads it from disk and re-injects it into the session. Your core project instructions persist no matter how long the conversation runs.

Auto memory MEMORY.md survives. It is loaded at session start and re-read after compaction, just like project-root CLAUDE.md.

Nested CLAUDE.md files in subdirectories do not automatically re-inject. They reload the next time Claude reads a file in that subdirectory. If an instruction seems to disappear after compaction, it likely lived in a nested CLAUDE.md that has not reloaded yet.

Conversation-only instructions do not survive. If you told Claude something in chat ("always use tabs here") but never saved it to CLAUDE.md or auto memory, compaction may drop it. The fix: tell Claude to remember it ("remember to always use tabs in this project"), or add it to CLAUDE.md yourself.

Troubleshooting common memory issues

Claude ignores your CLAUDE.md. Run /memory to verify the file is listed as loaded. If it is missing, check the file location. It must be in or above your working directory. Also check for conflicting instructions across multiple CLAUDE.md files. When two files give different guidance for the same behavior, Claude may pick one arbitrarily.

Auto memory saved something incorrect. Open ~/.claude/projects/<project>/memory/ and edit or delete the file. Everything is plain markdown. Run /memory to get a direct link to the folder.

CLAUDE.md is too large. Files over 200 lines reduce adherence. Move procedural instructions into skills (which load on demand via slash commands) and path-specific instructions into .claude/rules/ (which load only when Claude works with matching files).

Instructions work in one session but not the next. The instruction was likely given in conversation and never persisted. Ask Claude to save it to memory, or add it to CLAUDE.md directly.

As projects grow, a single CLAUDE.md becomes unwieldy. Claude Code provides the .claude/rules/ directory for modular, scoped instructions.

Place markdown files in .claude/rules/, one topic per file:

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

Rules without frontmatter load at launch alongside CLAUDE.md. Rules with a paths frontmatter field load only when Claude works with matching files:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- All endpoints must include input validation
- Use the standard error response format

This keeps context lean. Your API rules load only when Claude touches API files. Frontend rules load only when Claude touches components. For a monorepo with multiple teams, use claudeMdExcludes in settings to skip other teams' CLAUDE.md files.

Team and organization patterns

Commit .claude/CLAUDE.md and .claude/rules/ to version control so the entire team shares the same instructions. Keep personal preferences in CLAUDE.local.md (gitignored) or ~/.claude/CLAUDE.md (user-level).

For organizations deploying Claude Code across many developers, the managed policy CLAUDE.md at the system level (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS) cannot be excluded by individual users. This makes it the right place for security policies, compliance requirements, or company-wide coding standards.

Symlinks also work in .claude/rules/, so you can maintain a shared set of rules across multiple projects:

ln -s ~/shared-claude-rules .claude/rules/shared

When memory alone is not enough

CLAUDE.md and auto memory handle instructions and preferences. But agents also produce artifacts: generated files, analysis results, reports. For local projects, git handles artifact persistence naturally. For teams where agents build deliverables and hand them off to humans, a shared storage layer adds durability beyond what local files provide. Fast.io workspaces give agents and humans the same file access through both UI and MCP server, with versioning and audit trails that persist independent of any single Claude Code session. Other options include S3 buckets, shared drives, or cloud storage like Google Drive.

The key distinction: memory tells Claude how to behave. Storage gives it somewhere to put the work.