Agent Memory

Introduced in Claude Code v2.1.33 (February 2026), the memory frontmatter field gives each subagent its own persistent markdown-based knowledge store. Before this, every agent invocation started from scratch.

Overview

The memory frontmatter field enables persistent knowledge for subagents:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Write, Edit, Bash
model: sonnet
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Memory Scopes

user

Location: ~/.claude/agent-memory/<agent-name>/

Not version controlled
Not shared between users
Cross-project knowledge
Recommended default

project

Location: .claude/agent-memory/<agent-name>/

Version controlled
Shared with team
Project-specific knowledge

local

Location: .claude/agent-memory-local/<agent-name>/

Git-ignored
Not shared
Personal project knowledge

These scopes mirror the settings hierarchy: ~/.claude/settings.json → .claude/settings.json → .claude/settings.local.json

How It Works

On startup

First 200 lines of MEMORY.md are injected into the agent’s system prompt

Tool access

Read, Write, Edit are auto-enabled so the agent can manage its memory

During execution

The agent reads/writes to its memory directory freely

Curation

If MEMORY.md exceeds 200 lines, the agent moves details into topic-specific files

~/.claude/agent-memory/code-reviewer/     # user scope example
├── MEMORY.md                              # Primary file (first 200 lines loaded)
├── react-patterns.md                      # Topic-specific file
└── security-checklist.md                  # Topic-specific file

Agent Memory vs Other Memory Systems

System	Who Writes	Who Reads	Scope
CLAUDE.md	You (manually)	Main Claude + all agents	Project
Auto-memory	Main Claude (auto)	Main Claude only	Per-project per-user
`/memory` command	You (via editor)	Main Claude only	Per-project per-user
Agent memory	The agent itself	That specific agent only	Configurable (user/project/local)

These systems are complementary — an agent reads both CLAUDE.md (project context) and its own memory (agent-specific knowledge).

Practical Example

---
name: api-developer
description: Implement API endpoints following team conventions
tools: Read, Write, Edit, Bash
model: sonnet
memory: project
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions from your preloaded skills.
As you work, save architectural decisions and patterns to your memory.

This combines skills (static knowledge at startup) with memory (dynamic knowledge built over time).

Best Practices

Prompt memory usage

Include explicit instructions in your agent’s system prompt:“Before starting, review your memory. After completing, update your memory with what you learned.”

Request memory checks

When invoking agents, explicitly ask them to check memory:“Review this PR, and check your memory for patterns you’ve seen before.”

Choose the right scope

user for cross-project knowledge
project for team-shared patterns
local for personal project-specific notes

Technical Reports

Tips & Tricks

Overview

Memory Scopes

user

project

local

How It Works

Agent Memory vs Other Memory Systems

Practical Example

Best Practices

Sources

​Overview

​Memory Scopes

user

project

local

​How It Works

​Agent Memory vs Other Memory Systems

​Practical Example

​Best Practices

​Sources

Overview

Memory Scopes

How It Works

Agent Memory vs Other Memory Systems

Practical Example

Best Practices

Sources