Agent Memory Frontmatter
Frontmatter system introduced in Claude Code v2.1.33 (February 2026). Agent files can declare `memory: user | project | local` to specify their persistent memory scope, distinct from the CLAUDE.md system and file-based auto-memory. All three scopes persist from session to session, in three different places: `user` in `~/.claude/agent-memory/<agent>/` (all projects), `project` in `.claude/agent-memory/<agent>/` (this project, meant to be versioned with the repository), `local` in `.claude/agent-memory-local/<agent>/` (this project, kept out of git) ([subagents documentation](https://code.claude.com/docs/en/sub-agents)).
Strengths
- Declarative scope, the agent itself defines where its memory is stored (user / project / local)
- Clean separation of agent memory vs project memory, no cross-pollution
- Distinct from the auto-memory system, both coexist without conflict
Limitations
- Recent feature (v2.1.33, Feb 2026), official documentation still sparse
- Debugging complexity, hard to know which memory layer is active without manual inspection
Best for
- Specialized agents (reviewers, auditors) that need to remember their previous observations
- Multi-session workflows where an agent accumulates context over several days