↓ 跳过正文

Claude Code Memory 分层机制详解

·14 分钟

一、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 完全不参与,不进任何 promptcontext 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/repopull(启动时)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 messagescache 边界之后通道 C:agent 主动读agent 运行时自己调 FileReadTool读 team-memory 目录下任何文件每轮都能读新写入的任何文件 → agent 想读就能读到读出来的内容作为 tool_result进入对话历史 → 自动参与上下文位置:conversation history(每轮增长,自然 cache 安全)

同步契约

操作语义冲突处理
pullserver 覆盖 local(服务器权威)无冲突 —— 服务器版本优先
pushupsert 语义:请求里的 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-forgetexecuteExtractMemories()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 /clearsystemPromptSection('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 行截断)。

4.2 萃取触发时序

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 恢复

源码参考:src/constants/prompts.ts · src/constants/systemPromptSections.ts · src/memdir/memdir.ts · src/memdir/memoryTypes.ts · src/services/extractMemories/prompts.ts · src/services/extractMemories/extractMemories.ts · src/services/SessionMemory/sessionMemory.ts · src/services/teamMemorySync/index.ts · src/services/teamMemorySync/watcher.ts · src/tools/AgentTool/agentMemory.ts · src/tools/AgentTool/loadAgentsDir.ts · src/utils/attachments.ts · src/query.ts · src/query/stopHooks.ts