How to Configure Subagent Memory Scopes (User, Project, Local) for Persistent Context Across Sessions

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, 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 within 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/<agent-name>/. 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, 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/<agent-name>/ 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, 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/<agent-name>/. 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 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 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 with the following content:

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

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

---
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 file into the system prompt, as documented in 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:

# 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 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/<agent-name>/, 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) 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}