概要

Semble はエージェント向けの超高速・高精度なコード検索ライブラリ。 grep+read より約98%トークン効率が良く、全工程がCPUのみで完結。 Claude Code, Cursor, Codex, OpenCode 等のMCP対応エージェントで即利用可能。 インデックス作成・検索ともに極めて高速（大規模リポジトリでも秒単位）。 APIキー・GPU・外部サービス不要のゼロセットアップ。

Semble：エージェントのための超高速コード検索

• Semble は、エージェントが必要とするコードスニペットを即座に返すコード検索ライブラリ
• grep+read 方式と比べ、約98%少ないトークン消費で必要な文脈のみ返却
• インデックス作成 ・ 検索 ：平均250ms/1.5ms（全てCPU上で動作）
• MCPサーバー または Bashツール として利用可能
• APIキー不要、 GPU不要、 外部サービス不要 のシンプル構成

主な特徴

• インデックス作成速度：平均リポジトリで約250ms
• 検索応答速度：1.5ms（CPUのみ）
• トークン効率： grep+read 比で約98%削減
• 精度：NDCG@10 = 0.854（コード特化型トランスフォーマーモデルの99%相当）
• MCPサーバーとしてClaude Code, Cursor, Codex, OpenCode等に即時連携
• ローカル/リモート（git URL）両対応、変更検知時は自動再インデックス

セットアップと利用方法

• MCPサーバーとして利用
  • uv パッケージが必要
  • Claude Code: claude mcp add semble -s user -- uvx --from "semble[mcp]" semble
  • Codex, OpenCode, Cursor: 各設定ファイルにコマンド・パラメータを追加
• Bash統合
  • pip install semble または uv tool install sembleでインストール
  • AGENTS.mdやCLAUDE.mdにコード検索スニペットを追記
  • 例：
    • semble search "authentication flow" ./my-project
    • semble find-related src/auth.py 42 ./my-project
• CLIとしても単独利用可能（MCP不要）

ワークフロー例

• semble searchで関連コードチャンクを高速抽出
• 返却されたチャンクで文脈不足の場合のみファイル全体確認
• 必要に応じてsemble find-relatedで関連実装を探索
• 完全一致や文字列確認のみgrep併用

機能詳細

• search ：自然言語またはコードクエリでコードベース検索
• find_related ：指定ファイル・行番号に類似するコードチャンク抽出
• savings ：トークン節約量を可視化（期間別・コール種別で集計）
• 更新 ：pip install --upgrade sembleやuv tool upgrade sembleで簡単アップデート
• Python API ：
  • SembleIndex.from_path("./my-project")でローカルディレクトリをインデックス化
  • SembleIndex.from_git("https://github.com/MinishLab/model2vec")でリモートリポジトリも対応
  • index.search("save model to disk", top_k=3)で自然言語検索
  • index.find_related(results[0], top_k=3)で類似コード抽出

仕組み・アルゴリズム

• Chonkie でファイルをコード認識型チャンクに分割
• Model2Vec（potion-code-16M） による静的埋め込み＋ BM25 による識別子・API名のレキシカルマッチ
• RRF（Reciprocal Rank Fusion） で融合し、コード特有のシグナルで再ランク
  • シンボル定義の優先表示
  • 識別子ステムによる追加重み付け
  • 複数チャンク一致時のファイル単位ブースト
  • テスト・レガシー・ダミーコードのノイズ低減
• 全処理がCPUで完結、ミリ秒単位のレスポンス

ベンチマーク・トークン効率

• 63リポジトリ・19言語・約1250クエリで評価
  • Semble：NDCG@10=0.854、インデックス263ms、クエリ1.5ms
  • CodeRankEmbed Hybrid（137Mパラメータ）と比較し99%の精度・218倍の速度
• トークン削減例：
  • grep+read：100kトークン必要→Sembleは2kトークンで94%リコール達成
  • 実際の節約量はsavingsコマンドで確認可能

ライセンス・引用

• MITライセンス
• 論文・研究利用時の引用形式：

  @software{minishlab2026semble,
    author = {{van Dongen}, Thomas and Stephan Tulkens},
    title = {Semble: Fast and Accurate Code Search for Agents},
    year = {2026},
    publisher = {Zenodo},
    doi = {10.5281/zenodo.19785932},
    url = {https://github.com/MinishLab/semble},
    license = {MIT}
  }
  

参考リンク・フィードバック

• GitHub: https://github.com/MinishLab/semble
• ベンチマーク: https://github.com/MinishLab/semble/tree/main/benchmarks
• モデル: https://huggingface.co/minishlab/potion-code-16M
• フィードバック・質問：IssueまたはGitHub Discussionsで受付