Claude Code memory: how it works and what it doesn't share

On Monday you tell Claude Code to use pnpm, not npm. On Tuesday it uses pnpm without being asked. On Wednesday your teammate opens the same repo, and their Claude Code reaches for npm.

Nothing is broken. Claude Code memory is working exactly as designed. It remembers in files, and most of those files belong to one person on one machine.

This guide explains how Claude Code memory works: which files load, in what order, how much of each, what happens after compaction, and which parts your team actually shares. Everything here comes from Anthropic's memory documentation, checked on 4 November 2026.

How Claude Code memory works

Claude Code memory is two systems that load into every session. CLAUDE.md files are instructions you write. Auto memory is notes Claude writes for itself. Every session starts with a fresh context window, and these files are how anything carries over.

	CLAUDE.md files	Auto memory
Who writes it	You	Claude
What it holds	Instructions and rules	Learnings, corrections, preferences
Scope	Organization, user, or project	One repository, shared across its worktrees
When it loads	Every session	Every session, first 200 lines or 25KB of the index
Who else sees it	Teammates, if committed to the repo	Nobody. It stays on your machine

The documentation is direct about one point: Claude treats both as context, not enforced configuration. A memory file makes a behavior likely. It does not make it certain. If something must never happen, Anthropic points you to hooks and permission settings instead.

Where Claude Code looks for CLAUDE.md

Claude Code reads CLAUDE.md from four kinds of location. Each one has a different owner and a different audience.

Scope	Location	Shared with
Managed policy	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md. Linux and WSL: /etc/claude-code/CLAUDE.md. Windows: C:\Program Files\ClaudeCode\CLAUDE.md	Every user on the machine
User	~/.claude/CLAUDE.md	Only you, in every project
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Teammates, through git
Local	./CLAUDE.local.md (add it to .gitignore)	Only you, in this project

Two more sources sit beside these. Files in .claude/rules/ split project instructions by topic, and a rule with paths frontmatter loads only when Claude works on matching files. Personal rules in ~/.claude/rules/ apply to every project on your machine.

A CLAUDE.md can also pull in other files with @path/to/file. Imports can nest four levels deep. They help you organize a long file, but they do not save context, because an imported file loads together with the file that imports it.

What loads at session start, and what loads later

Claude Code does not read every memory file at launch. Some load immediately and some wait until Claude touches a related file.

At launch, Claude Code loads:

1. The managed CLAUDE.md, if your organization deployed one.
2. Your user CLAUDE.md and user rules.
3. Every CLAUDE.md and CLAUDE.local.md from the filesystem root down to the directory where you started Claude. Files closer to your working directory come later in context, and CLAUDE.local.md comes after CLAUDE.md at each level.
4. Project rules in .claude/rules/ that have no paths field.
5. The first 200 lines or first 25KB of auto memory's MEMORY.md, whichever comes first.

Later, on demand, Claude Code loads:

• A CLAUDE.md in a subdirectory, once Claude reads, writes, or edits a file in that subdirectory.
• A path-scoped rule, once Claude opens a file that matches its pattern.
• Auto memory topic files, when Claude decides it needs them.
• Skills, when you invoke one or Claude judges it relevant to your prompt.

Files are concatenated, not merged. If two instructions conflict, the documentation says Claude may pick one arbitrarily. Run /context in a session to see which memory files actually loaded.

Where Claude Code auto memory is stored

Auto memory lives in ~/.claude/projects/<project>/memory/. The project path comes from the git repository, so every worktree and subdirectory of one repo shares a single memory directory.

Inside, a MEMORY.md index holds one line per memory, and each memory is its own markdown file. Claude tags each one with a type:

• user: your role, expertise, and working preferences
• feedback: corrections you gave and approaches you confirmed
• project: ongoing work, deadlines, and decisions it can't derive from the code
• reference: where to find things outside the project, like a dashboard

Claude skips anything it can work out from the codebase and anything your CLAUDE.md already says. It does not save something every session. When you see "Saved 2 memories" or "Recalled 2 memories", it is reading or writing this directory.

Auto memory is on by default in local sessions. To manage it, run /memory: it lists your memory files, opens the auto memory folder, and has the on/off toggle. The files are plain markdown, so you can read, edit, or delete any of them.

Memory files are not removed by Claude Code's transcript cleanup. Old session transcripts expire after the retention period, but MEMORY.md and its topic files stay until you or Claude change them.

How much memory Claude Code can hold

Each kind of memory file has its own limit, and the limits behave differently.

File	Limit	What happens past it
CLAUDE.md loaded at launch	Recommended under 200 lines. Hard limit 4 MiB	Long files reduce adherence. A file over 4 MiB is skipped entirely
MEMORY.md index	First 200 lines or 25KB	Everything after the limit is not loaded
Subdirectory CLAUDE.md and path-scoped rules	40,000 characters on a 200K context window; 150,000 to 200,000 on 1M, depending on model	Claude receives only the start, with a note to read the rest
@ imports	Four levels of nesting	Deeper imports are not followed

The first row is the one teams hit. A CLAUDE.md that grows every time Claude makes a mistake gets longer and less effective at the same time. Claude Code warns at startup when a file is over the recommended length, and /doctor prompt-audit (v2.1.283 or later) looks for outdated and conflicting instructions without changing anything until you approve.

What happens to memory after /compact and between sessions

Memory files survive compaction. Conversation does not. That difference explains most "Claude forgot what I told it" reports.

After /compact, Claude re-reads the project-root CLAUDE.md from disk. Nested CLAUDE.md files and path-scoped rules come back the next time Claude touches a matching file. An instruction you only typed into the chat is at risk. The documentation's fix is plain: if it must persist, put it in CLAUDE.md.

A new session behaves the same way. It loads memory files fresh and knows nothing of the previous conversation, unless you reopen that conversation with claude --continue or claude --resume. For a practical guide on what to save where between sessions, see Claude Code keeps forgetting context?.

Why Claude Code ignores memory you wrote

Claude Code can load a memory file and still not follow it. CLAUDE.md content arrives as a user message after the system prompt, and Anthropic's documentation says there is no guarantee of strict compliance, especially for vague or conflicting instructions.

When an instruction is being ignored, check these in order:

1. Did it load? Run /context and look under Memory files. A subdirectory CLAUDE.md will not appear there, because it loads on demand.
2. Is it specific? "Run npm test before committing" works better than "test your changes".
3. Does something contradict it? Look across CLAUDE.md, nested files, and .claude/rules/.
4. Is it too long? A file past 200 lines spreads attention thin.
5. Should it be a hook? If an action must happen at a fixed point, such as before every commit, a hook runs as a shell command regardless of what Claude decides.

This is the honest limit of memory files. They inform the agent. They do not enforce anything. For each cause in detail, with a hook example, see why Claude Code ignores your CLAUDE.md.

Does Claude Code memory work with AGENTS.md?

Yes. Since v2.1.277, Claude Code reads AGENTS.md as project instructions when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If both exist, it reads CLAUDE.md only by default. You can change that in /config under Project instructions, or import the file with @AGENTS.md at the top of a CLAUDE.md. For the full rules and the /config options, see AGENTS.md vs CLAUDE.md.

What Claude Code memory doesn't share with your team

Claude Code memory is built for one developer working in one repository. A team needs something it doesn't provide.

What a team needs	What Claude Code memory offers	The gap
Lessons one person taught their agent	Auto memory	Machine-local. Your teammate's agent never sees it
Rules for every repo in the company	Managed CLAUDE.md	Pushed to machines by IT with MDM or Group Policy. One text for everyone on the machine
Rules for one team or one service	Project CLAUDE.md and rules	Per repository. Each repo keeps its own copy, and copies drift
A decision made in Slack or a PRD	Nothing, until someone types it into a file	Most product decisions never reach a CLAUDE.md
Knowing a rule was replaced	Whatever the file says now	No owner, no status, no history of what changed and why

The demand is visible in public. A feature request for shared team memory in Claude Code asks for exactly this, and a separate request about memory lost across context compactions has more than 100 comments from people who built their own workarounds.

How to share Claude Code memory across a team

You can get a long way with what Claude Code already does. Start here before adding any tool:

1. Commit a short project CLAUDE.md. Build commands, boundaries, and the conventions every task needs. Keep it under 200 lines.
2. Split the rest into .claude/rules/. Use paths so frontend rules load only for frontend files. What belongs in CLAUDE.md covers the split in detail.
3. Share rules across repos with symlinks. .claude/rules/ follows symlinks. Claude Code asks once per project before loading links that point outside the repo.
4. Use a managed CLAUDE.md for true company-wide rules, if your IT team can deploy it. Use managed settings, not CLAUDE.md, for anything that must be blocked.
5. Keep decisions in one shared record and point to it. A product call with an owner, a reason, and a replacement history does not belong in a file every agent loads every session.

Steps one to four cover instructions. Step five is the part native memory leaves to you. For subagent memory that lives in git and team plugin marketplaces, see Claude Code team memory.

Where Lockstep fits

Lockstep is shared team memory for Claude Code. It handles the rows in the gap table that files can't: decisions made outside the repo, and standards that need to reach every engineer's agent at the right version.

Decisions are captured from PRDs, Slack, and pull requests, and become binding when their owner approves them. At session start, Lockstep briefs Claude Code on the decisions that apply to the work, and the agent can query the same record over MCP mid-session. When a decision is replaced, the old version stays visible as replaced, so no agent treats it as current. For engineering leads, Standards & Skills publishes versioned standards and Claude Code skills once and rolls them out by team, repo, or path, with a view of which version reached which checkout.

It does not replace CLAUDE.md or auto memory. CLAUDE.md still tells Claude how this repository works, and auto memory still learns your habits. Lockstep carries what the whole team decided. Session briefings and managed skills ship for Claude Code today; other MCP clients can call the tools but don't get the automatic briefing yet. Try it on one repository with npx lockstep-cli onboard before rolling it out further.

Sources checked 4 November 2026

• https://code.claude.com/docs/en/memory
• https://github.com/anthropics/claude-code/issues/38536
• https://github.com/anthropics/claude-code/issues/34556
• https://github.com/lockstep-team-agent/lockstep

Related reading

For what to save where between sessions, see Claude Code keeps forgetting context?. For the CLAUDE.md and memory split, read CLAUDE.md vs agent memory. To compare add-on tools, see the best memory tools for Claude Code. For memory you connect over MCP, see the best MCP memory server for Claude Code. For connecting live systems instead of memory, see the best MCP servers for product engineers and dev teams. For the five layers of agent memory beyond Claude Code, see the AI coding agent memory guide.