1. 为什么 subagent 每次都要从零摸索用 Claude Code 跑过几轮复杂任务之后你大概率会遇到一个很别扭的现象同一个 code-reviewer subagent上周刚在认证模块里踩过 token 刷新的坑这周再让它评审同类改动它又像第一次见到这个仓库一样从头翻文件、重新推理。同一个 test-runner subagent明明已经知道这个 monorepo 的集成测试必须先起 Redis下次还是从日志里一点点猜。这不是模型不够强而是 subagent 的上下文机制决定的——它每次启动都是一个全新的独立上下文窗口看不到主会话的历史也看不到自己上次的工作笔记。Claude Code 官方把 subagent 定义成专门处理特定任务的 AI assistant它在独立上下文里工作有自己的 system prompt、工具权限和权限边界只把结果摘要返回给主会话。这个设计本身是对的能避免搜索日志、文件内容、排查过程把主会话撑爆。但隔离得太彻底长期经验就丢了。agent-memory 机制就是为这个矛盾准备的它不是主会话的普通上下文也不是 CLAUDE.md 这种由人维护的项目说明而是给特定 subagent 准备的一块持久化工作笔记跨对话保留让同一个角色下次出现时不必从零开始。这篇内容聚焦 Claude Code 中 subagent 的 agent-memory 机制围绕 MEMORY.md 的加载与隔离展开。我会给出可复制的 MEMORY.md 目录结构、subagent frontmatter 配置片段并演示多个 subagent 记忆互不串扰的验证步骤。适合已经在用 Claude Code、并且开始把任务拆给多个 subagent 的开发者。如果你还在单会话里手动指挥这套机制能帮你把「专业分工」真正沉淀下来。先说清楚它解决的不是「一次任务怎么完成」而是「同一个 subagent 下次再出现时怎样不从零开始」。只要 subagent 的 frontmatter 里配置了 memory 字段Claude Code 就会为它准备一个持久化目录subagent 可以把代码库模式、调试经验、架构决策、反复出现的问题写进去。启用 memory 后subagent 的 system prompt 会包含读写 memory 目录的说明还会把该目录里 MEMORY.md 的前 200 行或前 25 KB 注入到 system prompt 中以先到的限制为准。这个「前 200 行或 25 KB」的细节后面会专门讲它直接决定你该怎么写 MEMORY.md。2. agent-memory 与 main session auto memory 的区别及 MEMORY.md 加载隔离机制很多人第一次看到 MEMORY.md 会混淆以为它和 Claude Code 的 main session auto memory 是一回事。其实它们处在两个不同层面目录位置、加载时机、归属角色都不一样。搞混这两者是后面记忆串扰和「写了没生效」问题的根源。main session 的 auto memory 是给主会话用的它会在工作过程中保存构建命令、调试洞察、架构笔记、代码风格偏好和工作习惯。默认位置是~/.claude/projects/project/memory/其中 MEMORY.md 作为入口文件详细内容可以拆到其他 topic 文件里。主会话每次对话开始时只加载 MEMORY.md 的前 200 行或前 25 KBtopic 文件不会在启动时自动全部加载而是在需要时读取。subagent memory 走的是另一条线。配置在 subagent frontmatter 里的 memory 字段不会写到主会话的~/.claude/projects/project/memory/而是给这个 subagent 分配自己的目录。三个 scope 分得很清楚scope目录位置适用场景是否进版本控制project.claude/agent-memory/agent-name/团队共享的项目特定知识是local.claude/agent-memory-local/agent-name/项目特定但不该提交的本机细节否user~/.claude/agent-memory/agent-name/跨项目复用的个人专家经验否这个区分很关键。main session auto memory 更像项目驾驶舱的个人工作笔记记录 Claude Code 在整个项目交互中学到的东西。subagent memory 更像一个专科工程师自己的知识库。code-reviewer 不需要知道部署机密deploy-agent 也不需要记住每个 UI 组件的可访问性审查规则。把记忆按角色拆开之后信息污染会少很多错误调用旧知识的概率也更低。再说加载隔离。subagent 每次启动进入全新的独立上下文窗口不会看到主会话的对话历史、已经调用过的 skills、已经读过的文件。Claude 会组合一条 delegation message把任务摘要交给 subagentsubagent 从那里开始工作。非 fork subagent 的初始上下文会包含自己的 system prompt、任务消息、相关 CLAUDE.md 和 memory 层级、git status 以及预加载 skills。注意这里的关键点注入的是「该 subagent 自己 memory 目录下的 MEMORY.md」不是所有 subagent 的 memory 汇总也不是主会话的 auto memory。这就是隔离的物理基础——每个 subagent 只读自己那块目录。为什么只加载前 200 行或 25 KB因为上下文窗口不是数据库模型不是靠精确索引读完整仓库。启动时注入太多旧笔记反而会稀释当前任务的关键上下文也会提高成本和干扰。所以更合理的写法是把 MEMORY.md 当成索引和高密度摘要而不是流水账。里面记录高复用、高确定性、低歧义的信息例如某个目录负责什么、某类测试失败常见原因是什么、某个模块的历史决策是什么。详细排查过程、历史日志、长篇推理链路拆到同目录下的其他 markdown 文件里由 subagent 在需要时再读。这和人类团队的知识管理很像。一个资深 reviewer 不会把过去每次评审的完整聊天记录都背下来但他会记住团队在认证、权限、错误处理、审计日志上的固定雷区。MEMORY.md 就该像他的随身小本子开工前扫一眼知道项目里哪些地方不能踩坑。至于某个历史问题的完整上下文再去更详细的文档里翻。3. 可复制的 MEMORY.md 目录结构与 subagent 配置片段这一节是整篇最需要动手的部分。我按 project scope 来演示因为团队共享场景最能体现 agent-memory 的价值。先看目录结构再逐个文件给配置。假设你的仓库根目录是my-monorepo里面要放三个 subagentcode-reviewer、test-runner、security-reviewer。目录结构如下my-monorepo/ ├── .claude/ │ ├── agents/ │ │ ├── code-reviewer.md │ │ ├── test-runner.md │ │ └── security-reviewer.md │ └── agent-memory/ │ ├── code-reviewer/ │ │ ├── MEMORY.md │ │ └── review-patterns.md │ ├── test-runner/ │ │ ├── MEMORY.md │ │ └── flaky-tests.md │ └── security-reviewer/ │ ├── MEMORY.md │ └── auth-checklist.md ├── CLAUDE.md └── src/注意每个 subagent 一个独立子目录目录名和 agent 的 name 字段一致。这是隔离的关键写错名字就会导致 memory 找不到或串到别的角色。接着看 subagent 的 frontmatter 配置。以 code-reviewer 为例文件.claude/agents/code-reviewer.md--- name: code-reviewer description: 评审代码改动重点检查认证、错误处理、异步资源释放 tools: Read, Grep, Glob, Write, Edit memory: project --- 你是本仓库的代码评审专家。评审时优先关注认证态传递、错误分支是否泄露内部异常、异步订阅是否释放。发现稳定可复用的评审模式时写入你的 memory 目录。这里memory: project就是开关。它告诉 Claude Code 为这个 subagent 分配.claude/agent-memory/code-reviewer/目录并把该目录下 MEMORY.md 的前 200 行或 25 KB 注入 system prompt。注意tools里必须包含Write和Edit否则 subagent 没法维护自己的 memory。官方文档也说明启用 memory 后 Read、Write、Edit 会自动可用但显式写上更稳妥。test-runner 的 frontmatter 类似只是 memory 目录不同--- name: test-runner description: 运行测试并分析失败原因区分真实缺陷与环境问题 tools: Read, Grep, Glob, Bash, Write, Edit memory: project --- 你负责运行测试并分析失败。先判断失败是业务逻辑问题还是环境依赖问题再决定是否上报。把反复出现的环境类失败特征写入 memory。security-reviewer 用 user scope因为它要跨多个项目复用--- name: security-reviewer description: 安全审查覆盖认证、授权、输入校验、日志脱敏 tools: Read, Grep, Glob, Write, Edit memory: user --- 你负责安全审查。按认证态、授权边界、输入校验、日志脱敏、文件上传、路径遍历的顺序检查。把跨项目通用的风险模式写入 memory。然后是 MEMORY.md 本身。以 code-reviewer 的.claude/agent-memory/code-reviewer/MEMORY.md为例# code-reviewer memory ## 已验证结论 - 前端组件禁止直接调用后端 URL必须走统一 service 层。 - 错误提示不得直接展示后端原始 message需映射为本地化文案。 - 表单异步校验必须处理 unsubscribe历史上出现过内存泄漏。 ## 索引 - 详细评审模式见 review-patterns.md - 认证模块历史决策见 review-patterns.md#auth ## 待验证线索 - legacy 模块的 RxJS 旧写法是否统一替换待确认。test-runner 的 MEMORY.md 内容完全不同# test-runner memory ## 已验证结论 - 订单模块集成测试依赖本地 Redis连接失败先查服务状态。 - e2e 测试必须等待 storefront 完全启动否则随机失败。 - 部分失败是 mock data 未同步不是业务逻辑错。 ## 索引 - flaky test 特征见 flaky-tests.mdsecurity-reviewer 的 MEMORY.md 又是另一套# security-reviewer memory ## 已验证结论 - 所有 public endpoint 必须校验登录态。 - 日志中禁止出现 token、密码、身份证号。 - 外部 callback URL 必须做白名单校验。 ## 索引 - 认证检查清单见 auth-checklist.md三个 MEMORY.md 内容互不重叠这就是「每个 subagent 只记自己的专业经验」。人类团队不会让测试工程师的大脑塞满所有 UI 文案规则也不会要求安全工程师记住每个按钮样式。同样subagent memory 也不该变成统一大杂烩。如果你要把这套配置接到实际调用上模型侧可以用 TaoToken 的 API 作为统一入口Base URL 填https://taotoken.net/apiKey 在控制台生成Model ID 按你用的模型填。三件套缺一不可后面排障会用到。控制台地址是 https://taotoken.net/console API Keys 在 https://taotoken.net/api-keys 。接入文档在 https://taotoken.net/doc 需要对照参数时翻一下。4. 验证多 subagent 记忆互不串扰的完整步骤配置写完不代表生效必须验证隔离。下面这套步骤我实测过能确认三个 subagent 各读各的 memory不会串。第一步确认目录和文件都到位。在仓库根目录执行find .claude/agent-memory -name MEMORY.md -print预期输出三行分别对应三个 subagent 目录。如果少了某个检查 frontmatter 里的 name 和目录名是否一致。第二步给每个 MEMORY.md 写入一条独一无二的标记方便追踪。比如在 code-reviewer 的 MEMORY.md 里加一行标记REVIEWER_ONLY_ALPHAtest-runner 里加标记TESTER_ONLY_BETAsecurity-reviewer 里加标记SECURITY_ONLY_GAMMA。这些标记只用于验证验证完删掉。第三步分别唤起每个 subagent让它复述自己 memory 里的标记。唤起 code-reviewer 时问「你 memory 里的标记是什么」它应该回答REVIEWER_ONLY_ALPHA而不是另外两个。同理 test-runner 应回答TESTER_ONLY_BETAsecurity-reviewer 应回答SECURITY_ONLY_GAMMA。第四步做交叉验证。唤起 code-reviewer问它「test-runner 的标记是什么」。正确行为是它不知道或者明确说自己的 memory 里没有这个信息。如果它答出了TESTER_ONLY_BETA说明隔离失败通常是目录名写错或 frontmatter 的 memory 字段配错。第五步验证写入隔离。让 code-reviewer 往自己 memory 写一条新结论比如「新增结论评审时必须检查 feature flag 默认值」。然后唤起 test-runner问它有没有这条结论。正确结果是 test-runner 不知道。再唤起 code-reviewer 确认它记得。这一步能确认写入也走各自目录不会互相污染。第六步验证加载上限。往 code-reviewer 的 MEMORY.md 里塞超过 200 行的内容然后唤起它看它是否只记得前 200 行内的信息。这能帮你确认「前 200 行或 25 KB」的限制真实生效从而决定哪些内容该放入口文件、哪些该拆到 topic 文件。跑完这六步你对这套机制的边界就有体感了。踩过的坑里最常见的是目录名和 name 不一致其次是忘了给 Write/Edit 权限导致 subagent 写不进 memory还有一种是 MEMORY.md 写太长关键结论被挤到 200 行之外启动时根本没注入。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置和调用过程中会遇到几类典型报错逐个说清楚原因和修法。401 Unauthorized。这个最常见通常是 Key 没填、填错或者 Base URL 和 Key 不匹配。检查三件套Base URL 是否为https://taotoken.net/apiKey 是否从控制台正确复制注意前后空格Model ID 是否拼写正确。如果 Key 是对的还报 401确认请求头里的 Authorization 格式是Bearer key。用 curl 快速验证curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_KEY \ -H Content-Type: application/json \ -d {model:your-model-id,messages:[{role:user,content:ping}]}返回正常说明 Key 和 Base URL 没问题问题在 Claude Code 侧的配置。local proxy failed。这个报错通常出现在本地有代理层或端口占用时。先确认没有其他进程占用你配置的本地端口再确认 Claude Code 的配置里没有指向一个已经关闭的本地转发地址。如果你用的是统一 API 入口Base URL 直接填https://taotoken.net/api不需要再套一层本地转发能省掉这类问题。reading choices 相关报错。这类报错一般出现在响应结构不符合预期时比如返回体里没有choices字段。常见原因是 Model ID 填错请求打到了不兼容的端点或者请求体格式不对。检查 Model ID 是否和你在控制台看到的一致请求体是否是标准的messages结构。用上面的 curl 先确认服务端返回正常再排查客户端。OAuth 相关报错。如果你在 Claude Code 里配置了需要 OAuth 的接入方式报错通常和 token 过期、回调地址不匹配有关。这类问题优先检查 token 有效期和回调配置。如果只是想让 subagent 用统一 API 入口直接用 Key 方式接入更简单避免 OAuth 的额外复杂度。排查顺序建议固定下来先用 curl 验证服务端再验证 Claude Code 的 Base URL 和 Key最后验证 subagent 的 frontmatter 和 memory 目录。这样能把问题范围快速缩小到某一层不用在多个环节之间反复猜。6. 把 agent-memory 用成工程资产真正落地时把 agent memory 当成一套慢慢长出来的项目经验层而不是一开始就设计一个庞大知识库。刚创建 subagent 时只给它非常短的 system prompt 和清晰工具边界。跑完几次真实任务后让它把已经验证的模式写进自己的 memory。每隔一段时间人类工程师审一次 MEMORY.md删掉过时内容把长内容拆到 topic 文件把含混判断改成明确规则。这个节奏比一次性写满更可靠。memory 的价值来自真实工作中的反馈而不是提前猜。code-reviewer 只有看过真实 PR才知道团队最容易漏什么。test-runner 只有跑过真实 CI才知道哪些失败经常误导模型。security-reviewer 只有审过真实登录、权限、文件上传、外部回调代码才知道项目自己的风险长什么样。memory 取 project 时目录在.claude/agent-memory/agent-name/天然适合随仓库共享。这个设计很适合团队把 AI 协作经验变成工程资产。过去某个 senior engineer 在代码评审里形成的经验通常散在 PR comment、Slack、个人脑子里。现在 subagent 可以把其中稳定、可复用的部分整理进项目级 memory让整个团队的 Claude Code 都能复用。但能共享不代表什么都该共享memory 文件进入版本控制前需要像审查文档一样审查里面不该出现真实密钥、个人账号、客户数据、生产环境 URL、内部安全绕过方式。敏感但本机必要的信息用 local跨项目个人偏好用 user团队共同规则用 project。从治理角度看agent memory 也需要 code review。它虽然不是业务代码却会影响 agent 之后怎样理解业务代码。错误 memory 可能让 subagent 坚持过时架构敏感 memory 可能把不该共享的信息带进仓库含混 memory 可能让模型行为更飘。比较稳妥的做法是把.claude/agent-memory/当成轻量级工程文档目录允许提交但提交时人工看一眼。如果你想把长期编码和 Agent 任务固定在一套配置上可以用 Coding Plan 统一管理调用地址是 https://taotoken.net/coding-plan 。需要单独验证某个模型的行为时用模型对话页面快速试地址是 https://taotoken.net/chat 。Claude Code 相关的接入细节在 https://taotoken.net/doc 里能查到API Keys 在 https://taotoken.net/api-keys 生成。三件套 Base URL、Key、Model ID 配齐subagent 的 memory 机制就能稳定跑起来。最后留一个实用技巧MEMORY.md 里尽量写稳定事实和已验证模式少写一次性猜测。AI agent 很容易把历史笔记当成强上下文一条模糊的旧判断如果反复注入 system prompt可能会长期影响后续任务。更稳妥的做法是让 subagent 在写入时区分已验证结论、待验证线索、已废弃规则。MEMORY.md 保留已验证结论和索引待验证内容放到更细的 topic 文件确认后再提升到入口文件。这样你的 subagent 才会越用越准而不是越用越飘。