lockstep

Subagents

Subagents are specialized AI agents a main agent delegates to. Each works in its own context window and returns a summary, keeping the main context clean.

Subagents are specialized agents that a main agent delegates focused tasks to. The main agent keeps the plan; each subagent does deep work in its own context window and returns a condensed result. Anthropic's engineering team describes this as a way around context limits: a subagent might use tens of thousands of tokens exploring, but only the summary comes back.

Subagents in Claude Code

Claude Code subagents are defined in .claude/agents/ with their own instructions and tools. Two details matter for memory, per Anthropic's documentation:

  • The main conversation's auto memory is not loaded into subagents.
  • A subagent can have its own persistent memory with the memory field: user, project, or local scope.

With memory: project, the subagent's memory lives in .claude/agent-memory/<name>/ in the repository and goes through git like any other file. That makes a subagent one of the few native ways to share what an agent learned with a whole team. An example is in Claude Code team memory.

Subagents keep context clean, but they don't decide what is current. A subagent's memory can hold an outdated note as easily as a correct one, so review those files in pull requests. For five examples and best practices, see Claude Code subagents: 5 examples.

What is a subagent?
A separate agent that a main agent hands a focused task to. It works in its own context window, can use many tokens exploring, and returns only a condensed result, so the main conversation stays focused.
Do subagents share the main agent's memory?
Not by default. In Claude Code, the main conversation's auto memory isn't loaded into subagents, except a fork, which inherits the parent conversation. A subagent can have its own persistent memory with the memory field.
Can a subagent's memory be shared with a team?
Yes. With memory: project, a Claude Code subagent keeps its memory in .claude/agent-memory/<name>/ in the repository, which the team shares through git. Anthropic recommends project scope as the default.

Related