billion-context — прокси сжатия контекста: одна сессия агента на миллиарды токенов

billion-context — это прокси, который встаёт между агентом для написания кода и API модели. Он ничего не знает про конкретный агент: подходит любому клиенту, который говорит по протоколу Anthropic или OpenAI. Заявленные характеристики: окна в 100 тысяч токенов хватает, токенов уходит в пять раз меньше, а одна сессия живёт месяцами и прокручивает миллиарды токенов.

Зачем это нужно

Долгая работа агента раздувает контекст. Каждый провайдер берёт деньги за каждый токен, а когда контекстное окно переполняется, сессия начинает работать хуже или обрывается совсем. Подход billion-context такой: превращать уже прочитанную часть беседы в многослойные пересказы. Контекстное окно не обрезается, а продолжает работать.

Отличие от встроенных сжимателей, которые есть у самих агентов: сжатие здесь добавочное, обратимое и не ломает кэш префикса. Пересказы пишутся небольшими кусками, их можно развернуть обратно по требованию, а префикс кэша остаётся целым.

Что намерили

К проекту прилагается открытая научная работа — описание подхода и результаты долгого использования в бою: 4,5 месяца, три машины, 174 327 вызовов модели, 18,76 миллиарда входных токенов, ни одного выхода за окно на моделях в 204 800 токенов и марафонские сессии от 8 584 до 12 049 вызовов. Работа лежит в коде под лицензией MIT и её можно править через pull request.

Как это работает

Агент (Claude Code / Codex / OpenCode / Aider ...)
        │  вы направляете базовый адрес агента на прокси
        ▼
┌─────────────────┐
│  billion-context│   1. разбирает запрос (формат Anthropic или OpenAI)
│     прокси       │   2. прогоняет беседу через сжатие acp-kernel
│                 │   3. добавляет инструмент compress и правила сжатия
│                 │   4. отправляет запрос настоящему API модели
│                 │   5. переписывает потоковый ответ
└─────────────────┘
        │
        ▼
   настоящий API модели (Anthropic / OpenAI / совместимый)

Само сжатие делает acp-kernel. Важная деталь: решает модель. Она сама выбирает, когда и что сжимать, и пишет подробный пересказ. Жёсткого правила «обрезать всё после N токенов» тут нет.

Четыре инструмента работы с контекстом

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

Три способа подключить агента

Вариант 1 — родной плагин

Самый родной способ: billion-context становится плагином внутри агента. Ставится один раз, дальше агент запускается как обычно — без лаунчер-команды, переменных окружения, портов и правки адресов.

bili plugin install pi          # registers a plugin entry in pi
bili plugin install omp         # registers an extensions entry in omp's config.yml
bili plugin install opencode    # registers the plugin and disables native auto-compaction
bili plugin install claude      # managed settings block + SessionStart hook
bili plugin remove <client>     # undo, configs snapshotted to .bili-bak

Так поддерживаются pi, omp, opencode (1.x и 2.x), dsh, kimi, hermes и zcode. Для Claude Code есть отдельный путь через маркетплейс плагинов:

/plugin marketplace add ranxianglei/billion-context
/plugin install billion-context@billion-context

Вариант 2 — лаунчер

Одна команда поднимает прокси на отдельном порту и запускает агент уже через него. Настоящие файлы настроек агента при этом не меняются: прокси только читает их, чтобы понять, к каким HTTPS-хостам ходит клиент, и подставляет адрес через переменные окружения и сертификаты.

bili claude      # Claude Code
bili codex       # OpenAI Codex
bili opencode    # OpenCode 1.x and 2.x
bili gemini      # Gemini CLI
bili qwen        # Qwen Code
bili aider       # Aider

Полный список клиентов длинный: pi, codex, claude, omp, opencode, hermes, dsh, codebuddy, qoder, trae, jcode, kimi, gemini, iflow, qwen, antigravity, mcode, aider, copilot, amp, goose.

Вариант 3 — правка адреса

Самый универсальный способ: запустить прокси и добавить к базовому адресу клиента префикс /bili/.

bili

базовый адрес до:    https://api.openai.com/v1
базовый адрес после: http://localhost:8787/bili/https://api.openai.com/v1

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

Установка

npm install -g billion-context --prefix=~/.local

Команда bili попадает в ~/.local/bin — в большинстве дистрибутивов этот каталог уже в PATH. Если нет, добавьте строку в ~/.bashrc или ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

bili-proxy остаётся как псевдоним. На nvm и на Node из Homebrew префикс и так пользовательский — там подойдёт обычный npm install -g billion-context. На Windows дефолтный префикс тоже доступен для записи, команда та же. Префикс от root, на который npm ругается ошибкой EACCES, лечится ровно этой установкой с --prefix=~/.local, а не через sudo.

Проверка, что всё работает

Сначала убедитесь, что прокси отвечает и знает, куда пересылать:

curl -s http://localhost:8787/__bili/health
# → {S0:true,S1:S2}

После первого настоящего запроса доступна статистика живой сессии:

curl -s http://localhost:8787/__bili/stats

Дальше отправьте одно сообщение из агента и посмотрите журнал. По умолчанию он лежит в ~/.local/state/billion-context/bili.log и дублируется в stderr. Вы должны увидеть строку processTurn на каждый запрос, а когда беседа подрастёт — строку вида [acp-usage] round N input=X cached=Y (cache hit Z%) и событие compress.

Веб-интерфейс на http://localhost:8787 показывает сводку, список сессий с подробностями, живые логи, редактор конфига и проверку связи с провайдером. Те же данные отдаются в JSON: /__bili/stats, /__bili/sessions, /__bili/config.

Сжатие и кэш префикса

Сжатие срабатывает не по абсолютному размеру окна, а по приросту: по умолчанию мягкое сжатие срабатывает каждые 50 тысяч токенов сверх стартового содержимого. Порог настраивается через compress.nudgeGrowthTokens. Дополнительно есть предпроверка — если один только вход уже больше окна, сжатие включается жёстко.

Отсюда ответ на частый вопрос: почему первое сжатие приходит так поздно, иногда ближе к 200 тысячам. Если стартовое содержимое занимает около 100 тысяч, первая мягкая граница просто не наступит раньше. Лечится тремя способами: подрезать системный промпт и отключить ненужные инструменты, опустить compress.nudgeGrowthTokens до 50 тысяч, включить экономный режим.

Кэш префикса — главный показатель здоровья системы. В здоровой сессии он срабатывает в 95–97%, а само сжатие отнимает не больше двух процентов. Проверить это можно прямо в агенте командой /acp-cache: она печатает разбор, где видно, что именно сбросило кэш. Частые причины по порядку: истёк срок жизни кэша у провайдера, смена модели, ошибка в самом прокси, что-то ещё. Отдельным блоком отмечается смена ключа доступа — когда один и тот же адрес отдаёт запросы от разных аккаунтов.

В клиентах с родным плагином команда /acp показывает панель состояния прямо из прокси: сессия, блоки, какие диапазоны ещё сжимаются, расход контекста.

Сессии и их идентификация

Прокси определяет сессию по значению, которое клиент сам передаёт в запросе, — без хэширования и без привязки к протоколу или ключу API. Идентификатор остаётся внутри прокси и наверх не отправляется. Взять его можно из служебного заголовка плагина, из клиентских заголовков вроде x-claude-code-session-id или x-opencode-session-id, а если их нет — из поля session_id или prompt_cache_key в теле запроса.

Если клиент не передаёт ничего (например, pi в базовом режиме), прокси опознаёт сессию по самой истории: запрос возвращается к сохранённой сессии только если воспроизводит её цепочку сообщений побайтово с нуля. Практический вывод: продолженная беседа вернётся к своей сессии, а новая задача с тем же самым началом не унаследует чужие блоки.

Дочерние сессии — субагенты и форки — сообщают о своём происхождении при рождении. Прокси записывает связь только на чтение, и развёртывание свёрнутого куска и поиск по контексту при необходимости идут по цепочке родителей. Глубина ограничена восемью уровнями.

Что стоит учесть

• Проект молодой. Работа с протоколами и сжатие покрыты мок-тестами (500+ проходящих), тесты с настоящими моделями — следующая цель. Ожидайте шероховатостей.
• Двойное сжатие. Родные плагины и отдельные расширения (billion-context-pi, opencode-acp) исключают друг друга. Если активны оба, сжатие сработает дважды. Установщик сам меняет записи в конфиге и сохраняет копию в .bili-bak.
• Обновление. Прокси проверяет npm при старте и каждые три минуты, ставит новую версию на место, но перезапустить его нужно вручную. Флаг --auto-restart-on-update включает автоматический перезапуск.
• Аутентификации нет. По умолчанию прокси слушает только 127.0.0.1. Флаг --host 0.0.0.0 открывает доступ другим машинам — включайте его только в доверенной сети или за файрволом.
• Windows. Антивирус и индексатор умеют блокировать каталог сессий во время записи. Добавьте %USERPROFILE%\.local\share\billion-context\ в исключения.
• Лицензия. MIT плюс одно дополнительное условие: продукт, чьими пользователями могут пользоваться или взаимодействовать другие, должен указать использование billion-context со ссылкой на репозиторий на главной странице, в документации или в разделе About/Credits.

Что почитать дальше

• CLIENTS.md — как подключается каждый клиент, что куда пишется и какие ограничения есть у каждого.
• CONFIGURATION.md — полный справочник настроек: ключи, провайдеры, настройка сжатия, переменные окружения.
• TECHNICAL-NOTES.md — механика трёх способов подключения: жизненный цикл плагина, протокол runtime-info, порядок внедрения.
• SESSION-IDENTITY.md — дизайн идентификации сессии и модель угроз.
• acp-kernel — ядро, которое делает само сжатие.
• LICENSE — текст MIT и дополнительного условия.