Claude Code Subagents: Enable Persistent Memory

Full content

## Persistent memory for Claude Code subagents

Claude Code can give each custom subagent a persistent memory directory. Instead of starting from zero on every run, a subagent can accumulate project conventions, recurring bugs, debugging insights, and architectural decisions.

Add a `memory` field to the agent definition, for example `.claude/agents/code-reviewer.md`:

```markdown
---
name: code-reviewer
description: Reviews code for bugs, security risks, and project conventions
model: sonnet
memory: local
---

You are a senior code reviewer. Read your memory before each review. Afterward, save concise reusable lessons, but never store secrets, credentials, temporary status, or raw logs.
```

### Memory scopes

| Scope | Directory | Best for |
|---|---|---|
| `user` | `~/.claude/agent-memory/<agent-name>/` | Learnings shared across projects |
| `project` | `.claude/agent-memory/<agent-name>/` | Project knowledge shared through version control |
| `local` | `.claude/agent-memory-local/<agent-name>/` | Private project knowledge that should not be committed |

Start with `local`, and add `.claude/agent-memory-local/` to `.gitignore`. Promote only reviewed, non-sensitive knowledge to `project` memory.

Ensure auto memory is enabled in `.claude/settings.json` or `~/.claude/settings.json`:

```json
{
  "autoMemoryEnabled": true
}
```

The feature has no effect when auto memory is disabled through that setting or `CLAUDE_CODE_DISABLE_AUTO_MEMORY`.

When enabled, Claude Code injects memory-management instructions into the subagent prompt, loads the first 200 lines or 25KB of `MEMORY.md`, and automatically enables Read, Write, and Edit so the agent can maintain its memory. Each named subagent receives a separate memory directory.

Manage agents with `/agents`, or invoke one explicitly: `Use the code-reviewer subagent to review this PR. Consult your memory first and save reusable findings when done.`

Good uses include persistent code-review findings, project documentation, recurring QA failures, and refactoring conventions. Never use agent memory for passwords, API keys, personal data, `.env` contents, or unverified transient state.