billion-context — 長期セッション向けコンテキスト圧縮ツール

概要

AI コーディングエージェントを用いた開発では、作業が数日や数週間に及ぶと、会話履歴やツール実行ログの蓄積によってコンテキストウィンドウが急速に圧迫されます。トークン数の増大は API 利用コストの肥大化を招くだけでなく、モデルのコンテキスト制限を超過した際にセッションの継続が困難になるという課題が存在します。

billion-context は、エージェントと LLM の API エンドポイントの間に挟む形で動作するコンテキスト圧縮プロキシおよびプラグインです。ハードリミットによる単純な履歴の切り捨てではなく、モデル自身が状況を判断して不要な部分を折りたたみ、必要なときに復元できる仕組みを提供します。

100K 程度の比較的小さなコンテキストウィンドウのモデルを使いながら、何日も続く同一セッション内で大量のトークンを扱うコーディング作業を行いたい開発者や、API コストを抑えつつエージェントの記憶と文脈を維持したいユーザーに向いています。

主な特徴

モデル主導のインクリメンタル圧縮: 単純な文字数制限によるトランケーションではなく、モデル自身が必要に応じて過去のメッセージ範囲を高精度なサマリーへと折りたたみます。
可逆的なコンテキスト展開: 折りたたんだ過去の要約は必要に応じて元のメッセージへと復元（decompress）できるため、古い履歴の詳細な情報が必要になった場合でも文脈を失いません。
プレフィックスキャッシュとの高い親和性: サマリーを小さな単位で更新し、プレフィックスを維持するように設計されているため、プロバイダ側の prefix-cache ヒット率を 95〜97% 程度に保つ構造になっています。
4つのコンテキスト管理ツールを注入: モデルが呼び出せる専用ツール（圧縮、展開、検索、状態確認）を会話ストリームに注入し、モデル主導の自律的なメモリ管理を実現します。
多種多様なクライアントへの接続手段: オープンソースやプロプライエタリを問わず、各種コーディング CLI やエディタ（Claude、OpenCode、Pi、Gemini CLI、Zed など）に応じた連携手段が用意されています。

使い方

README では、npm を用いたグローバルインストール手順が記載されています。

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

インストール後は bili コマンドを介して各種クライアントと連携させます。README に記載されているクライアント別の起動例や設定方法は以下のとおりです。

ランチャー経由での起動

対応しているクライアントについては、専用のランチャーコマンドを使用して起動できます。

# 例: pi を起動する場合
bili pi

# 例: claude を起動する場合
bili claude

# 例: opencode を起動する場合
bili opencode

ネイティブプラグインとしての登録

クライアントのプラグインシステムに対応している場合は、インストールコマンドを通じてネイティブプラグインとして組み込むことも可能です。

# 例: pi にネイティブプラグインとして導入
bili plugin install pi

# 例: opencode に導入
bili plugin install opencode

# 例: claude に導入
bili plugin install claude

プラグイン機構を持たないバイナリ単体のツール（GitHub Copilot CLI や Zed など）に対しては、bili 経由での証明書を用いたプロキシ（cert-MITM）や、エンドポイント URL の書き換え（/bili/ プレフィックスの付与）を利用する形が案内されています。

技術的なポイント

アーキテクチャと acp-kernel によるストリーム書き換え

billion-context は TypeScript を主な言語として実装されており、Anthropic や OpenAI 互換の API ストリームを仲介します。コアとなる圧縮処理には acp-kernel が利用されており、クライアントとモデルの通信経路の間でストリームを動的に書き換えます。

会話へ注入される4つのツール

プロキシはモデルに対して以下の4つのツール定義を注入し、モデルが自律的にコンテキストを制御できるようにします。

compress: 指定した範囲のメッセージを詳細なサマリーに折りたたむ。
decompress: 正確な詳細が必要になった際に、圧縮済みの範囲を元のメッセージへ展開する。
search_context: 圧縮されたサマリーや表示中のメッセージ群を対象にキーワード検索を行う。
acp_status: コンテキストの使用状況と、現在どの範囲が圧縮可能かを確認する。

モデルが compress を呼び出すと、サーバー側（プロキシ側）で履歴が折りたたまれ、履歴が要約に置き換わった状態で会話が維持されます。

クライアントに応じた連携アーキテクチャ

README の「Which do I need?」の表に示されているとおり、接続先クライアントの内部構造に合わせて複数の連携方式が用意されています。

Native モード: クライアント内部のプラグインフックを利用し、プロセス内または直接連携する方式（Pi、OpenCode、dsh など）。
Launcher / URL Rewrite モード: クライアント起動時の環境変数（例: GOOGLE_GEMINI_BASE_URL や IFLOW_BASE_URL など）をプロキシのエンドポイント（/bili/）へ誘導する方式。
Cert-MITM モード: 拡張ポイントを持たない Go や Rust 製のバイナリクライアントに対し、ローカルプロキシと証明書を用いてトラフィックを仲介する方式。

論文およびベンチマーク検証

リポジトリ内にはプレプリント論文（paper/ ディレクトリ配下）が含まれており、4.5か月間にわたる3台のホストでの長期運用テスト（計174,327回の呼び出し、累計約24.7Bトークン）において、204,800トークンのモデルでウィンドウあふれを起こさずにセッションを維持した記録が示されています。また、LongMemEval-S、ContextBench、MemoryAgentBench といった外部ベンチマークを用いた評価結果も報告されています。

注意点

ライセンスの明記状況

論文ファイル（paper/ 配下）については MIT License である旨が README に明記されていますが、リポジトリ全体のライセンスはメタデータ上「不明」となっています。ソースコードを商用利用や再配布する際は、リポジトリ内の個別ファイルやライセンス表示の更新状況を確認する必要があります。

クライアントごとの導入手順の違い

すべてのツールで同じように動作するわけではありません。プラグインとして透過的に動くもの、起動コマンドを bili に差し替える必要があるもの、プロキシ証明書（cert-MITM）のセットアップが必要なものなど、対象クライアントの仕様に応じた設定が求められます。

キャッシュ状態の監視

prefix-cache のヒット率が低下した場合、上流キャッシュの TTL 切れ、モデルの切り替え、あるいはツールの不具合などが原因として挙げられています。セッション健全性を確認するためのコマンドとして /acp や /acp-cache が用意されており、トラブルシューティング時にはこれらを用いた原因切り分けが必要です。

まとめ

billion-context は、モデル自身に会話履歴の圧縮・展開を行わせることで、トークン制限を超えた長期セッションを実現する TypeScript 製のプロキシツールです。キャッシュ効率を維持しながら小規模なウィンドウでコーディングエージェントを長期間運用したい場合に、有力なアプローチを提供します。