How Claude Code Memory Works: CLAUDE.md, Auto Memory, MEMORY.md

Published July 30, 2026 · Archcore team

Claude Code assembles context from five layers: a hierarchy of CLAUDE.md files, path-scoped rules in .claude/rules/, Auto Memory (a MEMORY.md index plus topic files), skills, and per-subagent memory. Two facts surprise most teams. Only the first 200 lines or 25KB of the memory index load per session, and the memory itself lives outside your repository: per machine, per user, invisible to your teammates.

Here is how each layer works as of Claude Code v2.1.220 (July 2026), with the limits from the official docs and changelog, plus what none of the layers cover.

What are the layers?

How does CLAUDE.md actually load?

The four levels concatenate from broad to specific: managed policy, then user, then project, then CLAUDE.local.md. Nothing overrides anything; it all lands in context together. Two details worth knowing:

• CLAUDE.md is advice, not law. It is injected as a user message, not a system prompt, and the docs call it “context, not enforced configuration”. If you need a guarantee, that’s what hooks are for.
• Imports don’t save context. @path/to/file imports (max 4 hops deep) load at startup along with everything else. They organize your files; they don’t shrink the token bill.

The official size guidance is blunt: target under 200 lines per CLAUDE.md, because “longer files consume more context and reduce adherence.” The best-practices docs give a one-line test for every entry: would removing this cause Claude to make mistakes? If not, cut it. Bloated files cause Claude to ignore the instructions that matter.

How does Auto Memory work?

Auto Memory shipped in v2.1.32 (February 5, 2026) and is on by default. As Claude works, it decides what’s worth remembering and writes markdown into ~/.claude/projects/<project>/memory/: a MEMORY.md index plus topic files (debugging.md, api-conventions.md, and so on). At session start only the index loads, and only its first 200 lines or 25KB, whichever comes first. Topic files are read on demand. You manage all of it with /memory, and /context shows what actually loaded.

The limit has a telling history. It began as an undocumented 200-line cutoff that users discovered the hard way (#25006). A 25KB cap was added in v2.1.83 after reports of the index silently losing recent entries. A visible error on overflow, instead of silent truncation, only arrived in v2.1.210 in July 2026. Within a day of the feature’s release, the top requests were how to turn it off, and early users hit index corruption cascading into bad answers. It has improved steadily since then, but silent background memory earned its skeptics early.

Two design facts matter more than any bug, though. Auto Memory is per repository but machine-local: the docs say directly that files “are not shared across machines or cloud environments.” And it is unstructured: an index plus free-form topic files, no types, no relations, no search. Claude reads the index linearly and opens topic files by name.

What about rules, skills, and subagent memory?

• Rules (.claude/rules/, since v2.0.64) are CLAUDE.md split into files, with one genuinely useful property: a paths: frontmatter glob loads a rule only when Claude touches matching files. This is the right tool for directory-scoped standards.
• Skills load as a listing at startup (descriptions capped at 1,536 characters) and pull their body on invocation. They’re portable procedures: how to do things, not what this project decided.
• Subagent memory (memory: project in an agent’s frontmatter) writes to .claude/agent-memory/<name>/, which is committable, making it the only official memory layer your team can share through git. It feeds that one subagent, not the main session.

What can none of these layers hold?

Run one question over the table above: where does the project’s engineering record live? Nowhere in particular, it turns out.

1. The memory isn’t in your repo. Auto Memory accumulates on each developer’s machine separately. Your teammate’s Claude learns the same lessons yours did, from scratch. Nothing goes through a pull request, so a wrong “memory” never gets caught in review. (We wrote about where this road ends for vendor-side memory when Cursor removed its Memories feature.)
2. It’s tied to one tool. Claude Code explicitly does not read AGENTS.md, and the request is the most-upvoted open issue in the repository (4,475 👍 as of July 2026). Your CLAUDE.md means nothing to Cursor or Copilot, and their files mean nothing to Claude Code.
3. Nothing is typed or linked. A decision, a team rule, and a debugging note all look identical in free-form markdown. Nothing marks what’s binding, what’s stale, or which rule governs which directory, which is precisely the structure that keeps instruction files useful past the 200-line mark.
4. None of it is enforced. Every layer is advisory context; only hooks are deterministic.

How do you give Claude Code durable project memory?

Use the official layers for what they’re good at: a lean CLAUDE.md for session-critical facts, paths:-scoped rules for directory standards, skills for procedures, hooks for anything that must always happen.

For the engineering record (decisions with reasons, rules with scope, specs with status), keep repo memory: typed, versioned documents in the repository itself, reviewed like code. That’s what we build Archcore for; disclosure, it’s our tool. Documents live in .archcore/ with types and relations, load into Claude Code through MCP and session hooks, and the same files serve Cursor, Copilot, Gemini CLI, and any MCP-aware agent. The memory ends up belonging to the project rather than to one tool on one laptop. archcore init imports your existing CLAUDE.md and instruction files, so the 200 lines you’ve already written carry over.