Inside Claude Code: Memory, Sub-Agents and Swarms

The systems that make Claude Code more than one stateless loop.

Previous: tools and permissions. Start: high level architecture.

The 30 Second Version

Compaction keeps long conversations inside the context window.
CLAUDE.md carries explicit project and user instructions into the prompt.
The memory directory stores durable facts across sessions without dumping everything into one prompt.
Background agents can extract and consolidate memory after normal turns.
Sub-agents and coordinator mode let Claude Code delegate work instead of doing everything in one loop.

Why Memory Exists

Coding sessions produce a lot of state: files read, searches, command output, errors, diffs, decisions, and user preferences.

Keeping everything forever blows up the context window. Throwing everything away makes the agent forget useful information. Claude Code uses several layers to manage that tradeoff.

CLAUDE.md

CLAUDE.md is explicit project memory. Claude Code loads it from the project, parent directories, and the user config directory, then injects it into the system prompt.

Nested CLAUDE.md files can also be discovered during tool use and attached when the agent enters deeper directories. Local instructions stay close to the files they govern.

The Memory Directory

Claude Code also uses ~/.claude/projects/.../memory/. The entrypoint is MEMORY.md, but it is treated as an index rather than one giant memory blob.

MEMORY.md gives a concise map.
Topic files hold details like preferences, project facts, feedback, and references.
The prompt can stay small while deeper context remains fetchable through tools.

The system avoids saving information that can be derived from the repo, git history, or CLAUDE.md. Memory is for durable facts, not duplicating the codebase.

Auto Memory And Dreams

After a normal turn, Claude Code can fork a restricted background agent to extract durable memory. It can read broadly, write only inside the memory area, and use read-only bash.

The “dream” system is a background consolidation pass. It reviews recent transcripts, improves memory files, removes duplicates, and prunes stale facts. Memory is treated as a maintained knowledge base, not append-only logs.

Sub-Agents

The Agent tool can start another agent loop with its own context, tools, permissions, transcript, and file state cache.

Explore agents are optimized for read-only codebase search.
Plan agents do architecture/planning work without mutation.
General purpose agents get broader tool access.
Verification and guide-style agents handle more specialized jobs.

This makes the architecture recursive: the main loop can call a tool that starts another loop, then summarize the child result back into the parent.

Forked Agents

Forked agents can inherit the parent conversation and rendered system prompt. That keeps prompt-cache prefixes stable, reducing cost and latency when multiple children share context.

Forking is guarded to avoid recursive spawning. A forked child knows it is not the main agent and should not start its own child agents.

Coordinator And Swarm Mode

Coordinator mode turns Claude Code into a leader that can start workers, send messages, stop them, approve permissions, and synthesize results.

Workers can run in tmux panes, iTerm tabs, or in-process. The leader has to write self-contained prompts because workers do not automatically inherit the full user conversation.

The useful pattern is not “many agents magically solve it”. It is controlled delegation: research in parallel, implementation with clear file ownership, verification as a separate worker, then synthesis by the leader.

Key Takeaway

Claude Code’s core loop is simple, but the surrounding systems make it usable for longer engineering work: memory, compaction, prompt-cache aware forking, background maintenance, and multi-agent coordination.

Series recap: architecture, agentic loop, tools and permissions, memory and sub-agents.

Ask about Sushen