Obsidian Hybrid Search

Obsidian 混合搜索

你的 Obsidian 知识库已经记录了你最好的思考。Obsidian Hybrid Search 让这些思考更容易查找、重用，并融入 AI 辅助工作。

它为你的知识库提供一个检索引擎，以及三种实用的使用方式。原生 Obsidian 插件 在写作时为你提供快速搜索、预览、相似笔记、链接发现和图谱视图。MCP 服务让 AI Agent 能够通过工具调用搜索和阅读你的笔记。CLI 则为高级用户提供同一引擎，用于索引、筛选、重排、阅读和脚本编写。

该搜索功能理解真实知识库的构建方式。它结合语义搜索、BM25 全文搜索、模糊标题和别名匹配、标签、文件夹、frontmatter、双向链接、反向链接和相似笔记查找。你可以按想法、短语、标题、关系或元数据搜索，而不必记住自己写下的确切词句。

这让 Obsidian 成为更强大的个人知识系统，也是开展 AI 工作的更好起点。Agent 可以从你的笔记出发，从源文件中提取带引用的上下文，追踪相关资料，并使用你已信任的知识。OHS 默认在本地运行，使用 SQLite、FTS5、sqlite-vec、RRF 排序，以及可选的 OpenAI 兼容嵌入 API。

搜索质量

在 Obsidian Help 知识库上评估（171 篇笔记、58 个查询、本地模型）：

	OHS（本项目）	qmd
nDCG@5	0.733	0.659
MRR	0.788	0.665
Hit@1	0.724	0.500
平均查询时间	571 ms ¹	754 ms ²
模型下载大小	~117 MB	~2.2 GB

¹ CPU（Apple Silicon），混合模式，不进行重排。² GPU（Apple Silicon Metal），LLM 查询扩展 + 重排。

OHS 使用 Xenova/multilingual-e5-small。如何复现 → · 完整基准测试 →

真实知识库基准测试

OHS 也在 Andy Matuschak 的公开 evergreen 笔记上进行评估。这些笔记被转换成 Obsidian 知识库，使用基于标题的笔记文件名、frontmatter 中的源 URL、本地附件，以及分布在 1,357 篇笔记中的 5,000+ 个内部笔记链接。

经过筛选的标准答案集包含 78 个由人工判断的查询，涵盖已知内容查找、释义、引文片段、模糊主题、引文查找和多笔记证据。

使用默认的本地嵌入模型时，OHS 在这个密集的笔记网络中表现出色。

指标	值
nDCG@5	0.722
nDCG@10	0.753
MRR	0.874
Hit@1	0.795
Hit@5	0.974
Recall@10	0.972
AllRel@10	0.949

该基准测试评估了在高度互联的真实知识库中进行检索的能力，其中也包括不会简单重复笔记标题的查询。

结果 JSON · 复现与解读 →

大规模记忆基准测试

为了测试在更大的公开数据集上的检索效果， LongMemEval-S 已转换为一个包含 22,419 条笔记的 Obsidian 风格知识库，其中有 470 个检索查询。使用 baai/bge-m3 嵌入模型时，OHS 对包含答案的笔记进行了有效排序：

指标	数值
nDCG@5	0.895
MRR	0.920
Hit@1	0.889
Hit@5	0.968
Recall@10	0.950
AllRel@10	0.904

在此基准测试中，每个查询都使用 LongMemEval 提供的 haystack 作为搜索范围。这样既能让结果可复现、便于逐个检查查询，也能检验系统在大型生成式记忆库中的检索能力。

结果 JSON · 复现与解读 →

功能

• 混合搜索
  • BM25 + 模糊标题匹配 + 语义嵌入，使用 RRF 融合
• 别名搜索
  • 将 frontmatter 中含有 aliases: 的笔记编入索引，并支持通过任意别名搜索；在 BM25（权重 5×）和模糊标题评分中提高别名匹配的权重
• 四种搜索模式
  • 针对文本查询的 hybrid、semantic、fulltext、title
• 相似笔记查找
  • 传入 --path，使用已存储的文本块嵌入查找语义相关的笔记；若不可用，则回退到标题 + 内容匹配
• 图遍历
  • --path --related 按可配置的深度显示链接的笔记；使用 --direction outgoing|backlinks|both 筛选
• 链接与反向链接
  • 每个结果都包含外链和反向链接
• 范围筛选
  • 限定一个或多个子文件夹；支持多个值和排除项（-notes/dev/）
• 标签筛选
  • 按一个或多个标签筛选；支持多个值和排除项（-category/cs）
• 摘要控制
  • --snippet-length 设置上下文窗口；摘要为空时始终回退为笔记内容
• 扩展输出
  • --extended 会在 CLI 表格中添加 TAGS/ALIASES 列，显示 frontmatter 标签（#tag）和别名
• 增量索引
  • 仅重新索引已更改的文件；实时监视编辑
• 多查询分发
  • 一次传入多个查询（ohs "q1" "q2" 或 MCP 中的 queries[]）；结果通过 RRF 合并，因此在任一查询中排名靠前的笔记都会排到前面；当笔记使用的词汇可能与查询不同时，此功能尤其有用
• 交叉编码器重排
  • --rerank 使用 gte-multilingual-reranker-base 重新评估结果（ONNX int8，一次性下载约 341 MB）；可提升概念类和多语言查询的精确度；在多查询合并后应用
• 本地嵌入
  • 通过 @huggingface/transformers 离线运行（无需 API 密钥）；默认模型：Xenova/multilingual-e5-small，支持 100 多种语言
• 远程嵌入
  • OpenAI 兼容 API（OpenRouter、Ollama 等）
• 读取笔记
  • read 根据相对于知识库的路径读取一条或多条笔记；返回包含标题、别名、标签、链接和反向链接的完整内容；路径未匹配时返回最相近的 3 条建议
• 忽略模式
  • 排除文件夹、扩展名或特定文件
• Obsidian 插件
  • 由同一 CLI 驱动的 Obsidian 原生搜索弹窗；参见 obsidian-hybrid-search-plugin

安装

npm install -g obsidian-hybrid-search

CLI 用法

快速开始

建议在 ~/.zshrc 或 ~/.bashrc 中设置一次 OBSIDIAN_VAULT_PATH。这样就可以从任意目录运行 CLI。

export OBSIDIAN_VAULT_PATH="/path/to/your/vault"

打开新的终端并为知识库创建一次索引。

ohs reindex

现在可以从任意目录进行搜索。

ohs "zettelkasten"

在知识库中运行

也可以在知识库内的任意目录中运行 CLI，而无需设置环境变量。它会向上查找最近的 .obsidian/ 文件夹，以确定知识库根目录。

cd /path/to/your/vault
ohs reindex
ohs "zettelkasten"

在知识库外部运行时，请设置 OBSIDIAN_VAULT_PATH，或显式传入 --db /path/to/vault/.obsidian-hybrid-search.db。

可选的远程嵌入

默认情况下，CLI 使用本地 Xenova/multilingual-e5-small 模型。它无需 API 密钥即可离线运行，首次使用时会下载约 117 MB，并支持 100 多种语言。

如需使用远程 API，请将相关设置添加到 shell 配置文件中。

export OPENAI_API_KEY="sk-..."

# Override the default API base for another provider
# export OPENAI_BASE_URL="https://openrouter.ai/api/v1"  # OpenRouter
# export OPENAI_BASE_URL="http://localhost:11434/v1"     # Ollama (no key needed)
# export OPENAI_BASE_URL="http://localhost:1234/v1"      # LM Studio (no key needed)

# Override the default text-embedding-3-small model
# export OPENAI_EMBEDDING_MODEL="text-embedding-3-small"

搜索模式

CLI 支持四种搜索模式：hybrid、fulltext、semantic 和 title，还支持遍历关联笔记的图谱。以下命令展示了如何使用这些模式、应用筛选条件、重新排序结果以及控制输出。

# Hybrid search (default)
ohs "zettelkasten atomic notes"

# Fulltext BM25 search
ohs "permanent notes" --mode fulltext

# Fuzzy title search (fast, typo-tolerant)
ohs "zettleksten" --mode title

# Semantic / vector search
ohs "how to build a knowledge graph" --mode semantic

# Limit results and set a score threshold
ohs "productivity systems" --limit 5 --threshold 0.3

# Restrict to a subfolder
ohs "daily review" --scope notes/periodic/
ohs "daily review" --folder notes/periodic/    # alias for --scope

# Restrict to multiple subfolders (OR)
ohs "productivity" --scope notes/pkm/ --scope notes/2024/

# Exclude a subfolder
ohs "programming" --scope notes/ --scope -notes/archive/

# Filter by tag
ohs "productivity" --tag pkm
ohs "machine learning" --tag note/basic/primary

# Filter by multiple tags (AND include, exclude with -)
ohs "learning" --tag pkm --tag work

# Filter by frontmatter / properties (exact match, case-insensitive)
ohs "notes" --frontmatter status:todo
ohs "notes" --prop priority:high          # --prop is alias for --frontmatter

# Filter by multiple frontmatter fields (AND)
ohs "notes" --frontmatter status:todo --frontmatter priority:high

# Exclude by frontmatter value
ohs "notes" --frontmatter -status:done

# Filter-only mode: no query, just filters (returns all matching notes sorted by title)
ohs --frontmatter status:todo
ohs --folder notes/2024/
ohs --tag pkm
ohs --frontmatter status:done --tag archived

# Unlimited results in filter-only mode (default limit is 10)
ohs --folder notes/ --limit 0

# Find semantically similar notes
ohs --path notes/pkm/zettelkasten.md

# Graph traversal: show notes linked to/from this note
# Results show depth: -1/-2 = backlinks, 0 = source, +1/+2 = outgoing links
ohs --path notes/pkm/zettelkasten.md --related
ohs --path notes/pkm/zettelkasten.md --related --depth 2

# Only outgoing links (what this note references)
ohs --path notes/pkm/zettelkasten.md --related --direction outgoing

# Only backlinks (who references this note)
ohs --path notes/pkm/zettelkasten.md --related --direction backlinks

# Traverse standard Markdown note links instead of Obsidian wikilinks
ohs --path notes/pkm/zettelkasten.md --related --link-type markdown

# Traverse both wikilinks and standard Markdown note links
ohs --path notes/pkm/zettelkasten.md --related --link-type all

# Longer context around each link
ohs --path notes/pkm/zettelkasten.md --related --snippet-length 500

# Rerank results with a cross-encoder model (improves precision, ~1-3s extra latency)
# Downloads gte-multilingual-reranker-base ONNX (~341 MB) on first use, cached in ~/.cache/huggingface/
ohs "zettelkasten atomic notes" --rerank

# Show tags and aliases alongside results
ohs "zettelkasten" --extended

# JSON output (for scripting)
ohs "spaced repetition" --json

# Output only paths (one per line) — useful for piping into read
ohs --frontmatter id:OHS-4 --only-paths
ohs read ${(f)"$(ohs search --frontmatter status:todo --only-paths)"}  # zsh: read all matching notes

# Output absolute filesystem paths
ohs "zettelkasten" --only-absolute-paths

# Open results in Obsidian (each in a new tab)
ohs "zettelkasten" --open

# Reindex the vault
ohs reindex
ohs reindex --threads 4  # Limit local CPU inference to 4 threads

# Force full reindex
ohs reindex --force

# Reindex a single file
ohs reindex notes/pkm/zettelkasten.md

# Retry only the notes whose chunks failed to embed
ohs reindex --errors

# Show indexing status
ohs status

# Show recent indexing activity
ohs status --recent

# Show chunks that failed to embed
ohs status --errors

# Read a note by path (outputs body content without frontmatter)
ohs read notes/pkm/zettelkasten.md

# Read raw file from vault (with frontmatter, like cat)
ohs read notes/pkm/zettelkasten.md --raw

# Read multiple notes (separator between each)
ohs read notes/pkm/zettelkasten.md notes/pkm/evergreen-notes.md

# Cap content length
ohs read notes/pkm/zettelkasten.md --snippet-length 2000

# Structured output with all metadata
ohs read notes/pkm/zettelkasten.md --json

Shell 别名

将以下内容添加到 ~/.zshrc 或 ~/.bashrc，以便快速使用：

alias ohss='ohs --mode semantic'
alias ohst='ohs --mode title'
alias ohsf='ohs --mode fulltext'
alias ohsr='ohs read'
alias ohsi='ohs reindex'
alias ohsst='ohs status'

然后重新加载（source ~/.zshrc）并使用：

ohs "zettelkasten"                        # hybrid search
ohss "how to build a knowledge graph"     # semantic
ohst "zettelkasten"                       # fuzzy title (typo-tolerant)
ohsf "permanent notes"                    # fulltext BM25
ohsr "notes/pkm/zettelkasten.md"          # read note by path
ohsi                                      # reindex vault
ohsst                                     # show status
ohsst --recent                            # show recent indexing activity
ohsst --errors                            # show chunks that failed to embed

输出示例

混合搜索会返回包含分数和摘要的表格。分数会根据相关性以不同颜色显示：

分数	颜色	含义
0.8 – 1.0	green	高度相关
0.5 – 0.8	yellow	中度相关
0.2 – 0.5	plain	有一定相关性
0.0 – 0.2	dim	相关性较低

┌───────┬───────────────────────────────┬────────────────────────────────────────────┐
│ SCORE │ PATH                          │ SNIPPET                                    │
├───────┼───────────────────────────────┼────────────────────────────────────────────┤
│  0.98 │ notes/pkm/zettelkasten.md     │ A note-taking method developed by Niklas   │
│       │                               │ Luhmann. Each note contains one atomic...  │
├───────┼───────────────────────────────┼────────────────────────────────────────────┤
│  0.72 │ notes/pkm/evergreen-notes.md  │ Evergreen notes are written to evolve over │
│       │                               │ time. Unlike fleeting notes, they are...   │
└───────┴───────────────────────────────┴────────────────────────────────────────────┘

使用 --extended 时，会添加 TAGS/ALIASES 列。标签前缀为 #，别名则按原样显示：

┌───────┬───────────────────────────────┬──────────────────┬──────────────────────────────┐
│ SCORE │ PATH                          │ TAGS/ALIASES     │ SNIPPET                      │
├───────┼───────────────────────────────┼──────────────────┼──────────────────────────────┤
│  0.98 │ notes/pkm/zettelkasten.md     │ #pkm             │ A note-taking method...      │
│       │                               │ ЗК               │                              │
│       │                               │ slip-box         │                              │
├───────┼───────────────────────────────┼──────────────────┼──────────────────────────────┤
│  0.72 │ notes/pkm/evergreen-notes.md  │ #pkm             │ Evergreen notes are written  │
│       │                               │ #writing         │ to evolve over time...       │
└───────┴───────────────────────────────┴──────────────────┴──────────────────────────────┘

标题模式会自动省略摘要列。

MCP 服务

大多数 AI 助手无法访问你的个人知识，只能处理你粘贴到对话中的内容。添加此服务后，任何兼容 MCP 的助手都能获得一个持久、可搜索的整个知识库索引。它会成为一次工具调用，而非复制粘贴式的交互：助手会像调用其他工具一样查询你的笔记，获取带摘要和链接的排序结果，并可按需浏览你的知识图谱。

将以下内容添加到 MCP 配置中（.mcp.json、claude_desktop_config.json，或客户端对应的配置文件）。

最简配置（本地嵌入，无需 API 密钥）

使用内置的 Xenova/multilingual-e5-small 模型。模型完全离线运行，支持 100 多种语言。首次运行时会下载约 117 MB。

{
  "mcpServers": {
    "obsidian-hybrid-search": {
      "command": "npx",
      "args": ["-y", "-p", "obsidian-hybrid-search@latest", "obsidian-hybrid-search-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

完整配置（OpenRouter）

{
  "mcpServers": {
    "obsidian-hybrid-search": {
      "command": "npx",
      "args": ["-y", "-p", "obsidian-hybrid-search@latest", "obsidian-hybrid-search-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_PREFIX": "myvault_",
        "OBSIDIAN_RESPECT_GITIGNORE": "true",
        "OBSIDIAN_IGNORE_PATTERNS": ".obsidian/**,templates/**,*.canvas",
        "OBSIDIAN_INCLUDE_PATTERNS": "private/notes/**",
        "OPENAI_API_KEY": "sk-or-v1-...",
        "OPENAI_BASE_URL": "https://openrouter.ai/api/v1",
        "OPENAI_EMBEDDING_MODEL": "openai/text-embedding-3-small"
      }
    }
  }
}

注意： 首次运行时，npx 会自动安装该软件包。忽略模式会保存在数据库中，并在之后每次启动时恢复，即使缺少环境变量也是如此。

共享 HTTP 服务

当多个 MCP 客户端需要共用一个长期运行的搜索／索引进程时，请使用此方式。

启动或复用后台服务：

OBSIDIAN_VAULT_PATH="/path/to/your/vault" ohs serve

默认情况下，serve 会通过 HTTP 启动 MCP 服务；serve --http 是明确指定此方式的等效命令。该命令会输出服务 URL、PID、日志路径和客户端配置片段。默认绑定地址为 127.0.0.1:3939。

然后将以下内容添加到基于 URL 的 MCP 客户端配置中（.mcp.json、claude_desktop_config.json，或客户端对应的配置文件）：

{
  "mcpServers": {
    "obsidian-hybrid-search": {
      "url": "http://127.0.0.1:3939/mcp"
    }
  }
}

管理服务：

ohs serve status
ohs serve stop
ohs serve --foreground
ohs serve --http --foreground

HTTP 模式使用无状态 MCP Streamable HTTP。它不会签发或验证 Mcp-Session-Id，因此即使 MCP 客户端仍发送过期的会话标头，守护进程重启后也可以继续调用工具。此模式适用于服务的请求／响应工具，不提供持久 SSE 流、服务端发起的通知或 SSE 恢复功能。

如果端口 3939 已被占用，该命令会报错退出，而不会自动选择其他端口。使用 --port 为不同的知识库指定端口。

绑定到 localhost 之外的地址时，请允许 MCP 客户端将使用的所有主机名或地址。

ohs serve \
  --host 0.0.0.0 \
  --allowed-host 192.168.1.20:3939 \
  --allowed-host notes.example.com:3939

多个值可重复使用 --allowed-host。也可以通过 OBSIDIAN_MCP_ALLOWED_HOSTS 设置逗号分隔的列表。--allow-any-host 选项会为可信网络停用 Host 标头保护。

可用的 MCP 工具

工具	描述
search	搜索知识库。使用 query 进行文本搜索（mode：hybrid/semantic/fulltext/title），或使用 path 进行语义相似度搜索。将 path 与 related: true 结合使用可遍历图谱。传入 queries[] 可进行多查询扇出（并行搜索、RRF 合并）。支持 scope、tag、limit、threshold、depth、direction、snippet_length、rerank
read	按知识库相对路径获取一条或多条笔记。返回完整内容、标题、别名、标签、链接和反向链接。路径未匹配时：返回 found: false，并提供最匹配的前 3 条建议。接受单个路径或数组。使用 snippet_length 限制内容长度
reindex	重新索引知识库或指定文件
status	显示笔记总数、已索引数量和上次索引时间

设置 OBSIDIAN_PREFIX，为每个工具名称添加前缀。例如，myvault_ 会生成 myvault_search 和 myvault_read。默认前缀为空。

配置

环境变量	默认值	描述
OBSIDIAN_VAULT_PATH	MCP 必填；CLI 自动检测	知识库的绝对路径
OBSIDIAN_PREFIX	""	可选的 MCP 工具前缀，例如，myvault_ → myvault_search、myvault_read
OBSIDIAN_IGNORE_PATTERNS	.obsidian/**,templates/**,*.canvas	以逗号分隔的忽略模式
OBSIDIAN_RESPECT_GITIGNORE	true	读取根目录及嵌套的 .gitignore 文件；设为 false 可禁用
OBSIDIAN_INCLUDE_PATTERNS	""	以逗号分隔的模式，用于重新包含仅被 .gitignore 忽略的笔记
OBSIDIAN_CONTENT_IGNORE_PATTERNS	""	以逗号分隔的正则规则，用于从搜索中排除笔记正文，例如 /%%[\s\S]*?%%/g。原始文件和 read 不受影响。
OPENAI_API_KEY	无	API 密钥；省略后将使用本地模型嵌入或无需密钥的服务（Ollama、LM Studio）
OPENAI_BASE_URL	https://api.openai.com/v1	API 基础 URL
OPENAI_EMBEDDING_MODEL	text-embedding-3-small	嵌入模型名称

忽略模式

• 使用 folder/** 忽略目录及其所有内容。
• 使用 *.canvas 按扩展名忽略文件。
• 使用 exact/path.md 忽略特定文件。
• 使用 **/node_modules/** 忽略任意层级的目录。

默认情况下会遵循根目录及嵌套的 .gitignore 文件。设置 OBSIDIAN_RESPECT_GITIGNORE=false 可禁用此行为。使用 OBSIDIAN_INCLUDE_PATTERNS 重新包含仅被 .gitignore 忽略的 Markdown 笔记。包含模式不会覆盖 OBSIDIAN_IGNORE_PATTERNS 或内部排除规则。

数据库会存储忽略配置，并在服务重启时恢复该配置，即使缺少环境变量也不例外。

工作原理

1. 索引 按标题拆分笔记，并在必要时使用滑动窗口作为回退方式，生成嵌入，并将结果存储在 SQLite 中，同时使用 FTS5 和 sqlite-vec。
2. 搜索 并行执行 BM25、基于三元组的模糊标题和别名搜索，以及向量 KNN 搜索。BM25 对标题、别名和内容分别采用 10×、5× 和 1× 权重。随后，RRF 为语义搜索和 BM25 结果各赋予 1.5× 权重，为精确别名匹配赋予 2× 权重，为部分模糊匹配赋予 0.25× 权重。最终得分范围为 0 到 1，分数越高表示相关性越强。
3. 链接 从 [[note]] 等维基链接解析链接，将其映射到笔记路径并存储。每个搜索结果都包含 links 和 backlinks 数组。
4. 监视器 使用 chokidar 检测文件更改，并在后台更新索引。

许可证

MIT