Semble

uv tool upgrade semble   # upgrade
uv cache clean semble    # for MCP users (restart your MCP client after)

サンドボックス環境またはスクリプト環境では、--agent と、必要に応じて --type を指定してプロンプトを省略できます。

semble install --agent claude --type mcp subagent --yes

--agent には1つ以上のエージェント ID（例：claude、codex、pi）を指定できます。--type には mcp、instructions、subagent、all（デフォルト：all）を指定できます。--yes は確認プロンプトを省略します（完全な非対話型実行には --agent が必要です）。

Semble は .gitignore と .sembleignore ファイルを読み取り、インデックス化するファイルを決定します。どちらのファイルも標準的な gitignore 構文を使用し、パターンは統合されます。.sembleignore を使えば、.gitignore に手を加えずに Semble 固有のルールを追加できます。ルールは再帰的に適用されるため、サブディレクトリ内の .sembleignore はそのサブツリーに適用されます。

ファイルを除外する： .gitignore と同じ方法でパターンを追加します。

# .sembleignore
generated/     # exclude generated dir
*.pb.go.       # exclude Go protobuf files

デフォルト以外の拡張子を含める： 拡張子のパターンの先頭に ! を付けると、Semble がデフォルトではインデックス化しないファイルも強制的に含められます。

# .sembleignore
!*.proto       # include Protobuf files
!*.cob         # include COBOL files

semble file-types を実行すると、コンテンツタイプごとにインデックス化される拡張子を確認できます。一覧にない拡張子（.json や .csv などのデータファイルを含む）はデフォルトではインデックス化されませんが、上記のように ! パターンを使って強制的に含められます。

また Semble は、無視ファイルの設定にかかわらず、よく知られたソース以外のディレクトリ（node_modules/、.venv/、dist/、build/、__pycache__/ など）を常にスキップします。

semble savings を実行すると、すべての検索を通じて Semble が節約したトークン数を確認できます。

semble savings

  Semble Token Savings
  ════════════════════════════════════════════════════════════════════════

  Total saved:  ~714.2M tokens  (94%)
  Total calls:  14.3k
  Efficiency:  ███████████████████████░  94%

  By Period
  ────────────────────────────────────────────────────────────────────────
  Period             Calls           Saved  Ratio
  ────────────────────────────────────────────────────────────────────────
  Today                198    ~1.4M tokens  ███████████████████████░  95%
  Last 7 days        13.1k  ~707.2M tokens  ███████████████████████░  94%
  All time           14.3k  ~714.2M tokens  ███████████████████████░  94%

  By Call Type
  ────────────────────────────────────────────────────────────────────────
  #     Call type            Calls  Share
  ────────────────────────────────────────────────────────────────────────
  1.    search               14.1k  ████████████████    99%
  2.    find_related           205  █░░░░░░░░░░░░░░░     1%
  ════════════════════════════════════════════════════════════════════════

節約量は次のように計算されます。呼び出しごとに、Semble は返されたチャンクを含む一意なファイルの合計文字数と、返されたスニペットの文字数を記録します。推定節約トークン数は (file chars − snippet chars) / 4（1 トークンあたり 4 文字）です。これは控えめな推定です。ベースラインでは、コーディングエージェントが不慣れなコードを調査する際によく行う方法である、該当ファイル全体の読み込みを想定しています。

デフォルトでは、Semble の節約統計と保存済みインデックスは、OS のキャッシュフォルダー（macOS では ~/Library/Caches/semble/、Linux では ~/.cache/semble/、Windows では %LOCALAPPDATA%\semble\Cache\）に保存されます。保存先を変更するには、環境変数 SEMBLE_CACHE_LOCATION に、保存先となるキャッシュフォルダーのフルパス（例：~/my-folder/my-caches/semble）を指定します。

Semble は、プログラムからアクセスするための Python ライブラリとしても使用できます。カスタムツールの構築や、検索機能を独自のコードに直接統合する場合に便利です。

from semble import ContentType, SembleIndex

# Index a local directory (code only, the default)
index = SembleIndex.from_path("./my-project")

# Index docs and prose (markdown, rst, etc.)
index = SembleIndex.from_path("./my-project", content=ContentType.DOCS)

# Index everything (code, docs, and config)
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS, ContentType.CONFIG])

# Index code and docs together
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS])

# Index a remote git repository
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# Merge indexes from several repos into one (chunk paths are prefixed with the repo name)
index = SembleIndex.merge([("./service-a", SembleIndex.from_path("./service-a")), ("./service-b", SembleIndex.from_path("./service-b"))])

# Search the index with a natural-language or code query
results = index.search("save model to disk", top_k=3)

# Find code similar to a specific result
related = index.find_related(results[0], top_k=3)

# Each result exposes the matched chunk
result = results[0]
result.chunk.file_path   # "model2vec/model.py"
result.chunk.start_line  # 127
result.chunk.end_line    # 150
result.chunk.content     # "def save_pretrained(self, path: PathLike, ..."

多数のファイルをインデックスする必要がある場合、CLI と MCP サーバーは 4 つのワーカープロセスでファイルをチャンクに分割します（SEMBLE_INDEX_WORKERS で数を設定でき、0 で無効になります）。Python API ではデフォルトで無効です。有効にするには、SEMBLE_INDEX_WORKERS を設定し、各ワーカーがスクリプトを再インポートするため、if __name__ == "__main__": ブロック内から Semble を呼び出してください。

• 適応的な重み付け。 記号のようなクエリ（Foo::bar、_private、getUserById）では字句検索の重みを高め、自然言語のクエリでは意味検索と字句検索のバランスを保ちます。
• 定義のブースト。 クエリされたシンボルを定義するチャンク（class、def、func など）は、単にそのシンボルを参照するだけのチャンクより上位にランク付けされます。
• 識別子の語幹。 クエリのトークンを語幹化し、チャンク内の識別子の語幹と照合して、一致するものを含むチャンクに追加の重みを与えます。たとえば、parse config を検索すると、parseConfig、ConfigParser、config_parser を含むチャンクがブーストされます。
• ファイルの一貫性。 同じファイルの複数のチャンクがクエリに一致する場合、そのファイルをブーストし、文脈から外れた単一チャンクではなく、ファイル全体の関連性が結果の上位に反映されるようにします。
• ノイズのペナルティ。 テストファイル、compat/／legacy/ のシム、サンプルコード、.d.ts の宣言スタブは順位を下げ、正規の実装が先に表示されるようにします。