Claude Code Sub Agent(子智能体)持久化记忆

简单整理一下 Claude Code 官方文档中关于子智能体（Sub-agents）memory 字段的用法。这个功能主要是给子智能体分配一个持久化目录，让它在不同会话之间也能记住东西。

基本定义：持久化存储目录

memory 字段为子智能体提供了一个跨会话保留的持久化目录。子智能体利用该目录逐步积累知识，例如代码库模式、调试经验和架构决策等。通过在该目录下读写 Markdown 文件，智能体可以在后续任务中复用这些积累。

存储作用域（Scopes）

Claude Code 严格划分了三种记忆作用域，开发者需根据信息的敏感度和复用需求进行选择：

1. user (全局)：存储在 ~/.claude/agent-memory/<name-of-agent>/。记忆跨项目保留，适用于通用的编码风格和偏好。
2. project (项目共享)：存储在 .claude/agent-memory/<name-of-agent>/。记忆与特定项目相关，可通过 Git 等版本控制工具共享给团队。
3. local (本地私有)：存储在 .claude/agent-memory-local/<name-of-agent>/。记忆仅与当前项目相关，但不应提交到版本控制（通常会被加入 .gitignore）。

启用后的自动行为

设置 memory 字段后，系统会自动处理以下逻辑：

• 指令注入：在子智能体的 System Prompt 中自动加入读写记忆目录的指令。
• 加载 MEMORY.md：系统会自动将记忆目录下 MEMORY.md 的前 200 行内容加载进 System Prompt。
• 内容精简提示：如果 MEMORY.md 超过 200 行，系统会指示子智能体自行对内容进行精简。
• 工具自动启用：即便没有在 tools 中声明，系统也会自动为子智能体启用 Read、Write 和 Edit 工具，以确保其能管理记忆文件。

CLI 定义方式

通过命令行启动时，可以使用 --agents 标志以 JSON 格式定义具备记忆功能的子智能体：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob"],
    "memory": "user"
  }
}'

官方最佳实践

1. 优先使用 user 作用域：除非子智能体的知识仅与特定代码库相关，否则推荐默认使用 user。
2. 主动要求查阅记忆：在处理 PR 或特定任务时引导智能体：“Review this PR, and check your memory for patterns you’ve seen before.”
3. 任务结束后更新记忆：任务完成时手动触发保存：“Now that you’re done, save what you learned to your memory.”
4. 内置自动化维护指令：在子智能体的 markdown 定义文件中直接写入以下指令，让其自主管理知识库：

   Update your agent memory as you discover codepaths, patterns, library locations, and key architectural decisions. Write concise notes about what you found and where.

与通用记忆系统的关系

在 Claude Code 中，子智能体的记忆与主会话的“自动记忆”（Auto Memory）是两套独立的系统。

如何开启 Auto Memory

Auto Memory 目前正在逐步发布（rollout）过程中。如果你的主会话没有自动开启该功能，可以通过设置环境变量来强制启用：

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0

两者对比

下表对比了两套记忆系统的具体实现细节：

• 机制：两者在底层逻辑上高度一致，都采用了“Markdown 文件 + 200 行加载上限”的轻量化方案。
• 物理隔离：它们存储在完全不同的目录下。子智能体无法直接读取或“污染”主会话的自动记忆，主会话也无法直接看到子智能体在私有目录下的积累。
• 分层认知：这种设计允许主会话关注项目级的全局模式，而子智能体则可以专注于特定任务（如代码审查、特定框架维护）的细节知识。

参考链接：

• Claude Code - Manage Memory (Auto Memory)
• Create custom subagents - Enable persistent memory