Shayan Rais
109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
# Claude Code: Agent Memory Frontmatter
|
|
|
|
Persistent memory for subagents — enabling agents to learn, remember, and build knowledge across sessions.
|
|
|
|
<table width="100%">
|
|
<tr>
|
|
<td><a href="../">← Back to Claude Code Best Practice</a></td>
|
|
<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
|
|
</tr>
|
|
</table>
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
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.
|
|
|
|
```yaml
|
|
---
|
|
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
|
|
|
|
| Scope | Storage Location | Version Controlled | Shared | Best For |
|
|
|-------|-----------------|-------------------|--------|----------|
|
|
| `user` | `~/.claude/agent-memory/<agent-name>/` | No | No | Cross-project knowledge (recommended default) |
|
|
| `project` | `.claude/agent-memory/<agent-name>/` | Yes | Yes | Project-specific knowledge the team should share |
|
|
| `local` | `.claude/agent-memory-local/<agent-name>/` | No (git-ignored) | No | Project-specific knowledge that's personal |
|
|
|
|
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
|
|
|
|
| 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
|
|
|
|
```yaml
|
|
---
|
|
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).
|
|
|
|
---
|
|
|
|
## Tips
|
|
|
|
- **Prompt memory usage** — Include explicit instructions: `"Before starting, review your memory. After completing, update your memory with what you learned."`
|
|
- **Request memory checks** when invoking agents: `"Review this PR, and check your memory for patterns you've seen before."`
|
|
- **Choose the right scope** — `user` for cross-project, `project` for team-shared, `local` for personal
|
|
|
|
---
|
|
|
|
## Sources
|
|
|
|
- [Create custom subagents — Claude Code Docs](https://code.claude.com/docs/en/sub-agents)
|
|
- [Manage Claude's memory — Claude Code Docs](https://code.claude.com/docs/en/memory)
|
|
- [Claude Code v2.1.33 Release Notes](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
|