token_optimizer

slimctx — AI エージェント向けのトークンオプティマイザー

依存関係ゼロで、完全に可逆な AI エージェント向けコンテキスト圧縮。

slimctx は、ツールの出力、ログ、JSON、ソースファイル、文章など、エージェントが読み取る内容を LLM に渡す前に圧縮します。同じ回答を、わずかなトークン数で実現します。Python 標準ライブラリのみを使用し、ML モデルもダウンロードもネットワーク呼び出しも一切ありません。約 1,600 行で、最初から最後まで監査できます。

_{python3 benchmarks/demo.pyのライブ出力です。自分で実行してみてください。事前に用意された出力ではありません。}

from slimctx import Pipeline, Config

pipe = Pipeline(Config(target_tokens=32_000))
result = pipe.compress(messages)        # OpenAI/Anthropic-style dicts
print(result.savings_ratio)             # e.g. 0.82

original = pipe.retrieve("a1b2c3d4...")  # byte-exact original, any time

結果（実際のエージェントのトラフィックをモデル化した合成ワークロード）

ワークロード	圧縮前	圧縮後	削減率	重要な事実を保持
コード検索（100 件の結果）	5,557	916	84%	✓
SRE インシデントのデバッグ	61,699	298	100%	✓
GitHub イシューのトリアージ	12,836	975	92%	✓
コードベースの調査	5,734	2,760	52%	✓

実行ごとに、仕込まれた「針」（FIXME、OOMKill、外れ値）が圧縮後も残っていること、およびすべての不可逆変換がバイト単位で完全に元に戻せることも検証します。python3 benchmarks/bench.py で再現できます。

仕組み

messages ──► ContentRouter ──► one of:
                ├─ JSON  : lossless tabularization (repeated keys → header,
                │          constant columns → legend), then relevance-ranked
                │          row selection only if still over budget
                ├─ LOG   : Drain-style template mining — repeated lines
                │          collapse to `pattern [x1432]`; errors verbatim
                ├─ CODE  : AST skeleton — signatures + docstrings kept,
                │          bodies elided EXCEPT those relevant to the query
                └─ TEXT  : extractive sentence selection (BM25 + salience
                           + position), verbatim, never paraphrased

4 つの保証

1. 完全な可逆性。 損失を伴う変換を行う前に、元のデータをコンテンツアドレス方式のストア（メモリ／SQLite／独自の暗号化方式）に保存し、出力には[slimctx-ref <hash> ...]マーカーを付けます。モデルも、あなた自身も、いつでも元のデータをバイト単位で完全に復元できます。
2. エラーは決して削除されません。 すべての圧縮処理でエラー／警告の内容を保持します。ログのエラーはそのまま通過し、重要な JSON 行は保持され、重要な文は補足的な文より優先されます。
3. 決定論的な出力。 同じ入力なら、実行やプロセスをまたいでもバイト単位で同一の出力になります。圧縮されたプレフィックスは安定するため、プロバイダーのプロンプトキャッシュ（Anthropic／OpenAI）は引き続きヒットします。
4. 削減効果がなければ何もしません。 変換による削減トークン数がマーカー分のコストを十分に上回らない場合、元のデータを変更せずに保持します。ライブゾーン（システムプロンプト＋直近の N 件のメッセージ）は一切変更されません。

Headroomを使うだけではだめですか？

Headroomはこの分野で確立されたプロジェクトで、現在はより多機能です（SSEストリーミング対応のプロバイダープロキシ、エージェントラッパー、エージェント間のメモリ、ML圧縮モデル）。slimctxは異なるトレードオフを選択しており、制限の厳しい環境やクライアント先へのデプロイを想定しています。

	Headroom	slimctx
可逆性	JSONのみ（CCR）。削除されたテキストは復元できません	すべての非可逆変換
ログ処理	汎用的なテキストスコアリング	テンプレートマイニング（[x1432]の集約）
コード処理	ASTスケルトン	ASTスケルトン ＋クエリに関連する本体を保持
依存関係	Rustコア、ONNXランタイム、261MBのHFモデル	標準ライブラリのみ
ネットワークへのデータ送信	初回実行時にHuggingFaceから取得	一切なし
ストアの暗号化	なし（SQLiteに平文で保存）	暗号化フック（独自実装を使用）
決定性	cache-alignerコンポーネント	設計上保証（純粋関数＋メモ化）
監査対象の規模	3言語で約10万行のコード	Python約1,200行

プロキシやラッパーのエコシステムが必要なら、Headroomをお使いください。短時間でコードを読み切れ、エアギャップ環境で実行でき、クライアント環境向けに認証できるものが必要なら、slimctxをお使いください。

インストール／テスト

pip install slimctx           # from PyPI — or vendor the slimctx/ directory
python -m pytest tests/ -q    # 26 tests: invariants, not examples
python3 benchmarks/bench.py   # reproduce the numbers above

統合例

**ライブラリとして（任意のフレームワーク）：**プロバイダーSDKの呼び出しの直前にpipe.compress(messages)を呼び出し、モデルが元の内容を取得できるよう、pipe.retrieveをretrieveという名前のツールとして公開します。

**MCPサーバーとして（GitHub Copilot、Claude Code、Cursorなど）：**標準ライブラリのみで、組み込みで利用できます。

python3 -m slimctx.mcp_server --db ~/.slimctx/store.db

GitHub Copilot（.vscode/mcp.json）の設定とセキュリティデプロイのチェックリストについては、USAGE.mdを参照してください。

暗号化ストア：

from cryptography.fernet import Fernet          # optional, your choice
f = Fernet(key)
store = SqliteStore("ccr.db", cipher=(f.encrypt, f.decrypt))
pipe = Pipeline(store=store)

ライセンス

Apache-2.0。独自の実装であり、Headroom由来のコードは含まれていません。