智能体记忆持久化的设计原理：事件日志与恢复机制

一、问题的起点：崩溃之后的“失忆”困境

智能体（agent）在执行复杂任务时，往往需要跨越数十轮甚至上百轮交互：修改多个源码文件、执行命令、观察结果、调整策略。如果这个过程中进程意外崩溃，重启之后智能体是否还记得“刚才改到哪了”？

这个问题的答案完全取决于底层执行框架（harness）是否提供了真正的记忆能力。没有记忆，智能体就是失忆的：

• 用户问“刚才改到哪了”，它无法回答；
• 多轮对话中用户说“把刚才那个函数再改一下”，它不知道“刚才”指什么；
• 事后排查“它到底干了什么”，没有任何可查的依据。

因此，记忆不是锦上添花的附加功能，而是长时间运行智能体的基础设施。一个可靠的记忆方案可以概括为一个等式：

记忆 = 一份只能追加的流水账 + 记录、检查点、恢复三个机制

其中“流水账”是存储载体，“记录、检查点、恢复”是围绕这份日志建立的三套操作语义。本文围绕这三件事展开，解释其设计原理与工程取舍。

二、记忆的物理形态：一份追加式事件日志

2.1 日志文件的结构

从实现上看，智能体的记忆落在一个实实在在的文件里：每个会话对应磁盘上的一个 session.jsonl.zstd 文件。它是一条只追加（append-only）的 JSONL 事件日志，用 zstd 压缩。解压后是纯文本，每行一个 JSON 事件。

会话文件通常按工作区路径和会话标识组织在统一目录下，例如：

sessions/<escaped-workspace-path>/<session-id>/session.jsonl.zstd

这样的路径设计有两个直接好处：一是同一工作区的多个会话天然聚拢，便于按项目维度检索；二是转义后的工作区路径使目录名本身不携带分隔符歧义，跨平台迁移时不会因路径字符导致目录结构错乱。

2.2 会话头：一次性确立的身份

日志的第一行是会话头，具有特殊地位。它记录会话 id、创建时间、工作区路径、委派深度（delegationDepth）等元数据。其中委派深度用于区分会话层级：顶层会话为 0，子智能体会话递增。

会话头的关键语义是不可变：一个会话的身份从第一行就定死了，之后只允许追加事件，绝不改写会话头。这为后续所有事件提供了一个稳定的上下文锚点——恢复时只需读取第一行，就能确定“我是谁、在哪个工作区、处于哪一层委派”。

2.3 事件流：序号连续的增量记录

会话头之后是事件流。每个事件带有连续的序号（seq），按产生顺序追加。从一条真实任务日志中解压可以观察到，一次完整任务会产生数十条事件，涵盖模型输出分片、工具调用请求、工具执行结果、状态变更等类型。事件按类型可以归纳为若干代表性类别，各自承担不同的记录职责。

三、记录：只追加语义的三层体现

“只追加”是这份日志最核心的语义，它在三个层面体现。

3.1 写过的行永不重写

事件按序号连续追加，任何已写入的事件都不会被修改或删除。这不是实现细节，而是刻意设计：日志是唯一的事实来源，改历史等于伪造记忆。

这一约束带来的收益是深远的：

• 可审计性：任意时刻的系统状态都可以由日志重放推导，排查问题时不需要猜测“当时发生了什么”，只需读日志。
• 并发友好：追加操作天然是顺序写，多个写入方只需保证序号分配与落盘顺序，避免了随机更新带来的锁竞争。
• 崩溃安全：已完成写入的行不会因后续操作而损坏，最坏情况只是丢失尾部尚未落盘的部分。

3.2 打包压缩：用存储换空间

日志的每一行不一定对应一个事件。当连续出现多个同类型事件时（典型场景是模型输出被切成大量小分片），后端会把它们打包成一行存储（packChunks）。这种打包策略可以显著缩小日志体积，实测可减少约六成的存储占用。

打包的设计要点在于：打包只改变存储布局，不改变逻辑语义。恢复时按序解包，事件序列与打包前完全一致，从而在压缩率与可读性之间取得平衡。

3.3 增量落盘与缓冲的取舍

追加写并不意味着每条事件都立即触发一次磁盘同步。为了性能，写入通常经过缓冲，批量刷盘。这就引出了下一个机制要解决的问题：如果进程在缓冲尚未刷盘时崩溃，尾部事件会丢失。记录机制负责“尽量多写”，检查点机制负责“确保关键状态写完”。

四、检查点：在关键时点强制落盘

检查点的作用是在关键时点强制把缓冲中的事件写入磁盘，防止崩溃导致数据丢失。所谓“关键时点”，通常包括：

• 一轮模型推理与工具调用完成后；
• 状态发生重要迁移（如任务阶段切换）时；
• 即将执行高风险操作（如批量文件修改、长耗时命令）之前。

检查点的设计原则是以可控的性能开销换取可接受的丢失窗口。如果每条事件都强制同步，写入延迟会显著上升；如果完全不设检查点，崩溃可能丢失整轮对话。折中的做法是：普通事件走缓冲追加，关键边界强制刷盘并记录一个检查点标记。恢复时以最后一个完整检查点为基准，尾部不完整的数据可以被安全丢弃或标记为待确认。

五、恢复：从日志重建上下文

恢复机制回答“重启之后怎么办”。其流程可以拆解为四步：

1. 加载日志：定位会话文件，按 zstd 解压，逐行解析 JSONL。
2. 校验完整性：读取会话头确认身份与工作区；按序号连续性检测是否存在缺口；识别最后一个检查点位置，截断或隔离检查点之后的残缺尾部。
3. 重建对话历史：将事件流按类型回放，还原消息序列、工具调用与结果、文件变更记录等，构成模型下一轮推理所需的上下文。
4. 继续之前的轮次：以恢复出的状态为起点，继续分配序号、追加新事件，使会话在逻辑上无缝延续。

这里有一个重要设计判断：恢复的目标是“重建状态”，而不是“重放副作用”。日志中记录的是事件与结果，恢复过程不应重新执行已完成的工具调用（例如再次写入文件），否则会产生重复副作用。因此事件日志需要区分“意图”与“已生效结果”，恢复时以已记录的结果为准。

六、工程价值与适用边界

这套“追加日志 + 检查点 + 恢复”的方案，本质上把智能体记忆建模为一种事件溯源（event sourcing）结构。它的价值在于：

• 可追溯：任何行为都有据可查，满足调试与审计需求；
• 可恢复：崩溃不再等于失忆，长任务可以断点续跑；
• 可压缩：通过分片打包控制存储成本；
• 可扩展：会话按工作区与委派层级组织，天然支持多会话与子智能体场景。

其边界也需要清醒认识：追加日志会持续增长，需要配套的归档与清理策略；打包压缩增加了实现复杂度，解包逻辑必须与写入逻辑严格对称；检查点粒度需要根据任务特性调优，过密伤性能、过疏伤可靠性。

七、小结

智能体记忆的设计原理可以用一句话概括：用一份不可篡改的追加日志承载事实，用检查点控制丢失窗口，用恢复流程重建上下文。三者各司其职——记录保证“写得下、查得到”，检查点保证“关键时刻不丢”，恢复保证“重启之后接得上”。理解了这三件事，也就理解了长任务智能体为何能够在崩溃之后依然“记得自己改到哪了”。