Giving Your Subagents Persistent Memory

The Problem: Agents That Forget

By default, every time a subagent starts, it starts fresh. It receives its system prompt, the delegation message, and the project's CLAUDE.md files — but none of what it learned in previous runs. If your code-reviewer agent figures out that your team uses a specific error-handling pattern, it forgets that observation when the session ends. The next time it runs, it has to re-discover it.

Persistent memory solves this. When enabled, a subagent can write observations to disk during a session and read them back at the start of every future session. The agent builds up knowledge over time the same way a human team member does.

Enabling Memory with the memory Field

Add the memory frontmatter field to a subagent definition to enable persistent memory:

---
name: code-reviewer
description: Reviews code for quality, clarity, and potential bugs. Remembers project-specific patterns.
tools: Read, Glob, Grep
memory: project
---

Three scope values control where memory is stored and who shares it:

• user: Stored at ~/.claude/agent-memory/{agent-name}/. Available to this agent across all projects on your machine. Use for patterns and preferences that apply everywhere — language idioms, formatting conventions, common anti-patterns.
• project: Stored at .claude/agent-memory/{agent-name}/. Available to this agent in this project only. Can be committed to version control so the entire team shares the agent's learned knowledge. Use for project-specific architecture decisions, naming conventions, and patterns.
• local: Stored at .claude/agent-memory-local/{agent-name}/. Available to this agent in this project, but gitignored — not shared with the team. Use for personal preferences or work-in-progress observations you are not ready to commit.

How the Memory System Works

When a subagent with memory enabled starts, it receives an injected system prompt addition that describes the memory system and provides the path to its memory directory. The agent automatically gains Read and Write tool access to that directory, even if those tools are not in its allowlist.

At startup, only the MEMORY.md index file is loaded — the first 200 lines or 25KB, whichever comes first. This index contains brief pointers to topic-specific memory files:

# Memory Index — code-reviewer

## Project Patterns
- [Error Handling](error-handling.md) — project uses Result type, never throws
- [Naming Conventions](naming.md) — snake_case functions, PascalCase types
- [Test Patterns](tests.md) — each test file mirrors source file structure

## Known Issues
- [Legacy Auth Module](legacy-auth.md) — technical debt flagged for Q4 refactor

Topic files are loaded on demand when the agent reads them. Only the index is loaded automatically, keeping startup context usage minimal even when the agent has accumulated many observations over time.

What Agents Should and Should Not Remember

Well-designed agent memory contains observations that are genuinely useful to future sessions of the same agent: patterns it discovered, decisions that were made, constraints it learned about.

Poor agent memory is a dump of everything the agent saw: file contents, lists of completed tasks, conversation summaries. This bloats the memory files, makes the index unwieldy, and crowds out the actually useful observations.

Guide your agents with clear instructions in their system prompt about what to save:

When you discover a pattern, architectural decision, or convention that
applies to future reviews of this codebase, save it to memory using the
project scope. Do not save individual findings — only reusable knowledge.

Memory vs. Hard-Coded System Prompt Instructions

The alternative to agent memory is putting everything in the system prompt. For static information — tools the agent should use, output format requirements, fixed rules — the system prompt is the right place. For information that evolves as the agent learns — project patterns, past decisions, accumulated context — memory is better.

The practical difference: system prompt instructions require you to manually update the agent definition every time the agent learns something new. Memory updates automatically as the agent works. For agents that run repeatedly over a codebase, memory compounds in value over time in ways that static system prompts cannot.