Claude Code Memory: How Coding Agents Remember Your Codebase (2026)

TL;DR

Claude Code has three built-in memory surfaces: CLAUDE.md files that load at session start, a /memory command for editing them, and per-session context that disappears when the session ends. Together they solve project conventions well and organizational knowledge poorly. If you want a coding agent to remember why a decision was made six months ago, or to carry what it learned in one repository into another, you need a layer outside Claude Code itself. This guide covers what the built-in memory actually does, where it stops, and the options for going further. Sentra, the organizational memory layer, is the external option covered after the built-in surfaces, and this guide is clear that most teams do not need it yet.

What memory does Claude Code have built in?

Two mechanisms, not one, and most write-ups cover only the first. Every session starts with a fresh context window, and these are what carry knowledge across it.

The CLAUDE.md locations, in load order

Four scopes, loaded broadest first, so a project instruction lands in context after a user instruction.

Files are concatenated rather than overriding each other, ordered from the filesystem root down to your working directory, with CLAUDE.local.md appended after CLAUDE.md at each level. Files in subdirectories load on demand when Claude reads files there rather than at launch. A CLAUDE.md can pull in others with @path/to/file syntax to a maximum depth of four hops, though imports still load at launch so they organise content without reducing context. Larger projects can split instructions into .claude/rules/, where a paths: frontmatter field scopes a rule to glob patterns so it only enters context when Claude touches matching files. Claude Code reads CLAUDE.md and not AGENTS.md, so repositories using the latter should import it.

Auto memory, and the limit that actually bites

Auto memory is on by default and is the half most guides miss. Claude writes notes to itself as it works, in four kinds recorded as a type field in each file's frontmatter: user for your role and working preferences, feedback for corrections you gave and approaches you confirmed, project for ongoing work and decisions not derivable from the code or git history, and reference for pointers to things outside the project. It deliberately skips anything it could derive from the codebase, and anything your CLAUDE.md already says.

Storage is ~/.claude/projects/<project>/memory/, where <project> is derived from the git repository, so every worktree and subdirectory of the same repo shares one directory. Inside sits a MEMORY.md index plus one topic file per memory.

The number to know: only the first 200 lines of `MEMORY.md`, or the first 25KB, whichever comes first, load at the start of a conversation. Anything past that threshold is silently dropped on the next load. A write that pushes the index over still succeeds, and Claude Code then returns an error telling Claude to rewrite the index, which is the mechanism that keeps it short. The limit applies to the index alone: topic files are not loaded at startup and are read on demand, and a CLAUDE.md is loaded in full up to 4 MiB and skipped entirely above it, with under 200 lines the documented target for adherence rather than a hard cap.

Two scoping facts matter for teams. Auto memory is machine-local: files are not shared across machines or cloud environments, so nothing one engineer's agent learns reaches anyone else's. And a subagent does not inherit the main conversation's auto memory unless it is a fork, so a fan-out of subagents starts cold on everything the parent worked out.

Where does the built-in memory stop?

The mechanics above are well designed for what they target, which is one engineer on one repository. Four limits show up quickly once that stops being the shape of the problem.

1. It stops at the machine. Auto memory is machine-local by design and CLAUDE.local.md is gitignored, so the two surfaces that accumulate real working knowledge are the two that never reach your team. What survives is the part a human remembered to write into a checked-in file.

2. It stops at the repository. The <project> directory is keyed to the git repo, and a CLAUDE.md is scoped to its directory tree. An agent in the mobile repo cannot see a decision recorded in the backend repo, even when that decision governs both.

3. It stops at the codebase boundary. Auto memory explicitly skips what it can derive from the code, which is correct, and nothing fills the other side: the reason a module was written a particular way usually lives in a pull request thread, a design review, a support escalation or a meeting. None of that is in the repository, so none of it is in memory.

4. It has no relevance filter, only a size ceiling. Everything loaded is loaded in full on every request, and the response to growth is truncation rather than ranking: MEMORY.md past 200 lines is dropped, not deprioritised. Prompt caching bills a cache read at 0.1x the base input rate, which softens the cost of resending a stable prefix but does nothing about whether the content is still true, because caching is indifferent to correctness.

What are the options for giving coding agents real memory?

Ranked from least to most infrastructure, with what each is genuinely good at:

1. Disciplined `CLAUDE.md` hygiene. Keep it under a page, state rules as imperatives, and delete anything that has not been needed in a month. Free, and it solves the convention problem completely. It solves nothing else.

2. Repository-graph tools. Open-source projects such as GitNexus and codebase-memory-mcp build a structural graph of a repository and expose it to the agent over MCP, so the agent can traverse call paths rather than grepping. Strong for navigating unfamiliar code, scoped to a single repository, and blind to anything that is not code.

3. Per-agent memory services. Products such as Mem0, Zep and Supermemory store facts an assistant accumulates and recall them later. Genuinely good for a single long-running assistant. Because each service is scoped to its own application, a fact learned by your coding agent does not reach your support agent.

4. Prompt caching and context pruning. Anthropic and OpenAI both offer prompt caching that reduces the cost of resending a stable prefix. This is a cost optimization, not a memory system: the content still has to be assembled, and stale content is cached just as happily as fresh content.

5. An organizational memory layer. A separate system ingests code, tickets, documents and conversations, resolves them into facts with provenance and time bounds, and serves the small relevant subset to whichever agent asks. This is the category Sentra occupies. It is the only option on this list that carries context between repositories and between tools, and it is the heaviest to adopt.

Which approach fits which problem?

For a solo developer on one repository, CLAUDE.md plus a repository-graph tool covers almost everything, and adding infrastructure would be waste. The calculus changes when several agents and several people need the same answer and keep arriving at different ones.

How does an organizational memory layer differ in practice?

Three mechanical differences, not marketing ones.

It compiles rather than retrieves. Instead of finding documents that resemble the query and pasting them in, it resolves the underlying facts and sends those. Sending a resolved fact instead of the six documents it was derived from is what produces the large token reductions, on the order of 70 percent in Sentra's internal measurements, and internal measurements are exactly what they sound like, so treat them as directional until independently reproduced.

It is bi-temporal. Every fact carries both when it was true and when the system learned it. That is what makes it possible to answer "what did we believe in March" and to detect that a fact recorded in March was contradicted in June. A flat file cannot do this, and neither can a vector store, because both treat all content as equally current.

It is governed. Access is scoped by role, so an agent acting for one person sees what that person is allowed to see. This matters the moment memory contains anything from HR, finance or customer conversations.

FAQ

The decision rule

Use CLAUDE.md for anything that is true of the repository and stable. Add a repository-graph tool when navigation is the bottleneck. Add an organizational memory layer only when the same question is being answered differently by different agents or different people, because that is the specific failure the layer exists to fix, and it is expensive to adopt for any other reason.