headroom

Headroom — это слой сжатия контекста для агентов ИИ. Он сжимает всё, что читает агент — выводы инструментов, логи, фрагменты RAG, файлы и историю диалогов — прежде чем они достигнут LLM, с целью сохранить ответы неизменными при снижении расхода токенов. Сжатие выполняется локально; промпты и содержимое файлов не отправляются elsewhere для сжатия. Возможности: - Библиотека: `compress(messages)` на Python или TypeScript, пригодна для inline‑использования в любом приложении. - Прокси: `headroom proxy --port 8787` — локальный прокси «под ключ», не требующий изменений кода и работающий с любым клиентом, совместимым с OpenAI. - Обёртка‑агент: `headroom wrap` поддерживает Claude Code, Codex, Grok CLI, Cursor, Aider, Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe, Oh My Pi, Kimi CLI, ZCode и др.; `headroom unwrap` отменяет настройку. - MCP‑сервер: предоставляет инструменты `headroom_compress`, `headroom_retrieve` и `headroom_stats` для любого MCP‑клиента. - Кросс‑агентная память: общий deduplicated‑хранилище между Claude, Codex, Gemini и Grok. - `headroom learn`: анализирует неудачные сессии и записывает исправления в `CLAUDE.local.md` (по умолчанию, gitignored) или в другие файлы инструкций агентов. - Сокращение выходных токенов: опциональное управление verbosity и маршрутизацией усилий на стороне прокси для уменьшения токенов, которые модель пишет обратно, а не только тех, что отправляются. - Обратимое сжатие (CCR): оригиналы кэшируются локально и извлекаются по требованию через `headroom_retrieve`. Как это работает: ContentRouter определяет тип контента и выбирает компрессор — SmartCrusher для JSON, CodeCompressor (AST‑aware, поддерживающий Python, JS/TS, Go, Rust, Java, C/C++, Perl) и Kompress-v2-base (модель Hugging Face, обученная на agente‑трассах) для прозы. CacheAligner помечаетvolatile‑контент, который мог бы сломать префикс KV‑кеша провайдера без переписывания промптов; live‑zone сжатие сохраняет замороженный префикс байт‑в‑байт идентичным, чтобы кеши провайдера оставалися действительными. Предоставлены адаптеры фреймворков для Anthropic/OpenAI SDKs, Vercel AI SDK, LiteLLM, LangChain, Agno, Strands, ASGI‑приложений и multi‑agent SharedContext. В README приведены результаты офлайн‑бенчмарков: экономия 21 % при поиске кода, 57 % при отладке инцидентов SRE, 42 % при исследовании кодовой базы и 30 % при triage‑оценке GitHub‑issues; повторяющиеся payloads JSON/логов дают до 90 % сокращения. Задержка сжатия составляет значительно меньше миллисекунды при 10K токенов. Оценки точности в README показывают отсутствие заметной разницы на GSM8K и TruthfulQA, а также 97 % на SQuAD v2 и BFCL при сжатии 19–32 %. Установка: `uv tool install --python 3.13 "headroom-ai[all]"`, `pip install "headroom-ai[all]"`, `npm install headroom-ai` (только TypeScript SDK, без CLI) либо образ Docker `ghcr.io/headroomlabs-ai/headroom`. Требуется Python 3.10+; лицензия Apache 2.0. Гранулярные extras включают `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[vector]`, `[image]` и адаптеры фреймворков.