Why Claude Code Subagents Don't Share Memory — and How to Fix It (2026)

Isolation is the feature you're paying for

Start with what subagents are for. Claude Code's documentation describes the use case as a side task that would otherwise flood your main conversation with search results, logs, or file contents you won't reference again: "the subagent does that work in its own context and returns only the summary." Each one "runs in its own context window with a custom system prompt, specific tool access, and independent permissions."

That's a good trade and you shouldn't want it undone. Ten thousand lines of test output stay where they belong, and your main conversation gets three sentences. But notice what the same sentence implies: whatever the subagent understood along the way — the error wrapper, the naming quirk, the fact that two modules disagree — exists only in a context window that's now gone. What came back was the summary, and the summary is whatever the subagent thought was worth saying.

The main conversation's memory doesn't cross the boundary

Claude Code has auto memory, on by default, where Claude writes its own notes as it works: build commands, debugging insights, preferences it discovers. Those live per repository under ~/.claude/projects/<project>/memory/, with a MEMORY.md index loaded at the start of every conversation.

Every conversation, that is, except a subagent's. The documentation states it directly: "The main conversation's auto memory isn't loaded into subagents." The one exception is a fork, which inherits the parent conversation and system prompt outright. So the thing your main session learned about this repo last Tuesday is not in front of the subagent you dispatch today.

Each subagent's memory is its own directory

Subagents can keep their own notes, and this is worth enabling. Add a memory field to a subagent definition and it gets a persistent directory that survives across conversations, which the docs describe as a place to "build up knowledge over time, such as codebase patterns, debugging insights, and architectural decisions." Three scopes are available: user writes to ~/.claude/agent-memory/<name-of-agent>/, project writes to .claude/agent-memory/<name-of-agent>/ and is shareable through version control, and local writes to .claude/agent-memory-local/<name-of-agent>/ and stays out of git.

Read those paths carefully, because the answer to our question is in the directory name. Memory is scoped per agent name. The reviewer's accumulated knowledge is in the reviewer's folder; the test writer has its own folder; and there is no shared folder they both read. Two useful things also come with the feature and imply their own limits: the subagent's system prompt includes the first 200 lines or 25KB of its MEMORY.md, whichever comes first, and the whole mechanism is part of auto memory — turn auto memory off with autoMemoryEnabled or CLAUDE_CODE_DISABLE_AUTO_MEMORY and the memory field has no effect at all.

Two built-in subagents skip your CLAUDE.md as well

There's one more gap that surprises people, and it's documented: "Explore and Plan skip your CLAUDE.md files and the parent session's git status to keep research fast and inexpensive. Every other built-in and custom subagent loads both."

Explore is the subagent that goes and reads your codebase. It's the one you'd most want to know your conventions — and it's deliberately the one that doesn't. That's a reasonable performance decision, and it means the research feeding your main conversation was done by something that hadn't read your standards.

And none of it leaves the machine

Auto memory is machine-local. The documentation is unambiguous: all worktrees and subdirectories in a repo share one directory, and "Files are not shared across machines or cloud environments." Same for the per-agent directories, unless you commit the project-scoped ones.

So the accumulated knowledge of your agent team lives on one laptop, in per-agent folders, invisible to your other tools and to your teammates unless you deliberately check parts of it in. Which is fine for build commands. It's not fine for the reason a module is off-limits.

Putting everything in `CLAUDE.md`. The correct first move, and it does reach every subagent except Explore and Plan. The limit is size: the docs recommend targeting under 200 lines per file because longer files consume more context and reduce adherence. A CLAUDE.md big enough to hold what four subagents have learned is a CLAUDE.md nobody follows.

Writing longer subagent prompts. Works for standing instructions, doesn't work for discoveries. You can tell the test writer about the error wrapper once you know about it — but the point was that the reviewer knew and you didn't.

Telling the subagent to write a file. "Save what you learned to notes/review-findings.md." Effective, and essentially hand-rolling the memory feature. Fine until you have four agents, four files, and no convention about who reads which.

Using forks instead. A fork inherits the parent conversation and system prompt, which genuinely solves the "it doesn't know what we discussed" problem — at the cost of the context savings you wanted. Right tool for continuing your own thinking, wrong tool for isolating a noisy task.

Enabling per-agent memory and hoping it's enough. Do enable it; project scope is the documented recommendation because it makes that knowledge shareable through version control. Just don't expect it to be a shared brain. It's a per-agent notebook, and the docs describe it as exactly that.

Running fewer subagents. People end up here after the third contradiction. It works, and it's a real loss — you're paying context to avoid a coordination gap.

The isolation should stay. What needs to change is that "isolated context" and "isolated knowledge" are currently the same thing, and they don't have to be.

The shape that works is a shared store the main conversation and every subagent can read and write, sitting alongside the per-agent memory rather than replacing it. Discoveries that matter beyond one task — the error wrapper, the decision, the deprecated helper — go there, and every agent reads the same version. Per-agent memory keeps holding what's genuinely local to that agent's craft.

MemoryLake is a memory layer for that — one store your decisions, conventions, and source documents live in, reachable over MCP from Claude Code and its subagents, from Codex, and from ChatGPT through the API. Not another notebook per agent: one record with several readers.

Step 1: Create an API key

Generate a key and make your first request in about 30 seconds. Keep it in your environment or a secret manager rather than pasting it into a session.

Step 2: Upload your first memories

Drop in the documents, images, and files your agents keep rediscovering: the conventions, the architecture decisions, the incident writeups behind your rules, the API contracts, the "don't touch this" list with reasons attached. Upload the sources rather than a summary — a summary is what a subagent already hands you, and the compression is the problem you're solving.

Step 3: Connect your AI & agents

Give Claude, Codex, OpenClaw, and other AI agents access to memory via MCP or the API. Claude Code reads it over MCP alongside your CLAUDE.md files, and you can scope access per subagent: the docs note that declaring an MCP server inline in a subagent's mcpServers field keeps its tool descriptions out of the main conversation's context entirely — the subagent gets the tools, the parent doesn't. That's how you give the reviewer and the test writer the same memory without spending parent context on it.

The first difference is that a discovery outlives the task that produced it. The reviewer notices the error wrapper, writes it to the shared store, and the test writer reads it an hour later — without you being the message bus between two agents that can't see each other.

The second is that your CLAUDE.md can stay short enough to work. Instead of growing a file toward the size where adherence drops, standing rules stay in the file and accumulated detail moves to retrieval. This is the same reason an agent that re-reads your codebase every session is expensive: the knowledge exists, it just isn't where the agent looks.

The third is that the knowledge survives the laptop. Auto memory and per-agent memory are machine-local by design; a shared store is where the parts your team needs — the decisions, the reasons, the conventions — stop being one developer's local files. That's the difference between a colleague being able to ask "why is this off-limits" and having to ask you.

And it doesn't fight what Claude Code does natively. Auto memory keeps writing build commands and debugging notes per repo. Per-agent memory keeps accumulating each subagent's craft knowledge. Neither has to become a system of record, which is the role they're least suited to — and the same division of labor that makes several agents on one memory workable at all.

Turn on per-agent memory, at project scope

memory: project is the documented recommendation, and the reason is good: the directory is checked into version control, so a subagent's accumulated knowledge is reviewable by your team instead of trapped in your home directory. Use local only for notes that genuinely shouldn't be committed.

Ask for memory reads and writes explicitly

The docs suggest exactly this: prompt the subagent to consult its memory before starting ("check your memory for patterns you've seen before") and to update it after finishing ("save what you learned"). Better still, put those instructions in the subagent's own markdown body so it maintains itself without you remembering.

Keep MEMORY.md as an index, not a warehouse

Only the first 200 lines or 25KB of MEMORY.md get loaded — content past that is not loaded at session start. Keep one line per entry and push detail into topic files, which Claude reads on demand. A memory index that overflows silently is worse than a short one, because you'll believe it's in context.

Assume Explore hasn't read your conventions

Since Explore and Plan skip CLAUDE.md by design, don't treat their findings as convention-aware. If a research result is going to drive an edit, restate the relevant rule when you act on it — or give Explore a shared memory it can query, which is the more durable version of the same fix.

Don't confuse either memory with enforcement

Claude Code's documentation says instruction files and auto memory are "context, not enforced configuration," with no guarantee of strict compliance. Anything that must be true every time — never touch generated files, always run the linter — belongs in a hook or a CI check. Memory is for knowing; hooks are for guaranteeing. Anyone selling you memory as compliance is selling.

Write down the reason, not just the finding

"Payments uses a custom error wrapper" is a fact that will be questioned. "Payments uses a custom error wrapper because the upstream client swallows status codes — see the March incident" is a fact that survives being questioned by the next agent, and the next engineer.

Claude Code subagents don't share memory because they don't share context, and that isolation is the feature: each one works in its own window and returns only a summary. The memory situation is more nuanced than "they have none." They can have persistent memory, per agent, in a directory named after the agent, at user, project, or local scope. What doesn't exist is a shared surface: the main conversation's auto memory isn't loaded into subagents, per-agent directories don't read each other, Explore and Plan skip your CLAUDE.md entirely, and all of it stays on one machine.

So keep the isolation and fix the sharing. Enable per-agent memory at project scope, keep MEMORY.md an index, treat Explore as convention-blind, and put the knowledge that matters to more than one agent in one store they all read. Then the second agent starts from what the first one learned, and you stop being the integration layer between your own subagents.