Headroom MCP
Локальное сжатие контекста для агентов: выводы инструментов, логи, файлы и RAG ужимаются до отправки в LLM. Прокси, CLI, библиотека и MCP
- 78 276 ★ репозитория
- Последний коммит
- Apache-2.0
Широкий доступ
Почему такой уровень
- Весь трафик агента к провайдеру модели идет через локальный прокси вместе с ключами API
- wrap меняет конфигурацию агентов и регистрирует дополнительные MCP-серверы
- learn записывает изменения в CLAUDE.md и AGENTS.md
Установка
- Работает в
Ручная установка
uv tool install --python 3.13 "headroom-ai[all]"Или pip install "headroom-ai[all]". Проверка: headroom doctor.
Доступ и проверки
Как мы проверяемШирокий доступИнструмент может менять данные, выполнять команды или работать с секретами.
- Весь трафик агента к провайдеру модели идет через локальный прокси вместе с ключами API
- wrap меняет конфигурацию агентов и регистрирует дополнительные MCP-серверы
- learn записывает изменения в CLAUDE.md и AGENTS.md
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
Headroom встает между агентом и провайдером модели и сжимает то, что агент читает: JSON, код, логи и обычный текст, для каждого типа свой компрессор. Оригиналы хранятся локально, и модель может запросить полный текст через инструмент headroom_retrieve. Команда headroom wrap запускает прокси и сам агент (Claude Code, Codex, Aider, OpenCode, Goose и другие) уже через него, headroom unwrap все откатывает. Есть MCP-сервер с инструментами сжатия, извлечения и статистики, общая память между агентами, команда headroom learn, которая по неудачным сессиям дописывает поправки в CLAUDE.md или AGENTS.md, и опциональное сокращение ответов модели.
Для кого. Для разработчиков, которые много работают с агентами и хотят тратить меньше токенов на длинные выводы инструментов.
Подходит, если
- Агент тонет в длинных логах, JSON-ответах и результатах поиска
- Хотите снизить расходы на API без изменения кода
- Нужна общая память между Claude Code и Codex
- Собираете свое LLM-приложение и хотите сжимать сообщения библиотекой
Не подходит, если
- Контекст и так короткий и состоит из плотной прозы, выигрыш будет небольшим
- Нельзя пропускать трафик к провайдеру через локальный прокси
Пример запроса к агенту
Покажи, сколько токенов сэкономил Headroom в этой сессииMCP
- Транспорт
- stdio
- Авторизация
- не нужна
Ограничения
Экономия сильно зависит от содержимого: повторяющийся JSON и логи сжимаются хорошо, проза почти нет. CLI есть только в пакете PyPI, npm-пакет это лишь TypeScript-библиотека. wrap по умолчанию регистрирует Serena на уровне пользователя, отключается флагом --code-memory none. Сам Headroom работает локально, но доступ к API Anthropic и OpenAI из России требует VPN.
Как отключить. Выполните headroom unwrap <агент>, чтобы убрать обертку, и удалите пакет командой uv tool uninstall headroom-ai или pip uninstall headroom-ai.
Частые вопросы
Уходит ли содержимое промптов на чужие серверы для сжатия?
Нет, по README сжатие выполняется на вашей машине, оригиналы тоже хранятся локально.
Не испортит ли сжатие ответы модели?
Авторы публикуют прогон на GSM8K, TruthfulQA, SQuAD и BFCL без заметной потери точности, методика есть в документации.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
MCP-серверыЛокальная память для ИИ-агентов программиста: хуки записывают ход каждой сессии, и Claude Code, Codex или Cursor находят прошлые решения через MCP
Локальный слой управления контекстом для кодинг-агентов: понимает задачу, подбирает и сжимает контекст, ведет учет затрат
Скилл, который сокращает текстовые ответы агента, и локальный прокси, сжимающий то, что агент читает
Долговременная память для агентов: удаленный MCP-сервер, плагины для Claude Code, Cursor и Codex и API для своих приложений
MCP-сервер, который держит крупный вывод инструментов вне контекстного окна агента и хранит память сессии в SQLite
Локальное хранилище контекста для кодовых агентов: сохраняет знания о проектах и переиспользует их в Codex, Claude Code и OpenCode
Из блога
Коротко о README
README описывает четыре режима: библиотека compress для Python и TypeScript, прокси headroom proxy, обертка headroom wrap для агентов и MCP-сервер. Сжатие устроено через маршрутизатор по типу контента и отдельные компрессоры для JSON, кода и текста, плюс локальный кэш оригиналов. Приведены воспроизводимые замеры экономии и точности, таблица совместимости с агентами и настройки сокращения ответов модели. Лицензия Apache 2.0.