【echo-agent系列文章】给 Agent 加一个可恢复的状态层

你可能遇到过这样的场景：让 Agent 帮你修复测试失败，它先读日志、改代码、跑测试，然后进程突然重启。重新打开以后，它只记得用户最后一句话，却不知道刚才改过哪些文件、测试跑到哪一步、哪个工具结果已经验证过。

如果这只是聊天 Demo，丢掉历史也许还能接受。重新问一次，模型再答一次。但执行型 Agent 不一样，它的每一步都可能改变外部世界。状态丢了，不只是体验变差，而是系统失去继续工作的依据。

本篇只讲一个点：Agent 需要一个可恢复的状态层。

问题入口

很多人第一次写 Agent，会把状态放在内存里：一个messages数组、一份工具调用记录、一个当前任务对象。这样最容易跑通，因为它不需要数据库，也不需要迁移和恢复。

问题在于，内存状态只对当前进程有效。进程退出、部署重启、容器迁移、异常崩溃，都会让 Agent 回到“刚出生”的状态。

对普通文本型 Chatbot 来说，这通常只是上下文丢失。对 Agent 来说，影响更深：会话历史丢了，模型不知道前面发生过什么；任务状态丢了，系统不知道是否要继续、重试还是取消；审批记录丢了，后续动作无法证明授权边界；工具 trace 丢了，工程师只能看到最终结果，无法复盘过程。

存储层不是 Agent 的附属模块，而是长期运行能力的地基。

一个简单例子：用户说“帮我修复测试失败”。这句话背后至少有五类状态。

这也是为什么“把聊天记录写进数据库”还不够。Agent 的状态不是一种数据，而是一组有不同语义、不同一致性要求、不同恢复策略的运行事实。

状态边界

状态层最容易被误解成一个通用 KV：get(key)、set(key, value)，所有东西都塞进去。短期看很灵活，长期看会把查询逻辑、序列化约定和状态语义散落到各个模块里。

会话通常按session_key读写，还要按更新时间排序和归档；记忆需要按类型过滤，例如用户记忆、环境记忆或语义记忆；任务和工作流需要按workflow_id、status查询；日志需要按trace_id查询；向量需要按source_id加载；归档消息需要按session_key和compression_id组织。

这些访问模式本来就不同，硬塞进一个 KV，只会让上层模块自己补一层隐形协议。

为了不停留在抽象层面，下面以 echo-agent 的实现为例。它把持久化能力抽象为StorageBackend，但这个抽象不是数据库驱动的，而是状态语义驱动的。

class StorageBackend(ABC): async def initialize(self) -> None: ... async def close(self) -> None: ... ​ async def store_session(self, key: str, data: dict) -> None: ... async def load_session(self, key: str) -> dict | None: ... ​ async def store_memory(self, entry_id: str, data: dict) -> None: ... async def store_task(self, task_id: str, data: dict) -> None: ... async def store_log(self, trace_id: str, data: dict) -> None: ... async def archive_messages(self, session_key: str, messages: list[dict]) -> None: ...

这段伪代码的重点不是接口数量，而是设计方向：上层依赖的是“存储能力”，不是 SQLite 的表结构。

好的存储抽象不应该隐藏状态语义，而应该把状态语义变成稳定契约。

这样做也为后端替换留下空间。当前默认后端可以是 SQLite，未来也可以接 PostgreSQL、MySQL、对象存储或事件日志。但抽象不能假装所有后端都一样。不同后端在事务、并发、锁、延迟和故障模式上差异很大。合理的抽象应该暴露原子写、条件更新、迁移版本、批量读取、审计追加、过期清理这类与正确性相关的能力。

默认后端

echo-agent 默认使用 SQLite。这个选择很务实：单文件、无额外服务进程、便于备份和测试，适合个人部署、本地开发、轻量服务器和私有运行环境。

SQLite 不是所有场景的终点。高并发多实例、团队级共享 Agent、大规模集中审计，可能需要外部数据库。但默认后端的目标不是覆盖所有未来规模，而是让大多数本地和私有部署稳定运行。

在 echo-agent 中，SQLiteBackend初始化时会创建目录、连接数据库，并设置几个关键 PRAGMA：

async def _connect(self) -> None: self._db = await aiosqlite.connect(str(self._db_path)) await self._db.execute("PRAGMA journal_mode=WAL") await self._db.execute("PRAGMA foreign_keys=ON") await self._db.execute("PRAGMA busy_timeout=5000") await self._db.executescript(_SCHEMA_SQL) await self._run_migrations()

journal_mode=WAL改善轻量并发读写表现。Agent 可能同时保存会话、写日志、刷新记忆、更新任务状态，不能每次写入都轻易互相阻塞。

foreign_keys=ON打开外键约束，为后续表关系扩展保留正确性基础。busy_timeout=5000则是在数据库短暂被锁时等待 5 秒，而不是立即失败。这对后台任务和多会话写入更友好。

表设计也体现了一个折中：复杂业务对象整体存为 JSON，需要过滤和排序的字段单独建列。例如sessions保存完整会话对象，memories单独有type，tasks单独有workflow_id和status，logs单独有trace_id。

这种设计不追求数据库范式上的精细拆分，而是服务 Agent 的真实访问模式：对象结构要能演进，关键查询要足够快，默认部署不能太重。

结构演进

Agent 框架会持续变化。记忆系统可能从简单键值发展到情节记忆，压缩系统可能需要归档被压缩掉的消息，多 Agent 协作可能需要审计记录，向量检索可能需要新的索引。

如果每次升级都要求用户删库重建，这个系统就不可能长期运行。

所以 SQLiteBackend 内置了迁移机制：读取schema_migrations表，跳过已经应用的版本，只执行新的迁移。迁移列表中，第 4 到 13 号与高级记忆相关，包括memory_episodes、memory_graph、memory_contradictions、memory_access_log；第 16 和 17 号引入message_archive，用于保存压缩过程中移出主上下文的消息。

这说明存储层不是静态模块。它会随着 Agent 能力扩展而扩展。

迁移也有边界。当前这种单条 SQL 迁移适合创建表、创建索引、删除旧表等简单变更。如果未来要批量重写 JSON、做跨版本兼容检查、迁移不可重建数据，就需要更完整的迁移脚本和发布策略。

生产级判断标准很简单：旧会话能不能继续加载，旧任务能不能保持合法状态，旧记忆缺失新字段时有没有默认值，迁移失败会不会破坏旧数据，是否有旧版本样例测试。

恢复路径

可恢复状态层不只是在成功路径上写入数据库。真正重要的是失败路径：连接断了怎么办，保存失败怎么办，写到一半崩溃怎么办，同一会话并发进入怎么办。

echo-agent 在这里做了几层处理。

第一层是自动重连。每个读写方法都会先调用_ensure_connection。如果连接不存在，重新连接；如果执行SELECT 1失败，关闭旧连接，再建立新连接。上层模块不需要到处处理“数据库连接是否还活着”。

第二层是会话 fallback。SessionManager保存会话时优先走 storage backend，如果 storage 保存失败，会记录 warning，并回退到文件。

第三层是原子写。文件 fallback 使用 JSONL：第一行是 metadata，后续每行是一条消息。写入时先创建临时文件，写完后flush、fsync，最后用os.replace替换目标文件。

async def save(session): if storage: try: await storage.store_session(session.key, session.to_dict()) return except Exception: logger.warning("fallback to file") ​ tmp = write_temp_jsonl(session) fsync(tmp) os.replace(tmp, final_path)

这段逻辑保护的是一个很具体的故障场景：如果保存中途失败，旧文件仍然存在，不会被半截新文件覆盖。可靠性不是只证明“能保存”，还要证明“保存失败时不损坏旧数据”。

第四层是并发边界。SessionManager 为每个session_key维护一把 lock：同一会话内串行，不同会话间并发。

这不是性能细节，而是语义要求。同一会话中的用户消息、assistant 消息、tool call 和 tool result 必须保持顺序。如果两个处理流程交错，模型上下文就会被污染：工具结果可能插到错误位置，记忆整合可能基于不完整历史，任务状态也可能被后写覆盖。

第五层是缓存淘汰。SessionManager 有缓存上限，旧 session 被淘汰时会先保存。否则缓存只是把丢状态的时间从“进程退出”提前到了“缓存满”。

一致性层级

不是所有状态都需要同样强的一致性。这个判断很关键，否则很容易在两个方向上犯错：要么所有数据都上重型事务，系统复杂到跑不动；要么所有数据都轻描淡写，关键状态在部分失败时丢失。

比如 embedding 索引可以稍微滞后，因为它能补算；健康统计可以重算，因为它是派生数据；但会话最终回答和用户可见输出之间应尽量一致，审计记录不应随意丢失，未完成任务不能被缓存清理误删。

存储系统的目标不是“所有数据都写进去”，而是让系统在部分失败后仍能解释自己处于什么状态，并尽量恢复到可以继续工作的位置。

记忆边界

持久化不等于记忆。这个概念必须分清。

会话历史被持久化，但它主要服务当前对话恢复；工具日志被持久化，但它主要服务审计和排障；知识库索引被持久化，但它是外部文档的检索结构；技能被持久化，也更接近程序性流程。

真正的长期记忆需要语义抽取、作用域、置信度、冲突处理、遗忘和检索。仅仅把所有消息写进数据库，只会得到一个越来越大的历史仓库，不会自动得到一个更懂用户的 Agent。

可以这样区分：存储系统提供物理连续性，记忆系统提供认知连续性。前者保证数据还在，后者决定未来何时使用、如何解释、能否修正。

这也是状态治理的起点。状态保存得越久，影响未来行为的时间越长。短期上下文出错，影响当前请求；长期记忆、技能、调度任务出错，会影响未来很多请求。成熟 Agent 不能把状态系统当成无限追加日志，而要知道哪些状态可以删除，哪些必须保留，哪些需要审查，哪些可以重建。

生产可用性

判断一个 Agent 的状态层是否接近生产可用，不要只看有没有数据库。更硬的标准是看它在长期运行、升级、失败和排障时能否站住。

这些机制看起来不像“智能”本身，但它们决定智能能否长期存在。没有状态层，Agent 的能力只停留在当前上下文窗口；有了状态层，它才可能把一次交互转化为可恢复的持续协作。

小结

本篇讲的是 Agent 的状态层。它不是简单数据库，也不是记忆系统本身，而是让会话、任务、记忆、日志、索引和归档在进程之外继续存在，并在失败后能够恢复语义。

echo-agent 在这里的取舍很清楚：用StorageBackend表达状态语义，用 SQLiteBackend 提供低运维默认实现，用迁移机制承接结构演进，用自动重连、JSONL fallback、原子写和 per-session lock 控制失败路径。

存储解决的是“状态在哪里、如何恢复”。但一个长期运行的 Agent 还需要回答另一个问题：外部输入、内部任务、工具结果和最终回复如何在系统中流动。下一篇就进入消息总线。

（全篇完）

本文为 echo-agent 设计笔记系列第 04 篇。项目源码已开源至 GitHub。如果你对工业级 Agent 的工程落地感兴趣，欢迎加入[QQ群]参与日常讨论。下一篇我们将探讨 《用消息总线给 Agent 的通道解耦》，敬请期待。