token-compressor

token-compressor

意味を保ちながら、LLM のプロンプトトークンを 30～70% 削減します。

mcp-name: io.github.base76-research-lab/token-compressor

LLM ワークフロー向けの意味的なプロンプト圧縮です。意味を損なわずにトークン使用量を 40～60% 削減します。

Base76 Research Lab が開発 — 認識論的 AI アーキテクチャの研究。

---

ライブデモ

Intent Compiler MVP が公開されました。アイデア -> 仕様 -> 圧縮出力のフローの一部として、このプロジェクトを使用しています。

• ライブデモ: https://intent-compiler-mvp.pages.dev
• 製品リポジトリ: https://github.com/base76-research-lab/token-compressor

---

機能

token-compressor は、LLM に送信する前にプロンプトを圧縮する 2 段階のパイプラインです。

1. LLM による圧縮 — ローカルモデル（Ollama 経由の llama3.2:1b）が、すべての条件節と否定を保ちながら、プロンプトを意味的に最小限の形に書き換えます
2. 埋め込み検証 — 元のテキストと圧縮後のテキストの埋め込み間のコサイン類似度がしきい値（デフォルト: 0.85）を超える必要があります。超えない場合は、元のテキストを変更せずに送信します

その結果、プロンプトが短くなり、コストが下がり、意図は保たれます。

Input prompt (300 tokens)
        ↓
  LLM compresses
        ↓
  Embedding validates (cosine ≥ 0.85?)
        ↓
  Pass → compressed (120 tokens)   Fail → original (300 tokens)

設計上の重要な原則: 条件性は決して犠牲にしません。プロンプトに「Y の場合に限り X を実行する」とある場合、その制約は圧縮後も保持されます。

---

必要条件

• Python 3.10+
• ローカルで実行中の Ollama
• 次の 2 つのモデルを取得済みであること:

ollama pull llama3.2:1b
ollama pull nomic-embed-text

• Python の依存関係:

pip install ollama numpy

---

クイックスタート

from compressor import LLMCompressEmbedValidate

pipeline = LLMCompressEmbedValidate()
result = pipeline.process("Your prompt text here...")

print(result.output_text)   # compressed (or original if validation failed)
print(result.report())      # MODE / COVERAGE / TOKENS saved

結果オブジェクト:

フィールド	説明
output_text	LLM に送信するテキスト
mode	compressed / raw_fallback / skipped
coverage	コサイン類似度（0.0～1.0）
tokens_in	推定入力トークン数
tokens_out	推定出力トークン数
tokens_saved	差分

---

CLI の使用方法

echo "Your long prompt here..." | python3 cli.py

出力: 圧縮後のテキストは stdout に、統計情報は stderr に出力されます。

---

Claude Code フック（推奨設定）

~/.claude/settings.json の hooks → UserPromptSubmit に追加します。

{
  "type": "command",
  "command": "echo \"${CLAUDE_USER_PROMPT:-}\" | python3 /path/to/token-compressor/cli.py > /tmp/compressed_prompt.txt 2>/tmp/compress.log || true"
}

これはプロンプトを送信するたびに実行され、圧縮後のバージョンを一時ファイルに書き込みます。このファイルは、2 つ目のフックまたは MCP サーバーを介してコンテキストに挿入できます。

---

MCP サーバー

MCP サーバーは、Claude Code および MCP 対応のあらゆるクライアントから呼び出せるツールとして、圧縮機能を公開します。

インストール:

pip install token-compressor-mcp

ツール: compress_prompt

• 入力: text（文字列）
• 出力: 圧縮後のテキスト + 統計情報のフッター

Claude Code の MCP 設定（~/.claude/settings.json）:

{
  "mcpServers": {
    "token-compressor": {
      "command": "uvx",
      "args": ["token-compressor-mcp"]
    }
  }
}

または、ソースから実行します。

{
  "mcpServers": {
    "token-compressor": {
      "command": "python3",
      "args": ["-m", "token_compressor_mcp"],
      "cwd": "/path/to/token-compressor"
    }
  }
}

---

設定

pipeline = LLMCompressEmbedValidate(
    threshold=0.85,          # cosine similarity floor (lower = more aggressive)
    min_tokens=80,           # skip pipeline below this (not worth compressing)
    compress_model="llama3.2:1b",
    embed_model="nomic-embed-text",
)

---

仕組み

ステージ 1 — LLM による圧縮

圧縮プロンプトでは、モデルに次のことを指示します。

• すべての条件節（if、only if、unless、when、but only）を保持する
• すべての否定を保持する
• 余分な語句、婉曲表現、重複を削除する
• 元の長さの 40～60% を目標にする

ステージ 2 — 埋め込み検証

nomic-embed-text を使用して、元のテキストと圧縮後のテキストのコサイン類似度を計算します。類似度がしきい値を下回る場合、元のテキストを変更せずに返します。これにより、意味が気づかないうちに失われるのを防ぎます。

---

結果

スウェーデン語と英語のプロンプトを対象に、技術文と自然言語の両方でテストしました。

入力	入力トークン数	出力トークン数	削減率
研究概要（EN）	89	38	57%
セッションの意図（SV）	32	18	44%
技術的な指示	47	22	53%
短いコマンド（<80t）	—	—	スキップ

---

研究の背景

このツールは、以下のアーキテクチャを実装しています。

Wikström, B. (2026). アラインメントが不確実性を低減するとき：認識論的分散の崩壊とメタ認知 AI への影響。 DOI: 10.5281/zenodo.18731535

認識論的 AI インフラストラクチャ向けツールチェーンである Base76 Research Lab の一部です。

---

ライセンス

MIT — Base76 Research Lab、スウェーデン