Hermes 上下文压缩架构：长任务 Agent 不失忆的几个关键设计

原创于 2026-07-21 16:01:36 发布 · 146 阅读

4 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

AI 时代程序员必备技能

Codex、Claude Code、Cursor、Hermes Agent、OpenClaw等工程化实战专栏，讲透 AI 如何接管脏活累活

一键订阅

拆解 Hermes 如何用触发器、边界算法和 handoff 摘要，让长任务 Agent 在压缩后继续可靠执行。

长任务 Agent 最容易坏在一个很不起眼的地方：它不是没能力继续推理，而是已经看不完整自己刚才做过什么。

一次真实的工具型会话里，系统提示、历史消息、工具调用、终端输出、文件读取结果、截图、代码片段都会在每一轮重新塞回模型。窗口没满时，模型已经开始丢约束、重复读文件、重新推导旧决策；窗口真正溢出时，请求会直接被 provider 拒掉。Hermes 的上下文压缩机制，就是为了解这个问题。

它处理的不是长期记忆。MEMORY.md、USER.md、memory provider 负责跨会话事实；上下文压缩只管理当前会话的工作窗口。这个边界很重要，因为压缩天然有损，不能拿它替代真正的记忆系统。

图：上下文压缩只整理当前工作窗口，长期事实仍应进入 memory 层

ContextEngine：把上下文管理做成可替换引擎

Hermes 没把压缩逻辑写死在主循环里，而是抽象成 agent/context_engine.py 里的 ContextEngine。内置实现是 ContextCompressor，插件也可以接管整套上下文管理，比如换成无损上下文管理 LCM。

引擎选择由 config.yaml 的 context.engine 控制。插件不会自动启用，必须显式配置；没有匹配插件时，系统回退到内置 ContextCompressor。

图：上下文管理引擎的配置选择与回退路径

这层设计让压缩从“一个功能”变成了“一个策略接口”。主循环只关心什么时候问引擎、什么时候拿回新的消息列表，不必知道具体是 LLM 摘要、无损索引，还是别的上下文管理方案。

双层压缩：Gateway 兜底，Agent 主压缩

Hermes 有两道压缩线，位置和目的都不同。

第一道在 gateway，属于会话检查。它在 Agent 开始处理消息之前运行，阈值固定在 85%。它不是日常压缩主力，主要兜住隔夜会话、群聊积压、外部通道疯狂灌消息这类情况。

第二道在 Agent 内部，也就是 ContextCompressor。它运行在工具循环里，默认 50% 阈值，优先使用 provider 返回的真实 prompt_tokens。这是日常上下文管理的核心。

图：Gateway 兜底与 Agent 主压缩的分工

维度	Gateway 会话卫生	Agent 压缩器
触发阈值	固定 85%	默认 50%，可通过 `compression.threshold` 配置
运行位置	Agent 处理前	Agent 工具循环内部
token 来源	上轮真实 token，缺失时用字符估算	provider 返回的真实 `prompt_tokens` 优先
主要目标	防止超大会话直接打挂请求	常规上下文管理
额外保护	`hygiene_hard_message_limit`
默认 5000 条	防抖、边界对齐、会话锁、摘要失败降级

阈值错开不是随便定的。gateway 如果也按 50% 触发，长会话会在很多轮里提前压缩，成本高，信息损耗也大。它只应该接管那些 Agent 压缩器没来得及处理的异常会话。

三个触发器：预检、响应后、错误恢复

ContextCompressor 不是等 API 报错才行动。一次 turn 内，它有三个入口。

图：预检、响应后与错误恢复三类压缩入口

Preflight：请求发出前的廉价拦截

预检压缩位于 agent/turn_context.py 的 build_turn_context。它先跑一个便宜判断：消息数量是否已经超过保护头尾的安全范围，或者字符粗估是否已经很大。只有通过这个门控，才会做更贵的 token 粗估。

这里有两个细节容易被忽略。

第一，粗估必须把 tool schemas 算进去。工具一多，schema 本身就可能占 20K 到 30K token；只估 messages 会低估请求体。

第二，Hermes 会用 should_defer_preflight_to_real_usage() 抵抗 schema-heavy 请求的噪声。如果上一次压缩后的真实 token 已经证明请求能装下，就不要被同一批 schema 的粗估反复吓到。

Post-response：用真实 prompt token 做日常决策

响应后压缩位于 agent/conversation_loop.py。它在模型响应回来、工具结果追加后执行，是最常见的压缩路径。

核心逻辑可以简化成这样：

_compressor = agent.context_compressor

if _compressor.last_prompt_tokens > 0:
    real_tokens = _compressor.last_prompt_tokens
elif _compressor.last_prompt_tokens == -1:
    real_tokens = 0
else:
    real_tokens = estimate_request_tokens_rough(messages, tools=...)

if agent.compression_enabled and _compressor.should_compress(real_tokens):
    messages, active_system_prompt = agent._compress_context(...)

它只看 prompt_tokens，不把 completion_tokens 算进触发条件。原因很实际：推理模型的 reasoning token 可能很大，如果 completion 也参与判断，会让会话还没真正挤占输入窗口就过早压缩。

last_prompt_tokens == -1 是一个哨兵值。压缩刚结束时，系统还没拿到下一轮 provider 的真实 usage，此时把 token 视为 0，避免刚压完就被 schema 粗估拉回压缩循环。

Error recovery：窗口真的炸了再强制抢救

provider 返回 413、context overflow，或 Anthropic 长上下文层的 429 时，Hermes 会进入错误恢复压缩。它会降级 context 设置并强制压缩重试，最多 max_compression_attempts=3 次。

这条路径不是主流程，而是保险丝。真正健康的会话应该靠预检和响应后压缩解决，大部分时候不该走到 provider 报错这一步。

阈值计算：不是窗口乘百分比

很多上下文压缩实现会直接用 context_length × threshold。Hermes 没这么做。

它先从窗口里扣掉 max_tokens，因为输出空间也占 provider 给的总窗口。输入预算应该是：

effective_window = context_length - (max_tokens or 0)

完整逻辑大致如下：

@staticmethod
def _compute_threshold_tokens(
    context_length: int,
    threshold_percent: float,
    max_tokens: int | None = None,
) -> int:
    effective_window = context_length - (max_tokens or 0)
    if effective_window <= 0:
        effective_window = context_length

    pct_value = int(effective_window * threshold_percent)
    floored = max(pct_value, MINIMUM_CONTEXT_LENGTH)

    if effective_window > 0 and floored >= effective_window:
        return max(
            1,
            min(
                int(effective_window * ContextCompressor._MIN_CTX_TRIGGER_RATIO),
                effective_window - 1,
            ),
        )
    return floored

这段代码同时解决了几个问题。

第一，给输出预留空间。自定义 provider 如果把 max_tokens 配到 65536，输入预算会明显变小，不扣掉它就容易撞。

第二，大窗口模型不应该太早压。MINIMUM_CONTEXT_LENGTH=64K 让大上下文模型不会因为 50% 阈值就频繁压缩。

ContextCompressor：先剪枝，再摘要，最后重组

ContextCompressor.compress() 的目标不是把历史消息简单截断，而是把会话改造成三段：

保护头 + 结构化摘要 + 原样保留的尾部消息

压缩过程分四步。

图：先剪枝、再摘要、最后重组消息窗口

旧工具结果先做无损味道的降噪

第一阶段不调用模型，只做工程剪枝。保护尾之外的长工具输出会被压成信息化的一行，而不是丢成空占位。

[terminal] ran `npm test` -> exit 0, 47 lines output
[read_file] read config.py from line 1 (3,400 chars)

这一步有三遍扫描：

Pass	处理内容	为什么需要
Pass 1	重复文件读取去重，只保留最近全文	同一个文件被反复 read 时，旧副本没有必要继续占窗口
Pass 2	长工具结果缩成一行，截图剥离 base64	防止旧终端输出和旧截图永久拖累每轮请求
Pass 3	截断超大 tool_call 参数，但保持 JSON 合法	避免坏 JSON 毒化后续 provider 请求

这个阶段看起来朴素，却很值。很多上下文膨胀来自工具结果，而不是用户真正说了多少话。先用确定性规则降噪，可以减少后面 LLM 摘要的压力。

图：旧工具输出先被结构化压缩，降低后续摘要负担

边界算法：压缩不能切坏消息结构

压缩边界是这套机制里最有工程味的部分。它既要尽量多压，又不能把 tool call 组切坏，不能把最新用户任务卷进摘要，也不能让早期头部无限增长。

保护头只在第一次压缩时保护首轮任务框架

protect_first_n 默认保护最初几条非系统消息，让首次任务设定活过第一次压缩。但这份保护会衰减：

if self.compression_count >= 1 or self._previous_summary:
    return 0
return self.protect_first_n

原因很直接：第一次压缩后，早期任务框架已经进入 handoff 摘要。如果后续每次还保护前几条老消息，它们会变成“不朽消息”，在每个子会话里反复复制，头部无界增长。

系统提示不参与这个衰减。它由 _protect_head_size() 单独保护，始终保留。

尾部优先按 token 预算保护

尾保护不是简单保留最后 N 条消息，而是优先按 token 预算从尾往前切：

图：按 token 预算保护活跃任务尾部

这里的关键不是“保留最后 20 条”这种固定规则，而是让最近活跃任务在 token 意义上尽量完整。尾部只会增大，不会缩小：最近一条 user 消息必须在尾里，最近一条有文字内容的 assistant 回复也必须在尾里。

tool_call 配对要么一起压，要么一起留

OpenAI 消息格式要求 assistant tool_call 后面紧跟匹配的 tool 结果。压缩切边界时如果切进工具组中间，后续请求会报错。

Hermes 用两道防线处理这个问题。

第一道是边界对齐。边界落在 tool results 组里时，_align_boundary_backward() 会往前找到父 assistant 消息，让 assistant + tool_results 整组进入同一侧。

第二道是重组后的清理。_sanitize_tool_pairs() 会扫描还活着的 tool call id 和 tool result id：

图：孤儿 tool result 删除与缺失结果补桩

缺 result 的 tool call 会补一个类似 [Result from earlier conversation...] 的桩结果。它不假装还原历史内容，只保证 provider 消息结构合法。

结构化摘要：给续作看的 handoff，不是新指令

摘要阶段由 _generate_summary() 执行，使用辅助模型 call_llm(task="compression")。它不是让模型写一段“简短总结”，而是强制填一份 handoff 模板。

典型字段包括：

字段	保存什么	作用
`Historical Task Snapshot`	最近未完成用户输入的逐字原话	防止旧任务在压缩后变形
`Goal`	总体目标	保留会话主线
`Constraints & Preferences`	约束、偏好、编码风格	减少压缩后违反硬要求
`Completed Actions`	已完成动作、目标、结果、工具	避免重复做已完成工作
`Active State`	工作目录、分支、改动文件、测试状态、进程	支撑继续接手
`Blocked`	阻塞点和精确报错	防止重新踩同一个坑
`Key Decisions`	技术决策和原因	保留设计判断
`Resolved Questions`	已回答问题	防止重复解释
`Relevant Files`	读过、改过、创建过的文件	续作时定位上下文
`Critical Context`	精确配置值、报错、关键事实	抢救容易丢的细节

摘要前缀里有一条很重要的约束：这是一段来自旧 context window 的参考材料，不是当前用户指令。模型只应该响应摘要之后的新用户消息。

摘要尾部也有明确边界：

--- END OF CONTEXT SUMMARY — respond to the message below, not the summary above ---

这不是形式主义。压缩摘要里经常包含用户旧请求的逐字引用，弱模型可能把它当成新的待执行命令。Hermes 通过前缀、尾标记、时间锚定和过去时改写，把“历史事实”和“当前指令”分开。

图：handoff 摘要提供历史参考，但不应变成新的指令

多次压缩靠 previous summary 迭代更新

长会话可能压缩很多次。Hermes 不会每次只总结当前中段，而是把上一版摘要作为 PREVIOUS SUMMARY 一起交给辅助模型，让它更新而不是重写。

图：previous summary 在多次压缩中迭代更新

这样旧项目状态会从 in progress 移到 completed，新阻塞会被加入，过时内容会被删掉。resume 场景下，压缩器还会从当前消息里找最近的 handoff 摘要，恢复 _previous_summary。

跨会话泄漏也做了防护。如果内存里有 _previous_summary，但当前消息列表找不到对应 handoff，说明它可能来自已经结束的会话，压缩器会丢弃这份摘要。

摘要模型窗口：压缩质量最常见的暗坑

摘要模型的 context window 必须不小于主模型。原因很简单：被压缩的中段会一次性发给辅助模型。

如果辅助模型窗口比主模型小，摘要调用可能直接 context-length 错误。更麻烦的是，在默认降级路径下，压缩器可能用 fallback 摘要继续推进，中段细节就真的丢了。

Hermes 用 check_compression_model_feasibility 在会话开始或首次压缩时探测辅助模型可行性。实际配置时，最稳的方式还是显式选择窗口足够大的压缩模型：

auxiliary:
  compression:
    model: <context window 不小于主模型的模型>

摘要预算也不是固定值。它按被压缩内容量动态缩放：

content_tokens = estimate_messages_tokens_rough(turns_to_summarize)
budget = int(content_tokens * _SUMMARY_RATIO)  # 0.20
return max(_MIN_SUMMARY_TOKENS, min(budget, self.max_summary_tokens))

默认下限是 2000 token，上限是 min(context_length × 0.05, 12000)。这给摘要留出足够空间，但不会让摘要本身膨胀成新的上下文负担。

会话存储：轮转与原地压缩的取舍

压缩成功后，Hermes 还要处理 SQLite 里的会话存储。这里有两种模式，由 compression.in_place 控制。

图：原地压缩与会话轮转的落库差异

模式	行为	优点	风险
原地压缩	同一个 `session_id` 下软归档旧 turn，插入压缩后的 active turn	会话身份稳定，少很多轮转边界问题	需要存储层正确支持归档和检索
会话轮转	结束旧 session，创建 parent 指向旧会话的新 session	旧 transcript 保留，便于搜索	fork、回滚、goal 迁移、日志上下文同步都更复杂

配置注释里已经倾向推荐 in_place: true。长任务场景下，同一个 session id 持续存在，心智负担和边界 bug 都少一些。

并发安全靠 state.db 的 session 级压缩锁。两个 Agent 实例共享同一 session 时，只有一个能真正执行压缩；另一个拿不到锁就原样返回，让赢家完成。锁子系统异常时 fail-open，避免会话卡死。

Prompt caching：压缩会打断一部分缓存，但不该打断全部

压缩和 prompt caching 是两套机制，但它们会互相影响。

正常多轮里，system prompt 稳定，前缀缓存命中率高。压缩发生后，中段被重写，压缩区后面的缓存自然失效；但 system prompt 缓存仍然应该活着，尾部三条消息也会在一两轮内重新形成滚动缓存。

图：压缩后 system 缓存保留，滚动缓存重建

失败处理：宁可中止，也不要静默丢上下文

压缩失败不能只当普通异常处理。Hermes 把摘要失败分成几类：

失败类型	处理方式	原因
没配置 provider	长 cooldown 后返回失败	继续重试只会浪费时间
401 / 403	标记认证失败并中止压缩	凭证问题不会靠重试自愈
网络中断	标记网络失败并中止压缩	保留原会话，等网络恢复再压
允许降级的普通失败	插入确定性 fallback 摘要	至少保留连续性锚点
`abort_on_summary_failure=true`	直接中止	用户显式选择保守策略

中止时会设 _last_compress_aborted=True，上层可以向用户提示“会话已冻结，修复后再 /compress 或开新会话”。这比悄悄丢中段安全得多。

防抖也很关键。如果连续两次压缩节省不到 10%，should_compress() 会直接返回 False：

def should_compress(self, prompt_tokens=None) -> bool:
    tokens = prompt_tokens if prompt_tokens is not None else self.last_prompt_tokens
    if tokens < self.threshold_tokens:
        return False
    if self._ineffective_compression_count >= 2:
        return False
    return True

有些会话确实没有多少可压空间，比如尾部全是近期大工具输出。继续压只会空转，防抖能把这种循环停下来。

图片也有专门恢复路径。provider 因图片太大拒绝时，try_shrink_image_parts_in_messages() 会把 base64 图片重新编码到限制以内，再重试请求。旧图片在常规压缩中也会被 _strip_historical_media() 换成文字占位，避免多 MB 媒体长期留在窗口里。

Hermes 与 Claude Code：同一个模式，不同的控制面

Hermes 和 Claude Code 都走“保护头、摘要中段、保留尾”的大方向，但控制面差别很大。

维度	Hermes Agent	Claude Code
实现位置	客户端 `ContextCompressor`	服务端 Compaction API 加客户端配合
可配置性	阈值、尾部比例、保护消息数、辅助模型、原地压缩都可配	用户可调空间较少
触发阈值	Agent 默认 50%，gateway 85%	200K 模型上约 150K input tokens
工具输出处理	在上下文内剪枝、去重、截断	microcompaction 将工具输出落盘，窗口里保留引用
摘要模型	可独立配置辅助模型	主要由服务端 compaction 处理
失败防护	防抖、并发锁、摘要失败分级、fallback	更多由服务端策略接管
续作恢复	handoff 摘要 + session_search + memory provider	摘要 + 重读最近文件 + todo 恢复

两者共同的弱点也很明确：压缩擅长保留叙事连续性，不擅长保证每个精确约束都活下来。第 2 轮说的偏好、第 8 轮确认的配置值、第 12 轮临时加的禁用项，都可能在摘要时被模型认为“不够重要”。

这就是为什么 memory 层不能省。跨压缩、跨会话必须存活的事实，应该在压缩发生前进入 memory provider，而不是寄希望于摘要模型每次都判断正确。

配置建议：先保证不丢，再谈省钱

一个保守但实用的配置可以从这里开始：

compression:
  enabled: true
  threshold: 0.50
  target_ratio: 0.20
  protect_last_n: 20
  in_place: true
  abort_on_summary_failure: false

auxiliary:
  compression:
    model: <context window 不小于主模型的模型>

几条判断比参数本身更重要。

第一，辅助压缩模型窗口必须够大。这比换一个更便宜的摘要模型更重要。

第二，大上下文模型如果主要目标是省钱，可以适当降低 threshold；小窗口模型不用强行调，代码里已经有 85% 的退化保护。

第三，近期任务依赖工具输出和细粒度代码状态时，可以提高 target_ratio 或 protect_last_n。压得狠会省 token，但更容易丢活跃任务细节。

第四，建议开启 in_place。除非你明确依赖旧的会话轮转语义，否则原地压缩更符合长会话的直觉。

第五，看到压缩告警不要忽略。Session compressed N times 说明会话质量可能开始降；Compression skipped 说明窗口里缺少可压空间；Context compression aborted 往往是辅助模型、凭证或网络出了问题。

源码索引

文件	关注点
`agent/context_engine.py`	`ContextEngine`
抽象与生命周期
`agent/context_compressor.py`	压缩主算法、边界对齐、摘要生成、防抖
`agent/conversation_compression.py`	会话压缩落库、原地压缩、会话轮转、模型可行性探测
`agent/turn_context.py`	预检压缩入口
`agent/conversation_loop.py`	响应后压缩与错误恢复压缩
`agent/prompt_caching.py`	Anthropic `system_and_3` 缓存策略
`gateway/run.py`	Gateway 会话卫生安全网
`agent/model_metadata.py`	token 粗估，包含 tool schemas
`agent/auxiliary_client.py`	Codex gpt-5.5 窗口限制与阈值抬升