Headroom — слой сжатия контекста для AI-агентов

Headroom — слой сжатия контекста для AI-агентов. Он сжимает всё, что агент читает — вывод инструментов, логи, RAG-чанки, файлы и историю диалога — до того, как это попадёт в LLM. Ответы остаются теми же, токенов уходит в разы меньше. Компрессия выполняется локально: ни промпты, ни содержимое файлов никуда не отправляются.

Что умеет

• Библиотека — compress(messages) на Python или TypeScript, встраивается в любое приложение.
• Прокси — headroom proxy --port 8787, ноль изменений в коде, работает с любым языком.
• Обёртка агентов — headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|... одной командой, откат через headroom unwrap <tool>.
• MCP-сервер — инструменты headroom_compress, headroom_retrieve, headroom_stats для любого MCP-клиента.
• Кросс-агентная память — один общий стор для Claude, Codex, Gemini и Grok с автоматической дедупликацией.
• headroom learn — разбирает неудачные сессии и пишет коррекции в CLAUDE.local.md (по умолчанию, gitignored), CLAUDE.md, AGENTS.md, GEMINI.md или GROK.md.
• Сокращение выходных токенов — урезает не только то, что отправляется модели, но и то, что она пишет обратно.
• Обратимость (CCR) — оригиналы кешируются локально и достаются по запросу.

Как работает

 Ваш агент / приложение
   (Claude Code, Cursor, Codex, LangChain, Agno, ваш код…)
        │   промпты · вывод инструментов · логи · RAG · файлы
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Headroom   (работает локально — данные не уходят)  │
    │  CacheAligner  →  ContentRouter  →  CCR             │
    │                    ├─ SmartCrusher   (JSON)         │
    │                    ├─ CodeCompressor (AST)          │
    │                    └─ Kompress-v2-base (текст, HF)  │
    │  Кросс-агентная память · headroom learn · MCP       │
    └────────────────────────────────────────────────────┘
        │   сжатый промпт  +  инструмент поиска
        ▼
 LLM-провайдер  (Anthropic · OpenAI · Bedrock · …)

• ContentRouter определяет тип контента и выбирает компрессор.
• SmartCrusher / CodeCompressor / Kompress-v2-base обрабатывают JSON, исходный код и прозу соответственно.
• CacheAligner помечает волатильный контент, который сломал бы KV-кеш провайдера. Промпты он никогда не переписывает.
• CCR хранит оригиналы локально, чтобы модель могла вызвать headroom_retrieve, когда нужен полный текст.

Быстрый старт (60 секунд)

# 1 — Установка
uv tool install --python 3.13 "headroom-ai[all]"  # CLI в изолированном окружении
pip install "headroom-ai[all]"                    # Python — включает CLI
npm install headroom-ai                           # только TypeScript SDK, без CLI

# 2 — Выбор режима
headroom deploy                         # локальное развёртывание + конфиг агента
headroom wrap claude                    # обернуть кодинг-агента
headroom proxy --port 8787              # drop-in прокси, ноль изменений кода
# или: from headroom import compress     # встроенная библиотека

# 3 — Проверка и экономия
headroom doctor                         # health check — подтверждает маршрутизацию
headroom perf
headroom dashboard                      # live-экономия (нужен запущенный прокси)

Встраивание на Python:

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

headroom wrap запускает локальный прокси, устанавливает Serena для семантической навигации по коду и запускает агента с маршрутизацией через Headroom. Serena регистрируется на уровне пользователя (для Claude Code — в ~/.claude.json), поэтому остаётся доступной в других проектах до headroom unwrap. Отключить можно флагом --code-memory none.

CLI поставляется только в PyPI-пакете. npm-пакет headroom-ai — это TypeScript SDK (import { compress } from 'headroom-ai'), без команды headroom.

Доказательства

Четыре сценария на реальных форматах вывода MCP-серверов, замерено токенизатором провайдера:

Экономия растёт с повторяемостью данных. Повторяющиеся JSON-массивы и строки логов дают больше 90% в benchmarks/bench_latency.py; проза и уже плотный вывод сжимаются слабо. Точную цифру для своего трафика покажет headroom savings.

Сжатие стоит значительно меньше миллисекунды — 0,21 мс p50 на JSON-результате поиска в 10K токенов, 1,4 мс на 100K токенов — и не влияет на задержку агента.

Точность на python -m headroom.evals suite --tier 1:

При N=100 дельта ±0.03 попадает в доверительный интервал, так что на TruthfulQA разница не обнаружима, а не является улучшением.

Сокращение выходных токенов

Всё вышеперечисленное уменьшает отправляемый промпт. Но вы платите и за каждый токен, который модель пишет обратно — а на моделях уровня Opus вывод стоит в 5 раз дороже ввода. Большая часть этого вывода — церемонии: преамбулы «Great, let me…», перепечатанный код и глубокое рассуждение над рутинными шагами.

Headroom урезает это на прокси, без изменений в вашем коде:

• Управление многословием — добавляет короткую заметку «будь кратким, не повторяй контекст» в конец системного промпта, чтобы кеш промпта продолжал попадать.
• Маршрутизация усилий — снижает усилия на размышление, когда ход — это лишь продолжение после результата инструмента (чтение файла, прошедший тест). Новые вопросы и ошибки сохраняют полные усилия.

export HEADROOM_OUTPUT_SHAPER=1     # выключено по умолчанию
headroom proxy --port 8787

Экономия на выводе контрфактична — Headroom не видит, что модель написала бы — поэтому отчёт идёт с оценкой и доверительным интервалом:

headroom output-savings
# Reduction: 31.7%  (95% CI 27.7% … 35.7%)   [estimated]

Для измеренной цифры отложите 10% диалогов как контрольную группу: export HEADROOM_OUTPUT_HOLDOUT=0.1.

Совместимость с агентами

Любой OpenAI-совместимый клиент работает через headroom proxy. MCP-нативные клиенты: headroom mcp install. Долговременная обёртка снимается командой headroom unwrap <tool>.

Когда использовать, а когда пропустить

Подходит, если вы ежедневно работаете с кодинг-агентами и хотите экономить без изменений в коде, работаете с несколькими агентами и нужна общая память, или нужна обратимая компрессия — оригиналы остаются доступны через CCR в течение настроенного TTL.

Пропустите, если вам хватает нативной компакции одного провайдера и не нужна кросс-агентная память, или вы работаете в песочнице, где нельзя запускать локальные процессы.

Headroom окупается на длинных сессиях с тяжёлым выводом инструментов. Короткие разговорные обмены, проза и уже плотные данные сжимаются слабо, а блоки меньше min_input_words возвращаются байт-в-байт.

Интеграции

Что внутри

• SmartCrusher — универсальный JSON: массивы словарей, вложенные объекты, смешанные типы. Сохраняет элементы с ошибками, значения вне статистического диапазона и первую/последнюю границы — отбор по статистике дисперсии полей, а не по списку ключевых слов.
• CodeCompressor — AST-ориентированный для Python, JS/TS, Go, Rust, Java, C/C++ и Perl.
• Kompress-v2-base — HuggingFace-модель, обученная на агентных трейсах.
• Сжатие изображений — 40–90% сокращения через обученный ML-роутер.
• Live-zone компрессия — сжимаются только новые байты (свежий вывод инструментов, последний ход). Замороженный префикс остаётся байт-в-байт идентичным, поэтому кеш провайдера выживает, а история никогда не теряется.

Установка и лицензия

uv tool install --python 3.13 "headroom-ai[all]"  # CLI, изолированное окружение
pip install "headroom-ai[all]"                    # Python, всё включено — и CLI
npm install headroom-ai                           # TypeScript SDK (только библиотека)
docker pull ghcr.io/headroomlabs-ai/headroom:latest

Требуется Python 3.10+. Гибкие экстра: [proxy], [mcp], [ml] (Kompress-v2-base), [code], [memory], [vector], [image], [langchain], [agno] и другие. Обновление — headroom update.

Телеметрия: анонимный beacon включён по умолчанию — передаёт только метрики сжатия (коэффициенты, счётчики, ID провайдера и модели, ОС и архитектуру). Никогда не отправляет промпты, ответы, код или пути к файлам. Отключение: HEADROOM_BEACON=off, DO_NOT_TRACK=1 или --offline.

Лицензия — Apache 2.0. Всё в репозитории остаётся открытым; управляемое предложение для команд — отдельный продукт.