Semantic Search

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

2つのサーバーモードをサポートしています：

MCPモード — Claude Code統合用
RESTモード — OpenClaw、スクリプト、HTTPクライアント用

機能

sentence-transformersを使用したセマンティック検索
重複/類似ノートの検出
ファイル監視によるインデックスの自動更新
マルチディレクトリ対応
インラインタグ抽出 (#tag-name)

インストール

CPUのみ（推奨 — 約5GB節約、一般的なボルトサイズではパフォーマンスは同等）:

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

CUDAを使用する場合（専用GPUがある場合のみ）:

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

アップグレード

uv tool upgrade semantic-search

サーバーモード

MCPモード (Claude Code用)

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 serve

利用可能なツール:

search_related(query, top_k=5) — 意味的に関連するノートを検索
check_duplicates(file_path) — 重複/類似ノートを検出

RESTモード (OpenClaw/HTTP用)

CONTENT_PATH=/path/to/vault semantic-search-mcp serve --mode rest --port 8321

エンドポイント:

エンドポイント	メソッド	説明
`/search?q=...&top_k=5`	GET	セマンティック検索
`/duplicates?file=...&threshold=0.85`	GET	重複ノートの検索
`/health`	GET	インデックス統計を含むヘルスチェック
`/reindex`	GET/POST	インデックスの強制再構築

クエリ例:

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

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

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

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

2つのバイナリ

バイナリ	目的
`semantic-search-mcp`	サーバーモード — `serve` (MCPまたはREST)、および `search` と `duplicates`
`semantic-search`	CLIのみ — `search` と `duplicates` のワンショットコマンド、`serve` はなし

設定

環境変数

変数	説明	デフォルト
`CONTENT_PATH`	インデックス対象ディレクトリ（複数指定はカンマ区切り）	`./content`
`LOG_LEVEL`	ログレベル (DEBUG, INFO, WARNING, ERROR)	`INFO`

複数ディレクトリ

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

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

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

仕組み

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

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

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

コンポーネント	重み	メモ
ファイル名	3x
Frontmatter `title`	3x
Frontmatter `tags`	2x	インラインタグとマージ
Frontmatter `aliases`	2x
インラインタグ (`#tag`)	2x	本文から抽出
最初のH1見出し	2x
本文コンテンツ	1x	最初の500単語

開発

# 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 を参照してください。

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Appeared in Searches

A search for similar notes

Semantic Search MCP