<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>阅读笔记 · 我的博客</title><link>https://blog-ec6.pages.dev/tags/reading-notes/</link><description>阅读笔记 标签下的全部文章</description><generator>Hugo -- gohugo.io</generator><language>zh-cn</language><lastBuildDate>Sat, 14 Nov 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://blog-ec6.pages.dev/tags/reading-notes/rss.xml" rel="self" type="application/rss+xml"/><item><title>Claude Code Memory 分层机制详解</title><link>https://blog-ec6.pages.dev/posts/memory-timeline/</link><pubDate>Sat, 14 Nov 2026 00:00:00 +0000</pubDate><guid isPermaLink="true">https://blog-ec6.pages.dev/posts/memory-timeline/</guid><description>三层存储、一个写入机制、prefix cache 安全边界贯穿始终</description><category>AI</category><category>阅读笔记</category><content:encoded>&#10;&lt;link rel="stylesheet" href="https://blog-ec6.pages.dev/posts/memory-timeline/doc.css"&gt;&#10;&#10;&lt;h2 id="s1-overview"&gt;一、Overview&lt;/h2&gt;&#10;&#10;&lt;h3 id="s1-1-mechanism"&gt;1.1 记忆机制&lt;/h3&gt;&#10;&lt;p&gt;&#10; 多 agent 系统里，单次上下文窗口承载不完历史决策、用户偏好和跨会话事实。&#10; 记忆机制把信息按生命周期分成三层：&lt;code&gt;Session Memory&lt;/code&gt; 会话级旁路摘要、&lt;code&gt;Agent Memory&lt;/code&gt; agent 类型级长期记忆、&lt;code&gt;User Memory&lt;/code&gt; 用户级画像——每层独立写入、独立召回，通过统一的文件路径约定和 prefix cache 安全边界串成完整读写链路。&#10;&lt;/p&gt;&#10;&#10;&lt;h3 id="s1-2-panorama"&gt;1.2 三层 × 两机制 全景图&lt;/h3&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 980 360" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif"&gt;&#10;&#10; &lt;text x="30" y="28" fill="#8b949e" font-size="11" font-weight="600"&gt;维度&lt;/text&gt;&#10; &lt;text x="210" y="28" fill="#e3b341" font-size="11" font-weight="600"&gt;② Session Memory&lt;/text&gt;&#10; &lt;text x="450" y="28" fill="#3fb950" font-size="11" font-weight="600"&gt;① Agent Memory&lt;/text&gt;&#10; &lt;text x="710" y="28" fill="#bc8cff" font-size="11" font-weight="600"&gt;③ Team Memory&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="40" width="940" height="50" rx="6" fill="#21262d"/&gt;&#10; &lt;text x="30" y="60" fill="#8b949e" font-size="11"&gt;生命周期&lt;/text&gt;&#10; &lt;text x="30" y="76" fill="#8b949e" font-size="10.5" font-style="italic"&gt;解决什么问题&lt;/text&gt;&#10; &lt;text x="210" y="60" fill="#e3b341" font-size="11"&gt;单次会话 · 旁路摘要&lt;/text&gt;&#10; &lt;text x="210" y="76" fill="#8b949e" font-size="10.5"&gt;长会话 compact 省 token + 不切 tool_use 链&lt;/text&gt;&#10; &lt;text x="450" y="60" fill="#3fb950" font-size="11"&gt;跨会话 · agent 类型级&lt;/text&gt;&#10; &lt;text x="450" y="76" fill="#8b949e" font-size="10.5"&gt;agent 不止是静态 prompt，要能跨会话成长&lt;/text&gt;&#10; &lt;text x="710" y="60" fill="#bc8cff" font-size="11"&gt;跨机器 · repo 级协作&lt;/text&gt;&#10; &lt;text x="710" y="76" fill="#8b949e" font-size="10.5"&gt;多人协作时项目级知识不散落在个人本地&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="100" width="940" height="40" rx="6" fill="#161b22"/&gt;&#10; &lt;text x="30" y="124" fill="#8b949e" font-size="11"&gt;谁来写&lt;/text&gt;&#10; &lt;text x="210" y="124" fill="#e3b341" font-size="11"&gt;系统 postSampling subagent（沙箱化）&lt;/text&gt;&#10; &lt;text x="450" y="124" fill="#3fb950" font-size="11"&gt;⚠️ 无系统自动萃取，agent 主动 FileWrite/Edit&lt;/text&gt;&#10; &lt;text x="710" y="124" fill="#bc8cff" font-size="11"&gt;两条通道：Auto extract 写 + Agent 主动 FileWrite 写&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="150" width="940" height="40" rx="6" fill="#21262d"/&gt;&#10; &lt;text x="30" y="174" fill="#8b949e" font-size="11"&gt;进 prompt 吗&lt;/text&gt;&#10; &lt;text x="210" y="174" fill="#e3b341" font-size="11"&gt;❌ 不进常规 prompt，只有 compact 时登场&lt;/text&gt;&#10; &lt;text x="450" y="174" fill="#3fb950" font-size="11"&gt;✅ system prompt（spawn 时固定字符串）&lt;/text&gt;&#10; &lt;text x="710" y="174" fill="#bc8cff" font-size="11"&gt;MEMORY.md 进 system；正文进 attachment（每轮扫描）&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="200" width="940" height="40" rx="6" fill="#161b22"/&gt;&#10; &lt;text x="30" y="224" fill="#8b949e" font-size="11"&gt;cache 行为&lt;/text&gt;&#10; &lt;text x="210" y="224" fill="#e3b341" font-size="11"&gt;不参与 cache 讨论（旁路）&lt;/text&gt;&#10; &lt;text x="450" y="224" fill="#3fb950" font-size="11"&gt;天然 cache（agent 不 respawn 就不变）&lt;/text&gt;&#10; &lt;text x="710" y="224" fill="#bc8cff" font-size="11"&gt;MEMORY.md cache；正文 attachment 每轮刷新&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="250" width="940" height="40" rx="6" fill="#21262d"/&gt;&#10; &lt;text x="30" y="274" fill="#8b949e" font-size="11"&gt;新写入生效时机&lt;/text&gt;&#10; &lt;text x="210" y="274" fill="#e3b341" font-size="11"&gt;下次 compact 直接读文件，无延迟&lt;/text&gt;&#10; &lt;text x="450" y="274" fill="#3fb950" font-size="11"&gt;要等 agent respawn / /compact（cache clear）&lt;/text&gt;&#10; &lt;text x="710" y="274" fill="#bc8cff" font-size="11"&gt;MEMORY.md: cache clear 后；正文: 本轮就能被 attachment 扫到&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="300" width="940" height="40" rx="6" fill="#161b22"/&gt;&#10; &lt;text x="30" y="324" fill="#8b949e" font-size="11"&gt;存储位置&lt;/text&gt;&#10; &lt;text x="210" y="324" fill="#e3b341" font-size="11"&gt;~/.claude/projects/&amp;lt;hash&amp;gt;/session-memory/&lt;/text&gt;&#10; &lt;text x="450" y="324" fill="#3fb950" font-size="11"&gt;user / project / local 三个 scope 目录&lt;/text&gt;&#10; &lt;text x="710" y="324" fill="#bc8cff" font-size="11"&gt;&amp;lt;cwd&amp;gt;/.claude/team-memory/ ↔ 服务端同步&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="348" width="940" height="6" rx="2" fill="#30363d"/&gt;&#10; &lt;text x="30" y="364" fill="#8b949e" font-size="11" font-style="italic"&gt;&#10; 注：Auto Memory 不是独立存储层，是写入触发机制（第 5 章 Addon），能同时往 private 和 team 目录写。&#10; &lt;/text&gt;&#10;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h3 id="s1-3-cache-boundary"&gt;1.3 cache 安全边界（必须先讲清楚的核心前提）&lt;/h3&gt;&#10;&lt;p&gt;&#10; Claude 服务器侧有 prefix cache —— 如果发给模型的 messages 前几千 tokens 和上一轮完全一样，服务器直接复用 prefill 结果。&#10; 这省了 prefill 时间和费用，但 cache 的条件是 &lt;b&gt;前序字符串必须逐字节相同&lt;/b&gt;。&#10; 下面这张图展示了 Claude Code 在 prompt 组装时如何精心设计 cache 安全边界：&#10;&lt;/p&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;div class="prompt-stack"&gt;&#10; &lt;div class="ps-item ps-sys"&gt;&#10; &lt;span class="label"&gt;① Base System Prompt（角色 / 能力 / 基本规则）&lt;/span&gt;&#10; &lt;span class="meta"&gt;完全固定 · 天然 cache&lt;/span&gt;&#10; &lt;/div&gt;&#10; &lt;div class="ps-item ps-agent"&gt;&#10; &lt;span class="label"&gt;② Agent Memory Prompt（getSystemPrompt() 闭包返回值）&lt;/span&gt;&#10; &lt;span class="meta"&gt;agent definition 不变就不变 · 天然 cache&lt;/span&gt;&#10; &lt;/div&gt;&#10; &lt;div class="ps-item ps-auto"&gt;&#10; &lt;span class="label"&gt;③ Auto Memory Prompt（MEMORY.md 索引 + 类型/存储规则）&lt;/span&gt;&#10; &lt;span class="meta"&gt;systemPromptSection('memory') · cacheBreak: false · /compact /clear 才重算&lt;/span&gt;&#10; &lt;/div&gt;&#10; &lt;div class="ps-item ps-team"&gt;&#10; &lt;span class="label"&gt;④ Team Memory MEMORY.md 索引（和 Auto 一起进 loadMemoryPrompt）&lt;/span&gt;&#10; &lt;span class="meta"&gt;同上 · 同一个 systemPromptSection · 同样 cache&lt;/span&gt;&#10; &lt;/div&gt;&#10; &lt;div class="ps-item ps-sys"&gt;&#10; &lt;span class="label"&gt;⑤ 其他 dynamicSections（session_guidance / env_info / language / output_style / scratchpad ...）&lt;/span&gt;&#10; &lt;span class="meta"&gt;大多 cacheBreak: false&lt;/span&gt;&#10; &lt;/div&gt;&#10; &lt;div class="ps-item ps-danger"&gt;&#10; &lt;span class="label"&gt;⑥ mcp_instructions（唯一真正打破 cache 的 section）&lt;/span&gt;&#10; &lt;span class="meta"&gt;DANGEROUS_uncachedSystemPromptSection · 每轮重算&lt;/span&gt;&#10; &lt;/div&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;div class="cache-divider"&gt;&#10; ─────────────── PREFIX CACHE 安全边界 ───────────────&#10;&lt;/div&gt;&#10;&#10;&lt;div class="prompt-stack"&gt;&#10; &lt;div class="ps-item ps-hist"&gt;&#10; &lt;span class="label"&gt;⑦ Conversation History（历史 user/assistant/tool_use/tool_result 轮次）&lt;/span&gt;&#10; &lt;span class="meta"&gt;每轮增长，但已有的历史部分保持不变 → cache 安全&lt;/span&gt;&#10; &lt;/div&gt;&#10; &lt;div class="ps-item ps-attach"&gt;&#10; &lt;span class="label"&gt;⑧ relevant_memories Attachment（≤5 个选中的 memory topic 文件正文）&lt;/span&gt;&#10; &lt;span class="meta"&gt;每轮重新扫描目录 → 每轮都可能不同 → 不 cache&lt;/span&gt;&#10; &lt;/div&gt;&#10; &lt;div class="ps-item ps-attach"&gt;&#10; &lt;span class="label"&gt;⑨ 其他 Attachments（MCP tools delta / changed_files / plans / ...）&lt;/span&gt;&#10; &lt;span class="meta"&gt;每轮动态&lt;/span&gt;&#10; &lt;/div&gt;&#10; &lt;div class="ps-item ps-user"&gt;&#10; &lt;span class="label"&gt;⑩ User Message（当前 query）&lt;/span&gt;&#10; &lt;span class="meta"&gt;每轮变&lt;/span&gt;&#10; &lt;/div&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;p&gt;&#10; 源码证据：&lt;code&gt;systemPromptSection('memory', ...)&lt;/code&gt; 的 &lt;code&gt;cacheBreak: false&lt;/code&gt;（&lt;code&gt;src/constants/systemPromptSections.ts&lt;/code&gt;），&#10; 直到 &lt;code&gt;/compact&lt;/code&gt; 或 &lt;code&gt;/clear&lt;/code&gt; 才通过 &lt;code&gt;clearSystemPromptSections()&lt;/code&gt; 清 cache。&#10; 只有 &lt;code&gt;DANGEROUS_uncachedSystemPromptSection&lt;/code&gt; 才会每轮重算并打破 prefix cache。&#10;&lt;/p&gt;&#10;&#10;&lt;p class="anchor-ref"&gt;后面每层详解都会回到这个 cache 边界上，回答两个问题：①新写入什么时候能被模型看到？②这对 cache 有什么影响？&lt;/p&gt;&#10;&#10;&lt;h2 id="s2-layers"&gt;二、各层详解&lt;/h2&gt;&#10;&#10;&lt;h3 id="s2-1-session"&gt;2.1 Session Memory —— 会话级旁路摘要&lt;/h3&gt;&#10;&#10;&lt;h4 id="s2-1-what"&gt;存储什么&lt;/h4&gt;&#10;&lt;p&gt;&#10; 当前会话到目前为止的完整对话摘要 —— 不是长期记忆，是中间态压缩产物。&#10; 只有当会话足够长（累计 tokens ≥ 10K）才开始生效。内容是一段纯 markdown，&#10; 描述"到目前为止对话做了什么、决定了什么、还有什么待办"。&#10;&lt;/p&gt;&#10;&#10;&lt;h4 id="s2-1-index"&gt;索引&lt;/h4&gt;&#10;&lt;p&gt;&#10; &lt;b&gt;没有索引文件&lt;/b&gt;。整个 session-memory 文件本身就是一份摘要，无 MEMORY.md 也无 frontmatter。&#10;&lt;/p&gt;&#10;&#10;&lt;h4 id="s2-1-path"&gt;路径结构&lt;/h4&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 520 130" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, monospace" font-size="13"&gt;&#10; &lt;rect x="10" y="10" width="500" height="110" rx="6" fill="#0d1117" stroke="#e3b341"/&gt;&#10; &lt;text x="25" y="32" fill="#e3b341"&gt;~/.claude/projects/&amp;lt;sanitized-git-root&amp;gt;/session-memory/&lt;/text&gt;&#10; &lt;text x="25" y="55" fill="#c9d1d9"&gt;└── &amp;lt;session-uuid&amp;gt;.md ← 纯 markdown 摘要，无 frontmatter&lt;/text&gt;&#10; &lt;text x="25" y="78" fill="#8b949e" font-size="11.5"&gt;# 目录权限 0o700（只有属主可读写执行）&lt;/text&gt;&#10; &lt;text x="25" y="98" fill="#8b949e" font-size="11.5"&gt;# 文件权限 0o600（只有属主可读写）&lt;/text&gt;&#10; &lt;text x="25" y="116" fill="#f85149" font-size="11.5"&gt;创建时 flag: 'wx'（O_CREAT|O_EXCL）→ 不覆盖其他会话同名文件&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-1-extract"&gt;萃取时序（什么时候写、怎么写）&lt;/h4&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 800 260" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10; &lt;rect x="20" y="10" width="760" height="36" rx="6" fill="#21262d" stroke="#e3b341"/&gt;&#10; &lt;text x="32" y="32" fill="#e3b341"&gt;postSamplingHook 注册（每次模型采样完都检查）&lt;/text&gt;&#10; &lt;rect x="60" y="56" width="680" height="36" rx="6" fill="#161b22" stroke="#30363d"/&gt;&#10; &lt;text x="72" y="78" fill="#c9d1d9"&gt;shouldExtractMemory() 三重判断：①初始化阈值 ②更新阈值 ③自然断点&lt;/text&gt;&#10; &lt;rect x="100" y="102" width="600" height="80" rx="6" fill="#0d1117" stroke="#30363d"/&gt;&#10; &lt;text x="112" y="122" fill="#e3b341"&gt;· 累计 tokens &amp;lt; 10K → 不初始化，跳过&lt;/text&gt;&#10; &lt;text x="112" y="140" fill="#e3b341"&gt;· 距上次更新 &amp;lt; +5K tokens 且 &amp;lt; +3 次 tool call → 跳过&lt;/text&gt;&#10; &lt;text x="112" y="158" fill="#e3b341"&gt;· 最后一轮还有 tool_use 在跑 → 等自然断点（下一轮无 tool_use 时触发）&lt;/text&gt;&#10; &lt;text x="112" y="176" fill="#c9d1d9" font-style="italic"&gt;三重都通过 → 开始萃取&lt;/text&gt;&#10; &lt;rect x="60" y="200" width="680" height="40" rx="6" fill="#161b22" stroke="#e3b341"/&gt;&#10; &lt;text x="72" y="222" fill="#e3b341"&gt;forked subagent（沙箱化）→ 只有 FileEditTool + 路径锁死连 FileReadTool 都 deny → 完整重写摘要文件&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-1-recall"&gt;召回时序（什么时候读）&lt;/h4&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 800 150" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10; &lt;rect x="20" y="10" width="760" height="36" rx="6" fill="#f8514922" stroke="#f85149"/&gt;&#10; &lt;text x="32" y="32" fill="#f85149"&gt;常规 query loop → Session Memory 完全不参与，不进任何 prompt&lt;/text&gt;&#10; &lt;rect x="20" y="60" width="760" height="36" rx="6" fill="#21262d" stroke="#e3b341"/&gt;&#10; &lt;text x="32" y="82" fill="#e3b341"&gt;context tokens 接近上限 → compact 触发（手动 / 自动阈值）&lt;/text&gt;&#10; &lt;rect x="20" y="110" width="760" height="30" rx="6" fill="#0d1117" stroke="#e3b341"/&gt;&#10; &lt;text x="32" y="130" fill="#c9d1d9"&gt;trySessionMemoryCompaction() → 同步读本地文件 → 作为 SummaryMessage 插进 messages&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-1-cache"&gt;cache 关系&lt;/h4&gt;&#10;&lt;p&gt;&#10; Session Memory 完全旁路，不在常规 prompt 链路里。它既不影响也不受影响 prefix cache。&#10; 写入时用完整重写策略，读入时只有 compact 才触发。&#10;&lt;/p&gt;&#10;&#10;&lt;h4 id="s2-1-update"&gt;更新策略&lt;/h4&gt;&#10;&lt;p&gt;&#10; &lt;b&gt;每次完整重写&lt;/b&gt;（不是增量追加）。会话结束即废弃。有 &lt;code&gt;flag: 'wx'&lt;/code&gt; 防止覆盖其他会话的同名文件。&#10;&lt;/p&gt;&#10;&#10;&lt;h4 id="s2-1-example"&gt;案例文件示例&lt;/h4&gt;&#10;&#10;&lt;div class="example"&gt;&#10; &lt;b&gt;session-memory/xxxxxxxx-uuid.md&lt;/b&gt; （compliance-reviewer 场景）&#10; &lt;pre&gt;&#10;# Session Summary (2026-11-10)&#10;&#10;## 对话起始&#10;用户明确要求重写 auth middleware —— legal 标记当前 session token 存储方式不合规。&#10;项目即将发版，时间紧。&#10;&#10;## 已做决定&#10;- 用 Go context 包方案。用户之前否决过但这次同意。&#10;- middleware 重写方向：token 存到 context 上游，下游 handler 按需取，不存 session 表。&#10;&#10;## 待办&#10;- [ ] 改 middleware.go：context 注入 + 移除 session 表存储&#10;- [ ] 全量回归测试（用户强调 "测试必须 hit 真 DB，mock 曾导致生产事故"）&#10;- [ ] /claude team-memory 里要记住这个合规决定的原因&#10;&#10;## 遇到的坑&#10;- grep 发现 middleware.go 在 3 个地方直接读 session 表，不是单一入口 → 改动面比预期大&#10;- user 明确禁止用 mock 写测试，必须 hit 真 DB&lt;/pre&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h3 id="s2-2-agent"&gt;2.2 Agent Memory —— agent 类型级长期记忆&lt;/h3&gt;&#10;&#10;&lt;h4 id="s2-2-what"&gt;存储什么&lt;/h4&gt;&#10;&lt;p&gt;&#10; 某种 agent 类型的长期专属记忆。只有当 agent definition 里带 &lt;code&gt;memory&lt;/code&gt; 字段时才启用。&#10; 内容类型和 Auto Memory 相同（user / feedback / project / reference），&#10; 但作用域是"某个 agent 类型"，不是"某个项目"或"某个用户"。&#10;&lt;/p&gt;&#10;&#10;&lt;h4 id="s2-2-index"&gt;索引&lt;/h4&gt;&#10;&lt;p&gt;&#10; 复用 &lt;code&gt;MEMORY.md&lt;/code&gt; 协议 —— 每 topic 文件一行索引 + 描述，&#10; 硬截断 &lt;b&gt;200 行 / 25KB&lt;/b&gt;（防止 prompt 爆炸）。&#10; Agent Memory 和 Auto Memory 各有自己的 MEMORY.md，物理隔离。&#10;&lt;/p&gt;&#10;&#10;&lt;h4 id="s2-2-path"&gt;路径结构（三个 scope 独立物理目录）&lt;/h4&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 960 260" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, monospace" font-size="12.5"&gt;&#10; &lt;rect x="10" y="10" width="300" height="240" rx="8" fill="#0d1117" stroke="#3fb950"/&gt;&#10; &lt;text x="20" y="32" fill="#3fb950" font-weight="600"&gt;① user scope（跨项目复用）&lt;/text&gt;&#10; &lt;text x="20" y="56" fill="#c9d1d9"&gt;~/.claude/agent-memory/&lt;/text&gt;&#10; &lt;text x="20" y="76" fill="#79c0ff"&gt;└── compliance-reviewer/&lt;/text&gt;&#10; &lt;text x="30" y="98" fill="#c9d1d9"&gt; ├── MEMORY.md&lt;/text&gt;&#10; &lt;text x="30" y="118" fill="#c9d1d9"&gt; ├── compliance_token-rules.md&lt;/text&gt;&#10; &lt;text x="30" y="138" fill="#c9d1d9"&gt; └── framework_context.md&lt;/text&gt;&#10; &lt;text x="20" y="162" fill="#8b949e" font-size="11.5"&gt;适合：user 自己长期积累的合规经验&lt;/text&gt;&#10; &lt;text x="20" y="180" fill="#8b949e" font-size="11.5"&gt;所有项目共享同一份 user scope memory&lt;/text&gt;&#10;&#10; &lt;rect x="340" y="10" width="300" height="240" rx="8" fill="#0d1117" stroke="#3fb950"/&gt;&#10; &lt;text x="350" y="32" fill="#3fb950" font-weight="600"&gt;② project scope（当前项目内共享）&lt;/text&gt;&#10; &lt;text x="350" y="56" fill="#c9d1d9"&gt;&amp;lt;cwd&amp;gt;/.claude/agent-memory/&lt;/text&gt;&#10; &lt;text x="350" y="76" fill="#79c0ff"&gt;└── compliance-reviewer/&lt;/text&gt;&#10; &lt;text x="360" y="98" fill="#c9d1d9"&gt; ├── MEMORY.md&lt;/text&gt;&#10; &lt;text x="360" y="118" fill="#c9d1d9"&gt; └── team_specific_standards.md&lt;/text&gt;&#10; &lt;text x="350" y="142" fill="#8b949e" font-size="11.5"&gt;适合：这个项目独有的合规标准&lt;/text&gt;&#10; &lt;text x="350" y="160" fill="#8b949e" font-size="11.5"&gt;和项目绑定，换项目就另一份&lt;/text&gt;&#10;&#10; &lt;rect x="670" y="10" width="280" height="240" rx="8" fill="#0d1117" stroke="#3fb950"/&gt;&#10; &lt;text x="680" y="32" fill="#3fb950" font-weight="600"&gt;③ local scope（当前机器/挂载）&lt;/text&gt;&#10; &lt;text x="680" y="56" fill="#c9d1d9"&gt;&amp;lt;cwd&amp;gt;/.claude/agent-memory-local/&lt;/text&gt;&#10; &lt;text x="680" y="76" fill="#79c0ff"&gt;└── compliance-reviewer/&lt;/text&gt;&#10; &lt;text x="690" y="98" fill="#c9d1d9"&gt; └── MEMORY.md + topic files&lt;/text&gt;&#10; &lt;text x="680" y="122" fill="#8b949e" font-size="11.5"&gt;默认和 project 目录同结构&lt;/text&gt;&#10; &lt;text x="680" y="140" fill="#8b949e" font-size="11.5"&gt;remote 环境重定位到 memory mount&lt;/text&gt;&#10; &lt;text x="680" y="158" fill="#8b949e" font-size="11.5"&gt;适合：本机专属的临时经验&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-2-files"&gt;目录内文件结构&lt;/h4&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 800 180" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, monospace" font-size="12.5"&gt;&#10; &lt;rect x="10" y="10" width="780" height="160" rx="6" fill="#0d1117" stroke="#3fb950"/&gt;&#10; &lt;text x="25" y="30" fill="#f0883e"&gt;MEMORY.md（索引协议，每文件一行，200 行 / 25KB 截断）：&lt;/text&gt;&#10; &lt;text x="25" y="52" fill="#c9d1d9"&gt;- [token-storage-rules.md](token-storage-rules.md) — legal 2026-10-15 标记 session token 存储不合规 → 强制移至 context&lt;/text&gt;&#10; &lt;text x="25" y="72" fill="#c9d1d9"&gt;- [framework-context-package.md](framework-context-package.md) — Go context 包曾被用户否决，2026-11-10 又同意了，记住这个转折点&lt;/text&gt;&#10; &lt;text x="25" y="94" fill="#8b949e" font-style="italic"&gt;（永远不要把正文直接写进 MEMORY.md）&lt;/text&gt;&#10; &lt;text x="25" y="118" fill="#f0883e"&gt;topic 文件（独立 markdown，带 frontmatter）：&lt;/text&gt;&#10; &lt;text x="25" y="140" fill="#c9d1d9"&gt;---&lt;/text&gt;&#10; &lt;text x="25" y="156" fill="#c9d1d9"&gt;name: token-storage-rules.md type: feedback description: legal 合规要求&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-2-extract"&gt;萃取（写入）时序&lt;/h4&gt;&#10;&#10;&lt;p&gt;&lt;b&gt;⚠️ 无系统自动萃取&lt;/b&gt;，完全由 agent 在运行时主动 FileRead → FileWrite/Edit：&lt;/p&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 800 180" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10; &lt;rect x="20" y="10" width="760" height="36" rx="6" fill="#21262d" stroke="#3fb950"/&gt;&#10; &lt;text x="32" y="32" fill="#3fb950"&gt;agent 运行时自主判断"这条值得长期记住"&lt;/text&gt;&#10; &lt;rect x="60" y="56" width="680" height="36" rx="6" fill="#161b22" stroke="#30363d"/&gt;&#10; &lt;text x="72" y="78" fill="#c9d1d9"&gt;FileReadTool → 先读 MEMORY.md 看现有索引 → 决定是新建还是更新&lt;/text&gt;&#10; &lt;rect x="60" y="102" width="680" height="36" rx="6" fill="#161b22" stroke="#30363d"/&gt;&#10; &lt;text x="72" y="124" fill="#c9d1d9"&gt;FileWriteTool / FileEditTool → 新建或更新某条 topic 文件（带 frontmatter）&lt;/text&gt;&#10; &lt;rect x="60" y="148" width="680" height="24" rx="6" fill="#161b22" stroke="#30363d"/&gt;&#10; &lt;text x="72" y="164" fill="#c9d1d9"&gt;FileEditTool → 维护 MEMORY.md 索引（两步骤：先写 topic 文件，再更新索引）&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-2-recall-cache"&gt;召回 + cache 时序&lt;/h4&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 800 300" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10; &lt;rect x="20" y="10" width="760" height="46" rx="6" fill="#21262d" stroke="#3fb950"/&gt;&#10; &lt;text x="32" y="30" fill="#3fb950"&gt;agent spawn 时 getSystemPrompt() 被调用（agent definition 里的闭包）&lt;/text&gt;&#10; &lt;text x="32" y="46" fill="#8b949e" font-size="11"&gt;agent definition: getSystemPrompt = () =&gt; systemPrompt + '\n\n' + loadAgentMemoryPrompt(name, parsed.memory)&lt;/text&gt;&#10;&#10; &lt;rect x="60" y="66" width="680" height="36" rx="6" fill="#161b22" stroke="#30363d"/&gt;&#10; &lt;text x="72" y="88" fill="#c9d1d9"&gt;loadAgentMemoryPrompt(agentType, scope)&lt;/text&gt;&#10;&#10; &lt;rect x="100" y="112" width="600" height="60" rx="6" fill="#0d1117" stroke="#30363d"/&gt;&#10; &lt;text x="112" y="130" fill="#79c0ff"&gt;① 根据 scope 算出 memoryDir（user / project / local 三选一）&lt;/text&gt;&#10; &lt;text x="112" y="148" fill="#79c0ff"&gt;② 同步读 MEMORY.md（硬截断 200 行 / 25KB）&lt;/text&gt;&#10; &lt;text x="112" y="166" fill="#79c0ff"&gt;③ 返回一整段 prompt 字符串（规则 + scopeNote + MEMORY.md 内容）&lt;/text&gt;&#10;&#10; &lt;rect x="60" y="180" width="680" height="40" rx="6" fill="#3fb95022" stroke="#3fb950"/&gt;&#10; &lt;text x="72" y="204" fill="#3fb950" font-weight="600"&gt;cache 行为：天然 cache。这不是 systemPromptSection，是 agent definition 返回值。&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="230" width="760" height="60" rx="6" fill="#f8514922" stroke="#f85149"/&gt;&#10; &lt;text x="32" y="250" fill="#f85149"&gt;新写入什么时候生效？&lt;/text&gt;&#10; &lt;text x="32" y="270" fill="#c9d1d9"&gt;① MEMORY.md 索引更新 → 要等 agent 下次 respawn 才会重新读（或 /compact 清 cache 后）&lt;/text&gt;&#10; &lt;text x="32" y="288" fill="#c9d1d9"&gt;② 新 topic 文件正文 → agent 自己记得路径，后续通过 FileReadTool 显式读取&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-2-update"&gt;更新策略&lt;/h4&gt;&#10;&lt;p&gt;&#10; agent 自主 &lt;code&gt;FileEdit&lt;/code&gt; 原地修改 topic 文件 + 维护 MEMORY.md 索引。&#10; &lt;b&gt;Snapshot 机制&lt;/b&gt;：首次 spawn 时从 &lt;code&gt;&amp;lt;cwd&amp;gt;/.claude/agent-memory-snapshots/&amp;lt;agentType&amp;gt;/&lt;/code&gt;&#10; 初始化本地目录；启动后如果 snapshot 有更新，提示"新版可同步"。&#10; 这让 agent memory 可以随项目一起 ship —— 不是运行时副产物，而是可分发的角色资产。&#10;&lt;/p&gt;&#10;&#10;&lt;h4 id="s2-2-example"&gt;案例文件示例&lt;/h4&gt;&#10;&#10;&lt;div class="example"&gt;&#10; &lt;b&gt;compliance-reviewer 的 user scope MEMORY.md：&lt;/b&gt;&#10; &lt;pre&gt;&#10;- [token-storage-rules.md](token-storage-rules.md) — legal 2026-10-15 标记 session token 存储不合规&#10;- [framework-context-package.md](framework-context-package.md) — Go context 包曾被否决又在 11/10 同意，记住转折点&lt;/pre&gt;&#10;&#10; &lt;b&gt;token-storage-rules.md：&lt;/b&gt;&#10; &lt;pre&gt;&#10;&lt;span class="fm"&gt;---&#10;name: token-storage-rules.md&#10;type: feedback&#10;description: legal 2026-10-15 标记 session token 存储不合规 → 强制移至 context&#10;---&lt;/span&gt;&#10;&#10;Legal team 2026-10-15 flagged auth middleware: session tokens must not be stored in session table.&#10;**Why:** new compliance requirements for session token storage.&#10;**How to apply:** 审计任何新引入 session 表存储的代码，改为 Go context 传递。&lt;/pre&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h3 id="s2-3-team"&gt;2.3 Team Memory —— repo 级协作共享&lt;/h3&gt;&#10;&#10;&lt;h4 id="s2-3-what"&gt;存储什么&lt;/h4&gt;&#10;&lt;p&gt;&#10; 团队级 feedback（"测试必须 hit 真 DB"）、project（"合并冻结 2026-03-05 开始"）、&#10; reference（"pipeline bug 在 Linear INGEST 项目"）。&#10; &lt;b&gt;user 类型的 memory 永远 private&lt;/b&gt;，不会写进 team 目录。&#10; 写入什么由 memory type 定义里的 scope 规则决定。&#10;&lt;/p&gt;&#10;&#10;&lt;h4 id="s2-3-index"&gt;索引&lt;/h4&gt;&#10;&lt;p&gt;&#10; 独立的 MEMORY.md（和 Agent / Auto 各一份）。格式相同，200 行 / 25KB 截断。&#10; 索引里每条一行。&#10;&lt;/p&gt;&#10;&#10;&lt;h4 id="s2-3-sync-topo"&gt;同步拓扑&lt;/h4&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 900 220" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10; &lt;rect x="360" y="10" width="180" height="60" rx="8" fill="#bc8cff22" stroke="#bc8cff"/&gt;&#10; &lt;text x="450" y="34" fill="#bc8cff" text-anchor="middle" font-weight="600"&gt;Team Memory Server&lt;/text&gt;&#10; &lt;text x="450" y="54" fill="#8b949e" text-anchor="middle" font-size="11"&gt;/api/claude_code/team_memory?repo=owner/repo&lt;/text&gt;&#10;&#10; &lt;path d="M370 80 L200 110 L200 135 L440 90" stroke="#bc8cff" fill="none" stroke-width="1.5"/&gt;&#10; &lt;text x="195" y="127" fill="#bc8cff" font-size="11" text-anchor="end"&gt;pull（启动时）&lt;/text&gt;&#10;&#10; &lt;path d="M440 90 L700 120 L700 145 L550 80" stroke="#bc8cff" fill="none" stroke-width="1.5" stroke-dasharray="4,2"/&gt;&#10; &lt;text x="625" y="142" fill="#bc8cff" font-size="11" text-anchor="middle"&gt;push（fs.watch → 2s debounce → upsert + ETag）&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="150" width="400" height="60" rx="8" fill="#0d1117" stroke="#bc8cff"/&gt;&#10; &lt;text x="34" y="172" fill="#79c0ff"&gt;&amp;lt;cwd&amp;gt;/.claude/team-memory/&lt;/text&gt;&#10; &lt;text x="34" y="190" fill="#c9d1d9"&gt;├── MEMORY.md&lt;/text&gt;&#10; &lt;text x="34" y="206" fill="#c9d1d9"&gt;├── feedback_testing.md ← "测试必须 hit 真 DB"&lt;/text&gt;&#10;&#10; &lt;rect x="480" y="150" width="400" height="60" rx="8" fill="#0d1117" stroke="#bc8cff"/&gt;&#10; &lt;text x="494" y="172" fill="#79c0ff"&gt;同事机器：/home/bob/project/.claude/team-memory/&lt;/text&gt;&#10; &lt;text x="494" y="190" fill="#c9d1d9"&gt;├── MEMORY.md ← 同步拉取后相同&lt;/text&gt;&#10; &lt;text x="494" y="206" fill="#c9d1d9"&gt;└── project_auth-middleware.md&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-3-write-trigger"&gt;写入触发（两条通道）&lt;/h4&gt;&#10;&#10;&lt;div class="kv-list"&gt;&#10; &lt;div class="kv purple"&gt;&#10; &lt;b&gt;通道 A：Auto Memory extract subagent&lt;/b&gt; 根据 type scope 规则（feedback 默认 team，project 强倾向 team），&#10; 把合适的记忆写到 team-memory 目录。extract 完成后 fs.watch 自动触发 push。&#10; &lt;/div&gt;&#10; &lt;div class="kv purple"&gt;&#10; &lt;b&gt;通道 B：Agent Memory 主动 FileWrite&lt;/b&gt; agent prompt 里被指引"这条属于团队级知识"，&#10; 于是主动 FileWrite 到 team-memory 目录。fs.watch 自动触发 push。&#10; &lt;/div&gt;&#10; &lt;div class="kv red"&gt;&#10; &lt;b&gt;⚠️ 安全闸门&lt;/b&gt; &lt;code&gt;teamMemSecretGuard.ts&lt;/code&gt; 在 FileWriteTool/FileEditTool 写入 team-memory 前做 secret 扫描&#10; （gitleaks），防止 API key / 凭证等敏感信息进入共享目录。&#10; &lt;/div&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-3-recall-cache"&gt;召回 + cache 时序（三条通道！）&lt;/h4&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 900 320" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10;&#10; &lt;rect x="10" y="10" width="280" height="290" rx="8" fill="#0d1117" stroke="#bc8cff"/&gt;&#10; &lt;text x="25" y="32" fill="#bc8cff" font-weight="600"&gt;通道 A：MEMORY.md 索引&lt;/text&gt;&#10; &lt;text x="25" y="52" fill="#c9d1d9"&gt;loadMemoryPrompt() 被&lt;/text&gt;&#10; &lt;text x="25" y="68" fill="#c9d1d9"&gt;systemPromptSection('memory') 调用&lt;/text&gt;&#10; &lt;text x="25" y="92" fill="#3fb950"&gt;cacheBreak: false&lt;/text&gt;&#10; &lt;text x="25" y="108" fill="#8b949e" font-size="11"&gt;直到 /compact / /clear 才重算&lt;/text&gt;&#10; &lt;text x="25" y="128" fill="#f85149" font-size="11"&gt;新写入的索引更新 → 要等 cache clear&lt;/text&gt;&#10; &lt;text x="25" y="148" fill="#8b949e" font-size="10.5"&gt;进 system prompt → cache 安全&lt;/text&gt;&#10; &lt;line x1="25" y1="160" x2="265" y2="160" stroke="#30363d"/&gt;&#10; &lt;text x="25" y="180" fill="#8b949e" font-size="10.5"&gt;位置：system prompt 栈&lt;/text&gt;&#10; &lt;text x="25" y="196" fill="#8b949e" font-size="10.5"&gt;cache 边界之前&lt;/text&gt;&#10;&#10; &lt;rect x="310" y="10" width="280" height="290" rx="8" fill="#0d1117" stroke="#bc8cff"/&gt;&#10; &lt;text x="325" y="32" fill="#bc8cff" font-weight="600"&gt;通道 B：topic 文件正文&lt;/text&gt;&#10; &lt;text x="325" y="52" fill="#c9d1d9"&gt;findRelevantMemories() 每轮重新&lt;/text&gt;&#10; &lt;text x="325" y="68" fill="#c9d1d9"&gt;扫描 team-memory 目录文件头&lt;/text&gt;&#10; &lt;text x="325" y="88" fill="#c9d1d9"&gt;→ sideQuery 选 ≤5 个 → 注入&lt;/text&gt;&#10; &lt;text x="325" y="108" fill="#3fb950"&gt;每轮重扫描&lt;/text&gt;&#10; &lt;text x="325" y="124" fill="#f85149" font-size="11"&gt;新写入的 topic 文件 → 本轮就能被扫到！&lt;/text&gt;&#10; &lt;text x="325" y="148" fill="#8b949e" font-size="10.5"&gt;进 relevant_memories attachment&lt;/text&gt;&#10; &lt;line x1="325" y1="160" x2="565" y2="160" stroke="#30363d"/&gt;&#10; &lt;text x="325" y="180" fill="#8b949e" font-size="10.5"&gt;位置：attachment messages&lt;/text&gt;&#10; &lt;text x="325" y="196" fill="#8b949e" font-size="10.5"&gt;cache 边界之后&lt;/text&gt;&#10;&#10; &lt;rect x="610" y="10" width="280" height="290" rx="8" fill="#0d1117" stroke="#bc8cff"/&gt;&#10; &lt;text x="625" y="32" fill="#bc8cff" font-weight="600"&gt;通道 C：agent 主动读&lt;/text&gt;&#10; &lt;text x="625" y="52" fill="#c9d1d9"&gt;agent 运行时自己调 FileReadTool&lt;/text&gt;&#10; &lt;text x="625" y="68" fill="#c9d1d9"&gt;读 team-memory 目录下任何文件&lt;/text&gt;&#10; &lt;text x="625" y="88" fill="#3fb950"&gt;每轮都能读&lt;/text&gt;&#10; &lt;text x="625" y="104" fill="#f85149" font-size="11"&gt;新写入的任何文件 → agent 想读就能读到&lt;/text&gt;&#10; &lt;text x="625" y="128" fill="#8b949e" font-size="10.5"&gt;读出来的内容作为 tool_result&lt;/text&gt;&#10; &lt;text x="625" y="142" fill="#8b949e" font-size="10.5"&gt;进入对话历史 → 自动参与上下文&lt;/text&gt;&#10; &lt;line x1="625" y1="154" x2="865" y2="154" stroke="#30363d"/&gt;&#10; &lt;text x="625" y="174" fill="#8b949e" font-size="10.5"&gt;位置：conversation history&lt;/text&gt;&#10; &lt;text x="625" y="190" fill="#8b949e" font-size="10.5"&gt;（每轮增长，自然 cache 安全）&lt;/text&gt;&#10;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h4 id="s2-3-sync-contract"&gt;同步契约&lt;/h4&gt;&#10;&lt;table&gt;&#10;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;操作&lt;/th&gt;&lt;th&gt;语义&lt;/th&gt;&lt;th&gt;冲突处理&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&#10;&lt;tbody&gt;&#10;&lt;tr&gt;&lt;td&gt;&lt;b&gt;pull&lt;/b&gt;&lt;/td&gt;&lt;td&gt;server 覆盖 local（服务器权威）&lt;/td&gt;&lt;td&gt;无冲突 —— 服务器版本优先&lt;/td&gt;&lt;/tr&gt;&#10;&lt;tr&gt;&lt;td&gt;&lt;b&gt;push&lt;/b&gt;&lt;/td&gt;&lt;td&gt;upsert 语义：请求里的 key 覆盖，没出现的不动&lt;/td&gt;&lt;td&gt;ETag 乐观锁：If-Match + delta 上传&lt;/td&gt;&lt;/tr&gt;&#10;&lt;tr&gt;&lt;td&gt;&lt;b&gt;本地删除&lt;/b&gt;&lt;/td&gt;&lt;td&gt;不回同步 server&lt;/td&gt;&lt;td&gt;下次 pull 恢复（防误删）&lt;/td&gt;&lt;/tr&gt;&#10;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&#10;&lt;h4 id="s2-3-example"&gt;案例文件示例&lt;/h4&gt;&#10;&#10;&lt;div class="example"&gt;&#10; &lt;b&gt;team-memory/ MEMORY.md：&lt;/b&gt;&#10; &lt;pre&gt;&#10;- [feedback_testing.md](feedback_testing.md) — 测试必须 hit 真 DB，mock 曾导致生产事故&#10;- [project_auth-middleware.md](project_auth-middleware.md) — auth middleware 重写：legal 合规 + deadline&#10;- [reference_pipeline-bug.md](reference_pipeline-bug.md) — pipeline bug 在 Linear INGEST 项目&lt;/pre&gt;&#10;&#10; &lt;b&gt;project_auth-middleware.md：&lt;/b&gt;&#10; &lt;pre&gt;&#10;&lt;span class="fm"&gt;---&#10;name: project_auth-middleware.md&#10;type: project&#10;description: auth middleware 重写的合规驱动 + 关键决策&#10;---&lt;/span&gt;&#10;&#10;**Decision:** 重写 auth middleware，token 从 session 表移至 Go context 传递。&#10;**Why:** legal 2026-10-15 标记 session token 存储不合规。&#10;**How to apply:** 任何新引入 session 表存储的代码需审计；compliance-reviewer agent 已记住此规则。&#10;**Deadline:** 2026-11-12（发版前）。&#10;**Actor:** 后端团队，Tech Lead 拍板。&lt;/pre&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h2 id="s3-conflict"&gt;三、协同与冲突&lt;/h2&gt;&#10;&#10;&lt;h3 id="s3-1-prompt-assembly"&gt;3.1 会话内 prompt 组装（各层落到哪里）&lt;/h3&gt;&#10;&lt;p&gt;&#10; 回顾 1.3 的 cache 边界图，这里看每层具体落到哪一段：&#10;&lt;/p&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;div class="prompt-stack"&gt;&#10; &lt;div class="ps-item ps-sys"&gt;&lt;span class="label"&gt;① Base System Prompt&lt;/span&gt;&lt;span class="meta"&gt;完全固定 · 天然 cache&lt;/span&gt;&lt;/div&gt;&#10; &lt;div class="ps-item ps-agent"&gt;&lt;span class="label"&gt;② &lt;b&gt;Agent Memory&lt;/b&gt; MEMORY.md + 规则（getSystemPrompt() 固定字符串）&lt;/span&gt;&lt;span class="meta"&gt;agent definition 不变就不变&lt;/span&gt;&lt;/div&gt;&#10; &lt;div class="ps-item ps-auto"&gt;&lt;span class="label"&gt;③ Auto Memory private MEMORY.md + 类型/存储规则（loadMemoryPrompt）&lt;/span&gt;&lt;span class="meta"&gt;systemPromptSection('memory') · cacheBreak: false&lt;/span&gt;&lt;/div&gt;&#10; &lt;div class="ps-item ps-team"&gt;&lt;span class="label"&gt;④ &lt;b&gt;Team Memory&lt;/b&gt; MEMORY.md（和 ③ 共用 systemPromptSection）&lt;/span&gt;&lt;span class="meta"&gt;同上&lt;/span&gt;&lt;/div&gt;&#10; &lt;div class="ps-item ps-sys"&gt;&lt;span class="label"&gt;⑤ 其他 dynamicSections（session_guidance / env_info / language ...）&lt;/span&gt;&lt;span class="meta"&gt;大多 cacheBreak: false&lt;/span&gt;&lt;/div&gt;&#10; &lt;div class="ps-item ps-danger"&gt;&lt;span class="label"&gt;⑥ mcp_instructions（唯一真正打破 cache 的 section）&lt;/span&gt;&lt;span class="meta"&gt;DANGEROUS_uncached&lt;/span&gt;&lt;/div&gt;&#10;&lt;/div&gt;&#10;&lt;div class="cache-divider"&gt;PREFIX CACHE 安全边界（⑦ 之后每轮都刷新）&lt;/div&gt;&#10;&lt;div class="prompt-stack"&gt;&#10; &lt;div class="ps-item ps-attach"&gt;&lt;span class="label"&gt;⑦ &lt;b&gt;Agent/Team Memory&lt;/b&gt; topic 文件正文（relevant_memories attachment，每轮扫描）&lt;/span&gt;&lt;span class="meta"&gt;每轮重扫 → 新写的文件本轮生效&lt;/span&gt;&lt;/div&gt;&#10; &lt;div class="ps-item ps-attach"&gt;&lt;span class="label"&gt;⑧ 其他 Attachments（MCP tools / changed_files / plans ...）&lt;/span&gt;&lt;span class="meta"&gt;每轮动态&lt;/span&gt;&lt;/div&gt;&#10; &lt;div class="ps-item ps-user"&gt;&lt;span class="label"&gt;⑨ User Message（当前 query）&lt;/span&gt;&lt;span class="meta"&gt;每轮变&lt;/span&gt;&lt;/div&gt;&#10; &lt;div class="ps-item ps-hist"&gt;&lt;span class="label"&gt;⑩ Conversation History（历史 tool_use → FileRead team-memory）&lt;/span&gt;&lt;span class="meta"&gt;每轮增长，已有的不变 → cache 安全&lt;/span&gt;&lt;/div&gt;&#10; &lt;div class="ps-item ps-hist"&gt;&lt;span class="label"&gt;⑪ &lt;b&gt;Session Memory&lt;/b&gt; SummaryMessage（仅 compact 时登场）&lt;/span&gt;&lt;span class="meta"&gt;平时不在这里&lt;/span&gt;&lt;/div&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h3 id="s3-2-write-conflict"&gt;3.2 写入触发冲突：谁写了谁就不重跑&lt;/h3&gt;&#10;&lt;p&gt;&#10; &lt;b&gt;场景：&lt;/b&gt; Agent 在对话中主动 FileWrite 写了一条 Team Memory → 同时 stopHook 触发 Auto Memory extract → 会不会重复写？&#10;&lt;/p&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 850 200" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10; &lt;rect x="10" y="10" width="260" height="80" rx="6" fill="#3fb95022" stroke="#3fb950"/&gt;&#10; &lt;text x="25" y="30" fill="#3fb950"&gt;主 agent 在本轮对话中&lt;/text&gt;&#10; &lt;text x="25" y="48" fill="#c9d1d9"&gt;主动 FileWriteTool → 写了&lt;/text&gt;&#10; &lt;text x="25" y="66" fill="#c9d1d9"&gt;team-memory/feedback_testing.md&lt;/text&gt;&#10; &lt;text x="25" y="82" fill="#8b949e" font-size="11"&gt;（tool_use block 在 messages 里）&lt;/text&gt;&#10;&#10; &lt;rect x="330" y="10" width="190" height="80" rx="6" fill="#161b22" stroke="#f0883e"/&gt;&#10; &lt;text x="345" y="30" fill="#f0883e"&gt;handleStopHooks&lt;/text&gt;&#10; &lt;text x="345" y="48" fill="#c9d1d9"&gt;每轮结束 → fire-and-forget&lt;/text&gt;&#10; &lt;text x="345" y="66" fill="#c9d1d9"&gt;executeExtractMemories()&lt;/text&gt;&#10; &lt;text x="345" y="82" fill="#8b949e" font-size="11"&gt;Auto Memory extract 启动&lt;/text&gt;&#10;&#10; &lt;rect x="570" y="10" width="270" height="80" rx="6" fill="#f8514922" stroke="#f85149"/&gt;&#10; &lt;text x="585" y="30" fill="#f85149" font-weight="600"&gt;hasMemoryWritesSince() 检查&lt;/text&gt;&#10; &lt;text x="585" y="48" fill="#c9d1d9"&gt;扫描主 agent 的 tool_use blocks&lt;/text&gt;&#10; &lt;text x="585" y="66" fill="#c9d1d9"&gt;→ 发现已写 team-memory 目录&lt;/text&gt;&#10; &lt;text x="585" y="82" fill="#f85149" font-weight="600"&gt;→ extract 直接跳过本轮！&lt;/text&gt;&#10;&#10; &lt;line x1="130" y1="90" x2="570" y2="50" stroke="#30363d" stroke-width="1.5" stroke-dasharray="4,2"/&gt;&#10; &lt;line x1="425" y1="90" x2="570" y2="50" stroke="#30363d" stroke-width="1.5" stroke-dasharray="4,2"/&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;p&gt;&#10; 这是一个 &lt;b&gt;程序化的防冲突机制&lt;/b&gt;，完全在客户端侧。&#10; 另外 Agent Memory 和 Auto Memory 的存储目录物理隔离（&lt;code&gt;agent-memory/&amp;lt;type&amp;gt;/&lt;/code&gt; vs&#10; &lt;code&gt;projects/&amp;lt;hash&amp;gt;/memory/&lt;/code&gt;），各自独立 MEMORY.md，也不存在同文件冲突。&#10;&lt;/p&gt;&#10;&#10;&lt;h3 id="s3-3-team-concurrency"&gt;3.3 Team Memory 多人并发冲突&lt;/h3&gt;&#10;&#10;&lt;h4 id="s3-3-diff-keys"&gt;多人改不同 key —— upsert 天然合并&lt;/h4&gt;&#10;&lt;p&gt;&#10; 详细时序在上一轮对话中已经解释过。核心是：&#10;&lt;/p&gt;&#10;&lt;ul&gt;&#10; &lt;li&gt;服务器用仓库级 ETag + &lt;code&gt;If-Match&lt;/code&gt; 做乐观锁（不是本地文件系统锁）&lt;/li&gt;&#10; &lt;li&gt;upsert 语义让"请求里出现的 key 覆盖，没出现的不动" → 不同 key 的写入互相不干扰&lt;/li&gt;&#10; &lt;li&gt;客户端收到 412 → 只拉 server checksums（不拉正文）→ 重算 delta → 自动重试&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&#10;&lt;h4 id="s3-3-same-key"&gt;多人改同一 key —— 后到者覆盖（无 merge）&lt;/h4&gt;&#10;&lt;p&gt;&#10; 服务器层不做三方 diff / 文本合并。哪个客户端先收到 412 并自动重试成功，&#10; 哪个就是最终版本。被覆盖的人下次 pull 才发现。这是有意的工程权衡：&#10;&lt;/p&gt;&#10;&lt;div class="kv red"&gt;&#10; &lt;b&gt;"Content-level merge is not attempted — the local version simply overwrites the server version for that key,&#10; and the server's edit to that key is lost. This is the lesser evil: the local user is actively editing and can&#10; re-incorporate the teammate's changes, whereas silently discarding the local edit loses work the user just did&#10; with no recourse."&lt;/b&gt;&#10; — &lt;code&gt;index.ts#L876-L887&lt;/code&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h3 id="s3-4-stale-memory"&gt;3.4 读侧冲突：记忆过时&lt;/h3&gt;&#10;&lt;p&gt;统一解决，完全靠 prompt 引导模型（LLM 自决，无程序化处理）：&lt;/p&gt;&#10;&lt;div class="kv-list"&gt;&#10; &lt;div class="kv"&gt;&#10; &lt;b&gt;MEMORY_DRIFT_CAVEAT&lt;/b&gt; — "Memory records can become stale over time. If a recalled memory conflicts&#10; with current information, &lt;b&gt;trust what you observe now&lt;/b&gt; — and update or remove the stale memory rather&#10; than acting on it."&#10; &lt;/div&gt;&#10; &lt;div class="kv"&gt;&#10; &lt;b&gt;TRUSTING_RECALL_SECTION&lt;/b&gt; — 单独 section 告诉模型：记忆说某函数/文件存在 ≠ 现在还存在。&#10; 用记忆前 &lt;b&gt;先 grep / 检查文件是否存在&lt;/b&gt;。&#10; &lt;/div&gt;&#10; &lt;div class="kv"&gt;&#10; &lt;b&gt;用户显式"忽略记忆"&lt;/b&gt; — "proceed as if MEMORY.md were empty"，不要引用任何记忆内容。&#10; &lt;/div&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h3 id="s3-5-cache-edge"&gt;3.5 cache 边界导致的"新记忆不生效"问题（这不是 bug，是设计）&lt;/h3&gt;&#10;&#10;&lt;p&gt;这个问题值得单独拿出来说，因为它解释了为什么 cache 边界是这个位置：&lt;/p&gt;&#10;&#10;&lt;table&gt;&#10;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;更新的内容&lt;/th&gt;&lt;th&gt;什么时候生效&lt;/th&gt;&lt;th&gt;原因&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&#10;&lt;tbody&gt;&#10;&lt;tr&gt;&lt;td&gt;Agent Memory MEMORY.md 索引&lt;/td&gt;&lt;td&gt;要等 agent respawn 或 /compact&lt;/td&gt;&lt;td&gt;在 system prompt 里，被 getSystemPrompt() 固定字符串天然 cache&lt;/td&gt;&lt;/tr&gt;&#10;&lt;tr&gt;&lt;td&gt;Team Memory MEMORY.md 索引&lt;/td&gt;&lt;td&gt;要等 /compact /clear&lt;/td&gt;&lt;td&gt;systemPromptSection('memory', ...) · cacheBreak: false&lt;/td&gt;&lt;/tr&gt;&#10;&lt;tr&gt;&lt;td&gt;Agent Memory / Team Memory 新写入的 topic 文件正文&lt;/td&gt;&lt;td&gt;&lt;b&gt;本轮就能生效！&lt;/b&gt;&lt;/td&gt;&lt;td&gt;relevant_memories attachment 每轮重新扫描目录&lt;/td&gt;&lt;/tr&gt;&#10;&lt;tr&gt;&lt;td&gt;Agent Memory 新写入的 topic 文件&lt;/td&gt;&lt;td&gt;agent 自己记得路径，随时 FileRead&lt;/td&gt;&lt;td&gt;不在 prompt 链路里，但 agent 有主动读取能力&lt;/td&gt;&lt;/tr&gt;&#10;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&#10;&lt;p&gt;&#10; 这其实是一个精细的分工：&#10; &lt;b&gt;让需要 cache 的东西保持稳定（索引），让需要实时更新的东西放在 cache 边界之后（attachment）&lt;/b&gt;，&#10; 两者都不妥协。用户写入新 topic 文件后不会立刻在 MEMORY.md 里看到索引更新 —— 但新文件正文已经被下一轮的 attachment 扫到并注入 prompt 了。&#10;&lt;/p&gt;&#10;&#10;&lt;h2 id="s4-addon"&gt;四、Addon：Auto Memory 写入机制&lt;/h2&gt;&#10;&#10;&lt;h3 id="s4-1-positioning"&gt;4.1 定位说明&lt;/h3&gt;&#10;&lt;p&gt;&#10; Auto Memory &lt;b&gt;不是独立存储层&lt;/b&gt;，是写入触发机制。它能同时往两个目录写：&#10;&lt;/p&gt;&#10;&lt;div class="kv-list"&gt;&#10; &lt;div class="kv"&gt;&#10; &lt;b&gt;~/.claude/projects/&amp;lt;sanitized-git-root&amp;gt;/memory/&lt;/b&gt; —— private 目录（user 类型记忆强制落这里）&#10; &lt;/div&gt;&#10; &lt;div class="kv purple"&gt;&#10; &lt;b&gt;&amp;lt;cwd&amp;gt;/.claude/team-memory/&lt;/b&gt; —— team 目录（feedback 默认 team，project 强倾向 team，reference 通常 team）&#10; &lt;/div&gt;&#10;&lt;/div&gt;&#10;&lt;p&gt;&#10; 写入什么由 memory type 定义的 scope 规则决定（见 &lt;code&gt;TYPES_SECTION_COMBINED&lt;/code&gt;）。&#10; 两个目录各有独立 MEMORY.md，都在 system prompt 常驻（各自 200 行截断）。&#10;&lt;/p&gt;&#10;&#10;&lt;h3 id="s4-2-extract-trigger"&gt;4.2 萃取触发时序&lt;/h3&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 850 260" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10; &lt;rect x="20" y="10" width="810" height="36" rx="6" fill="#21262d" stroke="#58a6ff"/&gt;&#10; &lt;text x="34" y="32" fill="#58a6ff"&gt;handleStopHooks（每轮 query loop 结束后，final response 到达时）&lt;/text&gt;&#10;&#10; &lt;rect x="60" y="56" width="730" height="60" rx="6" fill="#161b22" stroke="#30363d"/&gt;&#10; &lt;text x="74" y="76" fill="#c9d1d9"&gt;三重门槛：feature('EXTRACT_MEMORIES') ✔ · 非 bare mode · !toolUseContext.agentId（非 subagent）&lt;/text&gt;&#10; &lt;text x="74" y="94" fill="#c9d1d9"&gt;+ isExtractModeActive() ✔&lt;/text&gt;&#10;&#10; &lt;rect x="60" y="130" width="730" height="36" rx="6" fill="#f8514922" stroke="#f85149"/&gt;&#10; &lt;text x="74" y="152" fill="#f85149"&gt;hasMemoryWritesSince() —— 主 agent 本轮已写 auto/team memory 目录？是则 extract 跳过&lt;/text&gt;&#10;&#10; &lt;rect x="60" y="176" width="730" height="74" rx="6" fill="#58a6ff22" stroke="#58a6ff"/&gt;&#10; &lt;text x="74" y="196" fill="#58a6ff" font-weight="600"&gt;fire-and-forget runExtraction()（不阻塞主交互）&lt;/text&gt;&#10; &lt;text x="74" y="214" fill="#c9d1d9"&gt;forked subagent（沙箱：FileRead / Grep / Glob / 只读 Bash / FileEdit+Write 仅 memory 目录）&lt;/text&gt;&#10; &lt;text x="74" y="232" fill="#c9d1d9"&gt;读现有 MEMORY.md → 优先 FileEdit 原地更新 → 新建 topic 文件 → 更新 MEMORY.md 索引&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h3 id="s4-3-recall"&gt;4.3 召回时序&lt;/h3&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 850 220" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10; &lt;rect x="20" y="10" width="810" height="36" rx="6" fill="#21262d" stroke="#58a6ff"/&gt;&#10; &lt;text x="34" y="32" fill="#58a6ff"&gt;startRelevantMemoryPrefetch()（每轮新 query 开始时）&lt;/text&gt;&#10;&#10; &lt;rect x="60" y="56" width="730" height="36" rx="6" fill="#161b22" stroke="#30363d"/&gt;&#10; &lt;text x="74" y="78" fill="#c9d1d9"&gt;@-mention agent？ → 是：只扫该 agent 的 memory dir（隔离）/ 否：并发扫 private + team 目录&lt;/text&gt;&#10;&#10; &lt;rect x="60" y="102" width="730" height="54" rx="6" fill="#161b22" stroke="#30363d"/&gt;&#10; &lt;text x="74" y="122" fill="#c9d1d9"&gt;findRelevantMemories() → 扫描文件头 → 生成 manifest → sideQuery 轻量选择&lt;/text&gt;&#10; &lt;text x="74" y="140" fill="#c9d1d9"&gt;→ ≤5 个文件（过滤 alreadySurfaced + readFileState）&lt;/text&gt;&#10;&#10; &lt;rect x="60" y="166" width="730" height="40" rx="6" fill="#e3b34122" stroke="#e3b341"/&gt;&#10; &lt;text x="74" y="190" fill="#e3b341"&gt;注入 relevant_memories attachment → 在 system prompt 之后 → 不影响 prefix cache → 每轮重扫&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h3 id="s4-4-with-layers"&gt;4.4 和三层存储的关系&lt;/h3&gt;&#10;&#10;&lt;div class="diagram-box"&gt;&#10;&lt;svg viewBox="0 0 900 180" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, sans-serif" font-size="12.5"&gt;&#10; &lt;rect x="360" y="10" width="180" height="55" rx="8" fill="#58a6ff22" stroke="#58a6ff"/&gt;&#10; &lt;text x="450" y="34" fill="#58a6ff" text-anchor="middle" font-weight="600"&gt;Auto Memory extract&lt;/text&gt;&#10; &lt;text x="450" y="52" fill="#8b949e" text-anchor="middle" font-size="10.5"&gt;写入触发机制&lt;/text&gt;&#10;&#10; &lt;path d="M360 55 L150 85 L150 110 L440 65" stroke="#79c0ff" fill="none" stroke-width="1.5"/&gt;&#10; &lt;text x="145" y="108" fill="#79c0ff" font-size="11" text-anchor="end"&gt;user 类型 → private 目录&lt;/text&gt;&#10;&#10; &lt;path d="M540 55 L750 85 L750 110 L460 65" stroke="#bc8cff" fill="none" stroke-width="1.5" stroke-dasharray="4,2"/&gt;&#10; &lt;text x="755" y="108" fill="#bc8cff" font-size="11" text-anchor="start"&gt;feedback/project/reference → team 目录&lt;/text&gt;&#10;&#10; &lt;rect x="20" y="125" width="260" height="40" rx="6" fill="#0d1117" stroke="#79c0ff"/&gt;&#10; &lt;text x="34" y="148" fill="#79c0ff"&gt;~/.claude/projects/&amp;lt;hash&amp;gt;/memory/&lt;/text&gt;&#10; &lt;text x="34" y="162" fill="#8b949e" font-size="10.5"&gt;（Auto private 目录）&lt;/text&gt;&#10;&#10; &lt;rect x="320" y="125" width="260" height="40" rx="6" fill="#0d1117" stroke="#bc8cff"/&gt;&#10; &lt;text x="334" y="148" fill="#bc8cff"&gt;&amp;lt;cwd&amp;gt;/.claude/team-memory/&lt;/text&gt;&#10; &lt;text x="334" y="162" fill="#8b949e" font-size="10.5"&gt;（Team Memory 目录 · 走同步链路）&lt;/text&gt;&#10;&#10; &lt;rect x="620" y="125" width="260" height="40" rx="6" fill="#0d1117" stroke="#3fb950"/&gt;&#10; &lt;text x="634" y="148" fill="#3fb950"&gt;&amp;lt;cwd&amp;gt;/.claude/agent-memory/&amp;lt;type&amp;gt;/&lt;/text&gt;&#10; &lt;text x="634" y="162" fill="#8b949e" font-size="10.5"&gt;（Agent Memory 目录 · Auto 不写这里）&lt;/text&gt;&#10;&lt;/svg&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h2 id="s5-summary"&gt;五、总结&lt;/h2&gt;&#10;&#10;&lt;h3 id="s5-1-problems"&gt;5.1 每层解决的具体问题（一行对照）&lt;/h3&gt;&#10;&#10;&lt;div class="kv-list"&gt;&#10; &lt;div class="kv yellow"&gt;&#10; &lt;b&gt;Session Memory&lt;/b&gt; —— 长会话 compact 时省额外 API 总结开销 + 保证 tool_use 链不被切断（有自然断点保护 + 完整重写策略）&#10; &lt;/div&gt;&#10; &lt;div class="kv green"&gt;&#10; &lt;b&gt;Agent Memory&lt;/b&gt; —— agent 不止是静态 prompt，要能跨会话成长、可 snapshot 分发、可升级。绑定 agent 类型，和 tool set / system prompt / definition 深度耦合。&#10; &lt;/div&gt;&#10; &lt;div class="kv purple"&gt;&#10; &lt;b&gt;Team Memory&lt;/b&gt; —— 多人协作时项目级知识不散落在个人本地。服务器权威 + upsert 同步 + ETag 乐观锁，本地手动删除不会同步。&#10; &lt;/div&gt;&#10; &lt;div class="kv"&gt;&#10; &lt;b&gt;Auto Memory 写入机制&lt;/b&gt; —— 用户不想每次显式"记住这个"，希望自动沉淀。覆盖 private + team 两个目录，四种 memory type + scope 规则决定写到哪里。&#10; &lt;/div&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;h3 id="s5-2-benefits"&gt;5.2 好处 vs 代价&lt;/h3&gt;&#10;&#10;&lt;table&gt;&#10;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;好处&lt;/th&gt;&lt;th&gt;代价&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&#10;&lt;tbody&gt;&#10;&lt;tr&gt;&lt;td&gt;&lt;b&gt;透明&lt;/b&gt;：全是 markdown 文件，人可读可改可 grep&lt;/td&gt;&lt;td&gt;&lt;b&gt;记忆治理&lt;/b&gt;：错误/过时/重复记忆会污染后续行为，靠 prompt 规则引导，无程序化 dedup&lt;/td&gt;&lt;/tr&gt;&#10;&lt;tr&gt;&lt;td&gt;&lt;b&gt;作用域清晰&lt;/b&gt;：user / project / local / team 四个独立目录，物理隔离&lt;/td&gt;&lt;td&gt;&lt;b&gt;冲突丢数据&lt;/b&gt;：多人改同一 Team Memory key → 后到者覆盖，无内容合并&lt;/td&gt;&lt;/tr&gt;&#10;&lt;tr&gt;&lt;td&gt;&lt;b&gt;cache 友好&lt;/b&gt;：需要稳定的（MEMORY.md 索引）进 system prompt 被 cache；需要实时的（正文）放 attachment 每轮刷新&lt;/td&gt;&lt;td&gt;&lt;b&gt;prompt 构造成本&lt;/b&gt;：每轮读 2-3 个 MEMORY.md；cache clear 后重新组装&lt;/td&gt;&lt;/tr&gt;&#10;&lt;tr&gt;&lt;td&gt;&lt;b&gt;检索成本可控&lt;/b&gt;：per-turn 只召回 ≤5 个文件，不是全文灌&lt;/td&gt;&lt;td&gt;&lt;b&gt;依赖模型遵守规则&lt;/b&gt;：写入/更新/删除全靠 LLM 遵守 prompt 指令，无 CRUD API&lt;/td&gt;&lt;/tr&gt;&#10;&lt;tr&gt;&lt;td&gt;&lt;b&gt;可分发&lt;/b&gt;：agent memory snapshot 让 agent 记忆随项目 ship&lt;/td&gt;&lt;td&gt;&lt;b&gt;删除不传播&lt;/b&gt;：Team Memory 本地删除不会同步 server，下次 pull 恢复&lt;/td&gt;&lt;/tr&gt;&#10;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&#10;&lt;p class="footnote"&gt;&#10; 源码参考：&lt;code&gt;src/constants/prompts.ts&lt;/code&gt; · &lt;code&gt;src/constants/systemPromptSections.ts&lt;/code&gt; ·&#10; &lt;code&gt;src/memdir/memdir.ts&lt;/code&gt; · &lt;code&gt;src/memdir/memoryTypes.ts&lt;/code&gt; ·&#10; &lt;code&gt;src/services/extractMemories/prompts.ts&lt;/code&gt; · &lt;code&gt;src/services/extractMemories/extractMemories.ts&lt;/code&gt; ·&#10; &lt;code&gt;src/services/SessionMemory/sessionMemory.ts&lt;/code&gt; ·&#10; &lt;code&gt;src/services/teamMemorySync/index.ts&lt;/code&gt; · &lt;code&gt;src/services/teamMemorySync/watcher.ts&lt;/code&gt; ·&#10; &lt;code&gt;src/tools/AgentTool/agentMemory.ts&lt;/code&gt; · &lt;code&gt;src/tools/AgentTool/loadAgentsDir.ts&lt;/code&gt; ·&#10; &lt;code&gt;src/utils/attachments.ts&lt;/code&gt; · &lt;code&gt;src/query.ts&lt;/code&gt; · &lt;code&gt;src/query/stopHooks.ts&lt;/code&gt;&#10;&lt;/p&gt;&#10;</content:encoded></item></channel></rss>