AI代理不需要更大的上下文窗口

这个仓库将上下文视为一种受管理的资源：压缩、缓存、检索和共享，而不是一个不断增长的提示。

8分钟之内，你将了解Headroom如何将代理上下文减少多达90%，同时不丢失对原始信息的访问。

观看一个编码代理调试生产问题。

它搜索仓库。grep返回1000个结果。它打开日志。5万个token。它读取堆栈跟踪。1万个token。

它实际上需要3个文件、1个堆栈帧、20行日志。大约800个token的信号。

为了得到这些，它消耗了7.7万个token。

这不是模型的问题。如果有正确的800个token，模型会表现很好。问题在于没有人能在信息到达之前过滤掉噪声。

上下文窗口不断增大。但更大的窗口并不能解决这个问题。它们只会让问题更昂贵。

一个拥有20万token上下文窗口的代理，如果其中60%都是无关的日志，它并不会变得更聪明。它只会变得更慢、更昂贵。注意力在7.7万个token上稀释，不如将注意力集中在800个token上可靠。

有一个名为Headroom的开源项目，它位于你的代理和LLM之间，在噪声到达之前就将其压缩。该架构中有一个想法特别值得仔细理解。

大多数压缩是一条单行道

所有现有的解决这个问题的方法都有相同的缺陷：一旦压缩，原始内容就消失了。

总结工具输出并丢弃它，细节就消失了。截断日志文件，模型无法恢复被截断的部分。提供商原生的压缩会折叠对话历史，而且这是不可逆的。

这迫使你面对一个不可能的权衡。激进压缩，冒着丢失重要信息的风险。保守压缩，则留下大部分节省空间的机会。

Headroom的核心架构称为CCR（压缩-缓存-检索），通过使压缩可逆来消除这种权衡。

当内容被压缩时，原始内容会以内容哈希的方式存储在本地缓存中。模型接收压缩版本以及一个名为headroom_retrieve的检索工具。

如果模型需要完整数据，它会调用headroom_retrieve(hash=abc123)，并在1毫秒内获得原始内容。

没有任何东西被永久丢失。你不再需要做出一个单向的决定。模型决定何时需要更多信息。Headroom确保当模型需要时，没有任何信息丢失。

三个压缩器，一个路由器

Headroom的ContentRouter对每个传入的内容进行分类，并将其发送到正确的压缩器。

SmartCrusher处理JSON。

一个返回1000个文件路径的grep结果会被缩减为最相关的20个。它是基于任务上下文进行选择，而不仅仅是按位置截断。

CodeCompressor是AST感知的。

它会移除文档字符串，将函数体折叠为签名，删除注释块。结构骨架保留下来。模型不需要的散文部分被移除。

Kompress-base是Headroom自己的HuggingFace模型，专门在代理痕迹数据上训练，而不是通用网页文本。

通用压缩器在结构化日志和堆栈跟踪上表现不佳，因为它们没有在该分布上训练。而Kompress-base是专门为此训练的。

CacheAligner

第四个组件CacheAligner，稳定提示前缀，使提供商的KV缓存能够实际命中。如果你的前缀结构在每个请求中有轻微变化，你会不断破坏缓存，并在延迟和计算上付出代价。CacheAligner将其标准化。

实际工作负载的数据：代码搜索减少了92%。SRE事件调试减少了92%。GitHub问题分类减少了73%。在GSM8K、TruthfulQA、SQuAD和BFCL上的准确率保持在测量误差范围内。

没有人谈论的功能：headroom learn

仓库中最被低估的东西是headroom learn。

改善代理行为的标准循环是：观察它失败，诊断模式，向CLAUDE.md或AGENTS.md写入修正，重复。这有效。但它完全手动，依赖于人类捕捉每一次失败。

headroom learn自动挖掘失败的会话。

代理卡住、产生错误输出或需要干预的会话。它从失败痕迹中提取模式，并直接将修正写入CLAUDE.md、AGENTS.md或GEMINI.md。

每一次代理失败都成为下一次会话的潜在改进，无需任何人手动提取教训。循环是：失败发生，模式被提取，修正被写入，下一次会话开始时更聪明。

大多数团队仍在运行这个循环的慢速版本。这个工具关闭了循环。

跨代理记忆

Headroom在多个代理之间维护一个共享的压缩记忆存储。

当Claude Code、Codex和Cursor都在同一个代码库上工作时，它们写入并读取同一个存储，自动去重。

上下文重建的token成本是多代理系统中最大的隐藏成本之一。每个代理重新读取相同文件、重新建立相同上下文，都在消耗之前会话中已经花费过的计算资源。

如何使用

安装：

选择你的路径：

零代码更改，作为代理运行：

将任何兼容OpenAI的客户端指向代理而非提供商。其他什么都不用改。

包装一个编码代理：

一个命令实现压缩、跨代理记忆和headroom learn。

在自有管道中内联使用：

通过MCP启用CCR：

这会将headroom_retrieve添加到模型的工具集中。如果没有这一步，压缩仍然是单向的。

它不能解决的问题

CCR只有在模型意识到有信息缺失时才有效。如果压缩版本足够合理，以至于模型没有意识到需要更多信息，重要细节可能会在未触发检索的情况下被悄悄丢失。

缓存增加了本地内存开销。默认TTL为5分钟，采用LRU淘汰策略，对大多数会话来说足够，但在长时间运行或高吞吐量的管道中可能成为瓶颈。

此外，它在工具密集的代理工作负载中表现出色。单轮提示且输入小而紧凑的场景不会获得显著收益。工具输出噪声越大，收益越大。

代理工作负载越来越多地由工具输出而非模型生成的文本组成。随着这些工作负载的增长，挑战从扩大上下文窗口转变为决定哪些内容值得放入窗口。

答案从来不是更大的窗口。而是更智能的窗口。