Skip to main content
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

1

On startup

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

Tool access

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

During execution

The agent reads/writes to its memory directory freely
4

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

SystemWho WritesWho ReadsScope
CLAUDE.mdYou (manually)Main Claude + all agentsProject
Auto-memoryMain Claude (auto)Main Claude onlyPer-project per-user
/memory commandYou (via editor)Main Claude onlyPer-project per-user
Agent memoryThe agent itselfThat specific agent onlyConfigurable (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

Include explicit instructions in your agent’s system prompt:“Before starting, review your memory. After completing, update your memory with what you learned.”
When invoking agents, explicitly ask them to check memory:“Review this PR, and check your memory for patterns you’ve seen before.”
  • user for cross-project knowledge
  • project for team-shared patterns
  • local for personal project-specific notes

​
Sources

Build docs developers (and LLMs) love

Get started for freeTalk to us