Sarup

สรุป は「要約する」という意味です。Headroomは空白区切りのトークナイザーではタイ語の単語境界を見つけられないため、タイ語を noop（削減率0％）に回します。SarupはPyThaiNLPのセグメンテーションを使うため、英語だけでなくタイ語も圧縮できます。また、元データをすべてキャッシュするため、データが失われることはありません。

目次

• 主な特長
• 安全性の理由 — 2段階の保証
• 仕組み
• ツール
• 圧縮モード
• 測定結果
• 使用例
• インストール
• Claude Code への登録
• 自動圧縮フック
• プライバシーとデータ
• 設定
• プロジェクト構成
• 技術スタックと手法
• テスト
• ロードマップ
• ライセンス

主な特長

• 🇹🇭 本格的なタイ語圧縮 — 空白ではなく、PyThaiNLPの newmm 単語セグメンテーションを使用します。
• ♻️ 保証付きの可逆性 — 圧縮のたびに元データをキャッシュします。verified: true はバイト単位で完全に元に戻せることを証明します。
• 🎚️ 5つのモード：オフラインで1ミリ秒のTF-IDFから、削減率78％のカスケードまで対応します。
• 🧠 オプションのローカルLLM — Ollamaによる埋め込みと書き換えに対応し、オフライン時には自動でフォールバックします。
• 📏 正確な指標：実行時には実際のトークナイザー（tiktoken）を使用します。公開数値にはClaude独自のトークナイザーとタイ語QA評価を使用しています（Claudeは引き続き正しく回答できるのか？）。
• 🕳️ 欠落箇所を明示：文が省略された箇所には […] を付けます。これにより、Claudeは近くにある事実を回答と誤認せず、検索して情報を取得できます。
• 🔌 コンテンツを認識 — JSONの圧縮、ログの重複排除、コードフェンスの逐語的な保持を標準で備えています。
• 🛟 Claudeの動作を妨げません — これはAPIプロキシではなくMCPツールです。サーバーが停止してもツールが使えなくなるだけで、Claudeはそのまま動作します。

安全性の理由 — 2段階の保証

元データは常に sarup_retrieve(hash) で取得できるため、積極的な非可逆圧縮も安全です。この仕組みによって、「最大限の削減」と「100％の精度」が両立します。それぞれ別の階層で実現されています。

仕組み

2つの入口から1つのエンジンに入力します。モデルが読む低コストな圧縮ビューと、元データをバイト単位で完全に復元できる取得ストアです。

flowchart TD
    M["🧑 Manual<br/>sarup_compress()"]:::entry --> R
    A["⚙️ Automatic<br/>PostToolUse hook<br/>(Read · Bash · Grep)"]:::entry --> R

    R{"Sarup compress<br/>extractive · semantic · abstractive · pipeline"}:::engine
    R -- "compressed view<br/>50–78% fewer tokens" --> V["📄 Model context"]:::lossy
    R -. "cache original" .-> S[("🗄️ Retrieval store<br/>hash → original")]:::lossless

    V -. "need full detail?" .-> RET["🔑 sarup_retrieve(hash)"]:::lossless
    RET --> S
    S == "byte-for-byte ✓" ==> V

    classDef entry fill:#e0e7ff,stroke:#6366f1,color:#111
    classDef engine fill:#fde68a,stroke:#d97706,color:#111
    classDef lossy fill:#fef3c7,stroke:#f59e0b,color:#111
    classDef lossless fill:#bbf7d0,stroke:#16a34a,color:#111

• 手動 — モデル自身が sarup_compress / sarup_retrieve を呼び出します。
• 自動 — フックが大きなツール出力を検出し、元データを SARUP_DB_PATH にキャッシュして、圧縮ビューと取得用ハッシュに置き換えます。ソースコードは処理をスキップし、小さな出力はそのまま通します。

ツール

sarup_compress の引数

圧縮モード

¹ 10 文から成るタイ語の段落（522 トークン）で測定。書き換えモデルは gemma4:12b です。すべてのモードでストアを使って 100% 復元可能です。Ollama モードはバックエンド停止時に適切に機能を低下させ、extractive に切り替わります。（gemma4:e4b：pipeline 82.2%、2026 年 6 月、gemma3:12b：88.1%。）

Extractive と semantic の出力は、入力文の原文そのままの一部です。文が削除された箇所には、独立した行に […] が表示されます。具体的な情報（数字、タイ語の数字、X-Api-Key などの識別子）を含む文は、一般的な記述より高いスコアになります。質問ではそうした情報が求められるためです。

測定結果

$ .\.venv\Scripts\python.exe bench\benchmark.py

sample                      before   after   savings   verify
Thai prose                     522     247    52.7%       OK
Thai prose (aggressive)        522     189    63.8%       OK
English prose                  105      60    42.9%       OK
JSON (lossless)                 67      44    34.3%       OK
Logs                           563     300    46.7%       OK
TOTAL                         1779     840    52.8%    ALL OK   → 100% recoverable

Mode comparison (Thai prose, 522 tok):
  extractive 52.7% (1ms) · semantic 63.8% (2.1s) · auto 63.8% (2.1s)
  abstractive 44.4% (8.3s) · pipeline 78.2% (5.8s)      ← gemma4:12b

トークン数は tiktoken の cl100k_base を使用しています。これは OpenAI のトークナイザーであり、特にタイ語では Claude のトークン数を過小評価します。bench\benchmark.py --claude を使うと、Claude 独自のトークナイザー（Anthropic の count_tokens。API キーが必要）による列が追加されます。

Claudeは今でも正しく答えられるのでしょうか？

トークン数を減らしても、事実が保たれなければ意味がありません。bench\eval_qa.py は8件のタイ語文書 （インシデント報告書、会議メモ、APIドキュメント、人事ポリシー、製品仕様書、サポートチャット、README、営業報告書。半分は1文ごとの行、半分は密な段落）を圧縮し、圧縮後の内容だけをもとにClaude Opus 5.5に32問を尋ね、決定論的に採点します。

$ .\.venv\Scripts\python.exe bench\eval_qa.py        # uses your local `claude` login

mode               claude tok   saved  correct  abstain  wrong
──────────────────────────────────────────────────────────────
original                 4601    0.0%     100%       0%      0
extractive:0.5           3204   30.4%      69%      31%      0
extractive:0.3           1969   57.2%      44%      56%      0
semantic:0.5             3214   30.1%      62%      38%      0
extractive:0.5+q         3207   30.3%     100%       0%      0
abstractive:0.5          2697   41.6%      91%       9%      0     ← gemma4:12b
pipeline:0.5             1854   59.8%      59%      41%      0     ← gemma4:12b

（gemma4:e4bも同じスコアでした：抽象化91％、パイプライン59％、誤答0。）

• 誤答 = 0 は安全性を示す性質です。事実が削除されていた場合、Claudeはその旨を伝え（回答を保留）、実際の利用では sarup_retrieve を呼び出します。残された情報から推測することはありませんでした。
• 回答を保留 することが、盲目的な圧縮の実質的なコストです。具体的な質問の約3分の1では、0.5 で検索の往復が必要です。探している内容がわかっている場合は、query として渡してください（+q 行）。
• 抽象化 はトークンあたりの事実を最も多く保持します（42％削減で91％）。書き換えなら、単語を削りながら数字をすべて残せる一方、抽出では文全体を削るしかないためです。文書ごとに数秒かかるので、フックではなく sarup_compress 経由で使用してください。
• どちらの評価でも、言い換えによって事実が誤った内容に変わることはありませんでした。しかし、8件の文書だけでは、書き換えでそのようなことが決して起きないとは証明できません。そのため、元の文書には sarup_retrieve を1回呼び出すだけでアクセスできる状態にしています。
• ここでのトークン数はClaude自身の数値（回答呼び出しの使用量から取得）で、約40トークンの [sarup: …] フッターも含みます。短い（約570トークンの）文書ではこのフッターの比重が大きくなりますが、フックが実際に圧縮する大きな出力では影響が薄れます。
• 8件の文書はサンプルとして少なく、モード間の数問程度の差はノイズです。

この評価をきっかけに修正する前（2026年10月）は、密なタイ語の段落はまったく圧縮されませんでした（文分割用のモデルがインストールされていませんでした）。extractive:0.5 は59％の質問に回答しましたが、自信のある誤答が1件あり、semantic:0.5 は47％でした。

使用例

タイ語の段落に対する実際の sarup_compress 呼び出し（mode="auto"、Ollamaが起動している場合 → semantic）：

// → sarup_compress(content="…518-token Thai paragraph…", mode="auto")
{
  "compressed": "จุดเด่นที่สำคัญที่สุดคือมันไม่มีทางทำให้ Claude พัง…",
  "hash": "caa568140bec0ff734937cf5",
  "original_tokens": 518,
  "compressed_tokens": 154,
  "tokens_saved": 364,
  "savings_percent": 70.3,
  "transforms": ["semantic_extractive", "embeddings", "thai"],
  "lossy": true,
  "verified": true,                    // round-trip proven byte-for-byte
  "token_method": "tiktoken:cl100k_base"
}

モデルは154トークンのビューで処理を続けます。元の518トークンの全文には、呼び出し1回でアクセスできます。

// → sarup_retrieve(hash="caa568140bec0ff734937cf5")
{ "content": "…the exact original text, restored byte-for-byte…" }

インストール

Claude Codeプラグインとして（最も簡単）

uv が必要です。このプラグインは uvx 経由でSarupを実行し、初回使用時にPythonと依存関係を取得します。クローンする必要はありません。Claude Codeで次を実行してください。

/plugin marketplace add PHUICMT/sarup
/plugin install sarup@sarup

これにより、MCP サーバー、自動圧縮フック、/sarup:sarup-setup スキルがインストールされます。キャッシュはプラグインのデータディレクトリに保存されるため、プラグインを更新しても保持されます。初回起動時は、uvx が環境を構築するため数秒かかります。代わりにシェルから実行する場合： claude plugin marketplace add PHUICMT/sarup、続けて claude plugin install sarup@sarup を実行します。

Ollamaは任意です。Ollamaなしでもすべてオフラインで動作します。フックとデフォルトの extractive モードはOllamaにアクセスせず、semantic、abstractive、pipeline を指定した場合は抽出的な方法にフォールバックし、何をインストールすればよいかを示す setup フィールドを返します。sarup_stats で利用可能なものを確認でき、/sarup:sarup-setup でOllamaと以下のモデルの追加手順を確認できます。

PyPIから（任意のMCPクライアント）

このパッケージはPyPI上の sarupです。uvを使えば手動でインストールする必要はありません。任意のMCPクライアントから uvx sarup を指定してください。

{
  "mcpServers": {
    "sarup": {
      "command": "uvx",
      "args": ["sarup"],
      "env": { "SARUP_DB_PATH": "/home/me/.sarup-cache.db" }
    }
  }
}

プラグインを使わずにClaude Codeで利用する場合：claude mcp add sarup -s user -- uvx sarup。フックは uvx --from sarup sarup-hook --db <same file as SARUP_DB_PATH> です。pip install sarup でもインストールでき、sarup と sarup-hook が PATH に追加されます。

クローンから

ワンコマンド（仮想環境を作成し、すべてをインストールして、すべてのプロジェクトで MCP サーバーを登録します。何度実行しても安全です）：

.\scripts\setup.ps1 -All      # Windows  (-All also adds the hook, the /sarup-setup skill, pulls Ollama models)
./scripts/setup.sh --all      # Linux / WSL / macOS

ヒント：-All／--all を指定すると、グローバルな /sarup-setup スキルがインストールされます。そのため、別のマシンでは Claude Code で /sarup-setup と入力するだけで、インストール手順が案内されます。（または、scripts/install-skill.ps1／install-skill.sh を単独で実行してください。）

アンインストールも同様に簡単です（Sarup が追加したものだけを削除します。-Purge／--purge を指定すると、仮想環境とキャッシュも削除されます）：

.\scripts\uninstall.ps1       # Windows
./scripts/uninstall.sh        # Linux / WSL / macOS

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

オプションのローカル LLM モード（semantic／abstractive／pipeline）には、Ollama が必要です：

ollama pull nomic-embed-text     # embeddings → semantic mode
ollama pull gemma4:12b           # rewrite → abstractive / pipeline, 7.6 GB (or gemma4:e4b / gemma3:12b)

Claude Code への登録

ワンコマンドセットアップ（推奨）。 このマシンのパスを検出し、Ollama を確認して（最適なモードとモデルを選択）、既存の設定を上書きせずに .mcp.json／.claude/settings.json に統合します（最初に .bak が作成されます）：

.\.venv\Scripts\python.exe scripts\install.py --with-hook --pull

• Ollama がありませんか？オフラインの extractive モードが設定されます。それでもすべての機能を利用できます。
• Ollama が起動していますか？sarup_compress 用に、nomic-embed-text（semantic）と、インストール済みの中で最適な書き換えモデル（gemma4:12b → gemma4:e4b → gemma3:12b → qwen3）が自動選択されます。フックはどちらの場合も extractive のままです（すべてのツール呼び出しで実行されます）。不足しているモデルは --pull で取得できます。
• 何度実行しても安全です。再実行できます。--global を指定すると、~/.claude に書き込みます。

手動 — または、MCP 設定（例：.mcp.json や ~/.claude.json）に自分で追加してください。<SARUP_DIR> は、このリポジトリをクローンした絶対パスに置き換えます（上記のインストーラーで自動入力されます）：

{
  "mcpServers": {
    "sarup": {
      "command": "<SARUP_DIR>/.venv/Scripts/python.exe",
      "args": ["-m", "sarup.server"],
      "env": { "SARUP_DB_PATH": "<SARUP_DIR>/.sarup-cache.db" }
    }
  }
}

Linux/macOS では、インタープリターは <SARUP_DIR>/.venv/bin/python です。

または、stdio 経由で直接実行します：

.\.venv\Scripts\python.exe -m sarup.server

自動圧縮フック

手動でのツール呼び出しをすべて省略できます。PostToolUse フックをインストールすると、大きな Read／Bash／Grep の出力がコンテキストに入る前に圧縮され、元の内容は取得用にキャッシュされます。安全のため、ソースコードの読み取りはスキップされます。セットアップの詳細は hooks/README.md をご覧ください。

2026 年 10 月に修正されました。 以前のバージョンでは、圧縮されたテキストを通常の文字列として返していました。 Claude Code が受け付けるのは、ツール本来の形式に従った updatedToolOutput（Bash の場合は {stdout, stderr, …}、Read の場合は {type, file: {content, …}}）だけです。通常の文字列は黙って破棄されるため、どの環境でもフックが適用されていませんでした。現在は各ツールの形式が保持されます。CLI（2.1.289）で検証済みです。モデルには圧縮された内容と取得用ハッシュが渡されます。お使いのビルドでフックの動作を確認するには、SARUP_HOOK_LOG にファイルパスを設定してください（呼び出しごとに JSON が 1 行記録されます）。

プラグインがこの設定を行います。クローンから設定する場合は、<SARUP_DIR> をクローン先のパスに置き換えるか、install.py --with-hook を実行してください：

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Read|Bash|Grep",
        "hooks": [{ "type": "command",
          "command": "<SARUP_DIR>/.venv/Scripts/sarup-hook --db <SARUP_DIR>/.sarup-cache.db" }] }
    ]
  }
}

プライバシーとデータ

復元を保証するため、Sarup は元の内容をストアにキャッシュします。次の 2 点にご注意ください。

• SARUP_DB_PATH を設定すると、元の内容は暗号化されず平文でその SQLite ファイルに書き込まれます。圧縮した内容を保存したキャッシュとして扱ってください。
• 秘密情報を含むツール出力（例：.env のダンプやログ内の認証情報）を圧縮すると、それらもキャッシュに保存されます。自動フックはソースコード／設定ファイルの読み取りをスキップしますが、Bash の出力は対象になります。何を処理するか確認してください。

*.db は Git の対象外に設定されているため、キャッシュがコミットされることはありません。ディスク上にデータを一切残したくない場合は、SARUP_DB_PATH を未設定のままにしてください（メモリのみで動作します。MCP サーバーの再起動時にキャッシュは失われ、フックによる置き換えも行われません。フックのドキュメントをご覧ください）。

設定

プロジェクト構成

sarup/
├── src/sarup/
│   ├── server.py       # MCP stdio server — 3 tools
│   ├── compressor.py   # router + modes (extractive/semantic/abstractive/pipeline/auto)
│   ├── thai.py         # PyThaiNLP tokenization, sentence split, TF-IDF
│   ├── semantic.py     # embedding centrality + cosine dedup
│   ├── llm.py          # optional Ollama backend (generate + embed)
│   ├── tokens.py       # real token counting (tiktoken)
│   └── store.py        # CCR store: hash → original (memory + SQLite)
├── hooks/
│   ├── sarup_hook.py   # PostToolUse auto-compression hook
│   └── README.md       # hook install guide
├── bench/benchmark.py  # before/after measurement
├── tests/              # test_thai, test_mcp, test_hook, ...
├── README.md
└── STACK.md            # full stack + techniques

技術スタックと手法

Python 3.11 · MCP · PyThaiNLP newmm · tiktoken · Ollama（任意）· SQLite · hatchling · pytest。

各モードの手法（TF-IDF スコアリング、埋め込みの中心性、カスケードパイプライン、コンテンツルーティング、グレースフルデグラデーション）については、STACK.md に記載されています。

テスト

.\.venv\Scripts\python.exe -m pytest tests/ -q

テストスイートでは、タイ語 NLP、MCP ツールのコントラクト、すべてのモード（Ollama へのフォールバック経路を含む）、ラウンドトリップ検証の保証、自動圧縮フック（プロセス間の取得を含む）を網羅しています。

品質はモデルが必要なため、別途測定します。bench\eval_qa.py を実行してください（Claude は今でも正しく答えられる？を参照）。デフォルトではローカルの claude CLI で実行されます。Anthropic API キーがある場合は --backend api を指定できます。--dry-run と --limit を使うと、手軽に確認できます。全件実行すると Claude を約 170 回呼び出します。

リリース

1. pyproject.toml と server.json（その中の両方の箇所）の version を更新します。
2. 対応するタグをプッシュします：git tag v0.2.0 && git push origin v0.2.0。publish ワークフローがテスト、ビルドを行い、トークンなしの信頼された公開を通じて PyPI にアップロードします。
3. MCP レジストリにリリースを登録します：mcp-publisher login github を実行してから、mcp-publisher publish を実行します（server.json を読み込みます。この README の先頭にある mcp-name コメントは、PyPI パッケージがその名前に属することを証明します）。

プラグインにはこれらの作業は不要です。リポジトリからインストールされ、コミットごとに更新されます。

ロードマップ

• QA 評価を 8 件のドキュメント以上に拡大する（長いツール出力、ログ、コードの混在など）。その結果を根拠に auto → semantic などのデフォルトを変更する前に実施します。
• mcp 2.x に移行する（現時点では <2 に固定しています。2.x では Server.list_tools が削除されました）。
• Typhoon 2.1 の抽象化を任意で追加する（Ollama のテンプレート修正待ち）。
• コンテンツごとに target_ratio を適応させる。
• PyPI パッケージ (sarup) と MCP レジストリの掲載情報（io.github.PHUICMT/sarup）を公開済みです。
• Claude Code プラグインとしてインストール可能です。

ライセンス

MIT