MinishLab/semble

Semble – AIコーディングエージェント向けの高速でトークン効率的なコード検索

何であるか – Sembleは、大規模言語モデルベースのコーディングアシスタント（Claude Code、Cursor、Codex、OpenCodeなど）がリポジトリから必要なコードスニペットを正確に取得できるPythonライブラリ／CLI／MCP互換サーバーです。これは、単純な「grep + 全ファイル読み込み」アプローチと比較して約99％のトークンを削減しつつ、137Mパラメータのコード専用トランスフォーマーと同等の検索品質を維持します。

なぜ重要か – エージェントはしばしば unfamiliar なコードベースを探索する必要があります。モデルのコンテキストに全ファイルを読み込むのは高コストで遅いです。Sembleはリポジトリを約0.5秒でインデックス化し、CPU上で自然言語クエリを約1msで応答するため、エージェントはAPIキー、GPU、外部サービスなしに即座に必要なコード断片を取得できます。

主な機能

高速性 – 平均的なリポジトリを約500msでインデックス化；クエリ遅延は約1ms（CPUのみ）。同等のトランスフォーマー基盤のリトリーバーと比較して、インデックス化が340倍高速、クエリが17倍高速。
正確性 – 著者によるベンチマークでNDCG@10 = 0.854。137Mパラメータモデルと同等の性能。
トークン効率 – 必要なスニペットのみを返すため、全ファイルを読む場合に比べて約99％のトークンを節約。
ゼロセットアップ – GPU不要、APIキー不要。pip/uvでインストール可能。
MCPサーバー – 任意のMCP互換エージェント向けにsearchとfind_relatedをネイティブツールとして公開。
ローカル・リモートリポジトリ – ファイルシステムパスまたはGit URLをサポート。
細かい制御 – .gitignoreと専用の.sembleignoreで、ファイルや拡張子の含む／除外を指定可能。
キャッシュと統計 – インデックスとトークン節約統計をキャッシュ。semble savingsで回避されたトークン数を確認可能。

クイックスタート（CLI）

# ツールのインストール（uvが必要）
uv tool install semble
semble install          # インタラクティブモード – エージェントと統合タイプを選択

# ローカルリポジトリでの基本検索
semble search "authentication flow" ./my-project

# リモートリポジトリの検索（必要に応じてクローン）
semble search "save model to disk" https://github.com/MinishLab/model2vec

# 結果数制限、スニペット行数制限、ドキュメント/設定ファイルの検索
semble search "deployment guide" ./my-project --content docs --top-k 5 --max-snippet-lines 10

semble uninstallで統合を削除、semble clear ...でキャッシュをクリア可能。

Pythonライブラリとしての使用

from semble import ContentType, SembleIndex

# インデックスの構築（初回はキャッシュ）
idx = SembleIndex.from_path("./my-project", content=ContentType.CODE)
# またはドキュメント/設定を含める
# idx = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS])

# 自然言語またはコードクエリ
results = idx.search("save model to disk", top_k=3)
for r in results:
    print(r.chunk.file_path, r.chunk.start_line, r.chunk.content[:120])

# 特定の場所に類似するコードを検索
related = idx.find_related(results[0], top_k=3)

このライブラリはカスタムツールの構築や、自社アプリケーション内に検索機能を直接埋め込むのに便利です。

MCPサーバーモード

MCPツールとしてインストールすると、エージェントは以下のツールを呼び出せます：

ツール	説明
`search`	リポジトリ（ローカルパスまたはGit URL）上で自然言語またはコードクエリを実行。
`find_related`	ファイルパスと行番号を指定し、意味的に類似したコード断片を返す。
セットアップ手順は `docs/installation.md#mcp-server` を参照。

内部の仕組み

チャンク分割 – tree-sitter を使ってコードに適したチャンクにファイルを分割。
二重リトリーバー –
- Model2Vec 静的埋め込み（potion-code-16M-v2）で意味的類似度を算出。
- BM25 で識別子やAPI名に対する高速な語彙マッチングを実行。
融合 – 両方のリトリーバーのスコアをReciprocal Rank Fusionで統合。
再ランク付け – 適応的重み付け、定義の優先度、識別子のステム一致、ファイルの整合性ボーナス、ノイズペナルティで最終順位を最適化。
キャッシュ – インデックスはディスクに保存。ファイル変更時にインクリメンタル更新が行われ、完全再構築を回避。
モデルの柔軟性 – 必要に応じてSEMBLE_MODEL_NAMEをカスタムModel2Vecモデルに設定可能。

すべての処理は1つのCPUコア上でミリ秒単位で完了します。埋め込みモデルは静的（クエリ時にトランスフォーマーの順伝播なし）であるためです。

ベンチマーク（報告値）

品質 – 63リポジトリ、19言語でNDCG@10 = 0.854。137MパラメータのCodeRankEmbedモデルと同等。
速度 – インデックス化が340倍高速、クエリが17倍高速。トランスフォーマーベースラインと比較。
トークン節約 – grep+readベースラインと比較して約99％のトークン削減。2kトークンで97％のリコールを達成。一方、grep+readは85％リコール達成に約100kトークンが必要。詳細は benchmarks/README.md を参照。

インストールとキャッシュ場所

uv（uv tool install semble）またはpip install sembleでインストール。
キャッシュディレクトリはOSのキャッシュ場所（Linuxでは~/.cache/sembleなど）をデフォルト。SEMBLE_CACHE_LOCATIONで上書き可能。
モデルファイルは標準のHugging-Faceキャッシュ（~/.cache/huggingface）に保存。
1MiB以上のファイルはデフォルトでスキップ。SEMBLE_MAX_FILE_BYTESで調整可能。

ライセンスと引用

ライセンス：MIT（許容性高く、商用利用可）。
引用：学術的な使用には、提供されたBibTeXエントリ（Zenodo DOI 10.5281/zenodo.19785932）を使用してください。

まとめ

SembleはAIコーディングエージェントに、ローカルで高速かつトークンコストが低いコード取得手段を提供し、高コストなAPI呼び出しや大容量コンテキストウィンドウの必要性を排除します。CLI、Pythonライブラリ、MCPサーバーとして即時利用可能で、LLM駆動の開発ワークフローに実用的な追加要素です。