一、Overview 1.1 记忆机制 多 agent 系统里,单次上下文窗口承载不完历史决策、用户偏好和跨会话事实。
记忆机制把信息按生命周期分成三层:Session Memory 会话级旁路摘要、Agent Memory agent 类型级长期记忆、User Memory 用户级画像——每层独立写入、独立召回,通过统一的文件路径约定和 prefix cache 安全边界串成完整读写链路。
1.2 三层 × 两机制 全景图 维度 ② Session Memory ① Agent Memory ③ Team Memory 生命周期 解决什么问题 单次会话 · 旁路摘要 长会话 compact 省 token + 不切 tool_use 链 跨会话 · agent 类型级 agent 不止是静态 prompt,要能跨会话成长 跨机器 · repo 级协作 多人协作时项目级知识不散落在个人本地 谁来写 系统 postSampling subagent(沙箱化) ⚠️ 无系统自动萃取,agent 主动 FileWrite/Edit 两条通道:Auto extract 写 + Agent 主动 FileWrite 写 进 prompt 吗 ❌ 不进常规 prompt,只有 compact 时登场 ✅ system prompt(spawn 时固定字符串) MEMORY.md 进 system;正文进 attachment(每轮扫描) cache 行为 不参与 cache 讨论(旁路) 天然 cache(agent 不 respawn 就不变) MEMORY.md cache;正文 attachment 每轮刷新 新写入生效时机 下次 compact 直接读文件,无延迟 要等 agent respawn / /compact(cache clear) MEMORY.md: cache clear 后;正文: 本轮就能被 attachment 扫到 存储位置 ~/.claude/projects/<hash>/session-memory/ user / project / local 三个 scope 目录 <cwd>/.claude/team-memory/ ↔ 服务端同步 注:Auto Memory 不是独立存储层,是写入触发机制(第 5 章 Addon),能同时往 private 和 team 目录写。
1.3 cache 安全边界(必须先讲清楚的核心前提) Claude 服务器侧有 prefix cache —— 如果发给模型的 messages 前几千 tokens 和上一轮完全一样,服务器直接复用 prefill 结果。
这省了 prefill 时间和费用,但 cache 的条件是 前序字符串必须逐字节相同 。
下面这张图展示了 Claude Code 在 prompt 组装时如何精心设计 cache 安全边界:
① Base System Prompt(角色 / 能力 / 基本规则)
完全固定 · 天然 cache
② Agent Memory Prompt(getSystemPrompt() 闭包返回值)
agent definition 不变就不变 · 天然 cache
③ Auto Memory Prompt(MEMORY.md 索引 + 类型/存储规则)
systemPromptSection('memory') · cacheBreak: false · /compact /clear 才重算
④ Team Memory MEMORY.md 索引(和 Auto 一起进 loadMemoryPrompt)
同上 · 同一个 systemPromptSection · 同样 cache
⑤ 其他 dynamicSections(session_guidance / env_info / language / output_style / scratchpad ...)
大多 cacheBreak: false
⑥ mcp_instructions(唯一真正打破 cache 的 section)
DANGEROUS_uncachedSystemPromptSection · 每轮重算
─────────────── PREFIX CACHE 安全边界 ───────────────
⑦ Conversation History(历史 user/assistant/tool_use/tool_result 轮次)
每轮增长,但已有的历史部分保持不变 → cache 安全
⑧ relevant_memories Attachment(≤5 个选中的 memory topic 文件正文)
每轮重新扫描目录 → 每轮都可能不同 → 不 cache
⑨ 其他 Attachments(MCP tools delta / changed_files / plans / ...)
每轮动态
⑩ User Message(当前 query)
每轮变
源码证据:systemPromptSection('memory', ...) 的 cacheBreak: false(src/constants/systemPromptSections.ts),
直到 /compact 或 /clear 才通过 clearSystemPromptSections() 清 cache。
只有 DANGEROUS_uncachedSystemPromptSection 才会每轮重算并打破 prefix cache。
后面每层详解都会回到这个 cache 边界上,回答两个问题:①新写入什么时候能被模型看到?②这对 cache 有什么影响?
二、各层详解 2.1 Session Memory —— 会话级旁路摘要 存储什么 当前会话到目前为止的完整对话摘要 —— 不是长期记忆,是中间态压缩产物。
只有当会话足够长(累计 tokens ≥ 10K)才开始生效。内容是一段纯 markdown,
描述"到目前为止对话做了什么、决定了什么、还有什么待办"。
索引 没有索引文件 。整个 session-memory 文件本身就是一份摘要,无 MEMORY.md 也无 frontmatter。
路径结构 ~/.claude/projects/<sanitized-git-root>/session-memory/ └── <session-uuid>.md ← 纯 markdown 摘要,无 frontmatter # 目录权限 0o700(只有属主可读写执行) # 文件权限 0o600(只有属主可读写) 创建时 flag: 'wx'(O_CREAT|O_EXCL)→ 不覆盖其他会话同名文件
postSamplingHook 注册(每次模型采样完都检查) shouldExtractMemory() 三重判断:①初始化阈值 ②更新阈值 ③自然断点 · 累计 tokens < 10K → 不初始化,跳过 · 距上次更新 < +5K tokens 且 < +3 次 tool call → 跳过 · 最后一轮还有 tool_use 在跑 → 等自然断点(下一轮无 tool_use 时触发) 三重都通过 → 开始萃取 forked subagent(沙箱化)→ 只有 FileEditTool + 路径锁死连 FileReadTool 都 deny → 完整重写摘要文件
召回时序(什么时候读) 常规 query loop → Session Memory 完全不参与,不进任何 prompt context tokens 接近上限 → compact 触发(手动 / 自动阈值) trySessionMemoryCompaction() → 同步读本地文件 → 作为 SummaryMessage 插进 messages
cache 关系 Session Memory 完全旁路,不在常规 prompt 链路里。它既不影响也不受影响 prefix cache。
写入时用完整重写策略,读入时只有 compact 才触发。
更新策略 每次完整重写 (不是增量追加)。会话结束即废弃。有 flag: 'wx' 防止覆盖其他会话的同名文件。
案例文件示例 session-memory/xxxxxxxx-uuid.md (compliance-reviewer 场景)
# Session Summary (2026-11-10)
## 对话起始
用户明确要求重写 auth middleware —— legal 标记当前 session token 存储方式不合规。
项目即将发版,时间紧。
## 已做决定
- 用 Go context 包方案。用户之前否决过但这次同意。
- middleware 重写方向:token 存到 context 上游,下游 handler 按需取,不存 session 表。
## 待办
- [ ] 改 middleware.go:context 注入 + 移除 session 表存储
- [ ] 全量回归测试(用户强调 "测试必须 hit 真 DB,mock 曾导致生产事故")
- [ ] /claude team-memory 里要记住这个合规决定的原因
## 遇到的坑
- grep 发现 middleware.go 在 3 个地方直接读 session 表,不是单一入口 → 改动面比预期大
- user 明确禁止用 mock 写测试,必须 hit 真 DB 2.2 Agent Memory —— agent 类型级长期记忆 存储什么 某种 agent 类型的长期专属记忆。只有当 agent definition 里带 memory 字段时才启用。
内容类型和 Auto Memory 相同(user / feedback / project / reference),
但作用域是"某个 agent 类型",不是"某个项目"或"某个用户"。
索引 复用 MEMORY.md 协议 —— 每 topic 文件一行索引 + 描述,
硬截断 200 行 / 25KB (防止 prompt 爆炸)。
Agent Memory 和 Auto Memory 各有自己的 MEMORY.md,物理隔离。
路径结构(三个 scope 独立物理目录) ① user scope(跨项目复用) ~/.claude/agent-memory/ └── compliance-reviewer/ ├── MEMORY.md ├── compliance_token-rules.md └── framework_context.md 适合:user 自己长期积累的合规经验 所有项目共享同一份 user scope memory ② project scope(当前项目内共享) <cwd>/.claude/agent-memory/ └── compliance-reviewer/ ├── MEMORY.md └── team_specific_standards.md 适合:这个项目独有的合规标准 和项目绑定,换项目就另一份 ③ local scope(当前机器/挂载) <cwd>/.claude/agent-memory-local/ └── compliance-reviewer/ └── MEMORY.md + topic files 默认和 project 目录同结构 remote 环境重定位到 memory mount 适合:本机专属的临时经验
目录内文件结构 MEMORY.md(索引协议,每文件一行,200 行 / 25KB 截断): - [token-storage-rules.md](token-storage-rules.md) — legal 2026-10-15 标记 session token 存储不合规 → 强制移至 context - [framework-context-package.md](framework-context-package.md) — Go context 包曾被用户否决,2026-11-10 又同意了,记住这个转折点 (永远不要把正文直接写进 MEMORY.md) topic 文件(独立 markdown,带 frontmatter): --- name: token-storage-rules.md type: feedback description: legal 合规要求
⚠️ 无系统自动萃取 ,完全由 agent 在运行时主动 FileRead → FileWrite/Edit:
agent 运行时自主判断"这条值得长期记住" FileReadTool → 先读 MEMORY.md 看现有索引 → 决定是新建还是更新 FileWriteTool / FileEditTool → 新建或更新某条 topic 文件(带 frontmatter) FileEditTool → 维护 MEMORY.md 索引(两步骤:先写 topic 文件,再更新索引)
召回 + cache 时序 agent spawn 时 getSystemPrompt() 被调用(agent definition 里的闭包) agent definition: getSystemPrompt = () => systemPrompt + '\n\n' + loadAgentMemoryPrompt(name, parsed.memory) loadAgentMemoryPrompt(agentType, scope) ① 根据 scope 算出 memoryDir(user / project / local 三选一) ② 同步读 MEMORY.md(硬截断 200 行 / 25KB) ③ 返回一整段 prompt 字符串(规则 + scopeNote + MEMORY.md 内容) cache 行为:天然 cache。这不是 systemPromptSection,是 agent definition 返回值。 新写入什么时候生效? ① MEMORY.md 索引更新 → 要等 agent 下次 respawn 才会重新读(或 /compact 清 cache 后) ② 新 topic 文件正文 → agent 自己记得路径,后续通过 FileReadTool 显式读取
更新策略 agent 自主 FileEdit 原地修改 topic 文件 + 维护 MEMORY.md 索引。
Snapshot 机制 :首次 spawn 时从 <cwd>/.claude/agent-memory-snapshots/<agentType>/
初始化本地目录;启动后如果 snapshot 有更新,提示"新版可同步"。
这让 agent memory 可以随项目一起 ship —— 不是运行时副产物,而是可分发的角色资产。
案例文件示例 compliance-reviewer 的 user scope MEMORY.md:
- [token-storage-rules.md](token-storage-rules.md) — legal 2026-10-15 标记 session token 存储不合规
- [framework-context-package.md](framework-context-package.md) — Go context 包曾被否决又在 11/10 同意,记住转折点 token-storage-rules.md:
---
name: token-storage-rules.md
type: feedback
description: legal 2026-10-15 标记 session token 存储不合规 → 强制移至 context
---
Legal team 2026-10-15 flagged auth middleware: session tokens must not be stored in session table.
**Why:** new compliance requirements for session token storage.
**How to apply:** 审计任何新引入 session 表存储的代码,改为 Go context 传递。 2.3 Team Memory —— repo 级协作共享 存储什么 团队级 feedback("测试必须 hit 真 DB")、project("合并冻结 2026-03-05 开始")、
reference("pipeline bug 在 Linear INGEST 项目")。
user 类型的 memory 永远 private ,不会写进 team 目录。
写入什么由 memory type 定义里的 scope 规则决定。
索引 独立的 MEMORY.md(和 Agent / Auto 各一份)。格式相同,200 行 / 25KB 截断。
索引里每条一行。
同步拓扑 Team Memory Server /api/claude_code/team_memory?repo=owner/repo pull(启动时) push(fs.watch → 2s debounce → upsert + ETag) <cwd>/.claude/team-memory/ ├── MEMORY.md ├── feedback_testing.md ← "测试必须 hit 真 DB" 同事机器:/home/bob/project/.claude/team-memory/ ├── MEMORY.md ← 同步拉取后相同 └── project_auth-middleware.md 写入触发(两条通道) 通道 A:Auto Memory extract subagent 根据 type scope 规则(feedback 默认 team,project 强倾向 team),
把合适的记忆写到 team-memory 目录。extract 完成后 fs.watch 自动触发 push。
通道 B:Agent Memory 主动 FileWrite agent prompt 里被指引"这条属于团队级知识",
于是主动 FileWrite 到 team-memory 目录。fs.watch 自动触发 push。
⚠️ 安全闸门 teamMemSecretGuard.ts 在 FileWriteTool/FileEditTool 写入 team-memory 前做 secret 扫描
(gitleaks),防止 API key / 凭证等敏感信息进入共享目录。
召回 + cache 时序(三条通道!) 通道 A:MEMORY.md 索引 loadMemoryPrompt() 被 systemPromptSection('memory') 调用 cacheBreak: false 直到 /compact / /clear 才重算 新写入的索引更新 → 要等 cache clear 进 system prompt → cache 安全 位置:system prompt 栈 cache 边界之前 通道 B:topic 文件正文 findRelevantMemories() 每轮重新 扫描 team-memory 目录文件头 → sideQuery 选 ≤5 个 → 注入 每轮重扫描 新写入的 topic 文件 → 本轮就能被扫到! 进 relevant_memories attachment 位置:attachment messages cache 边界之后 通道 C:agent 主动读 agent 运行时自己调 FileReadTool 读 team-memory 目录下任何文件 每轮都能读 新写入的任何文件 → agent 想读就能读到 读出来的内容作为 tool_result 进入对话历史 → 自动参与上下文 位置:conversation history (每轮增长,自然 cache 安全)
同步契约 操作 语义 冲突处理 pull server 覆盖 local(服务器权威) 无冲突 —— 服务器版本优先 push upsert 语义:请求里的 key 覆盖,没出现的不动 ETag 乐观锁:If-Match + delta 上传 本地删除 不回同步 server 下次 pull 恢复(防误删)
案例文件示例 team-memory/ MEMORY.md:
- [feedback_testing.md](feedback_testing.md) — 测试必须 hit 真 DB,mock 曾导致生产事故
- [project_auth-middleware.md](project_auth-middleware.md) — auth middleware 重写:legal 合规 + deadline
- [reference_pipeline-bug.md](reference_pipeline-bug.md) — pipeline bug 在 Linear INGEST 项目 project_auth-middleware.md:
---
name: project_auth-middleware.md
type: project
description: auth middleware 重写的合规驱动 + 关键决策
---
**Decision:** 重写 auth middleware,token 从 session 表移至 Go context 传递。
**Why:** legal 2026-10-15 标记 session token 存储不合规。
**How to apply:** 任何新引入 session 表存储的代码需审计;compliance-reviewer agent 已记住此规则。
**Deadline:** 2026-11-12(发版前)。
**Actor:** 后端团队,Tech Lead 拍板。 三、协同与冲突 3.1 会话内 prompt 组装(各层落到哪里) 回顾 1.3 的 cache 边界图,这里看每层具体落到哪一段:
① Base System Prompt 完全固定 · 天然 cache
② Agent Memory MEMORY.md + 规则(getSystemPrompt() 固定字符串) agent definition 不变就不变
③ Auto Memory private MEMORY.md + 类型/存储规则(loadMemoryPrompt) systemPromptSection('memory') · cacheBreak: false
④ Team Memory MEMORY.md(和 ③ 共用 systemPromptSection) 同上
⑤ 其他 dynamicSections(session_guidance / env_info / language ...) 大多 cacheBreak: false
⑥ mcp_instructions(唯一真正打破 cache 的 section) DANGEROUS_uncached
PREFIX CACHE 安全边界(⑦ 之后每轮都刷新)
⑦ Agent/Team Memory topic 文件正文(relevant_memories attachment,每轮扫描) 每轮重扫 → 新写的文件本轮生效
⑧ 其他 Attachments(MCP tools / changed_files / plans ...) 每轮动态
⑨ User Message(当前 query) 每轮变
⑩ Conversation History(历史 tool_use → FileRead team-memory) 每轮增长,已有的不变 → cache 安全
⑪ Session Memory SummaryMessage(仅 compact 时登场) 平时不在这里
3.2 写入触发冲突:谁写了谁就不重跑 场景: Agent 在对话中主动 FileWrite 写了一条 Team Memory → 同时 stopHook 触发 Auto Memory extract → 会不会重复写?
主 agent 在本轮对话中 主动 FileWriteTool → 写了 team-memory/feedback_testing.md (tool_use block 在 messages 里) handleStopHooks 每轮结束 → fire-and-forget executeExtractMemories() Auto Memory extract 启动 hasMemoryWritesSince() 检查 扫描主 agent 的 tool_use blocks → 发现已写 team-memory 目录 → extract 直接跳过本轮!
这是一个 程序化的防冲突机制 ,完全在客户端侧。
另外 Agent Memory 和 Auto Memory 的存储目录物理隔离(agent-memory/<type>/ vs
projects/<hash>/memory/),各自独立 MEMORY.md,也不存在同文件冲突。
3.3 Team Memory 多人并发冲突 多人改不同 key —— upsert 天然合并 详细时序在上一轮对话中已经解释过。核心是:
服务器用仓库级 ETag + If-Match 做乐观锁(不是本地文件系统锁) upsert 语义让"请求里出现的 key 覆盖,没出现的不动" → 不同 key 的写入互相不干扰 客户端收到 412 → 只拉 server checksums(不拉正文)→ 重算 delta → 自动重试 多人改同一 key —— 后到者覆盖(无 merge) 服务器层不做三方 diff / 文本合并。哪个客户端先收到 412 并自动重试成功,
哪个就是最终版本。被覆盖的人下次 pull 才发现。这是有意的工程权衡:
"Content-level merge is not attempted — the local version simply overwrites the server version for that key,
and the server's edit to that key is lost. This is the lesser evil: the local user is actively editing and can
re-incorporate the teammate's changes, whereas silently discarding the local edit loses work the user just did
with no recourse."
— index.ts#L876-L887
3.4 读侧冲突:记忆过时 统一解决,完全靠 prompt 引导模型(LLM 自决,无程序化处理):
MEMORY_DRIFT_CAVEAT — "Memory records can become stale over time. If a recalled memory conflicts
with current information, trust what you observe now — and update or remove the stale memory rather
than acting on it."
TRUSTING_RECALL_SECTION — 单独 section 告诉模型:记忆说某函数/文件存在 ≠ 现在还存在。
用记忆前 先 grep / 检查文件是否存在 。
用户显式"忽略记忆" — "proceed as if MEMORY.md were empty",不要引用任何记忆内容。
3.5 cache 边界导致的"新记忆不生效"问题(这不是 bug,是设计) 这个问题值得单独拿出来说,因为它解释了为什么 cache 边界是这个位置:
更新的内容 什么时候生效 原因 Agent Memory MEMORY.md 索引 要等 agent respawn 或 /compact 在 system prompt 里,被 getSystemPrompt() 固定字符串天然 cache Team Memory MEMORY.md 索引 要等 /compact /clear systemPromptSection('memory', ...) · cacheBreak: false Agent Memory / Team Memory 新写入的 topic 文件正文 本轮就能生效! relevant_memories attachment 每轮重新扫描目录 Agent Memory 新写入的 topic 文件 agent 自己记得路径,随时 FileRead 不在 prompt 链路里,但 agent 有主动读取能力
这其实是一个精细的分工:
让需要 cache 的东西保持稳定(索引),让需要实时更新的东西放在 cache 边界之后(attachment) ,
两者都不妥协。用户写入新 topic 文件后不会立刻在 MEMORY.md 里看到索引更新 —— 但新文件正文已经被下一轮的 attachment 扫到并注入 prompt 了。
四、Addon:Auto Memory 写入机制 4.1 定位说明 Auto Memory 不是独立存储层 ,是写入触发机制。它能同时往两个目录写:
~/.claude/projects/<sanitized-git-root>/memory/ —— private 目录(user 类型记忆强制落这里)
<cwd>/.claude/team-memory/ —— team 目录(feedback 默认 team,project 强倾向 team,reference 通常 team)
写入什么由 memory type 定义的 scope 规则决定(见 TYPES_SECTION_COMBINED)。
两个目录各有独立 MEMORY.md,都在 system prompt 常驻(各自 200 行截断)。
handleStopHooks(每轮 query loop 结束后,final response 到达时) 三重门槛:feature('EXTRACT_MEMORIES') ✔ · 非 bare mode · !toolUseContext.agentId(非 subagent) + isExtractModeActive() ✔ hasMemoryWritesSince() —— 主 agent 本轮已写 auto/team memory 目录?是则 extract 跳过 fire-and-forget runExtraction()(不阻塞主交互) forked subagent(沙箱:FileRead / Grep / Glob / 只读 Bash / FileEdit+Write 仅 memory 目录) 读现有 MEMORY.md → 优先 FileEdit 原地更新 → 新建 topic 文件 → 更新 MEMORY.md 索引
4.3 召回时序 startRelevantMemoryPrefetch()(每轮新 query 开始时) @-mention agent? → 是:只扫该 agent 的 memory dir(隔离)/ 否:并发扫 private + team 目录 findRelevantMemories() → 扫描文件头 → 生成 manifest → sideQuery 轻量选择 → ≤5 个文件(过滤 alreadySurfaced + readFileState) 注入 relevant_memories attachment → 在 system prompt 之后 → 不影响 prefix cache → 每轮重扫
4.4 和三层存储的关系 Auto Memory extract 写入触发机制 user 类型 → private 目录 feedback/project/reference → team 目录 ~/.claude/projects/<hash>/memory/ (Auto private 目录) <cwd>/.claude/team-memory/ (Team Memory 目录 · 走同步链路) <cwd>/.claude/agent-memory/<type>/ (Agent Memory 目录 · Auto 不写这里) 五、总结 5.1 每层解决的具体问题(一行对照) Session Memory —— 长会话 compact 时省额外 API 总结开销 + 保证 tool_use 链不被切断(有自然断点保护 + 完整重写策略)
Agent Memory —— agent 不止是静态 prompt,要能跨会话成长、可 snapshot 分发、可升级。绑定 agent 类型,和 tool set / system prompt / definition 深度耦合。
Team Memory —— 多人协作时项目级知识不散落在个人本地。服务器权威 + upsert 同步 + ETag 乐观锁,本地手动删除不会同步。
Auto Memory 写入机制 —— 用户不想每次显式"记住这个",希望自动沉淀。覆盖 private + team 两个目录,四种 memory type + scope 规则决定写到哪里。
5.2 好处 vs 代价 好处 代价 透明 :全是 markdown 文件,人可读可改可 grep记忆治理 :错误/过时/重复记忆会污染后续行为,靠 prompt 规则引导,无程序化 dedup作用域清晰 :user / project / local / team 四个独立目录,物理隔离冲突丢数据 :多人改同一 Team Memory key → 后到者覆盖,无内容合并cache 友好 :需要稳定的(MEMORY.md 索引)进 system prompt 被 cache;需要实时的(正文)放 attachment 每轮刷新prompt 构造成本 :每轮读 2-3 个 MEMORY.md;cache clear 后重新组装检索成本可控 :per-turn 只召回 ≤5 个文件,不是全文灌依赖模型遵守规则 :写入/更新/删除全靠 LLM 遵守 prompt 指令,无 CRUD API可分发 :agent memory snapshot 让 agent 记忆随项目 ship删除不传播 :Team Memory 本地删除不会同步 server,下次 pull 恢复