Subagent memory in Claude Code: when to turn it on, and when to leave it off

TL;DR Yes for the subagent you run daily on the same repo, with two lines in its body (check your memory first, save what you learned after) and the directory committed to git. No for one-shot or read-only agents: turning memory on hands them Write and Edit back even if you had removed them.

A subagent starts empty every time. Launch your reviewer on Monday and it knows nothing of what it found on Friday: the repo's conventions, the bug that keeps coming back, where things live. It rediscovers all of it, spends tokens doing so, and whatever it learned dies with the summary it returns. It is the same reason they come back with incomplete results: they inherit nothing, not from your conversation and not from their own earlier runs.

The memory: frontmatter field gives the agent a directory of its own. At startup its system prompt carries the first 200 lines or 25 KB of whatever MEMORY.md sits there, and while it works it can write to it. By the third run it arrives knowing how your project works. This is not the auto memory of your main session: it is a notebook per agent, with the agent's name in the path, read only by that agent.

Result, after one test run with memory: project where I asked it to store a fact:

.claude/agent-memory/noter/
├── MEMORY.md                        # index: one line per entry
└── project_secret_greeting_word.md  # the entry, with its own frontmatter

# MEMORY.md
- [Project secret greeting word](project_secret_greeting_word.md) — the word is 'zanahoria'

The subagent chose the format on its own: a one-line-per-topic index and one file per topic with name, description and a "why" and "how to apply" block. It is the same scheme the main session's auto memory uses, and it comes from the instructions the binary injects along with the path.

When to turn it on

The candidate is the agent you launch several times a week on the same repo and whose work gets better with accumulated context: the reviewer, the test writer, the one that knows your domain.

1. The line, and the two sentences that make it use it

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality and best practices
memory: project
---

You are a senior code reviewer for this repository.

Before you start, check your agent memory for conventions and recurring
issues you have already recorded. When you finish, save what you learned:
new patterns, repeated mistakes, where things live.

Without the two sentences the memory exists but the agent consults it when it feels like it. With them, it reads at the start and updates at the end. The docs also suggest asking for it in each task prompt ("review this PR, and check your memory first"), but with the sentences in the agent body you do not depend on remembering.

2. The scope

The docs recommend project, and for a reviewer it makes sense: what it learns about your code, your teammate's reviewer inherits.

3. Check git status after the first run

With project, the directory shows up untracked and you commit it. With local, in my test it showed up untracked too: the binary carries a rule that excludes agent-memory-local from the repository, but the scheduled-tasks component writes it, not the subagent, and in a -p session .git/info/exclude stayed empty. If you pick local, make sure it does not end up in a commit.

When to leave it off

• One-shot agents. An agent that searches, summarizes or does a mechanical refactor has nothing to remember. What you get is a bigger cold start, because the index rides in the system prompt of every run, and a subagent shares no cache with your session. Better informed, yes. Less costly, no.
• Agents with restricted tools. Turning memory on hands them Read, Write and Edit back so they can manage their files. A reviewer defined with tools: Read, Grep, Glob so it never touches anything stops being read-only.
• user scope for project knowledge. One notebook for all your repos: what it learned in one it applies in another where it does not fit.
• project scope on a team without agreeing on it. Everyone's subagent writes into the repository, and those files land in every PR. Decide who commits it and when, or use local.
• An index nobody curates. Only the first 200 lines or 25 KB of MEMORY.md get in. When a write goes over, the binary warns inside the tool response itself ("compact it now: keep one line per entry, move detail into topic files"). Whatever sits past the limit does not exist for the agent.

What actually reaches the prompt

Two runs on the same test agent, each in a fresh session:

tools: Glob             + memory: project     →  "zanahoria", zero tool calls
tools: Glob             + auto memory off     →  two Glob calls and "unknown"

In the first, the agent could not read files and still answered: the fact was in the index line, and that line was inside its system prompt. In the second, with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, the memory: field did nothing: no instructions, no tools, and the agent searched blind and gave up. Subagent memory depends on auto memory: with autoMemoryEnabled: false or that variable set, the frontmatter line is decoration.

Official docs: Enable persistent memory

Requirements

• Checked on Claude Code v2.1.260, with a subagent on model: sonnet.
• Auto memory enabled (the default).