How does Claude Code memory work?

Claude Code memory is two sets of markdown files loaded at the start of every session: CLAUDE.md files that you write, and auto memory, notes Claude writes itself in ~/.claude/projects/<project>/memory/. According to Anthropic's Claude Code docs, each session begins with a fresh context window, and these two mechanisms are what carry knowledge from one session to the next. Claude treats both as context, not enforced configuration. CLAUDE.md files in and above your working directory load at launch, and a subdirectory CLAUDE.md loads on demand, cut short past a per-file size limit; auto memory loads up to 200 lines or 25KB of its MEMORY.md index and opens the other memory files only when it needs them.

What is the difference between CLAUDE.md and auto memory?

CLAUDE.md holds the rules you write; auto memory holds what Claude learns while working with you. The Claude Code memory docs compare them like this:

	CLAUDE.md files	Auto memory
Who writes it	You	Claude
What it contains	Instructions and rules	Learnings and patterns
Scope	Project, user or organization	One repository, shared across its worktrees
Loaded at session start	Each file in full, up to 4 MiB	MEMORY.md, up to 200 lines or 25KB
Shared with teammates	Project file, through version control	No, machine-local

When you say "remember that the API tests require a local Redis instance", Claude saves it to auto memory. To put a rule in CLAUDE.md instead, ask "add this to CLAUDE.md" or edit the file through /memory.

Where does Claude Code look for CLAUDE.md files?

Claude Code loads CLAUDE.md files from four scopes, broadest first, and concatenates them instead of letting one override another:

1. Managed policy, deployed by IT: /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL.
2. User: ~/.claude/CLAUDE.md, your preferences for every project.
3. Project: ./CLAUDE.md or ./.claude/CLAUDE.md, shared through version control.
4. Local: ./CLAUDE.local.md, personal and kept out of git.

Files in the working directory and the directories above it load at launch; files in subdirectories load when Claude works there. Rules in .claude/rules/ can carry paths frontmatter so they load only for matching files, and @path imports pull in other files up to four hops deep. Repositories that use AGENTS.md are covered in CLAUDE.md vs AGENTS.md.

How does auto memory decide what to save?

Auto memory saves four kinds of notes, recorded as a type field: user (your role and preferences), feedback (corrections and confirmed approaches), project (ongoing work and decisions not visible in the code) and reference (where outside information lives, such as an issue tracker). According to the Claude Code docs, Claude skips anything it can derive from the codebase or that CLAUDE.md already says, and it does not save something every session. Auto memory is on by default in local sessions. You can switch it off in /memory, with the autoMemoryEnabled setting, or with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. The files are plain markdown you can read, edit or delete, and they are not shared across machines.

When are CLAUDE.md and auto memory not enough?

The built-in memory fits one developer working in one repository with Claude Code. It reaches its limits when several people or agents need the same knowledge, because auto memory is machine-local, and when facts conflict, because the docs note that with contradictory instructions "Claude may pick one arbitrarily". elephant.broker, a pluggable runtime for AI agents, addresses that case: on every turn elephant.broker assembles context from your tools, teammates and past sessions, drops what is stale or off-task, and flags sources that disagree. elephant.broker connects to Claude Code through an MCP server, native plugins or a REST API, and lets you bring the memory you already run. To make memory last on one machine, see persistent memory in Claude Code.

Sources

• Anthropic: Claude Code memory docs, Claude Code context window
• elephant.broker: overview, how a turn flows, features

Product details come from each vendor's public documentation as viewed on 2026-10-28 and may have changed. Product names are trademarks of their respective owners; elephant.broker is not affiliated with them.