updated report
This commit is contained in:
Shayan Rais
@@ -152,3 +152,4 @@ See [weather-orchestration-architecture](weather-orchestration/weather-orchestra
|
||||
| [CLAUDE.md Loading in Monorepos](reports/claude-md-for-larger-mono-repos.md) | Understanding ancestor vs descendant loading behavior for CLAUDE.md files |
|
||||
| [Global vs Project Settings](reports/claude-global-vs-project-settings.md) | Which features are global-only (`~/.claude/`) vs dual-scope, including Tasks and Agent Teams |
|
||||
| [Skills Discovery in Monorepos](reports/claude-skills-for-larger-mono-repos.md) | How skills are discovered and loaded in large monorepo projects |
|
||||
| [Agent Memory Frontmatter](reports/claude-agent-memory.md) | Persistent memory scopes (`user`, `project`, `local`) for subagents — enabling agents to learn across sessions |
|
||||
|
||||
+23
-159
@@ -9,30 +9,11 @@ Persistent memory for subagents — enabling agents to learn, remember, and buil
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Syntax](#syntax)
|
||||
3. [Memory Scopes](#memory-scopes)
|
||||
4. [How It Works Under the Hood](#how-it-works-under-the-hood)
|
||||
5. [Agent Memory vs Other Memory Systems](#agent-memory-vs-other-memory-systems)
|
||||
6. [Practical Patterns](#practical-patterns)
|
||||
7. [Tips for Effective Agent Memory](#tips-for-effective-agent-memory)
|
||||
8. [Sources](#sources)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Introduced in **Claude Code v2.1.33** (February 2026), the `memory` frontmatter field transforms subagents from stateless tools into **context-aware assistants** that persist knowledge across conversations.
|
||||
|
||||
Before this feature, every agent invocation started from scratch — a code review agent couldn't remember patterns it flagged last week, and a debugging agent couldn't recall the architecture it mapped yesterday. The `memory` field fixes this by giving each agent its own persistent markdown-based knowledge store.
|
||||
|
||||
---
|
||||
|
||||
## Syntax
|
||||
|
||||
Add the `memory` field to the YAML frontmatter of any agent file in `.claude/agents/`:
|
||||
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
|
||||
---
|
||||
@@ -47,131 +28,50 @@ You are a code reviewer. As you review code, update your agent memory with
|
||||
patterns, conventions, and recurring issues you discover.
|
||||
```
|
||||
|
||||
The `memory` field accepts one of three scope values: `user`, `project`, or `local`.
|
||||
|
||||
---
|
||||
|
||||
## Memory Scopes
|
||||
|
||||
| Scope | Storage Location | Version Controlled | Shared With Team | Best For |
|
||||
|-------|-----------------|-------------------|-----------------|----------|
|
||||
| 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 |
|
||||
|
||||
### Scope Selection Guide
|
||||
|
||||
**Use `user` when** the agent's knowledge applies across projects — coding style preferences, common anti-patterns, general best practices. This is the recommended default scope.
|
||||
|
||||
**Use `project` when** the agent's knowledge is codebase-specific AND should be shared — architectural decisions, project conventions, known quirks. This gets committed to version control so teammates benefit.
|
||||
|
||||
**Use `local` when** the agent's knowledge is codebase-specific but personal — your local environment setup, debugging notes, personal workflow preferences for this project.
|
||||
|
||||
### Scope Hierarchy Parallel
|
||||
|
||||
These scopes mirror the existing settings hierarchy:
|
||||
|
||||
| Agent Memory Scope | Settings Equivalent | Philosophy |
|
||||
|-------------------|---------------------|------------|
|
||||
| `user` | `~/.claude/settings.json` | Global personal defaults |
|
||||
| `project` | `.claude/settings.json` | Team-shared project config |
|
||||
| `local` | `.claude/settings.local.json` | Personal project overrides |
|
||||
These scopes mirror the settings hierarchy (`~/.claude/settings.json` → `.claude/settings.json` → `.claude/settings.local.json`).
|
||||
|
||||
---
|
||||
|
||||
## How It Works Under the Hood
|
||||
## How It Works
|
||||
|
||||
When an agent has `memory` configured:
|
||||
|
||||
1. **On startup**: The first 200 lines of `MEMORY.md` from the agent's memory directory are injected into the agent's system prompt
|
||||
2. **Tool access**: `Read`, `Write`, and `Edit` tools are automatically enabled (regardless of the `tools` frontmatter) so the agent can manage its memory files
|
||||
3. **During execution**: The agent can read from and write to its memory directory at any time
|
||||
4. **Memory structure**: The agent maintains a `MEMORY.md` file and can create additional topic-specific files as needed
|
||||
|
||||
### Memory Directory Structure
|
||||
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 memory file (first 200 lines loaded)
|
||||
├── MEMORY.md # Primary file (first 200 lines loaded)
|
||||
├── react-patterns.md # Topic-specific file
|
||||
└── security-checklist.md # Topic-specific file
|
||||
```
|
||||
|
||||
**Important**: If `MEMORY.md` exceeds 200 lines, the agent is instructed to curate it — moving detailed notes into separate topic files and keeping the main file as a high-level index.
|
||||
|
||||
---
|
||||
|
||||
## Agent Memory vs Other Memory Systems
|
||||
|
||||
Claude Code has multiple memory mechanisms. Here's how they compare:
|
||||
| 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) |
|
||||
|
||||
| System | Who Writes It | Who Reads It | Scope | Location |
|
||||
|--------|--------------|-------------|-------|----------|
|
||||
| **CLAUDE.md** | You (manually) | Main Claude + all agents | Project | `./CLAUDE.md` |
|
||||
| **Auto-memory** | Main Claude (automatically) | Main Claude only | Per-project per-user | `~/.claude/projects/<hash>/memory/` |
|
||||
| **`/memory` command** | You (via editor) | Main Claude only | Per-project per-user | Opens auto-memory files |
|
||||
| **Agent memory** ✨ | The agent itself | That specific agent only | Configurable (user/project/local) | Scope-dependent (see above) |
|
||||
|
||||
### Key Distinctions
|
||||
|
||||
- **CLAUDE.md** is human-authored project instructions — shared with everyone, loaded everywhere
|
||||
- **Auto-memory** is what the main Claude conversation learns about your project over time — personal, automatic
|
||||
- **Agent memory** is what a specific subagent learns over repeated invocations — scoped to that agent, self-maintained
|
||||
- These systems are **complementary, not overlapping** — an agent reads both CLAUDE.md (for project context) and its own memory (for agent-specific knowledge)
|
||||
These systems are **complementary** — an agent reads both CLAUDE.md (project context) and its own memory (agent-specific knowledge).
|
||||
|
||||
---
|
||||
|
||||
## Practical Patterns
|
||||
|
||||
### Pattern 1: Code Review Agent with Learning
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Reviews PRs for quality, patterns, and conventions
|
||||
memory: project
|
||||
---
|
||||
|
||||
Review the code changes. Check your memory for known patterns and recurring
|
||||
issues in this codebase. After reviewing, update your memory with any new
|
||||
patterns or conventions you discovered.
|
||||
```
|
||||
|
||||
Over time this agent builds a project-specific knowledge base of code conventions, common mistakes, and architectural patterns — shared with the whole team via `project` scope.
|
||||
|
||||
### Pattern 2: Architecture Explorer
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: arch-explorer
|
||||
description: Maps and remembers codebase architecture
|
||||
memory: user
|
||||
---
|
||||
|
||||
Explore the codebase to answer architecture questions. Consult your memory
|
||||
first for previously mapped codepaths. Update your memory as you discover
|
||||
new architectural decisions, module boundaries, and key integration points.
|
||||
```
|
||||
|
||||
Using `user` scope means this agent's architectural knowledge carries across all your projects.
|
||||
|
||||
### Pattern 3: Debugging Assistant
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: debugger
|
||||
description: Investigates bugs with context from past debugging sessions
|
||||
memory: local
|
||||
---
|
||||
|
||||
Investigate the reported issue. Check your memory for similar bugs or
|
||||
known problematic areas. Document your findings and resolution in memory
|
||||
for future reference.
|
||||
```
|
||||
|
||||
Using `local` scope keeps personal debugging notes private and project-specific.
|
||||
|
||||
### Pattern 4: Complete Agent with Skills and Memory
|
||||
## Practical Example
|
||||
|
||||
```yaml
|
||||
---
|
||||
@@ -189,51 +89,15 @@ 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 loaded at startup) with **memory** (dynamic knowledge built over time).
|
||||
This combines **skills** (static knowledge at startup) with **memory** (dynamic knowledge built over time).
|
||||
|
||||
---
|
||||
|
||||
## Tips for Effective Agent Memory
|
||||
## Tips
|
||||
|
||||
### 1. Prompt the Agent to Use Its Memory
|
||||
|
||||
Include explicit memory instructions in the agent's markdown body:
|
||||
|
||||
```markdown
|
||||
Before starting work, review your memory for relevant context.
|
||||
After completing the task, update your memory with what you learned.
|
||||
```
|
||||
|
||||
### 2. Request Memory Consultation
|
||||
|
||||
When invoking agents, you can ask them to check their memory:
|
||||
|
||||
> "Review this PR, and check your memory for patterns you've seen before."
|
||||
|
||||
### 3. Request Memory Updates
|
||||
|
||||
After task completion, prompt the agent to save learnings:
|
||||
|
||||
> "Now that you're done, save what you learned to your memory."
|
||||
|
||||
### 4. Include Proactive Memory Instructions in the Agent Body
|
||||
|
||||
For agents that should always maintain their memory:
|
||||
|
||||
```markdown
|
||||
Update your agent memory as you discover codepaths, patterns, library
|
||||
locations, and key architectural decisions. This builds institutional
|
||||
knowledge across conversations. Write concise notes about what you found
|
||||
and where.
|
||||
```
|
||||
|
||||
### 5. Choose the Right Scope
|
||||
|
||||
| If the knowledge is... | Use scope |
|
||||
|------------------------|-----------|
|
||||
| Useful across all your projects | `user` |
|
||||
| Codebase-specific, useful for the team | `project` |
|
||||
| Codebase-specific, personal to you | `local` |
|
||||
- **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
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user