Semantic Search

Markdownファイルに対するセマンティック検索。キーワードだけでなく、意味で関連するノートを見つけます。新しいノートを作成する前に重複を検出します。

2つのサーバー転送方式をサポートしています：

• stdio MCP — Claude Code統合用（セッションごとに1プロセス）

• HTTP — 1つのポートでMCP-over-HTTPとRESTを統合。すべてのクライアントで共有される1つのウォームプロセス

機能

• sentence-transformersを使用したセマンティック検索

• 重複/類似ノートの検出

• ファイル監視による自動インデックス更新

• マルチディレクトリ対応

• インラインタグ抽出 (#tag-name)

インストール

CPUのみのインストール — macOS（すべてのMac、Apple SiliconまたはIntel）およびNVIDIA GPUを搭載していないLinux/Windowsに推奨。約5GBのCUDAバイナリを節約します。macOSでは、Apple GPU (MPS) がPyTorchの組み込みMPSバックエンドを介して自動的に検出・使用されます。「CPU」というラベルはCUDAが存在しないことのみを指しており、実行時の計算デバイスを指すものではありません。

uv tool install --index https://download.pytorch.org/whl/cpu \
  git+https://github.com/bborbe/semantic-search

CUDAインストール — 専用のNVIDIA GPUを搭載したLinux/Windows専用。macOSには適用されません（MacではNVIDIA CUDAはサポートされていません）。

uv tool install git+https://github.com/bborbe/semantic-search

アップグレード

uv tool upgrade semantic-search

サーバーモード

stdio MCP (セッションごとのClaude Code)

Claude Codeセッションごとに1つのプロセスを生成します。シンプルですが、各セッションが約400MB〜1GBのモデルコピーを個別に読み込みます。

claude mcp add -s project semantic-search \
  --env CONTENT_PATH=/path/to/vault \
  -- \
  uvx --from git+https://github.com/bborbe/semantic-search semantic-search-mcp

利用可能なツール:

• search_related(query, top_k=5) — 意味的に関連するノートを検索

• check_duplicates(file_path) — 重複/類似ノートを検出

HTTP (すべてのクライアントで共有)

単一の長時間実行プロセスが、/mcp でMCP-over-HTTPを、/search、/duplicates、/health、/reindex でRESTを提供します。すべてのClaude CodeセッションとRESTクライアントが1つのウォームインデクサーを共有します。

CONTENT_PATH=/path/to/vault semantic-search-http --host 127.0.0.1 --port 8321

MCP設定を介してClaude Codeから接続します：

{
  "mcpServers": {
    "semantic-search": {
      "type": "http",
      "url": "http://127.0.0.1:8321/mcp"
    }
  }
}

RESTエンドポイント:

クエリ例:

# Search
curl 'http://127.0.0.1:8321/search?q=kubernetes+deployment'

# Find duplicates
curl 'http://127.0.0.1:8321/duplicates?file=notes/my-note.md'

# Health check
curl 'http://127.0.0.1:8321/health'

バックグラウンド実行

本番環境のような用途では、semantic-search-http をバックグラウンドサービスとして実行し、すべてのClaude Codeセッション（およびRESTクライアント）が1つのウォームプロセスを共有できるようにします。

クイック例 (macOS):

launchctl load ~/Library/LaunchAgents/com.github.bborbe.semantic-search-http.plist

クイック例 (Linux):

systemctl --user enable --now semantic-search-http.service

CLIコマンド

サーバーを実行しないワンショットコマンド:

# Search
CONTENT_PATH=/path/to/vault semantic-search search "kubernetes deployment"

# Find duplicates
CONTENT_PATH=/path/to/vault semantic-search duplicates path/to/note.md

バイナリ

設定

環境変数

複数ディレクトリ

パスをカンマで区切ることで、複数のディレクトリをインデックス化できます：

CONTENT_PATH=/path/to/vault1,/path/to/vault2,/path/to/docs

すべてのディレクトリは一緒にインデックス化され、1つの統合インデックスとして検索されます。

仕組み

初回実行時に小さな埋め込みモデル（約90MB）をダウンロードし、Markdownファイルをインデックス化します（一般的なボルトで1秒未満）。ファイルシステム監視により、ファイル変更時にインデックスが自動更新されます。

インデックス化されるコンテンツ

各Markdownファイルは、重み付けされたコンポーネントでインデックス化されます：

開発

# Clone
git clone https://github.com/bborbe/semantic-search
cd semantic-search

# Install dev dependencies
make install

# Run checks
make check

# Run tests
make test

ライセンス

BSD 2-Clause License — LICENSE を参照。