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.

What memory does Claude Code have built in?

Anthropic's Claude Code documentation describes a file-based memory system rather than a learned one. Three surfaces matter:

1. Project memory (`./CLAUDE.md`) sits in the repository root, is checked into git, and loads automatically at the start of every session. This is where team-wide conventions belong: package manager, test command, architectural rules, files never to touch.

2. User memory (`~/.claude/CLAUDE.md`) applies to every project on your machine and is not shared with the team. Personal shortcuts and preferences live here.

3. Imported files let a CLAUDE.md pull in other files with @path/to/file syntax, so a large ruleset can be split rather than crammed into one document.

Claude Code reads these files recursively upward from the working directory, so a monorepo can carry different rules per package. The /memory command opens them for editing mid-session, and the # prefix appends a line to memory without leaving the conversation.

The important property: this is text loaded into the context window, not a model that learns. Nothing you write is compressed, ranked, or resolved against anything else. Whatever is in the file is sent, every session, in full.

Where does the built-in memory stop?

Four limits show up quickly on real teams.

1. It does not persist reasoning across sessions. When a session ends, everything the agent worked out during it is gone unless a human wrote it down. The next session re-derives the same conclusions from the same files.

2. It does not span repositories. A CLAUDE.md is scoped to its directory tree. An agent working in the mobile repo has no access to what was decided in the backend repo, even when the decision governs both.

3. It does not know anything outside the codebase. The reason a module was written a particular way usually lives in a pull request comment, 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 grows without bound and every token is paid for on every request. Because CLAUDE.md loads in full at session start, a file that accumulates for a year becomes a fixed tax on every single request. There is no relevance filter.

The fourth point is the one teams underestimate. Anthropic's own prompt-caching documentation notes that cached input tokens are billed at a reduced rate, which softens the cost but does not remove it, and caches expire. A long instruction file is charged repeatedly whether or not any of it is relevant to the task at hand.

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.