Headroom — это слой сжатия контекста для AI-агентов, который перехватывает всё, что агент собирается отправить в LLM (tool outputs, логи, RAG-чанки, файлы, историю переписки), сжимает это локально и только потом пускает дальше. Результат: те же ответы, в разы меньше токенов.
Вот реальные цифры с агентских задач:
| Задача | До | После | Экономия |
|---|---|---|---|
| Code search (100 результатов) | 17 765 | 1 408 | 92% |
| Отладка SRE-инцидента | 65 694 | 5 118 | 92% |
| Триаж GitHub Issues | 54 174 | 14 761 | 73% |
| Исследование кодовой базы | 78 502 | 41 254 | 47% |
При этом бенчмарки не проседают: GSM8K остаётся 0.870, TruthfulQA даже чуть подрастает, SQuAD v2 и BFCL держат 97% при 19–32% сжатии.
Как это устроено внутри
Внутри Headroom три ключевых компонента:
- ContentRouter — определяет тип контента и выбирает подходящий компрессор
- SmartCrusher / CodeCompressor / Kompress-base — сжимают JSON, AST и обычный текст соответственно
- CacheAligner — стабилизирует префиксы промптов, чтобы KV-кеш провайдера работал эффективно
- CCR (reversible compression) — оригиналы кешируются локально; LLM может запросить их через
headroom_retrieve, если они понадобятся
Всё работает на твоей машине — данные никуда не улетают.
Четыре режима работы
- Библиотека —
compress(messages)в Python или TypeScript, вставляешь прямо в свой код - Прокси —
headroom proxy --port 8787, без изменений в коде, для любого языка - Обёртка агента —
headroom wrap claude|codex|cursor|aider|copilot|opencodeодной командой - MCP-сервер — инструменты
headroom_compress,headroom_retrieve,headroom_statsдля любого MCP-клиента
Быстрый старт
# Установка
pip install "headroom-ai[all]" # Python
npm install headroom-ai # Node / TypeScript
# Запуск
headroom wrap claude # обернуть агента
headroom proxy --port 8787 # прокси без изменений в коде
# Посмотреть экономию
headroom perf
headroom dashboard
Требуется Python 3.10+.
Бонус: режет и выходные токены
Кроме сжатия того, что ты отправляешь, Headroom умеет укорачивать и то, что модель пишет в ответ — а на Opus-class моделях выходные токены стоят в 5 раз дороже входящих.
Два механизма:
- Verbosity steering — дописывает в конец системного промпта короткую инструкцию «отвечай лаконично, не пересказывай контекст» (кеш промпта при этом не ломается)
- Effort routing — если модель просто продолжает работу после tool result (прочитала файл, тест прошёл), thinking effort снижается; на новые вопросы и ошибки по-прежнему идёт полный режим
Ещё из полезного: кросс-агентная память с авто-дедупликацией между Claude, Codex и Gemini, и headroom learn — инструмент, который анализирует упавшие сессии и записывает поправки в CLAUDE.md / AGENTS.md.