# How to Configure Subagent Memory Scopes (User, Project, Local) for Persistent Context Across Sessions > Learn to configure subagent memory scopes user project or local for persistent context across sessions Set the memory field in your subagent YAML for custom knowledge store locations - Repository: [Shayan Rais/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) - Tags: how-to-guide - Published: 2026-03-12 --- **Configure subagent memory scopes by setting the `memory` field in your subagent's YAML frontmatter to `user`, `project`, or `local`, which determines whether the persistent markdown knowledge store lives in your home directory, the repository, or a git-ignored local folder.** Claude Code subagents can maintain persistent context across sessions using markdown-based memory stores. When you configure subagent memory scopes, you control where this knowledge lives and who can access it. The `shanraisshan/claude-code-best-practice` repository documents this implementation in [`reports/claude-agent-memory.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-memory.md), showing how the `memory` front-matter field selects between three distinct persistence scopes. ## Understanding the Three Memory Scopes The subagent memory system supports three scopes that determine storage location, version control behavior, and sharing characteristics. As defined in the [scope table](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-memory.md#L33-L40) within [`reports/claude-agent-memory.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-memory.md), each scope serves different collaboration and persistence needs. ### User Scope (`user`) The **user scope** stores agent memory in `~/.claude/agent-memory//`. This location falls outside any repository, making it ideal for cross-project knowledge that should persist regardless of which codebase you open. According to [`reports/claude-agent-memory.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-memory.md), this is the default scope when no `memory` field is specified. Use the user scope for personal conventions, coding preferences, or patterns you want applied across all your projects. ### Project Scope (`project`) The **project scope** stores memory in `.claude/agent-memory//` within the repository. Because this directory is not git-ignored by default, it becomes version-controlled and shared with the entire team. As documented in [`reports/claude-agent-memory.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-memory.md), this scope enables team-wide knowledge bases that track architectural decisions and shared APIs. Use the project scope when the agent needs to remember decisions that affect the entire codebase and should be shared with teammates. ### Local Scope (`local`) The **local scope** stores memory in `.claude/agent-memory-local//`. This directory is automatically git-ignored, creating a personal, project-specific stash that never leaves the developer's machine. The `shanraisshan/claude-code-best-practice` repository notes in [`reports/claude-agent-memory.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-memory.md) that this is perfect for experimental notes or temporary data. Use the local scope for personal notes on a specific project that you don't want to share or commit to version control. ## How to Configure Memory Scopes in Subagent Definitions To configure subagent memory scopes, add the `memory` field to the YAML frontmatter of your subagent definition file. The [`implementation/claude-subagents-implementation.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/implementation/claude-subagents-implementation.md) file in the reference repository details how this frontmatter controls the persistence layer. ### Example: Project-Scoped Agent Create a file at [`.claude/agents/api-developer.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/api-developer.md) with the following content: ```yaml --- name: api-developer description: Implements API endpoints following team conventions tools: Read, Write, Edit, Bash model: sonnet memory: project # ← persists in .claude/agent-memory/api-developer/ skills: - api-conventions - error-handling-patterns --- ``` This configuration stores the agent's [`MEMORY.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/MEMORY.md) and any additional knowledge files in `.claude/agent-memory/api-developer/`, making them visible to git and shareable with the team. ### Example: User-Scoped Agent For personal preferences that span all repositories: ```yaml --- name: lint-assistant description: Provides linting suggestions based on personal style tools: Read, Write, Edit model: haiku memory: user # ← stored in ~/.claude/agent-memory/lint-assistant/ --- ``` All projects you open with Claude Code will access this same memory store, maintaining consistent linting advice across your development environment. ### Example: Local-Scoped Agent For experimental work that shouldn't be committed: ```yaml --- name: quick-prototype description: Tests a new data-structure in isolation tools: Read, Write, Edit model: opus memory: local # ← stored in .claude/agent-memory-local/quick-prototype/ --- ``` This creates a sandboxed memory space that remains project-specific but never appears in git status. ## Reading and Writing Memory During Execution When a subagent runs, Claude automatically injects the first 200 lines of its [`MEMORY.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/MEMORY.md) file into the system prompt, as documented in [`reports/claude-agent-memory.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-memory.md). The agent can then use standard tools to update this knowledge. ### Updating Memory Within a Task An agent can append new learnings to its memory file: ```python # Conceptual example of agent tool usage Read .claude/agent-memory/api-developer/MEMORY.md # Append architectural decision Write .claude/agent-memory/api-developer/MEMORY.md "Added GET /users endpoint with pagination logic (2024-03-12). Follows cursor-based pattern from RFC 5988." ``` Because the agent declares `memory: project` in its frontmatter, the **Read**, **Write**, and **Edit** tools automatically have access to this directory without additional permission configuration. ### Memory Persistence Across Sessions The markdown-based storage system ensures that knowledge persists between Claude Code sessions. When you restart Claude or switch to a different terminal, the agent retains access to its previous notes, code patterns, and architectural decisions stored in the configured scope location. ## Summary - **Configure subagent memory scopes** by setting the `memory` field in YAML frontmatter to `user`, `project`, or `local`. - **User scope** stores data in `~/.claude/agent-memory/` for cross-project personal knowledge. - **Project scope** stores data in `.claude/agent-memory/` for version-controlled, team-shared knowledge. - **Local scope** stores data in `.claude/agent-memory-local/` for git-ignored, personal project notes. - Agents automatically receive the first 200 lines of [`MEMORY.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/MEMORY.md) in their system prompt and can use **Read**, **Write**, and **Edit** tools to update their knowledge store. ## Frequently Asked Questions ### What happens if I don't specify a memory scope in my subagent definition? If you omit the `memory` field, Claude Code defaults to the **user scope**. The agent will store its persistent knowledge in `~/.claude/agent-memory//`, making it available across all projects you work on but isolated from your teammates. This default ensures that personal agent configurations persist regardless of which repository you open. ### Can I change the memory scope of an existing agent without losing data? Changing the `memory` field value does not automatically migrate existing data between locations. If you switch from `user` to `project`, the agent will start with an empty memory store in the new location. You must manually copy content from the old path (e.g., `~/.claude/agent-memory/my-agent/MEMORY.md`) to the new path (e.g., [`.claude/agent-memory/my-agent/MEMORY.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agent-memory/my-agent/MEMORY.md)) to preserve existing knowledge. ### How does the 200-line limit on MEMORY.md injection work? When a subagent initializes, Claude Code automatically reads the first 200 lines of the agent's [`MEMORY.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/MEMORY.md) file from its configured memory directory and injects this content into the system prompt. This provides immediate context without requiring explicit tool calls. If the file exceeds 200 lines, the remaining content remains available on disk and can be accessed via the **Read** tool when needed, but it won't appear in the initial context window. ### Is agent memory encrypted or protected from other users on the system? The memory files are stored as plain markdown text on the filesystem with standard Unix permissions. **User scope** memories reside in your home directory (`~/.claude/...`) and inherit your user permissions. **Project scope** memories follow the repository's permission structure. **Local scope** memories use standard file permissions. There is no additional encryption layer provided by Claude Code, so sensitive data should follow your organization's standard security practices for filesystem storage.