记忆系统

一个智能体只要运行得比单个上下文窗口更久，就得记住自己做过什么，还得在底层运行环境消失之后恢复。它留下的状态有三种形态：一次会话的持久记录、它改动过的工作区，以及它跨会话带着走的记忆。会话日志必须把意图和结果分开记；给对话开分支便宜，给工作区开分支却不便宜；共享向量存储是数据泄露风险，而不只是相关性 bug。

一次跑了两遍的提交

先从故障讲起，因为它点明了整章的主题。一个运行框架向模型发出 prompt，模型请求运行 git commit，沙箱执行、提交落地，紧接着运行框架就在副作用触发与其记录抵达持久存储之间的那个窗口里崩溃了。恢复时读到的是最后一个持久状态，也就是提交之前的状态，于是智能体重放：它又发出同一条 git commit。

这不是什么稀奇的边缘情况。一个运行框架必须能承受四种常规事件中的任意一种：运行框架崩溃、副本重新调度、沙箱丢失，或者用户在数天后恢复一次会话。对一个长时间运行的智能体来说，这些全是正常运转区间，而已有报告称智能体的重试率在 15% 到 30% 之间，这让上面那种重放成了一个必须专门设计的常态，而非偶发意外 (Fast.io 2025)。它暴露出的核心困难，在于一个副作用和它的提交之间的缝隙。一份持久日志先记录意图（「调用 git commit」），再分开记录结果（「提交成功」）。一旦运行框架在这两次写入之间崩溃，恢复就会重新发出该操作。对幂等操作来说，这无害。可对非幂等操作，比如第二次提交、一张重复的工单、一笔重复的付款，存储和外部世界就会无声地分叉，而日志里没有任何东西能表明这件事发生过。

承受这些事件，意味着把状态写进一个持久存储，而难题不在于状态放哪里，而在于记录什么。智能体留下的状态有三种形态，失败的方式也各不相同。会话日志是追加式的意图，它的典型故障就是上面那道意图与结果之间的缝隙。工作区是可变的沙箱状态，它的故障是持久性：一块无法跨可用区边界跟随 pod 的卷，一次间隔太长的快照。长期记忆是那个存在时间超过会话、经整理且可检索的存储，它的故障是租户归属：一次跨越用户边界的检索，不是一个错误答案，而是一次数据泄露。三者共享一组很小的操作契约，即追加、读取、快照、fork，但这些操作落在形态并不统一的状态上。设计上的纪律，在于如实交代每个存储不保证什么。分析这三个存储时，核心问题始终相同：每个换来了什么，又拒绝了什么。

会话日志：记录一步的三种办法

会话日志可以有三种建法，它们之间有意义的区别，在于相对副作用各自记录什么，这就决定了意图与结果之间的缝隙落在哪里。图 39.3 把这三种都放到同一条轴上看。

追加式事件日志把每一条用户消息、模型响应、工具调用和工具结果都写进一个持久存储。日志是唯一的恢复产物：任何副本都能靠重放它来服务任何会话。这换来的是可重放、可审计，以及与传输无关的恢复，而它也正是把意图与结果之缝隙以最纯粹形式暴露出来的模型。仅从日志看，「请求过但从未运行」和「运行过但从未被记录」是一回事：一次没有结果的工具调用。这正是开篇那次崩溃踏进去的缝隙。

持久步日志靠在意图和结果之间加入第三条记录来弥合这道缝隙：一道在副作用执行之前就写下的持久步边界。重放会跳过任何结果已经持久化的步，于是「我们请求做 X」和「X 已完成」成了两个分开、各自持久的事实，重放可以追问「这一步是否已经完成？」，而不是默认它没完成。这就是持久执行框架最终选定的答案，而它的演化值得一追。基础事件日志给了可重放性，却把意图和结果含混在了一起。Restate (Ewen et al. 2025)、Temporal (Davis 2025) 和 Inngest (Poly 2026) 把每一步记账、运行副作用、再记录其结果，把事件日志含混带过的那个区分形式化了。Temporal 自己的说法是，LLM 的概率性行为使得基础重试逻辑不够用，而这恰恰是持久记账要应对的情形 (WorkOS 2025)。到 2025 年，这套做法已进入主流：AWS Lambda durable functions、Cloudflare Workflows 和 Vercel 的 Workflow DevKit 都把 AI 智能体用例作为首要定位发布 (Poly 2026)。这种模式不再是某个框架特有的了。

文件系统即状态模型走向相反的极端：工作上下文是临时的，而文件系统才是任务状态的唯一权威记录 (Zhou and others 2026)。事件日志降格为一份次要的意图日志；文件系统持有真相，通常是借一种由智能体维护的、有主张的约定（progress.md、plan.md）。对任何文件系统能表示的东西，这都绕开了意图与结果之间的缝隙，文件要么有新内容、要么没有，但它只是把缝隙挪了个位置，并没有消除它：一次 git push、一次外部 API 调用、一次 MCP 服务端游标推进，仍然在文件系统的触及范围之外。

从列表到树

会话日志记录的是步，但它的形态与其持久性是分开演化的。一份线性的追加式日志把会话当作一个列表，要回退就只能从头来。生产环境的运行框架早已走过了这一步。回退与截断会跳回某个检查点、丢弃尾部，并把工作区一并回滚以匹配，正如 Claude Code 的 /rewind (Anthropic 2025) 和 Cursor 的逐次编辑检查点 (Cursor 2025)。可 fork 的树走得更远：从任意检查点拉出多条同时存活的分支，全部保留。LangGraph 的时间旅行模型把检查点当作一张带显式分支 ID 的 DAG (LangChain 2025)，Claude Code 的 /fork 从一个共享的历史点派生出一个子会话 (Anthropic 2025)，Replit Agent (Replit 2025) 和 OpenAI 的 Codex CLI (OpenAI 2026) 也各自交付了自己的变体。会话不再是一个列表，而成了一棵树，或者至少是一份带可移动头指针的日志。这棵树建起来之所以便宜，只因为对话状态是一种指针结构，而下一节里工作区会打破这个假设。

工作区：部分持久，分支昂贵

工作区是沙箱那个可变的文件系统。它活得比单次工具调用更久，却不在持久日志上，正是这个区别带来了两种会话日志没有的故障。

工作区持久化只是部分持久，而非完整恢复。 让工作区跨过 pod 生命周期事件，有它自己的一套故障模式。常见的 Kubernetes 模式是在 /workspace 挂载一个 PersistentVolumeClaim；最主要的故障是可用区作用域。一个 ReadWriteOnce 的 PVC 由一块按可用区划分的块设备支撑，这块设备只能在它自己所在的可用区内物理挂接，所以当 pod 跨可用区重新调度时，卷无法跟随，恢复只能退回到一次完整的重新引导 (Rack2Cloud 2026; Kubernetes 2023)。当 pod 被有意销毁时（拆解、超时、缩容），PVC 往往会随之被删除，未提交的工作就没了：Gitpod issue #9544 是典型，一次工作区超时在最终同步完成之前触发，一位用户损失了大约两小时的工作 (Gitpod 2022)。另一条路，即按一定节奏给完整状态打检查点，会把快照频率和存储开销直接放在天平两端，而频率这个控制参数很关键，因为它设定了一次崩溃所能抹掉的工作量上限。Replit 的快照引擎把文件系统与对话上下文一并捕获，并报告称能从每小时一次的 OOM 崩溃中恢复而不丢数据 (Replit 2025; Replit 2025)。任何声称「会话可无限期存活」的设计，都欠一份明确的交代：它覆盖了哪些故障模式，又不覆盖哪些。

改一下下面的快照间隔，看那两条曲线朝相反方向移动：快照打得越密，崩溃时抹掉的工作越少，但写入也越频繁。

import numpy as np
import matplotlib.pyplot as plt
rng = np.random.default_rng(0)
intervals = np.array([1, 2, 5, 10, 15, 30, 60])  # 两次快照之间的分钟数
trials = 20000
lost = []
for iv in intervals:
    crash = rng.uniform(0, iv, trials)  # 该间隔内的崩溃时刻
    lost.append(crash.mean())           # 自上次快照以来的工作量，以分钟计
lost = np.array(lost)
writes = 60 / intervals                 # 每小时快照写入次数
for iv, l, w in zip(intervals, lost, writes):
    print(f"每 {iv:2d} 分钟: 约损失 {l:4.1f} 分钟，每小时 {w:5.1f} 次写入")
fig, ax1 = plt.subplots()
ax1.plot(intervals, lost, "o-", color="#c0392b", label="期望损失工作量（分钟）")
ax1.set_xlabel("快照间隔（分钟）"); ax1.set_ylabel("损失工作量（分钟）")
ax2 = ax1.twinx()
ax2.plot(intervals, writes, "s--", color="#2980b9", label="每小时写入次数")
ax2.set_ylabel("每小时快照写入次数")
fig.legend(loc="upper center"); plt.show()

给对话开分支便宜，给工作区开分支昂贵。 给对话状态分支是一次指针操作：日志是一棵事件 ID 的树，fork 一棵树很便宜。给工作区分支就不是了，因为工作区是一个真实的文件系统，两条分支不可能都拥有它。

如 图 39.4 所示，这个选择收缩成一道两难：共享工作区的 fork 会在它上面竞态，分支 A 的写入对分支 B 可见；而克隆工作区的 fork 要付克隆代价。由此引出三种故障模式。一条分支无法 fork 它所触及的外部系统，git 远端、问题追踪器、MCP 游标都不行，于是可分支的状态和不可分支的状态会渐行渐远。合并回去则是结构性未解的：文件在检查点处有一个共同祖先，所以三方合并适用，但两段分叉的对话没有合并基点，因为其内容是一条推理轨迹，不是可编辑的行，这正是为什么文件合并必须由智能体而非运行框架来解决。而孤儿分支会持续占用工作区和会话日志资源，直到某个 TTL 把它们回收，所以一旦没有 TTL，这种泄漏就会无声地累积。单凭回退就足以应付交互式编码；可 fork 的树，则在用户并行探索多个备选方案、或一条评估流水线用改过的 prompt 重放一次会话时才划算。

长期记忆：因可检索而有用，也因同一属性而危险

一次会话受上下文压缩所界定（第 35 章）：上下文窗口被填满、被摘要，早先的回合落到模型够不着的地方。所以，一个本该跨数周认识某个用户的智能体，不能只靠上下文窗口。它需要一个独立的存储，持久且可查询，由运行框架按需加载进上下文。那个存储就是记忆，它是一个独立于会话日志的系统：日志是追加式的意图，记忆则是经整理、可检索的。

记忆的形态

记忆有一种值得点名的结构。短期记忆是单次对话内的会话上下文。长期记忆分为情景记忆（过去的交互）、语义记忆（关于用户或领域的事实）和程序记忆（学到的工作流）。外部知识，即检索增强生成（第 44 章）背后的语料和知识图谱，与之并列，却是另一回事：记忆是按用户的、经整理的、可写的，而 RAG 是从一个智能体并不拥有的共享语料里检索。

最底层是向量存储加嵌入检索：每一条记忆都被转成一个向量（一串能刻画其语义的数字），存下来，再通过寻找与查询最接近的那些向量来召回。Pinecone (Pinecone 2025)、pgvector (pgvector 2025) 和 Chroma (Chroma 2025) 是有代表性的基底。在它们之上是有主张的记忆框架，Letta (Letta 2025)（MemGPT (Packer et al. 2023) 的继任者）、Zep (Zep 2025) 和 Mem0 (Chhikara et al. 2025)，由它们来决定写什么、何时写、怎么压缩。知识图谱显式地建模实体与关系，适合组合式查询，但更难自动填充；而时序知识图谱加上了时间维度，使一个事实可以在一段时间内有效、然后被取代。

这个品类的到来方式和另外两个存储一样，是一个研究产物固化成了一个产品。MemGPT (Packer et al. 2023) 把 LLM 刻画成一个操作系统，在一个有界上下文里把记忆换进换出，而它的继任者 Letta (Letta 2025) 把那变成了一个托管原语。Zep (Zep 2025) 在一个时序知识图谱上构建记忆，Mem0 (Chhikara et al. 2025) 则为低延迟和 token 成本做了优化。这个品类还很年轻，年轻到它的基准仍有争议。

如今已成主流的另一条路，是完全绕开索引，把记忆存成普通文件，让智能体用它平时的工具去读写。Anthropic 的记忆工具给模型一个 /memories 目录，供它跨会话查看、创建与编辑，每一次文件操作都由应用侧在客户端执行 (Anthropic 2025)；编码智能体里的 CLAUDE.md 惯例，是同一个想法的手工版本。召回从相似度查询变成一次智能体式的读取或 grep，整理从框架的写入策略变成模型自己动手编辑。本章收尾要谈的几笔权衡也随之改变：文件记忆不用押注任何嵌入模型，因此没有重建索引的悬崖；按租户划分的目录可以直接翻查、直接删除；代价则是能召回的只有智能体当初想到要写下、后来又想到去读的那些东西。

记忆不保证什么

记忆是在成本与简单之间、在写时安全与读时便利之间做权衡。记忆要么被环境式地加载进每一个 prompt（简单、昂贵），要么作为一个工具暴露出来由智能体按需查询（更便宜、扩展性更好，但智能体得知道何时该问）。更换嵌入模型会使现有索引失效，逼出一次昂贵的重建索引，所以嵌入的选择是一项长期承诺。

最关键的权衡是租户归属，它正是使一个共享向量存储成为数据泄露风险、而非相关性 bug 的原因。让记忆有用的那个属性，即被检索到的内容直接落进模型的上下文，同时也让它变得危险，因为那内容与用户或运行框架放进去的指令无从区分。针对一个共享向量存储、又没有强制租户过滤的 top-k 相似度查询（取回存储中与查询最接近的 k 个向量），可能返回另一个租户的数据，而防御必须住在索引里，不能放在应用代码里。要在写入时分区，按租户分命名空间、用 pgvector 的行级安全或独立 schema，使一次查询在物理上就无法触及另一个租户的向量。给每个分块都打归因、在查询之后再过滤是较弱的做法，因为读时过滤离一次泄露只差一个 bug，而写时分区是失败即关闭的。这正是记忆最直接地消费身份模型的地方（第 56 章）：租户归属来源于身份，而分区把它强制落地。

第二种租户风险是记忆特有的，在会话日志里没有对应物：由于智能体根据用户消息写记忆，一个恶意用户可以精心构造消息，植入持久的错误信息。这是提示注入问题被搬进了记忆存储，并在那里跨会话存活。一条被错误检索或被投毒的记录落进 prompt，以难以调试的方式改变智能体的行为，因为追踪显示检索是成功的：被注入的文本不是一个错误，它是对错误内容的一次正确检索。

第一次崩溃之前就要定下的两个属性

下面这两个属性，在恰恰最糟的那一刻之前都看不见，这就是为什么它们属于设计，而不属于事后复盘。

第一个是对账缺口，也就是开篇那次崩溃的运维形态。如果沙箱持有持久日志之外的可变状态，运行框架在恢复时就必须把两者对账。对幂等操作，这无所谓；操作运行一次还是两次，结果都一样。对非幂等操作，向文件追加、给计数器加一、创建一次提交、调用一个有副作用的 API，运行框架就需要一道步日志边界，或一把穿过工具的幂等键。日志在副作用触发之前记下该步的意图和它的键；重放时，运行框架会针对这把键执行 check-then-act，或者针对外部系统自身的去重、git 的 ref 状态、支付处理商的幂等头去做，而不是盲目地重新发出。步日志本身并不能让外部副作用变得幂等，它提供的是把它们做成幂等的接口。

# 以幂等键标识的步，概念示意。
def run_step(journal, key, effect):
    if journal.has_outcome(key):     # 重放：跳过一个已完成的步
        return journal.outcome(key)
    journal.record_intent(key)       # 在副作用之前的持久边界
    result = effect()                # 非幂等的副作用
    journal.record_outcome(key, result)
    return result

第二个是删除的触及范围。一个删除权请求必须级联到每一个持有该用户数据的存储，而记忆往往是最棘手的一类：框架托管的记忆可能根本不暴露删除 API，于是一个为召回质量而选的存储，会悄悄变成一个删不掉的存储。写时分区在这里也有帮助，因为一个按租户的命名空间是一个可以整体丢弃的单位。更广的审计与合规机制，防篡改日志、数据驻留、那些监管制度，留到 第 56 章 再谈；记忆特有的义务，是让每一条记录都可归因到某个租户、并可按租户删除。

至于记忆存储本身，基础实现是一个向量索引（在既有 Postgres 里的 pgvector (pgvector 2025) 是运维开销最低的默认；当值得用一个专用存储时，再上 Pinecone (Pinecone 2025) 或 Chroma (Chroma 2025)），外面或者套一个管理写入与压缩策略的框架（Letta (Letta 2025)、Zep (Zep 2025)、Mem0 (Chhikara et al. 2025)），或者在策略简单到可以自己拥有时，套一层很薄的自定义层。运行框架（第 41 章）就是把结果加载进上下文的那个，或环境式地、或经由一个检索工具，把这条回路接回那个被记忆延长的会话。

延伸阅读