Sophon

Sophon

MCP エージェント向けの決定論的なコンテキスト圧縮。 Rust の単一バイナリ。クエリ時の ML は不要。再現可能なベンチマークと実データでの測定。

Sophon は、Model Context Protocol を使用するエージェント向けの決定論的なコンテキストレイヤーです。クエリ時の埋め込みモデル、GPU、API キーを使わずに、プロンプト、会話メモリ、コードダイジェスト、ファイル差分、シェル出力を圧縮します。

単一の 5.2 MB Rust バイナリ。 MCP ネイティブ。cl100k_base に正確に対応。デフォルトのビルドでは Python も ML の重みもネットワークも不要です。

---

30 秒でわかる機能

ツール	解決する課題
compress_prompt	長い構造化プロンプト → クエリに関連するセクションだけを残します
compress_history	増え続ける会話 → 要約＋事実＋直近のウィンドウ＋任意の検索
compress_output	シェルの stdout/stderr → 21 種類のドメイン対応フィルター（git、cargo、docker、kubectl、JSON など）
read_file_delta / write_file_delta	ファイルの再読み込み＋編集 → 差分のみ。ファイル全体は決して読み込みません
encode_fragments	繰り返される定型文 → 単一のトークン参照
update_memory	ターンを追加 → JSONL に保存＋増分ローリング要約
navigate_codebase	tree-sitter / regex＋PageRank を使ったリポジトリダイジェストをクエリに基づいてランク付け

MCP ツールは合計 11 個です（下記の全表）。

---

実測値 — このリポジトリ自体の開発サイクルで測定

エージェントのツールトラフィックの異なる部分をそれぞれ捉える、独立したベンチマークを 4 つ作成しました。いずれもオペレーターのマシン上で、このリポジトリの実際の Git 履歴と作業ツリーを使って実行します。cargo build --release があれば、誰でもバイト単位で再現可能です。

対象	測定内容	削減率	ベンチマーク
履歴	実際のコミットに対する compress_history	94.6 %	real_session_capture.py
シェル	実際の git / cargo / gh / ls の stdout に対する compress_output	84.4 %	real_session_shell.py
ファイル読み込み	実際の Rust / Python / Markdown / TOML ファイルに対する compress_prompt	71.7 %	real_session_filereads.py
検索	実際の grep / find パターンに対する compress_output	79.5 %	real_session_search.py
🎯 加重平均（35/30/20/15）	一般的なエージェントセッションの推定値	84.7 %	real_session_holistic.py

real_session_holistic.py は --json を指定して 4 つのサブベンチマークをすべて実行し、結果を解析して加重平均を算出します。デフォルトの重みは、このリポジトリで観測された構成を反映しています。独自のワークロードをモデル化するには、--weights "history=0.4,..." を渡してください。

Claude Opus 4.7 での米ドル換算の節約額

	セッションあたりの節約額
キャッシュなしの入力料金（$15/MT）	$2.03
プロンプトキャッシュあり（25 ターン分の読み込み、$1.50/MT）	$3.24

より安価なモデルの料金で再計算する場合は、real_session_deep_dive.py に --model sonnet または --model haiku を渡してください。

各指標の限界（私たち自身が明言しています）

• 履歴が測るのは、git が記録する内容（コミット＋差分）だけです。通常、実際のセッションのツールトラフィックの約 5～10 % にすぎません。94.6 % は上限値であり、典型的な数値ではありません。
• シェルには、効率よく圧縮できるコマンド（git diff は 95 %）と、そうでないコマンド（gh repo view --json はトークンを増加させ、−9 %）が混在しています。84.4 % は、厳選した好事例ではなく、実環境での平均値です。
• ファイル読み取りのベンチマークでは、ソースファイルに対する compress_prompt はクエリに応じてルーティングするのではなく、予算上限まで圧縮することが分かりました。同じファイルに異なる 3 つのクエリを指定しても、出力は同一です。セクション検出が機能するのは、構造化された入力（Markdown の見出し、XML タグ）に限られます。この内容はベンチマークにインラインで記載しています。
• 検索は、完全にあなたのリポジトリの状態に依存します。TODO がないリポジトリでは、grep TODO の結果は 0 % です。

84.7 % という加重平均は、4 つの実測値を単純な線形加重平均で算出した概算です。都合のよい合成データではありません。 ベンチマークを自分で実行して検証してください。

その他の再現可能なベンチマーク（合成データ、主張に沿ったもの）

テスト	結果	ベンチマーク
18 のコマンドファミリーにわたる compress_output	加重集計 90.1 %	compress_output_per_command.py
25 ターンの合成 Claude Code セッション	セッションのトークンを 68.1 % 削減	session_token_economics.py
22 種類のプロンプト形式に対する compress_prompt	平均 70.2 %、平均レイテンシ 36 ms	prompt_compression_extended.py
「X はどこにある？」という質問に対するコード検索	recall@3 = 70 %（grep は 10 %、FULL は 20 %）	repo_qa.py
構造化プロンプトでの LLMLingua-2 との比較	レイテンシを 35 分の 1 に抑えつつ、精度が +8.9 pt	llmlingua_compare.py
Sophon + Anthropic のプロンプトキャッシュ	キャッシュに加えて、トークンを +24 %、コストを +49 % 削減	sophon_plus_prompt_caching.py
Sophon + mem0	取得したメモリをさらに削減	sophon_plus_mem0.py

---

Sophon を選ぶ理由 — 「X の手前に配置」

Sophon は、メモリプラットフォームでも、想起システムでも、OCR スタックでも、プロバイダー側キャッシュの代替でもありません。既存のメモリ／キャッシュ／コードナビゲーションのレイヤーの手前に組み込める決定論的な圧縮ツールであり、それらのレイヤーでは処理できないトークンを削減します。

Anthropic／OpenAI のプロンプトキャッシュの手前に配置

プロバイダーのキャッシュが処理するのは、リクエストの静的な部分、つまりシステムプロンプト、ツール定義、再利用されるドキュメントです。動的な部分（増加していく会話履歴、ツール出力）には手を加えません。Sophon は、まさにその部分を圧縮します。両者はきれいに併用できます。

25 ターンの Claude セッションで、プロンプトキャッシュに加えてトークンを 24 %、コストを 49 % 削減しました。キャッシュされない動的ブロックには、キャッシュされたブロックの 10 倍の料金がかかるためです。詳細は sophon_plus_prompt_caching.py を参照してください。

mem0／Letta／Zep／Graphiti の手前に配置

メモリシステムは、適切なメモリを取得します。Sophon は、取得後に LLM へ送信される内容を縮小します。mem0 が 2 kB の未加工メモリを返す場合、compress_prompt はクエリが実際に参照するセクションだけを残します。

正直な注意点：取得したブロックが非常に短い場合（約 200 トークン未満）、Sophon のラッパーによるオーバーヘッドが加わるため、そのまま通すべきです。ベンチマークでもこの点をそのまま報告しています。

Claude Code／Cursor／Cline の手前に配置

主なユースケースです。繰り返し読み込むファイルはすべて read_file_delta に変換され、すべてのシェルコマンド出力は compress_output を通り、繰り返される定型文ブロックはすべて fragment_cache トークンになります。sophon hook install --agent claude --global で透過的にインストールできます。

RAG パイプラインの手前に配置

navigate_codebase は PageRank によるリポジトリダイジェストを生成します。RAG リトリーバーが通常なら、このダイジェストの作成に高コストな埋め込み呼び出しを行います。11 の言語に対応した Tree-sitter／正規表現によるシンボル抽出を、1 秒未満で実行します。

Sophon を使用しないケース

• 80％を超える長文会話の想起が必要な場合 — Sophon の LOCOMO での上限は約40％であり、それ以上は目指していません。想起には mem0 ／ Letta ／ Zep を実行し、必要に応じてその出力を Sophon に渡してください。
• 大規模なドキュメントに対するマルチホップ推論 — その場合は HippoRAG または GraphRAG をご利用ください。
• OCR ／ PDF レイアウト — 対象外です。上流で Docling ／ Marker ／ Unstructured をご利用ください。
• 非常に小さな入力（約200トークン未満） — Sophon のセクション構成によって、節約できる量を上回るコストがかかる場合があります。

---

クイックスタート

npm でインストール（推奨）

npm install -g mcp-sophon
sophon doctor          # verify install + show config

postinstall スクリプトは、GitHub Releases ページから、お使いのプラットフォームに合ったビルド済みバイナリをダウンロードします。対応環境：macOS arm64/x64、Linux arm64/x64、Windows x64。

ソースからビルド

git clone https://github.com/lacausecrypto/mcp-sophon
cd mcp-sophon/sophon
cargo build --release -p mcp-integration       # ~5.2 MB binary

オプション機能：

# 11-language tree-sitter AST extraction (~25 MB):
cargo build --release -p mcp-integration --features codebase-navigator/tree-sitter

# BGE-small semantic embedder (~34 MB), activate with SOPHON_EMBEDDER=bge:
cargo build --release -p mcp-integration --features bge

# All features (~42 MB):
cargo build --release -p mcp-integration --features "codebase-navigator/tree-sitter,bge"

Rust 1.75 以降が必要です。

MCP クライアントに接続する

ほとんどのクライアントで、次のスニペットを使用できます（Claude Desktop、Claude Code、Cursor、Cline、Continue）：

{
  "mcpServers": {
    "sophon": {
      "command": "sophon",
      "args": ["serve"]
    }
  }
}

sophon doctor を実行すると、お使いのクライアントに適した設定パスが表示されます。

推奨ランタイム設定

# Persistent memory + on-disk retriever store + BM25+Hash hybrid
export SOPHON_MEMORY_PATH=~/.sophon/memory.jsonl
export SOPHON_RETRIEVER_PATH=~/.sophon/retriever
export SOPHON_HYBRID=1

sophon serve

CLI クイックスタート

sophon exec -- cargo test                       # run + compress combined output
sophon compress-prompt --prompt ./system.txt --query "rust errors" --max-tokens 500
sophon hook install --agent claude --global     # transparent Claude Code integration
sophon stats --period session                   # token savings rollup

プログラムから実行（単発の JSON-RPC）

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"compress_prompt","arguments":{"prompt":"<rust>?: operator</rust><web>fetch()</web>","query":"rust errors","max_tokens":500}}}' \
  | sophon serve

---

バイナリに含まれるもの

MCP ツール11個（すべて stdio）：

ツール	機能
compress_prompt	長いプロンプトからクエリに関連するセクションを保持します
compress_history	会話の要約＋事実＋直近の内容＋オプションの検索を提供します
compress_output	コマンドの stdout/stderr からノイズを除去します（21種類のドメインフィルター＋JsonStructural）
navigate_codebase	クエリに基づいて PageRank を適用した、リポジトリの tree-sitter ／正規表現ダイジェストを生成します
update_memory	メッセージを追加し、JSONL で永続化し、オプションでローリング要約を作成します
read_file_delta	バージョン／ハッシュを考慮してファイルを読み込み、変更がなければ最小限のペイロードを返します
write_file_delta	ファイル全体ではなく差分として編集内容を送信します
encode_fragments / decode_fragments	繰り返しの定型文を検出し、トークンに置き換えます
count_tokens	cl100k_base に基づく正確なトークン数をカウントします
get_token_stats	セッション単位の節約量を集計します

機能セット別のバイナリサイズ：

ビルド	サイズ
デフォルト（正規表現エクストラクター、HashEmbedder）	5.2 MB
+ tree-sitter（11言語）	約25 MB
+ BGE セマンティックエンベッダー	約34 MB
すべての機能	約42 MB

MCP プロトコル： 2025-06-18。notifications/cancelled は実際にレスポンスを破棄します（v0.5.4 以降）。構造化 JSON-RPC エラーコード（-32000..-32099 は Sophon 用に予約）。障害が発生しないディスパッチャーにより、不正なリクエストで stdio ループが停止することはありません。

---

ファイルシステムのアクセス制限（オプトイン）

信頼できないプロンプトを実行するクライアントでは、SOPHON_ALLOWED_ROOT に既存のワークスペースディレクトリを設定してください。read_file_delta、write_file_delta、navigate_codebase は、このディレクトリの外を指す解決済みパスを拒否します。デフォルトでは、信頼できるローカル統合は制限なくファイルシステムにアクセスできます。これはパスレベルの防御であり、強化された OS サンドボックスではありません。既知のシンボリックリンクとリンク先のないシンボリックリンクは検査されますが、ディレクトリリンクを変更できる同時実行中のアクターが、認可から後続のファイル操作までの間にパスを差し替える可能性があります（TOCTOU）。同じファイルシステムへの書き込み権限を持つ悪意あるユーザーに、これらのツールを公開しないでください。厳格なセキュリティ境界が必要な場合は、オペレーティングシステムによる分離を使用してください。アクセス制限が有効な場合、新しいファイルの作成には既存の親ディレクトリが必要です。

設定

**sophon doctor**を実行すると、現在設定されているすべてのSOPHON_*環境変数と、検証時の警告を確認できます。全24個のフラグの一覧はruntime_flags.rsにあります。知っておくべきフラグは次のとおりです。

フラグ	効果	コスト
SOPHON_RETRIEVER_PATH=/dir	セマンティック検索機能を有効化します（チャンクストアをディスクに保存）	~0
SOPHON_MEMORY_PATH=/file.jsonl	sophon serveの実行をまたいで会話メモリを永続化します	~0
SOPHON_HYBRID=1	BM25のスパースな語彙検索とHashEmbedderをRRFで統合します	~1 ms
SOPHON_ROLLING_SUMMARY=1	クエリ時ではなく、update_memory時にローリングサマリーを作成します	LLM呼び出しを取り込み時に移動
SOPHON_CHUNK_TARGET=500	チャンクを大きくして、文をまたぐ文脈を保持します	~0
SOPHON_EMBEDDER=bge	HashEmbedderをBGE-smallに切り替えます（--features bgeが必要）	起動時にモデルを読み込み
SOPHON_LLM_CMD="claude -p --model haiku"	LLMのシェル実行コマンド（設定時、要約機能で使用）	呼び出しごとのサブプロセス

非推奨のv0.4.0リコール追求フラグ — SOPHON_HYDE、SOPHON_FACT_CARDS、SOPHON_ENTITY_GRAPH、SOPHON_ADAPTIVE、SOPHON_LLM_RERANK、SOPHON_TAIL_SUMMARY、SOPHON_REACT、SOPHON_GRAPH_MEMORY、SOPHON_MULTIHOP_LLM — は、現在は最適化の対象としていないLOCOMOのリコールを追求するものです。引き続き動作しますが、sophon doctorで警告されます。将来のメジャーバージョンで削除されます。

---

正直な制限事項

全リストはBENCHMARK.md § 8にあります。主な点は次のとおりです。

• LOCOMOの会話リコールは約40％が上限です。 mem0 / HippoRAGはクエリ時のニューラル検索で80～90％を達成しますが、こちらは決定性と100 ms未満のp99を選びました。このリコールが必要な場合は、Sophonの前段にmem0を接続してください。
• HashEmbedderはキーワードに依存します。「favorite food」と「weakness for ginger snaps」は一致しません。セマンティックリコールを有効にするにはBGE（SOPHON_EMBEDDER=bge）を使ってください。バイナリが25 MB増加し、モデルの読み込みが必要になります。
• マルチモーダルの取り込みには対応していません。 画像／PDF／音声は対象外です。上流でDocling／Marker／Unstructuredを実行してください。
• 小規模なセッションではローリングサマリーの効果がありません。 要約前の末尾部分が予算内に収まる場合、ローリングキャッシュは何もしません。SOPHON_LLM_CMDを設定した長時間実行セッションで役立ちます。
• 一部のコマンドでは圧縮されません。 gh repo view --jsonはトークンを増やし、git log --onelineで削減されるのは0.4％です。Sophonの役割は、すでに簡潔な出力をさらに圧縮することではなく、冗長な出力を圧縮することです。ベンチマークでは、こうしたギャップを明示しています。

---

プロジェクトの構成

.
├── README.md           ← you are here
├── BENCHMARK.md        ← full per-section benchmark detail
├── CHANGELOG.md        ← version history + deprecated numbers
├── benchmarks/         ← reproducible scripts for every number above
├── npm/                ← npm wrapper package
└── sophon/crates/      ← 11-crate Rust workspace
    ├── prompt-compressor/    compress_prompt
    ├── memory-manager/       compress_history, update_memory, rolling summary
    ├── delta-streamer/       read/write_file_delta
    ├── fragment-cache/       encode/decode_fragments
    ├── semantic-retriever/   chunker + HashEmbedder + BM25 + entity graph
    ├── output-compressor/    21 command-aware filters + JsonStructural
    ├── codebase-navigator/   tree-sitter / regex + PageRank
    ├── cli-hooks/            transparent agent installer
    └── mcp-integration/      stdio server, async dispatch, cancellation

---

貢献

PRを歓迎します。テストスイートを実行してください。

cd sophon && cargo test --workspace --lib --tests --exclude prompt-compressor   # 405 tests
cd sophon && cargo test --features codebase-navigator/tree-sitter               # +AST tests
cd sophon-py && .venv/bin/pytest tests/                                         # 4 Python tests

すべてのベンチマークの主張は再現可能です。スクリプトへのリンクはBENCHMARK.mdにあります。お使いの環境で数値を再現できない場合は、issueを作成してください。

特に、次の貢献を歓迎します。

• TypeScriptバインディング（Pythonバインディングはsophon-py/にあります）
• ghファミリーのフィルター（gh run list、gh pr list、gh repo view --json）— ベンチマークでは、これが現在のギャップであることが示されています
• Voyage／OpenAI／Cohere向けのSOPHON_EMBEDDER_CMDシェル実行プラグインのパターン（SOPHON_LLM_CMDを参考）
• 人気のあるオープンソースリポジトリを対象とした、複数リポジトリでのreal_session_holistic.py実行

---

ライセンス

MITです。LICENSEを参照してください。