会拒绝压缩的那道门:compression.checkpoint_required 到底在保护什么

一个会话跑到第三个小时,上下文窗口满了,Hermes 做一次压缩,你接着干活。两天后你问“当初为什么选这个方案”,得到一个很自信的答案——但那是摘要的摘要。严格说没有任何东西坏掉,只是你真正需要的那段话,从来没被写进任何持久的地方,而装着它的对话记录已经被改写过了。
compression.checkpoint_required 就是为这件事准备的。它是个笨办法:门一开,Hermes 宁可拒绝压缩,也不在没有备份的情况下重写你的历史。
一句话说清这道门
压缩本质上是有损的——一长段对话变成一份更短的摘要加一截最近的尾巴。这道门的要求是:在这次改写发生之前,必须已经有人把未压缩的完整记录提交到持久存储,并且告诉 Hermes 提交完成了。
这个“有人”是谁?是记忆提供者插件。不是摘要模型,不是会话数据库,也不是模型本身。
怎么打开
compression:
checkpoint_required: true # 默认 false
或者等价地:
hermes config set compression.checkpoint_required true
hermes config get compression.checkpoint_required
运维层面就这么多。下面说的都是后果,因为它带来的影响远不止一个布尔值。
这道门挡住了什么
门打开之后,一次压缩尝试会在任何有损改写之前直接失败:
- 未压缩的记录原样保留;
- 这次尝试报
BLOCKED_MISSING_PREREQUISITE,并说明缺了什么; - 等你的归档存储恢复后可以重试。
这道门约束的是所有压缩权力,不只是 Hermes 自己的摘要器。启用后,服务端原生压缩会被抑制;轮次结束后的微压缩会在 agent 初始化时被强制关掉(它把旧对话吸收进滚动摘要,路径里根本没有检查点钩子);codex_app_server 这种 API 模式会在启动时被拒绝——那个运行时压缩自己的线程,没有可信的“压缩前边界”,无法保证检查点。于是带检查点能力的 Hermes 压缩器成为唯一有损权威。
这就是诚实的代价:打开这道门会让压缩变严格,在某些运行时上甚至变得不可能。它是数据完整性设置,不是性能设置。
提供者要实现什么
契约很小,也很明确。提供者通过声明 API 版本 2 来加入:
from agent.memory_provider import MemoryProvider
class MyArchivingProvider(MemoryProvider):
pre_compress_checkpoint_api_version = 2
def on_pre_compress(self, messages, *, require_checkpoint=False):
ids = self._archive(messages) # 返回前必须已经持久化
return f"checkpoint: {ids}" # 会转发进摘要提示词
require_checkpoint 映射的就是运维的那项设置:它为 True 时,这个方法抛出异常就会拦住有损改写。能正常返回就意味着“持久副本已提交”——所以“部分成功”不是选项,文档明确要求任何失败都要抛,而不是乐观地返回。
版本 2 的提供者拿到的也不是原始列表,而是归一化后的直接证据:只有用户和助手的文本行。工具结果、系统消息、助手消息里的 tool_calls 载荷、以及之前的压缩摘要,都会在宿主侧被过滤掉。之前的摘要靠一个持久标记识别,所以恢复的会话不会把“摘要的摘要”当成原始证据重新喂进你的归档。
还有一个要求经常让人踩坑:检查点必须幂等。一次失败退出之后,下一次尝试会拿同一份记录再调一次 on_pre_compress();而一份只长大了一点的记录,产生的证据大量重叠。所以要按内容(比如记录摘要的哈希)作为键来 upsert,否则重试会堆出一堆重复归档。
11 月 6 日改了什么
这道门更早就存在,但有个很尖的边角,直到 11 月 6 日合并的 PR #149763 才补上。两个问题:
- 子代理和分叉是以“禁用记忆”构建的。
delegate_task、curator、批处理运行器、飞书评论回合各自跑自己的记录,这些分叉被以skip_memory=True创建。门一开,它们第一次压缩就以BLOCKED_MISSING_PREREQUISITE失败——不是你的提供者有问题,而是这个分叉从来没被配上提供者。 - 主动工具结果裁剪不理会这道门。 它为了省 token 会丢掉大的工具结果,不需要调模型,而它丢的时候并没有先做检查点——悄悄删掉了这道门本该保护的证据。
两个都修好了。现在门打开时分叉会保留提供者,而宿主会抑制它们的写入和召回(它们在子代理上下文里跑,而不是假装成你)。裁剪也在调用点被暂缓,直到检查点存在为止。
如果你在那次修复之前就打开了门,并且看到子代理第一轮压缩就挂,原因就在这儿——现在值得再试一次。
要不要打开
只需问一个问题:今天的你,压缩过的记录还能找回来吗?
如果答案是“有摘要就够了”,那就保持关闭。它默认关闭,而且 Hermes 自带的提供者没有一个声明检查点 API v2——在没有 v2 提供者的情况下打开这道门,会拦住所有压缩尝试,手动和自动都拦。初始化时会打一条警告并点出当前提供者的名字,每次拒绝也会指明 compression.checkpoint_required 这个键可以关掉它,所以它至少是响亮地失败,而不是悄悄失败。
如果答案是“我们存档了每一段对话,而且这份存档必须完整”,那这道门会把“无声的丢失”变成“大声的停机”,在受监管或长期运行的环境里通常正是你想要的效果。配一个按摘要哈希 upsert 的提供者,同时接受一个事实:压缩行为从“尽力而为”变成“确定性”。
想看更大的图景——一次压缩到底能省回多少窗口、token 都花在哪儿——可以配着上下文 token 优化指南一起读。如果你本来就要升级,v0.23.0 发版页列了这一轮里其它压缩相关的改动,包括可选的后台预写摘要。