语义搜索

对 Markdown 文件进行语义搜索。通过含义而非仅仅关键词查找相关笔记。在创建新笔记前检测重复内容。

支持两种服务器模式：

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（仅限拥有独立显卡时）：

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

两个二进制文件

二进制文件	用途
`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

所有目录会被合并索引，并作为一个统一的索引进行搜索。

工作原理

首次运行时会下载一个小型的嵌入模型（约 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。

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