Skip to content

claude-agent-memory.md

Latest commit

 

History

History
108 lines (78 loc) · 3.95 KB

claude-agent-memory.md

File metadata and controls

108 lines (78 loc) · 3.95 KB

Claude Code: Agent Memory Frontmatter

Persistent memory for subagents — enabling agents to learn, remember, and build knowledge across sessions.

← Back to Claude Code Best Practice Claude

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.

---
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

---
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