Obsidian MCP+混合检索：2026年参考指南

Obsidian不是笔记应用。它是一个本地优先、纯文本、图结构化的Markdown语料库；加入检索基础设施后，它会成为AI上下文储备池。16,894个文件。49,746个分块。23ms查询。0次API调用。1个83 MB的SQLite文件。本指南涵盖完整系统：从知识库架构到hybrid检索，再到MCP集成与运营工作流。

关键要点

这是上下文工程，而不是记笔记。 Obsidian库对AI的价值不在于笔记本身，而在于让这些笔记可查询的检索层。没有检索的16000个文件库只是一个只写数据库。集成了混合搜索和MCP的200个文件库，才是AI知识库。检索基础设施才是产品，笔记只是原材料。

混合检索优于纯关键词搜索或纯语义搜索。 BM25擅长捕捉精确标识符和函数名。向量搜索擅长捕捉不同术语之间的同义表达和概念匹配。Reciprocal Rank Fusion（RRF）无需分数校准即可合并两者。单独使用任一方法都无法覆盖这两类失败模式。关于MS MARCO段落排名的研究也印证了这一模式：混合检索始终优于单独使用任一方法。³ 混合检索器深度解析介绍了RRF数学原理、带真实数字的示例、失败模式分析，以及一个交互式融合计算器。

MCP让AI工具可以直接访问库。 Model Context Protocol（MCP）服务器将检索器暴露为工具，供Claude Code、Codex CLI、Cursor和其他AI工具直接调用。代理查询库，接收带来源归属的排序结果，并在不加载整个文件的情况下使用上下文。MCP服务器只是检索引擎外的一层轻量封装。

本地优先意味着零API成本和完整隐私。 整个栈都运行在单台机器上：SQLite用于存储，Model2Vec用于embeddings，FTS5用于关键词搜索，sqlite-vec用于向量KNN。没有云服务，没有API调用，也没有网络依赖。个人笔记不会离开本机。按OpenAI API价格计算，对49746个分块完整重新嵌入大约需要0.30美元，但真正的成本在于延迟、隐私暴露，以及让一个本应离线工作的系统依赖网络。⁴

增量索引能在10秒内保持系统最新。 通过比较文件修改时间检测变更。只有被修改的文件会重新chunking（分块）并重新嵌入。在Apple M系列硬件上，完整重建索引大约需要4分钟。典型一天编辑量的增量更新可在10秒内完成。系统无需手动干预即可保持最新。

该架构可从200篇笔记扩展到20000+篇笔记。 同样的三层设计（摄取、检索、集成）适用于任意库规模。可以从小型库上的纯BM25搜索开始。当关键词冲突成为问题时，加入向量搜索。当需要同时获得精确匹配和语义匹配时，加入RRF融合。每一层都可以独立发挥作用，也可以独立移除。

如何使用本指南

本指南覆盖完整系统。您的起点取决于当前所处阶段：

标记为Contract的章节包含实现细节、配置块和失败模式。标记为Narrative的章节聚焦概念、架构决策及设计选择背后的原因。标记为Recipe的章节提供分步工作流。

为什么将Obsidian用于AI基础设施

本指南的核心论点是：Obsidian库是个人AI知识库的最佳基底，因为它本地优先、采用纯文本、具备图结构，并且用户可以控制栈中的每一层。

Obsidian为AI提供了哪些替代方案没有的能力

纯文本markdown文件。 每条笔记都是文件系统上的一个.md文件。没有专有格式，不需要数据库导出，也不需要API来读取内容。任何能读取文件的工具都能读取您的库。grep、ripgrep、Python的pathlib、SQLite FTS5——它们都能直接作用于源文件。构建检索系统时，您索引的是文件，而不是API响应。由于源就是文件系统，索引始终与源保持一致。

本地优先架构。 库保存在您的机器上。没有服务器，没有云同步依赖，没有API速率限制，也没有服务条款来约束您如何处理自己的内容。无需任何外部服务，就可以对笔记进行嵌入、索引、chunking（分块）和搜索。这对AI基础设施很重要，因为检索流水线的速度取决于磁盘，而不是API端点的响应速度。它对隐私同样重要：包含凭证、健康数据、财务信息和私人思考的个人笔记不会离开您的机器。

通过wiki-link形成图结构。 Obsidian的[[wiki-link]]语法会在笔记之间创建有向图。关于OAuth实现的笔记会链接到关于令牌轮换、会话管理和API安全的笔记。图结构编码了人工整理的概念关系。向量embeddings可以捕捉语义相似性，但wiki-link捕捉的是作者在思考主题时建立的有意连接。这种图信号是embeddings无法复制的。

插件生态。 Obsidian拥有2500+个社区插件（截至2026年3月，高于2025年中期的1800+）。Dataview可以像查询数据库一样查询您的库。Templater使用JavaScript逻辑从模板生成笔记。Git集成会将库同步到仓库。Linter强制执行格式一致性。Bases核心插件（在v1.9.10中引入）基于frontmatter属性作为字段，在库文件之上添加类似数据库的视图——表格、画廊、日历和看板，并保存为.base文件。¹⁵ 这些插件在不改变底层纯文本格式的前提下，为库增加结构。检索系统索引的是这些插件的输出，而不是插件本身。

500万+用户。 Obsidian拥有庞大而活跃的社区，持续产出模板、工作流、插件和文档。当您遇到库组织或插件配置问题时，很可能已有他人记录了解决方案。社区还产出Obsidian周边工具：MCP服务器、索引脚本、发布流水线和API封装器。

单独的文件系统无法提供什么

markdown文件目录具备纯文本优势，但缺少Obsidian提供的3项能力：

1. 双向链接。 Obsidian会自动跟踪backlink。当您从笔记A链接到笔记B时，笔记B会显示笔记A引用了它。图谱面板会可视化连接集群。这种双向感知是原始文件系统无法提供的元数据。

2. 带插件渲染的实时预览。 Dataview查询、Mermaid图表和callout块都会实时渲染。写作体验比文本编辑器更丰富，而存储格式仍保持纯文本。您在丰富环境中写作和组织内容；检索系统索引原始markdown。

3. 社区基础设施。 插件发现、主题市场、同步服务（可选）、发布服务（可选）和文档生态。您可以用独立工具复刻任何单项功能，但Obsidian将它们打包成了一个连贯的工作流。

Obsidian不做什么（以及您需要构建什么）

Obsidian不包含检索基础设施。它有基础搜索（全文、文件名、标签），但没有embedding流水线、没有向量搜索、没有融合排序、没有MCP服务器、没有凭证过滤、没有chunking策略，也没有面向外部AI工具的集成钩子。本指南介绍的是您在Obsidian之上构建的基础设施。 库是基底。检索流水线、MCP服务器和集成钩子才是基础设施。

这里描述的架构是markdown优先，而非Obsidian独占。 如果您使用Logseq、Foam、Dendron，或只是一个普通的markdown文件目录，检索流水线同样适用。chunker读取.md文件。embedder处理文本字符串。indexer写入SQLite。这些组件都不依赖Obsidian特有功能。Obsidian的贡献在于提供写作和组织环境，产出供检索器索引的markdown文件。

Obsidian MCP 设置

Model Context Protocol（MCP）是标准接口，可让Claude Code、Codex CLI、Cursor以及其他AI工具直接访问Obsidian知识库。本节将在5分钟内把知识库连接到AI工具。您将安装Obsidian、创建知识库、安装MCP服务器，并运行第一次查询。快速入门使用社区MCP服务器，便于立即看到结果。后续章节会介绍如何为生产环境构建自定义检索流水线。

前置条件

• macOS、Linux或Windows
• Node.js 18+（用于MCP服务器）
• Obsidian 1.12+（用于CLI集成；1.13.1是当前公开桌面版；更早版本也适用于仅使用MCP的设置）
• 已安装Claude Code、Codex CLI或Cursor

步骤1：创建知识库

从obsidian.md下载Obsidian并创建一个新知识库。选择一个容易记住的位置——MCP服务器需要使用绝对路径。

# Example vault location
~/Documents/knowledge-base/

添加几篇笔记，让检索器有内容可处理。即使只有10-20篇笔记，也足以看到结果。每篇笔记都应是一个.md文件，标题要有意义，并至少包含一段正文。

步骤2：安装MCP服务器

多个社区MCP服务器可以提供即时的知识库访问能力。这个生态在2025-2026年显著发展。其中一个值得注意的是MCPVault（npm @bitbonsai/mcpvault，仓库bitbonsai/mcpvault），目前为v0.12.1——它与下文的MarkusPfundstein/mcp-obsidian是不同项目，并非后者改名而来。其v0.11.0（2026年3月）新增了list_all_tags，可扫描frontmatter和标签并统计数量，同时改进了带点文件夹处理，并支持.base/.canvas。针对其路径过滤受限目录拒绝列表，已披露两个中等严重性安全公告（GHSA-9c83-rr99-vfwj和GHSA-j99q-93c9-h869），因此请运行当前版本。¹³

2026年4月变化——Obsidian CLI成为首选桥接方式： Obsidian 1.12.0引入了一等公民级别的CLI，公开版1.12.7安装程序（2026年3月23日）捆绑了独立二进制文件、TUI以及socket文件改进，使终端工作流更易安装和运行。¹⁶ 当前公开桌面版1.13.1（公开通道，2026年6月9日）是在1.13.0基础上的版本更新——包含设置UX优化和CodeMirror升级——但除1.12.x CLI表面能力外，没有新增AI/自动化能力。²⁵²⁶ 社区工具正在积极从Local REST API插件（mcp-obsidian所依赖的插件）迁移到基于CLI的集成，因为它更快、更稳定。MarkusPfundstein/mcp-obsidian仓库仍在维护——截至2026年5月的提交新增了包括search_by_tag和get_frontmatter在内的工具——但它没有发布带标签的版本（请从固定提交安装）。它仍然基于Local REST API；对于新设置，CLI桥接通常更快、更稳定，因此建议优先选择它或下方列出的较新社区替代方案。²⁰ 推荐设置请参阅本指南后面的“面向AI工作流的Obsidian CLI”部分。

对于快速入门，最简单的选项是直接读取.md文件的基于文件的服务器：

npm install -g obsidian-mcp-server

步骤3：配置AI工具

Claude Code——添加到~/.claude/settings.json：

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "args": ["--vault", "/absolute/path/to/your/vault"]
    }
  }
}

Codex CLI——添加到.codex/config.toml：

[mcp_servers.obsidian]
command = "obsidian-mcp-server"
args = ["--vault", "/absolute/path/to/your/vault"]

Cursor——添加到.cursor/mcp.json：

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "args": ["--vault", "/absolute/path/to/your/vault"]
    }
  }
}

步骤4：运行第一次查询

打开AI工具，并提出一个可由知识库笔记回答的问题：

Search my Obsidian vault for notes about [topic you wrote about]

AI工具会调用MCP服务器，后者搜索您的知识库并返回匹配内容。您应能看到带有文件路径和相关摘录的结果。

Claude连接后可以做什么

确切工具名称会因服务器而异，但各实现的核心能力面基本一致：

实践中，Claude可以基于您的笔记回答问题并附带来源归属，将先前决策和参考资料拉入编码会话，并在不把整个文件加载进上下文的情况下探索知识库结构。一些社区服务器也暴露写入操作（创建、追加、标签和frontmatter管理）；本指南后面构建的自定义服务器会刻意保持只读，笔记创建则交由hooks处理。

深入阅读：MCP服务器架构介绍工具和权限设计，Claude Code集成介绍hooks和桥接模式，Codex CLI集成以及Cursor和其他工具介绍其他agent。

刚刚构建了什么

您通过标准协议将本地知识库连接到了AI工具。MCP服务器读取知识库文件，执行基础搜索，并返回结果。这是最小可用版本。

此快速入门不提供以下能力： - Hybrid检索（BM25 + 向量搜索 + RRF融合） - 基于embeddings的语义搜索 - 凭据过滤 - 增量索引 - 基于hooks的自动上下文注入

本指南其余部分会介绍如何构建这些能力。快速入门用于验证概念。完整流水线则提供生产级检索能力。

面向 AI Workflows 的 Obsidian CLI

Obsidian 1.12（2026年2月）引入了内置命令行界面，为 AI workflows 打开了新的集成入口；截至 1.13.1 公共桌面版（公共频道，2026年6月9日），它仍是当前版本。该版本主要是 settings-UX + CodeMirror 版本升级，没有新增 CLI 能力。¹⁶²⁵²⁶ CLI 相当于 Obsidian GUI 的远程控制器——Obsidian 必须正在运行（或会在首次命令时自动启动）。请在 Settings > General > Command line interface 中启用。

为什么 CLI 对 AI 基础设施很重要

CLI 提供了对 Obsidian 原生操作的程序化访问；这些操作此前需要通过 GUI 或插件 API 才能完成。对于 AI workflows，关键能力包括：

• 从脚本和 hook 中搜索。 obsidian search "query" 和 obsidian search:context "query" 可以从任意 shell 脚本、hook 或自动化流水线中运行 vault 搜索。search:context 变体会返回匹配行及其周边上下文，适合将结果送入 AI prompts。
• 每日笔记自动化。 obsidian daily 会打开或创建今天的每日笔记。结合 shell 脚本后，可以实现自动化每日简报流程——hook 可以把 AI 生成的摘要追加到每日笔记中。
• 基于模板创建笔记。 obsidian template list 和 obsidian template create 会基于 Templater 或核心模板生成笔记，使 AI agents 无需直接写入 markdown 文件，也能创建结构化 vault 条目。
• 属性管理。 obsidian property set 和 obsidian property get 可读取和写入 frontmatter 属性，让脚本无需解析 YAML 即可更新元数据。
• 插件控制。 obsidian plugin enable/disable/list 可以程序化管理插件，适合在批量操作期间切换索引插件。
• 任务管理。 obsidian task list/add/complete 提供结构化任务访问，适合管理 vault 中工作项的 AI agents。

用于 AI 访问的 CLI 与 MCP 对比

CLI 和 MCP 服务器承担不同角色，二者相辅相成，而非彼此竞争：

建议： 将 CLI 用于采集自动化（创建笔记、管理属性、运行 Obsidian 原生搜索），将 MCP 用于检索（结合 embeddings 的 hybrid search）。PreToolUse hook 可以先调用 obsidian search:context 做快速预检查，再回退到完整的 MCP 检索器以获取排序结果。

示例：由 CLI 驱动的采集 hook

#!/bin/bash
# Hook: append today's signals to daily note via CLI
DATE=$(date +%Y-%m-%d)
SUMMARY="$1"
obsidian daily  # ensure daily note exists
obsidian file append "Daily Notes/${DATE}.md" "## AI Summary\n${SUMMARY}"

Obsidian Agent 插件

越来越多的 Obsidian 插件开始将 AI coding agents 直接嵌入 vault UI，为外部 MCP 服务器配置提供另一种选择。这些插件会在 Obsidian 侧边栏内运行 AI agent，而不是从外部工具连接。

Claudian

Claudian 将 Claude Code 作为 AI 协作者嵌入 vault。vault 目录会成为 Claude 的工作目录，使其具备完整的 agentic 能力：文件读写、搜索、bash 命令，以及多步骤工作流。¹⁷

面向 AI 基础设施的关键功能： - 上下文感知 prompts。 自动附加当前聚焦的笔记，支持 @notename 文件提及、基于标签的排除，以及将编辑器选区作为上下文。 - 视觉支持。 可通过拖放、粘贴或文件路径分析图像——适合处理保存在 vault 中的截图和图表。 - Slash commands。 创建由 /command 触发的可复用 prompt 模板，从而实现标准化 vault 操作。 - 权限模式。 YOLO（自动批准）、Safe（逐项批准）和 Plan（仅计划）模式，并提供安全 blocklist 和 vault 限定范围。

Agent Client

Agent Client 通过 Agent Client Protocol（ACP）将 Claude Code、Codex CLI 和 Gemini CLI 汇入统一的 Obsidian 侧边栏。¹⁸

关键功能： - 多 agent 切换。 可在同一面板中与 Claude Code、Codex 或 Gemini CLI 对话，并按需在 agents 之间切换。 - 笔记提及。 使用 @notename 将笔记内容纳入 prompts，类似 Claudian，但不绑定特定 agent。 - Shell 执行。 在聊天中内联执行终端命令——构建脚本、git 命令，或任何终端操作，无需离开对话。 - 动作批准。 对文件读取、编辑和命令执行进行细粒度控制。

何时使用 agent 插件，何时使用外部 MCP

建议： 将 agent 插件用于以 vault 为中心的工作流（撰写、整理、总结笔记）。将外部 MCP 服务器用于开发工作流，此时 AI agent 需要完整检索流水线，并需要访问 vault 之外的代码库。两种方式可以并存——在 Obsidian 内运行 Claudian 处理笔记工作，同时在外部使用带 MCP 的 Claude Code 进行开发。

决策框架：Obsidian与替代方案

并非所有用例都需要Obsidian。本节说明什么时候Obsidian是合适的基础，什么时候显得过度，以及什么时候其他工具更适合。

决策树

START: What is your primary content type?
│
├─ Structured data (tables, records, schemas)
│  → Use a database. SQLite, PostgreSQL, or a spreadsheet.
│  → Obsidian is for prose, not tabular data.
│
├─ Ephemeral context (current project, temporary notes)
│  → Use CLAUDE.md / AGENTS.md in the project repo.
│  → These travel with the code and reset per project.
│
├─ Team wiki (shared documentation, onboarding)
│  → Evaluate Notion, Confluence, or a shared git repo.
│  → Obsidian vaults are personal-first. Team sync is possible
│    but not native.
│
└─ Growing personal knowledge corpus
   │
   ├─ < 50 notes
   │  → A folder of markdown files + grep is sufficient.
   │  → Obsidian adds value mainly through the link graph,
   │    which needs density to be useful.
   │
   ├─ 50 - 500 notes
   │  → Obsidian adds value. Wiki-links create a navigable graph.
   │  → BM25-only search (FTS5) is sufficient at this scale.
   │  → Skip vector search and RRF until keyword collisions appear.
   │
   ├─ 500 - 5,000 notes
   │  → Full hybrid retrieval becomes valuable. Keyword collisions
   │    increase. Semantic search catches queries that BM25 misses.
   │  → Add vector search + RRF fusion at this scale.
   │
   └─ 5,000+ notes
      → Full pipeline is essential. BM25-only returns too much noise.
      → Credential filtering becomes critical (more notes = more
        accidentally pasted secrets).
      → Incremental indexing matters (full reindex takes minutes).
      → MCP integration pays dividends on every AI interaction.

对比矩阵

什么时候Obsidian显得过度

• 单项目上下文。 如果AI只需要当前代码库的上下文，请放入CLAUDE.md、AGENTS.md或项目级文档。这些文件会随repo一起移动，并自动加载。
• 结构化数据。 如果内容是表格、记录或schemas，请使用数据库。Obsidian笔记以 prose 为主。Dataview可以查询frontmatter字段，但真正的数据库更适合处理结构化查询。
• 临时研究。 如果笔记会在项目结束后丢弃，使用包含markdown文件的草稿目录更简单。不要为短期内容构建检索基础设施。

什么时候Obsidian是正确选择

• 跨数月或数年积累知识。 随着语料库增长，价值会不断复利。一个每天查询、持续使用6个月的200条笔记vault，比只查询一次的5,000条笔记vault更有价值。
• 一个语料库覆盖多个领域。 包含编程、架构、安全、设计和个人项目笔记的vault，可以受益于跨领域检索，这是项目专属CLAUDE.md无法提供的。
• 隐私敏感内容。 Local-first意味着检索流水线绝不会把内容发送到外部服务。vault中包含您放入的任何内容，包括您不愿上传到云服务的内容。

心智模型：三层结构

该系统有三层，它们各自独立运行，但组合后会相互增强。每一层关注的问题不同，失败模式也不同。

┌─────────────────────────────────────────────────────┐
│                 INTEGRATION LAYER                     │
│  MCP servers, hooks, skills, context injection        │
│  Concern: delivering context to AI tools              │
│  Failure: wrong context, too much context, stale      │
└──────────────────────┬──────────────────────────────┘
                       │ query + ranked results
┌──────────────────────┴──────────────────────────────┐
│                  RETRIEVAL LAYER                      │
│  BM25, vector KNN, RRF fusion, token budget           │
│  Concern: finding the right content for any query     │
│  Failure: wrong ranking, missed results, slow queries │
└──────────────────────┬──────────────────────────────┘
                       │ chunked, embedded, indexed
┌──────────────────────┴──────────────────────────────┐
│                   INTAKE LAYER                        │
│  Note creation, signal triage, vault organization     │
│  Concern: what enters the vault and how it's stored   │
│  Failure: noise, duplicates, missing structure        │
└─────────────────────────────────────────────────────┘

摄取决定什么内容进入vault。如果没有筛选，vault会积累噪声：推文截图、没有注释的复制粘贴文章、缺少上下文的半成品想法。摄取层负责在入口处进行质量控制。它可以是评分流水线、标签约定或人工审核流程，也可以是任何确保vault包含值得检索内容的机制。

检索让vault可查询。这是系统的引擎：将笔记chunking（分块）成搜索单元，把chunks转换为embeddings（嵌入）并放入向量空间，为关键词和语义搜索建立索引，再用RRF融合结果。检索层把一个文件目录转化为可查询的知识库。没有这一层，vault只能通过手动浏览和基础搜索来导航，而无法被AI工具以编程方式访问。

集成将检索层连接到AI工具。MCP服务器将检索暴露为可调用工具。Hooks会自动注入上下文。Skills会把新知识捕获回vault。集成层是知识库与消费它的AI agents之间的接口。

这些层在设计上彼此解耦。摄取评分流水线不了解embeddings。检索器不了解信号路由规则。MCP服务器不了解笔记是如何创建的。这种解耦意味着您可以独立改进任何一层。替换embedding模型，而无需更改摄取流水线。新增MCP能力，而无需修改检索器。调整信号评分启发式规则，而无需触碰索引。

面向AI消费的Vault架构

针对AI检索优化的vault，与针对个人浏览优化的vault，遵循的是不同约定。本节介绍文件夹结构、笔记schema、frontmatter约定，以及能够提升检索质量的具体模式。

文件夹结构

为顶层文件夹使用数字前缀，以建立可预测的组织层级。这些数字不表示优先级，而是用于归类相关领域，并让结构一目了然。

vault/
├── 00-inbox/              # Unsorted captures, pending triage
├── 01-projects/           # Active project notes
├── 02-areas/              # Ongoing areas of responsibility
├── 03-resources/          # Reference material by topic
│   ├── programming/
│   ├── security/
│   ├── ai-engineering/
│   ├── design/
│   └── devops/
├── 04-archive/            # Completed projects, old references
├── 05-signals/            # Scored signal intake
│   ├── ai-tooling/
│   ├── security/
│   ├── systems/
│   └── ...12 domain folders
├── 06-daily/              # Daily notes (if used)
├── 07-templates/          # Note templates (excluded from index)
├── 08-attachments/        # Images, PDFs (excluded from index)
├── .obsidian/             # Obsidian config (excluded from index)
└── .indexignore            # Paths to exclude from retrieval index

应当索引的文件夹：所有包含markdown正文的内容——项目、领域、资源、信号、每日笔记。

应当从索引中排除的文件夹：模板（其中包含占位变量，而非内容）、附件（二进制文件）、Obsidian配置，以及任何包含敏感内容且您不希望进入检索索引的文件夹。

.indexignore文件

在vault根目录创建.indexignore文件，以明确从检索索引中排除路径。其语法与.gitignore一致：

# Obsidian internal
.obsidian/

# Templates contain placeholders, not content
07-templates/

# Binary attachments
08-attachments/

# Personal health/medical notes
02-areas/health/

# Financial records
02-areas/finance/personal/

# Career documents (resumes, salary data)
02-areas/career/private/

索引器会在扫描前读取此文件，并完全跳过匹配的路径。被排除路径中的文件不会被chunking，不会生成embeddings，也不会出现在搜索结果中。

笔记Schema

每篇笔记都应包含YAML frontmatter。检索器会使用frontmatter字段进行筛选和上下文增强：

---
title: "OAuth Token Rotation Patterns"
type: note           # note | signal | project | moc | daily
domain: security     # primary domain for routing
tags:
  - authentication
  - oauth
  - token-management
created: 2026-01-15
updated: 2026-02-28
source: ""           # URL if captured from external source
status: active       # active | archived | draft
---

检索所需字段：

• title——用于搜索结果展示，并作为BM25的标题上下文
• type——支持按类型筛选的查询（“只显示MOC”或“只显示信号”）
• tags——以0.3权重索引到FTS5标题上下文中，即使正文使用不同术语，也能提供关键词匹配

可选但很有价值的字段：

• domain——支持按领域限定的查询（“只搜索安全笔记”）
• source——为捕获内容提供出处；检索器可以在结果中包含来源URL
• status——允许从活跃搜索中排除已归档或草稿笔记

Chunking约定

检索器会在H2（##）标题边界进行chunking。这意味着笔记结构会直接影响检索粒度：

有利于检索：

## Token Rotation Strategy

The rotation interval depends on the threat model...

## Implementation with refresh_token

The OAuth 2.0 refresh token flow requires...

## Error Handling: Expired Tokens

When a token expires mid-request...

3个H2小节会生成3个可独立搜索的chunk。每个chunk都有足够上下文，便于embedding捕捉其含义。关于“过期token处理”的查询会精确匹配第三个chunk。

不利于检索：

# OAuth Notes

Token rotation depends on threat model. The OAuth 2.0 refresh
token flow requires storing the refresh token securely. When a
token expires mid-request, the client should retry after refresh.
The rotation interval is typically 15-30 minutes for access tokens
and 7-30 days for refresh tokens...

一个没有H2标题的长小节会生成一个大chunk。embedding会在该小节的所有主题之间取平均。关于任何子主题的查询都会同等匹配整篇笔记。

经验法则：如果一个小节涵盖多个概念，请将其拆分为H2子小节。其余工作交给chunker处理。

不应放入笔记的内容

会降低检索质量的内容：

• 未加注释地原样复制整篇文章。检索器会索引原文关键词，用并非您撰写的内容稀释vault。建议改为添加摘要、提取要点，或链接到来源URL。
• 没有文字说明的截图。检索器索引的是markdown文本。没有alt文本或周边说明的图片，对BM25和向量搜索都是不可见的。
• 凭据字符串。API密钥、token、密码、连接字符串。即使有凭据过滤，最安全的做法仍然是永远不要把密钥粘贴到笔记中。请改用名称引用（例如“~/.env中的Cloudflare API token”）。
• 未经整理的自动生成内容。如果某个工具生成了一篇笔记（会议转录、Readwise高亮、RSS导入），请在其进入永久vault前进行审阅和批注。未经整理的自动导入只会增加体量，而不会增加可检索价值。

AI Workflows的插件生态

能够提升AI检索库质量的Obsidian插件可分为三类：结构类（强制一致性）、查询类（暴露元数据）和同步类（保持库内容最新）。

必备插件

Dataview。 使用frontmatter字段像查询数据库一样查询您的库。创建动态索引，例如：“过去30天内更新、标记为security的所有笔记”，或“状态为active的所有项目笔记”。Dataview不会直接帮助检索，但能帮助您发现库覆盖范围中的缺口，并找出需要更新的笔记。

TABLE type, domain, updated
FROM "03-resources"
WHERE status = "active"
SORT updated DESC
LIMIT 20

Templater。 基于模板创建带动态字段的笔记。使用预填created、type和domain字段的模板，确保每篇新笔记一开始就具备正确的frontmatter。一致的frontmatter可提升检索过滤效果。

<%* /* New Resource Note Template */ %>
---
title: "<% tp.file.cursor() %>"
type: note
domain: <% tp.system.suggester(["programming", "security", "ai-engineering", "design", "devops"], ["programming", "security", "ai-engineering", "design", "devops"]) %>
tags: []
created: <% tp.date.now("YYYY-MM-DD") %>
updated: <% tp.date.now("YYYY-MM-DD") %>
source: ""
status: active
---

## Key Points

## Details

## References

Linter。 在整个库中强制执行格式规则。一致的标题层级（H1用于标题，H2用于章节，H3用于小节）可确保chunker生成可预测的结果。对检索重要的Linter规则包括：

• 标题递增：强制标题层级按顺序递增（不要从H1跳到H3）
• YAML标题：与文件名匹配
• 行尾空格：删除（避免FTS5分词伪影）
• 连续空行：限制为1行（生成更干净的chunks）

Git集成。 为您的库提供版本控制。跟踪随时间发生的变更，在多台机器之间同步，并从误删中恢复。Git还提供索引器用于增量变更检测的mtime数据。

有助于索引的插件

Smart Connections。 这是一个Obsidian插件，可在Obsidian内部提供AI驱动的语义搜索。Smart Connections v4默认创建本地embeddings（嵌入）——库完成索引后，语义连接和查找可完全离线运行，无需任何API调用。¹¹ v4.5.0（2026年5月5日） 将页脚连接纳入Smart Connections Core，因此每次安装都可以在页脚显示相关笔记连接，而无需打开侧边面板。近期v4版本还为连接列表添加了图视图、可配置的停靠位置、索引运行中断后的块嵌入恢复改进，以及“Substrate”：一种跨插件环境，让Smart Connections、Smart Chat和Smart Composer共享状态。²¹ 虽然本指南中的检索系统位于Obsidian外部（作为Python pipeline运行），但Smart Connections有助于在写作时探索语义关系。这两个系统索引相同内容，但服务于不同用例：Smart Connections用于编辑器内发现，外部retriever则通过MCP集成AI工具。

2026年4月发布的AI原生插件。 一批新的社区插件直接面向Claude Code / Codex / Gemini-CLI工作流：

请将其视为正在涌现的功能版图——未来几个季度，其中若干插件很可能会整合，或被Smart Connections / Obsidian core吸收。如果今天要选择一个，VaultSearch和Hybrid Search MCP在理念上最接近本指南的外部retriever。

Dataview说明： Dataview（长期存在的Obsidian查询插件）最后一次发布是2025年4月的0.5.70，此后实际上已处于停滞状态。对于新工作，Obsidian内置的Bases功能（1.9+）是隐含的继任者，也是推荐路径。

Metadata Menu。 提供结构化frontmatter编辑，并为字段值提供自动补全。减少type、domain和tags字段中的拼写错误。一致的元数据可提升检索过滤准确性。

不利于索引的插件

Excalidraw。 将绘图作为嵌入在markdown文件中的JSON保存。该JSON在语法上是有效的markdown，但在chunking（分块）和嵌入后会产生无用内容。请通过.indexignore从索引中排除Excalidraw文件，或按文件扩展名过滤。

Kanban。 将看板状态存储为特殊格式的markdown。该格式面向Kanban渲染设计，而不是面向散文检索。chunker会生成卡片标题和元数据的碎片，这些内容不适合嵌入。请从索引中排除Kanban看板。

Calendar。 创建内容极少的每日笔记（通常只有日期标题）。空笔记或近乎空白的笔记会产生低质量chunks。如果使用每日笔记，请在其中写入实质性内容，或从索引中排除每日笔记文件夹。

关键插件配置

文件恢复 → 已启用。 防止意外删除笔记。它与检索没有直接关系，但对于您所依赖的知识库至关重要。

严格换行 → 已禁用。 相比Obsidian严格模式（单换行表示<br>），Markdown标准换行（双换行表示段落）会生成更干净的chunks。

默认新文件位置 → 指定文件夹。 将新文件路由到00-inbox/，避免未分类笔记污染领域文件夹。收件箱是暂存区；文件会在分拣后移动到领域文件夹。

Wiki-link格式 → 尽可能使用最短路径。 更短的链接目标更便于retriever在索引链接结构时解析。

Embedding Models：选择与配置

embedding模型会将文本chunk转换为用于语义搜索的数值向量。模型选择会决定检索质量、索引大小、embedding速度和运行时依赖。本节说明为什么默认选择Model2Vec的potion-base-8M，以及何时应选择其他方案。

为什么选择Model2Vec potion-base-8M

模型：minishlab/potion-base-8M 参数量：760万 维度：256 大小：约30 MB 依赖：model2vec（仅numpy，无需PyTorch） 推理：仅CPU，静态词embedding（无attention层）

Model2Vec会将sentence transformer的知识蒸馏到静态token embedding中。它不像BERT、MiniLM和其他transformer模型那样对输入运行attention层，而是通过对预先计算的token embedding进行加权平均来生成向量。⁵实际效果是：由于没有顺序计算，embedding速度比基于transformer的模型快50到500倍。

在当前Model2Vec结果页面上，potion-base-8M达到all-MiniLM-L6-v2全任务分数约92%的水平（51.32对55.80），同时速度快出数个数量级。⁶剩余的质量差距，是换取速度和简单性优势的取舍。对于较短的markdown chunk（典型知识库中平均200到400词），这种质量差异没有在长文档上那么明显，因为两个模型在短小、聚焦的文本上会收敛到相似的表示。

配置

# embedder.py
DEFAULT_MODEL = "minishlab/potion-base-8M"
EMBEDDING_DIM = 256

class Model2VecEmbedder:
    def __init__(self, model_name=DEFAULT_MODEL):
        self._model_name = model_name
        self._model = None

    def _ensure_model(self):
        if self._model is not None:
            return
        _activate_venv()  # Add isolated venv to sys.path
        from model2vec import StaticModel
        self._model = StaticModel.from_pretrained(self._model_name)

    def embed_batch(self, texts):
        self._ensure_model()
        vecs = self._model.encode(texts)
        return [v.tolist() for v in vecs]

懒加载。模型在首次使用时加载，而不是在导入时加载。当retriever以仅BM25的回退模式运行时（例如embedding venv未安装），导入embedder模块不会产生额外成本。

隔离的虚拟环境。模型在专用venv中运行（例如~/.claude/venvs/memory/），以避免与工具链其他部分发生依赖冲突。_activate_venv()函数会在运行时将venv的site-packages添加到sys.path。

# Create isolated venv
python3 -m venv ~/.claude/venvs/memory
~/.claude/venvs/memory/bin/pip install model2vec

批处理。embedder以64条为一批处理文本，以摊销Model2Vec的开销。indexer会将chunk送入embed_batch()，而不是一次只为一个chunk生成embedding。

何时选择其他方案

当您希望获得比potion-base-8M更好的质量，同时仍留在静态embedding系列中时，选择potion-base-32M。它使用从baai/bge-base-en-v1.5蒸馏而来的更大词汇表，达到52.83的全任务分数（比potion-base-8M高约3%），同时保持相同的256维输出和仅numpy依赖。⁸模型文件大4倍，会增加内存占用，但embedding速度仍比transformer模型快数个数量级。

当主要用例是检索时（知识库搜索正是如此），选择potion-retrieval-32M。这个变体专门针对检索任务从potion-base-32M微调而来，在Model2Vec检索基准表中得分为35.06，高于potion-base-32M的32.67。⁸取舍在于，它针对检索而非通用embedding质量进行优化。

当您的知识库包含多种语言的笔记时，选择potion-multilingual-128M。该模型于2025年5月发布，支持101种语言，是多语言任务中表现最好的静态embedding模型。它可以为任意语言的文本生成embedding，同时保持与其他potion模型相同的仅numpy依赖。¹²较大的模型文件（约500 MB）是获得跨语言能力的代价。如果您的笔记中既有英文内容，也有日语、中文、德语或其他非英文语言内容，请使用它。

当检索质量比速度更重要，并且已经安装PyTorch时，选择all-MiniLM-L6-v2。与256维向量相比，384维向量会让SQLite数据库大小增加约50%。在M系列硬件上，对15,000个文件进行完整重建索引时，embedding速度会从不到1分钟降至约10分钟。

当需要尽可能好的本地检索质量，并且可以接受较慢的索引速度时，选择nomic-embed-text-v1.5。768维向量会让数据库大小大约增加到3倍。它需要PyTorch以及现代CPU或GPU。

当网络延迟和隐私可以接受作为取舍时，选择text-embedding-3-small。API会生成最高质量的embedding，但也会引入云端依赖、按token计费的成本（每百万token 0.02美元），并将您的内容发送到OpenAI服务器。

其他所有情况下都继续使用potion-base-8M。速度优势对迭代式索引非常关键（开发期间反复重建索引），仅numpy依赖避免了PyTorch安装复杂度，256维向量也能让数据库保持紧凑。

量化与降维

Model2Vec v0.5.0+支持以更低精度和更低维度加载模型。⁸这对于在受限硬件上部署，或在不切换模型的情况下减小数据库大小很有帮助：

from model2vec import StaticModel

# Load with int8 quantization (25% of original size)
model = StaticModel.from_pretrained("minishlab/potion-base-8M", quantize=True)

# Load with reduced dimensions (e.g., 128 instead of 256)
model = StaticModel.from_pretrained("minishlab/potion-base-8M", dimensionality=128)

量化模型能以更小的内存占用保留几乎相同的检索质量。降维遵循Matryoshka式截断，即前N个维度承载最多信息。对于短文本检索，将维度从256降到128，可以让向量存储减半，同时质量损失很小。

Model2Vec v0.8.x更新了tokenizer和持久化内部机制，弃用Python 3.9支持，并将已发布结果刷新到较新的MTEB表。升级生产indexer前，请固定或测试model2vec版本，因为即使embedding模型名称保持不变，库升级也可能改变模型加载路径。¹⁰

针对知识库特定embedding进行微调

Model2Vec v0.4.0+支持在静态embedding之上训练自定义分类模型，v0.7.0加入了词汇表量化和用于蒸馏的可配置pooling，v0.8.x则重构了tokenizer和持久化行为。¹⁰这对包含专业词汇的知识库很有意义，例如医学笔记、法律参考、领域专用术语。在这些场景中，默认potion模型可能无法捕捉语义细微差别：

from model2vec import StaticModel
from model2vec.train import train_model

# Fine-tune on vault-specific data
model = StaticModel.from_pretrained("minishlab/potion-base-8M")
trained_model = train_model(model, train_texts, train_labels)
trained_model.save_pretrained("./vault-embeddings")

对于大多数知识库，默认potion-base-8M已经能提供足够的检索质量。只有当检索持续漏掉通用模型无法捕捉的领域特定关联时，微调才值得投入。

模型哈希跟踪

indexer会存储一个由模型名称和词汇表大小派生出的哈希。如果更换embedding模型，indexer会在下一次增量运行时检测到不匹配，并自动触发完整重建索引。

def _compute_model_hash(self):
    """Hash model name + vocab size for compatibility tracking."""
    key = f"{self._model_name}:{self._model.vocab_size}"
    return hashlib.sha256(key.encode()).hexdigest()[:16]

这可以防止在同一个数据库中混用来自不同模型的向量，否则会产生毫无意义的cosine similarity分数。

失败模式

模型下载失败。首次运行会从Hugging Face下载模型。如果下载失败（网络问题、企业防火墙），retriever会回退到仅BM25模式。首次下载后，模型会缓存在本地。

维度不匹配。如果在未清空数据库的情况下切换模型，已存储向量的维度会与新的embedding不同。indexer会通过模型哈希检测到这一点，并触发完整重建索引。如果哈希检查失败（自定义模型没有正确哈希），sqlite-vec会在维度不匹配的KNN查询上报错。

大型知识库的内存压力。在单个批次中为50,000多个chunk生成embedding可能消耗大量内存。indexer会以64条为一批处理，以限制峰值内存占用。如果内存仍然紧张，请减小批次大小。

使用FTS5进行全文搜索

SQLite的FTS5扩展提供带BM25排序的全文搜索。FTS5是hybrid检索流水线中的关键词搜索组件。本节介绍FTS5配置、BM25擅长的场景，以及它的具体失效模式。

FTS5虚拟表

CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text,
    section,
    heading_context,
    content=chunks,
    content_rowid=id
);

内容同步模式。content=chunks参数指示FTS5直接引用chunks表，而不是存储一份重复的文本副本。这会将存储需求减半，但也意味着在插入、更新或删除chunk时，必须手动同步FTS5。

列。索引包含3列： - chunk_text——每个chunk的主要内容（BM25权重：1.0） - section——H2标题文本（BM25权重：0.5） - heading_context——笔记标题、标签和元数据（BM25权重：0.3）

BM25排序

BM25根据词频、逆文档频率和文档长度归一化对文档进行排序。FTS5中的bm25()辅助函数接受按列设置的权重：

SELECT
    c.id, c.file_path, c.section, c.chunk_text,
    bm25(chunks_fts, 1.0, 0.5, 0.3) AS score
FROM chunks_fts
JOIN chunks c ON chunks_fts.rowid = c.id
WHERE chunks_fts MATCH ?
ORDER BY score
LIMIT 30;

列权重（1.0、0.5、0.3）表示： - chunk_text中的关键词匹配对分数贡献最大 - section（标题）中的匹配贡献为其一半 - heading_context（标题、标签）中的匹配贡献为其30%

这些权重可以调节。如果您的vault中有描述性很强、能有效预测内容质量的标题，可以提高section权重。如果标签全面且准确，可以提高heading_context权重。

BM25何时胜出

BM25擅长处理包含精确标识符的查询：

• 函数名：_rrf_fuse、embed_batch、get_stale_files
• CLI标志：--incremental、--vault、--model
• 配置键：bm25_weight、max_tokens、batch_size
• 错误消息：SQLITE_LOCKED、ConnectionRefusedError
• 特定术语：PostToolUse、PreToolUse、AGENTS.md

对于这些查询，BM25会立即找到精确匹配。向量搜索会返回语义相关内容，但可能将精确匹配排在概念性讨论之后。

BM25何时失效

当查询使用的术语与已存内容不同，BM25就会失效：

• 查询：“how to handle authentication failures”→vault中包含关于“login error recovery”和“session expiration handling”的笔记。BM25不会匹配，因为关键词不同。
• 查询：“what is the best way to manage state”→vault中包含关于“Redux store patterns”和“context providers”的笔记。BM25会漏掉这些内容，因为“state management”是通过具体技术名称表达的。

BM25在规模扩大时还会因关键词碰撞而失效。在一个包含15,000个文件的vault中，搜索“configuration”会匹配数百篇笔记，因为几乎每个项目笔记都会提到配置。结果在技术上正确，但实际上难以使用——排序无法判断哪篇“configuration”笔记与当前查询相关。

FTS5分词器

FTS5默认使用unicode61分词器，可处理ASCII和Unicode文本。对于包含大量CJK（中文、日文、韩文）内容的vault，可以考虑使用trigram分词器：

-- For CJK-heavy vaults
CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text, section, heading_context,
    content=chunks, content_rowid=id,
    tokenize='trigram'
);

默认的unicode61分词器按词边界切分，这对词与词之间没有空格的语言效果较差。trigram分词器每3个字符切分一次，可以支持子串匹配，但代价是索引体积变大（约为原来的3倍）。

维护

当底层chunks表发生变化时，FTS5需要显式同步：

# After inserting chunks
cursor.execute("""
    INSERT INTO chunks_fts(chunks_fts)
    VALUES('rebuild')
""")

rebuild命令会根据内容表重建FTS5索引。批量插入（完整重建索引）后运行它，但不要在单条增量更新后运行；对于单条更新，请使用INSERT INTO chunks_fts(rowid, chunk_text, section, heading_context)同步单行。

使用 sqlite-vec 进行 Vector Search

sqlite-vec 扩展将向量 KNN（K-Nearest Neighbors）搜索引入 SQLite。本节介绍 sqlite-vec 配置、从笔记到可搜索向量的 embedding 流水线，以及具体的查询模式。

sqlite-vec 虚拟表

CREATE VIRTUAL TABLE chunk_vecs USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[256]
);

vec0 模块将 256 维浮点向量存储为打包的二进制数据。id 列与 chunks 表建立 1:1 映射，从而支持在向量结果与 chunk 元数据之间进行 join。

Embedding 流水线

流水线从笔记流向可搜索向量：

Note (.md file)
  → Chunker: split at H2 boundaries
    → Chunks (30-2000 chars each)
      → Credential filter: scrub secrets
        → Embedder: Model2Vec encode
          → Vectors (256-dim float arrays)
            → sqlite-vec: store as packed binary
              → Ready for KNN queries

向量序列化

Python 的 struct 模块会为 sqlite-vec 存储序列化浮点向量：

import struct

def _serialize_vector(vec):
    """Pack float list into binary for sqlite-vec."""
    return struct.pack(f"{len(vec)}f", *vec)

def _deserialize_vector(blob, dim=256):
    """Unpack binary blob to float list."""
    return list(struct.unpack(f"{dim}f", blob))

KNN 查询

向量搜索查询会先对输入查询生成 embedding，然后按 cosine distance 查找 K 个最近的 chunk：

def _vector_search(self, query_text, limit=30):
    query_vec = self.embedder.embed_batch([query_text])[0]
    packed = _serialize_vector(query_vec)

    results = self.db.execute("""
        SELECT
            cv.id,
            cv.distance,
            c.file_path,
            c.section,
            c.chunk_text
        FROM chunk_vecs cv
        JOIN chunks c ON cv.id = c.id
        WHERE embedding MATCH ?
            AND k = ?
        ORDER BY distance
    """, [packed, limit]).fetchall()

    return results

sqlite-vec 中的 MATCH 运算符执行近似最近邻搜索。k 参数控制返回的结果数量。distance 列包含 cosine distance（0=相同，2=相反）。

带 Distance 约束的 KNN 分页

从 sqlite-vec v0.1.7 开始，KNN 查询支持 WHERE distance < ? 约束，可在大型结果集中进行基于游标的分页，而无需重新扫描前面的页面。¹⁴ 后续的 v0.1.8 和 v0.1.9 稳定版本主要是打包和 DELETE bug 修复版本，并非新的查询模型版本，因此 v0.1.7 仍是此分页模式的功能边界。²³

展望后续，v0.1.10-alpha 版本线（2026年3月31日至5月18日）首次让 sqlite-vec 超越暴力 KNN：它引入了近似最近邻索引类型，包括 rescore、实验性的 ivf（inverted-file）索引（默认未启用），以及面向向量规模过大、无法常驻内存的知识库的磁盘型 DiskANN 索引。²³ 这些功能会改变超大型知识库的扩展方式，但 0.1.10 版本线仍是预发布（alpha）状态。请将 ANN 索引视为实验性功能；在稳定的 0.1.10 发布之前，生产知识库仍应继续基于稳定的 v0.1.9 暴力 KNN 路径构建。

def _paginated_vector_search(self, query_vec, page_size=20, max_distance=None):
    """Paginate through KNN results using distance constraints."""
    packed = _serialize_vector(query_vec)
    constraint = f"AND distance < {max_distance}" if max_distance else ""

    results = self.db.execute(f"""
        SELECT cv.id, cv.distance, c.file_path, c.chunk_text
        FROM chunk_vecs cv
        JOIN chunks c ON cv.id = c.id
        WHERE embedding MATCH ?
            AND k = ?
            {constraint}
        ORDER BY distance
    """, [packed, page_size]).fetchall()

    # Use last result's distance as cursor for next page
    next_cursor = results[-1][1] if results else None
    return results, next_cursor

这取代了以往获取较大的 k 后再在 Python 中切片的模式，可降低针对大型知识库进行探索性查询时的内存占用。

vec0 表中的 DELETE 支持

sqlite-vec v0.1.7 为 vec0 虚拟表添加了原生 DELETE 支持，v0.1.9 修复了涉及长度超过 12 个字符的元数据文本列的 DELETE 错误路径。¹⁴²³ 此前，移除向量需要删除并重建表。现在，索引器的文件移除路径可以直接删除向量：

# Before v0.1.7: required workaround (drop + recreate, or mark as inactive)
# After v0.1.7: direct DELETE works
db.execute("DELETE FROM chunk_vecs WHERE id = ?", [chunk_id])

这简化了笔记被删除或移动时的增量重新索引。索引器不再需要维护影子“active IDs”表，也无需批量重建。

Vector Search 何时更有优势

当概念比具体措辞更重要时，Vector Search 表现出色：

• 查询：”how to handle authentication failures” → 找到关于“login error recovery”的笔记（处于相同语义空间，但关键词不同）
• 查询：”what patterns exist for caching” → 找到关于“memoization”、“Redis TTL strategies”和“HTTP cache headers”的笔记（概念相关，术语多样）
• 查询：”approaches to testing asynchronous code” → 找到关于“pytest-asyncio fixtures”、“mock event loops”和“async test patterns”的笔记（同一概念通过实现细节表达）

Vector Search 何时失效

Vector Search 不擅长处理精确标识符：

• 查询：_rrf_fuse → 返回关于“fusion algorithms”和“rank merging”的笔记，但实际函数定义的排序可能低于概念性讨论
• 查询：PostToolUse → 返回关于“tool lifecycle hooks”和“post-execution handlers”的笔记，而不是具体的 hook 名称

Vector Search 也不擅长处理结构化数据。JSON 配置文件、YAML 块和代码片段生成的 embedding 往往捕捉的是结构模式，而不是语义含义。包含 "review": true 的 JSON 文件，与关于代码审查的散文式讨论，会得到不同的 embedding。

优雅降级

如果 sqlite-vec 加载失败（缺少扩展、平台不兼容、库损坏），retriever 会回退到仅 BM25 搜索：

class VectorIndex:
    def __init__(self, db_path):
        self.db = sqlite3.connect(db_path)
        self._vec_available = False
        try:
            self.db.enable_load_extension(True)
            self.db.load_extension("vec0")
            self._vec_available = True
        except Exception:
            pass  # BM25-only mode

    @property
    def vec_available(self):
        return self._vec_available

retriever 会在尝试向量查询前检查 vec_available。禁用后，所有搜索都只使用 BM25，并跳过 RRF fusion 步骤。

Reciprocal Rank Fusion（RRF）

RRF可以合并两个排序列表，而无需进行分数校准。本节介绍该算法、一个完整的查询追踪示例、k参数调优，以及为什么选择RRF而不是其他方案。如需使用可编辑排名、场景预设和可视化架构浏览器的交互式计算器，请参阅hybrid retriever深度解析。

算法

RRF仅根据每个列表中的排名位置为每个文档分配分数：

score(d) = Σ (weight_i / (k + rank_i))

其中： - k是平滑常数（60，遵循Cormack等人的设置³） - rank_i是文档在结果列表i中的从1开始的排名 - weight_i是可选的按列表设置的乘数（默认值为1.0）

在多个列表中排名靠前的文档会获得更高的融合分数。只出现在一个列表中的文档，则只从该单一来源获得分数。

为什么选择RRF而不是其他方案

加权线性组合需要校准BM25分数与cosine distances。BM25分数没有上界，并且会随语料库规模变化。Cosine distances限定在[0, 2]范围内。要将二者组合起来，就需要归一化，而归一化参数取决于具体数据集。RRF只使用排名位置；无论评分方法是什么，排名位置始终是从1开始的整数。

学习型融合模型需要带标签的训练数据，即查询-文档相关性配对。对于个人知识库，这类训练数据并不存在。您需要手动评判数百个查询-文档配对，才能训练出有用的模型。RRF无需任何训练数据即可工作。

Condorcet投票方法（Borda count、Schulze method）在理论上很优雅，但实现和调优更复杂。最初的RRF论文证明，RRF在TREC评测数据上的表现优于Condorcet方法。³

实践中的融合

查询：”how does the review aggregator handle disagreements”

BM25将review-aggregator.py排在第3位（精确匹配”review”、”aggregator”、”disagreements”等关键词），但将两个配置文件排得更高（它们对”review”的匹配更突出）。Vector search将同一chunk排在第1位（在冲突解决语义上匹配）。经过RRF融合后：

在两个列表中都排名靠前的chunk会浮到顶部。只出现在一个列表中的chunk只会得到单一来源分数，并排在双列表排名结果之后。实际的分歧解决逻辑胜出，是因为两种方法都找到了它：BM25通过关键词找到，vector search通过语义找到。

如需查看包含逐排名RRF计算的完整分步追踪，可以在交互式RRF计算器中尝试不同的k值。

实现

RRF_K = 60

def _rrf_fuse(self, bm25_results, vec_results,
              bm25_weight=1.0, vec_weight=1.0):
    """Fuse BM25 and vector results using Reciprocal Rank Fusion."""
    scores = {}

    for rank, r in enumerate(bm25_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {
                "rrf_score": 0.0,
                "file_path": r["file_path"],
                "section": r["section"],
                "chunk_text": r["chunk_text"],
                "bm25_rank": None,
                "vec_rank": None,
            }
        scores[cid]["rrf_score"] += bm25_weight / (self._rrf_k + rank)
        scores[cid]["bm25_rank"] = rank

    for rank, r in enumerate(vec_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {
                "rrf_score": 0.0,
                "file_path": r["file_path"],
                "section": r["section"],
                "chunk_text": r["chunk_text"],
                "bm25_rank": None,
                "vec_rank": None,
            }
        scores[cid]["rrf_score"] += vec_weight / (self._rrf_k + rank)
        scores[cid]["vec_rank"] = rank

    fused = sorted(
        scores.values(),
        key=lambda x: x["rrf_score"],
        reverse=True,
    )
    return fused

调优k

k常数控制排名靠前的结果相对于排名较低的结果获得多少权重：

• 较低的k（例如10）：排名靠前的结果占主导。排名1的分数为1/11 = 0.091，排名10的分数为1/20 = 0.050（相差1.8倍）。当您信任各个排序器能够正确找出第一名结果时，这种设置较合适。
• 默认k（60）：较为均衡。排名1的分数为1/61 = 0.0164，排名10的分数为1/70 = 0.0143（相差1.15倍）。排名差异被压缩，因此出现在多个列表中的结果会获得更高权重。
• 较高的k（例如200）：是否同时出现在两个列表中，比排名位置本身重要得多。排名1的分数为1/201，排名10的分数为1/210，几乎相同。当单个排序器产生的排名噪声较大，但跨列表一致性可靠时，可以使用这种设置。

从k=60开始。最初的RRF论文发现，该值在多种TREC数据集上都很稳健。只有在基于您自己的查询分布衡量失败案例之后，才建议进一步调优。

平局处理

当两个chunk具有相同的RRF分数时（少见但可能发生，例如在一个列表中排名相同，且均未出现在另一个列表中），按以下规则打破平局：

1. 优先选择同时出现在两个列表中的chunk，而不是只出现在一个列表中的chunk
2. 在同时出现在两个列表中的chunk之间，优先选择合并排名更低的那个
3. 在只出现在一个列表中的chunk之间，优先选择在该列表中排名更低的那个

完整检索流水线

本节追踪一次查询如何从输入到输出经过整条流水线：BM25搜索、向量搜索、RRF融合、token预算截断以及上下文组装。

端到端流程

User query: "PostToolUse hook for context compression"
  │
  ├─ BM25 Search (FTS5)
  │    → MATCH "PostToolUse hook context compression"
  │    → Top 30 results ranked by BM25 score
  │    → 12ms
  │
  ├─ Vector Search (sqlite-vec)
  │    → Embed query with Model2Vec
  │    → KNN k=30 on chunk_vecs
  │    → Top 30 results ranked by cosine distance
  │    → 8ms
  │
  └─ RRF Fusion
       → Merge 60 candidates (may overlap)
       → Score by rank position
       → Top 10 results
       → 3ms
       │
       └─ Token Budget
            → Truncate to max_tokens (default 4000)
            → Estimate at 4 chars per token
            → Return results with metadata
            → <1ms

总延迟：约23ms，基于Apple M3 Pro硬件上的49,746个chunk数据库测得。

Search API

class HybridRetriever:
    def search(self, query, limit=10, max_tokens=4000,
               bm25_weight=1.0, vec_weight=1.0):
        """
        Search the vault using hybrid BM25 + vector retrieval.

        Args:
            query: Search query text
            limit: Maximum results to return
            max_tokens: Token budget for total result text
            bm25_weight: Weight for BM25 results in RRF
            vec_weight: Weight for vector results in RRF

        Returns:
            List of SearchResult with file_path, section,
            chunk_text, rrf_score, bm25_rank, vec_rank
        """
        # BM25 search
        bm25_results = self._bm25_search(query, limit=30)

        # Vector search (if available)
        if self.index.vec_available:
            vec_results = self._vector_search(query, limit=30)
            fused = self._rrf_fuse(
                bm25_results, vec_results,
                bm25_weight, vec_weight,
            )
        else:
            fused = bm25_results  # BM25-only fallback

        # Token budget truncation
        results = []
        token_count = 0
        for r in fused[:limit]:
            chunk_tokens = len(r["chunk_text"]) // 4
            if token_count + chunk_tokens > max_tokens:
                break
            results.append(r)
            token_count += chunk_tokens

        return results

token预算截断

max_tokens参数用于防止检索器返回超过AI工具可用范围的上下文。估算方式采用每个token约4个字符（对英文散文而言是合理近似）。结果会按贪心策略截断：依排名顺序加入结果，直到预算耗尽。

这是一种保守策略。更复杂的做法会考虑每条结果的质量分数，并优先选择更短、质量更高的结果，而不是更长、质量更低的结果。贪心方法更简单，实践中效果也很好，因为RRF排名已经按相关性对结果排序。

数据库Schema（完整）

-- Chunk content and metadata
CREATE TABLE chunks (
    id INTEGER PRIMARY KEY,
    file_path TEXT NOT NULL,
    section TEXT NOT NULL,
    chunk_text TEXT NOT NULL,
    heading_context TEXT DEFAULT '',
    mtime_ns INTEGER NOT NULL,
    embedded_at REAL NOT NULL
);

CREATE INDEX idx_chunks_file ON chunks(file_path);
CREATE INDEX idx_chunks_mtime ON chunks(mtime_ns);

-- FTS5 for BM25 search (content-synced to chunks table)
CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text, section, heading_context,
    content=chunks, content_rowid=id
);

-- sqlite-vec for vector KNN search
CREATE VIRTUAL TABLE chunk_vecs USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[256]
);

-- Model metadata for compatibility tracking
CREATE TABLE model_meta (
    key TEXT PRIMARY KEY,
    value TEXT
);

优雅降级路径

Full pipeline:     BM25 + Vector + RRF  →  Best results
No sqlite-vec:     BM25 only            →  Good results (no semantic)
No model download:  BM25 only            →  Good results (no semantic)
No FTS5:           Vector only           →  Decent results (no keyword)
No database:       Error                 →  Prompt user to run indexer

检索器会在初始化时检查能力，并调整查询策略。缺失某个组件会降低质量，但不会导致错误。唯一的硬性失败是数据库文件缺失。

生产环境统计

基于包含16,894个文件、49,746个chunk、83 MB SQLite数据库的vault测得，硬件为Apple M3 Pro：

内容哈希与变更检测

索引器需要知道自上次索引运行以来哪些文件发生了变化。本节介绍变更检测机制和哈希策略。

文件修改时间比较

索引器会在chunks表中为每个chunk存储mtime_ns（以纳秒计的文件修改时间）。在增量运行时，索引器会：

1. 扫描vault中允许文件夹内的所有.md文件
2. 从文件系统读取每个文件的mtime_ns
3. 与数据库中存储的mtime_ns进行比较
4. 识别3类文件：
5. 新文件：路径存在于文件系统中，但不存在于数据库中
6. 已变更文件：路径两边都存在，但mtime_ns不同
7. 已删除文件：路径存在于数据库中，但不存在于文件系统中

def get_stale_files(self, vault_mtimes):
    """Find files whose mtime changed or are new."""
    stored = dict(self.db.execute(
        "SELECT DISTINCT file_path, mtime_ns FROM chunks"
    ).fetchall())

    stale = []
    for path, mtime in vault_mtimes.items():
        if path not in stored or stored[path] != mtime:
            stale.append(path)
    return stale

def get_deleted_files(self, vault_paths):
    """Find files in database that no longer exist in vault."""
    stored_paths = set(r[0] for r in self.db.execute(
        "SELECT DISTINCT file_path FROM chunks"
    ).fetchall())
    return stored_paths - set(vault_paths)

为什么使用mtime，而不是内容哈希

内容哈希（文件内容的SHA-256）会比mtime比较更可靠，因为它能检测到文件被触碰但内容未变的情况（例如git checkout恢复了原始mtime）。不过，哈希要求在每次增量运行时读取每个文件。对于16,894个文件，读取文件内容需要2到3秒。从文件系统读取mtime则不到100ms。

取舍在于：mtime比较偶尔会对未变更文件触发不必要的重新索引（误报），但不会漏掉实际变更。误报的代价只是每次运行多几个embedding调用。速度差异（100ms对3秒）让mtime成为务实之选，尤其是该系统会在每次AI交互时运行。

处理删除

当文件从vault中删除时，索引器会从数据库中移除该文件的所有chunk：

def remove_file(self, file_path):
    """Remove all chunks and vectors for a file."""
    chunk_ids = [r[0] for r in self.db.execute(
        "SELECT id FROM chunks WHERE file_path = ?",
        [file_path],
    ).fetchall()]

    for cid in chunk_ids:
        self.db.execute(
            "DELETE FROM chunk_vecs WHERE id = ?", [cid]
        )
    self.db.execute(
        "DELETE FROM chunks WHERE file_path = ?",
        [file_path],
    )

自sqlite-vec v0.1.7起，DELETE FROM chunk_vecs语句可原生工作；v0.1.9又修复了针对带有较长元数据文本列的vec0表执行DELETE操作的bug。¹⁴²³更早版本需要变通方案（删除并重建虚拟表，或维护一个外部“active IDs”集合）。如果运行的是0.1.9之前的版本，请先升级，再依赖元数据较重schema中的直接删除。

FTS5内容同步表需要通过INSERT INTO chunks_fts(chunks_fts, rowid, ...) VALUES('delete', ?, ...)为每个被移除的行显式删除。索引器会将此作为文件移除流程的一部分处理。

增量重建索引与完整重建索引

索引器支持两种模式：增量模式（速度快，适合日常使用）和完整模式（速度慢，偶尔使用）。本节介绍各自的使用场景、幂等性保证以及损坏恢复。

增量重建索引

使用场景：编辑笔记后的日常索引。默认模式。

执行内容： 1. 扫描知识库中的文件变更（比较mtime） 2. 删除已删除文件对应的chunk 3. 对已变更文件重新chunking并重新生成embeddings 4. 为新文件插入新的chunk 5. 同步FTS5索引

典型耗时：对于包含16,000个文件的知识库，一天编辑量通常少于10秒。

python index_vault.py --incremental

完整重建索引

使用场景： - 更改embedding模型后（检测到模型哈希不匹配） - schema迁移后（新增列、变更索引） - 数据库损坏后（完整性检查失败） - 增量索引产生意外结果时

执行内容： 1. 删除所有现有数据（chunks、vectors、FTS5条目） 2. 扫描整个知识库 3. 对所有文件进行chunking 4. 为所有chunk生成embeddings 5. 从头构建FTS5索引

典型耗时：在Apple M3 Pro上处理16,894个文件约需4分钟。

python index_vault.py --full

幂等性

两种模式都是幂等的：同一命令运行两次会产生相同结果。索引器会先删除某个文件已有的chunk，再插入新的chunk。因此，对已经是最新状态的数据库重新运行增量索引会产生零变更。重新运行完整索引会生成完全相同的数据库。

损坏恢复

如果SQLite数据库损坏（写入期间断电、磁盘错误、事务中途进程被终止）：

# Check integrity
sqlite3 vectors.db "PRAGMA integrity_check;"

# If corruption detected, full reindex rebuilds from source files
python index_vault.py --full

真实数据源始终是知识库文件，而不是数据库。数据库是派生产物，可以随时重建。这是一项关键设计属性：您永远不需要备份数据库。

--incremental标志

索引器使用--incremental运行时：

1. 模型哈希检查。将存储的模型哈希与当前模型进行比较。如果不同，自动切换到完整重建索引模式，并向用户发出警告。
2. 文件扫描。遍历允许的文件夹，收集文件路径和mtime。
3. 变更检测。与已存储数据进行比较。
4. 批量处理。以64个文件为一批，对已变更文件重新chunking并重新生成embeddings。
5. 进度报告。打印已处理文件数量和耗时。
6. 优雅关闭。处理SIGINT时，先完成当前文件再停止。

凭据过滤与数据边界

个人笔记中可能包含密钥：API密钥、bearer tokens、数据库连接字符串、调试期间粘贴的私钥。凭据过滤器会阻止这些内容进入检索索引。

问题

一篇关于调试OAuth集成的笔记可能包含：

The token was: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
I used this curl command:
  curl -H "Authorization: Bearer sk-ant-api03-abc123..."

如果不进行过滤，JWT和API密钥都会被chunking、生成embeddings，并存入数据库。搜索“authentication”会返回包含真实密钥的chunk。更糟的是，如果检索器通过MCP将结果提供给AI工具，这些密钥会出现在AI的上下文窗口中，并可能进入工具日志。

基于模式的过滤

凭据过滤器会在每个chunk入库存储前运行，匹配25种供应商特定模式以及通用模式：

供应商特定模式：

通用模式：

过滤器实现

def clean_content(text):
    """Scrub credentials from text before indexing."""
    result = ScanResult(is_clean=True, match_count=0, patterns=[])

    for pattern in CREDENTIAL_PATTERNS:
        matches = pattern.regex.findall(text)
        if matches:
            text = pattern.regex.sub(
                f"[REDACTED:{pattern.name}]", text
            )
            result.is_clean = False
            result.match_count += len(matches)
            result.patterns.append(pattern.name)

    return text, result

关键设计选择：

1. 先过滤，再生成embedding。用于生成embedding的是清理后的文本。向量表示永远不会编码凭据模式。查询“API key”会返回讨论API密钥管理的笔记，而不是包含真实密钥的笔记。

2. 替换，而不是删除。[REDACTED:pattern-name]标记会保留周围文本的语义上下文。embedding会捕捉到“这里曾有类似凭据的内容”，但不会编码凭据本身。

3. 记录模式，不记录值。过滤器会记录匹配到哪些模式（例如“Scrubbed 2 credential(s) from oauth-debug.md [jwt, bearer-token]”），但绝不会记录凭据值。

基于路径的排除

.indexignore文件提供按路径进行的粗粒度排除。凭据过滤器则在已索引文件内部提供细粒度清理。二者缺一不可：

• .indexignore用于明确包含敏感内容的整个文件夹（健康笔记、财务记录、职业文档）
• 凭据过滤器用于清理意外嵌入在原本可索引内容中的密钥

数据分类

对于包含多样内容的知识库，可以考虑按敏感度对笔记进行分类：

MCP服务器架构

Model Context Protocol（MCP）服务器会将检索器作为 AI agent 可调用的工具暴露出来。本节介绍服务器设计、能力范围和权限边界。

协议选择：STDIO 与 HTTP

MCP支持两种传输模式：

STDIO——AI 工具将 MCP服务器作为子进程启动，并通过 stdin/stdout 通信。这是本地工具的标准模式。Claude Code、Codex CLI 和 Cursor 都支持 STDIO MCP服务器。

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/path/to/vault",
        "DB_PATH": "/path/to/vectors.db"
      }
    }
  }
}

HTTP——MCP服务器作为独立 HTTP 服务运行。适用于远程访问、多客户端设置，或 vault 位于共享服务器上的团队配置。

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

建议：个人 vault 使用 STDIO。它更简单、更安全（无网络暴露），并且服务器生命周期由 AI 工具管理。只有当多个工具或多台机器需要并发访问同一个 vault 时，才使用 HTTP。

MCP规范演进。2025年6月的 MCP规范新增了 OAuth 2.1 授权、结构化工具输出（类型化返回 schema）以及 elicitation（服务器发起的用户提示）。2025年11月版本将 Streamable HTTP 作为一等传输模式发布，同时提供用于自动浏览服务器能力的 .well-known URL 发现、声明工具是只读还是会改变状态的结构化工具注解，以及 SDK 层级标准化系统。⁷⁹下一版修订现在已经明确：2026-07-28 规范已于2026年5月21日进入 Release Candidate，这是 MCP 发布以来最大的一次修订。其核心变化包括无状态协议核心（移除了 initialize 握手和 Mcp-Session-Id 头，因此服务器不再跟踪每个连接的会话状态）、MCP Apps（服务器可以返回服务器渲染的 HTML，并显示在沙盒化客户端 iframe 中）、Tasks 从实验性核心功能毕业为官方扩展（用于长时间运行操作的 tasks/get、tasks/update、tasks/cancel）、强化的 OAuth 2.0 / OIDC 授权，以及12个月功能弃用生命周期政策。最终规范将于2026年7月28日发布。²⁴对于个人 vault 服务器，STDIO 仍是最简单的路径，而无状态核心会让单用户 STDIO 服务器更加轻量。Streamable HTTP 传输、.well-known 发现和 MCP Apps 主要惠及具备多租户路由和负载均衡的企业级 HTTP 部署。请关注 MCP roadmap，了解会影响传输选择的更新。

能力设计

MCP服务器应暴露一组最小化工具：

search——主要工具。运行 hybrid 检索并返回排序后的结果。

{
  "name": "obsidian_search",
  "description": "Search the Obsidian vault using hybrid BM25 + vector retrieval",
  "parameters": {
    "query": { "type": "string", "description": "Search query" },
    "limit": { "type": "integer", "default": 5 },
    "max_tokens": { "type": "integer", "default": 2000 }
  }
}

read_note——按路径读取特定笔记的完整内容。当 agent 想查看某个搜索结果的完整上下文时很有用。

{
  "name": "obsidian_read_note",
  "description": "Read the full content of a note by file path",
  "parameters": {
    "file_path": { "type": "string", "description": "Relative path within vault" }
  }
}

list_notes——列出匹配筛选条件的笔记（按文件夹、标签、类型或日期范围）。当 agent 没有具体查询、需要探索时很有用。

{
  "name": "obsidian_list_notes",
  "description": "List notes matching filters",
  "parameters": {
    "folder": { "type": "string", "description": "Folder path within vault" },
    "tag": { "type": "string", "description": "Tag to filter by" },
    "limit": { "type": "integer", "default": 20 }
  }
}

get_context——便利工具：运行搜索，并将结果格式化为适合注入对话的上下文块。

{
  "name": "obsidian_get_context",
  "description": "Get formatted context from vault for a topic",
  "parameters": {
    "topic": { "type": "string", "description": "Topic to get context for" },
    "max_tokens": { "type": "integer", "default": 2000 }
  }
}

权限边界

MCP服务器应强制执行严格边界：

1. 只读。服务器读取 vault 和索引数据库。它不会创建、修改或删除笔记。写入操作（捕获新笔记）由单独的 hooks 或 skills 处理，而不是由 MCP服务器处理。

2. 限定在 vault 内。服务器只读取已配置 vault 路径内的文件。必须拒绝路径遍历尝试（../../etc/passwd）。

3. 凭据过滤输出。即使数据库中包含的是预过滤内容，也应在输出时应用凭据过滤，作为纵深防御措施。

4. 限制响应 token。对所有工具响应强制执行 max_tokens，防止 AI 工具接收过大的上下文块。

错误处理

MCP工具应返回结构化错误消息，帮助 AI 工具恢复：

def search(self, query, limit=5, max_tokens=2000):
    if not self.db_path.exists():
        return {
            "error": "Index database not found. Run the indexer first.",
            "suggestion": "python index_vault.py --full"
        }

    results = self.retriever.search(query, limit, max_tokens)

    if not results:
        return {
            "results": [],
            "message": f"No results found for '{query}'. Try broader terms."
        }

    return {
        "results": [
            {
                "file_path": r["file_path"],
                "section": r["section"],
                "text": r["chunk_text"],
                "score": round(r["rrf_score"], 4),
            }
            for r in results
        ],
        "count": len(results),
        "query": query,
    }

Claude Code 集成

Claude Code 是 Obsidian 检索系统的主要使用方。本节介绍 MCP 配置、hook 集成以及 obsidian_bridge.py 模式。

MCP 配置

将 Obsidian MCP 服务器添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/vault",
        "DB_PATH": "/absolute/path/to/vectors.db"
      }
    }
  }
}

添加配置后，重启 Claude Code。MCP 服务器将作为子进程启动。验证它是否正在运行：

> What tools do you have from the obsidian MCP server?

Claude Code 应列出可用工具（obsidian_search、obsidian_read_note 等）。

Hook 集成

Hooks 会在定义好的生命周期节点扩展 Claude Code 的行为。与 Obsidian 集成相关的 hook 有两个：

PreToolUse hook —— 在 agent 处理工具调用之前查询库。自动注入相关上下文。

#!/bin/bash
# ~/.claude/hooks/pre-tool-use/obsidian-context.sh
# Automatically inject vault context before tool execution

TOOL_NAME="$1"
PROMPT="$2"

# Only inject context for code-related tools
case "$TOOL_NAME" in
    Edit|Write|Bash)
        # Query the vault
        CONTEXT=$(python /path/to/retriever.py search "$PROMPT" --limit 3 --max-tokens 1500)
        if [ -n "$CONTEXT" ]; then
            echo "---"
            echo "Relevant vault context:"
            echo "$CONTEXT"
            echo "---"
        fi
        ;;
esac

PostToolUse hook —— 将重要的工具输出捕获回库中，供后续检索使用。

#!/bin/bash
# ~/.claude/hooks/post-tool-use/capture-insight.sh
# Capture significant outputs to vault (selective)

TOOL_NAME="$1"
OUTPUT="$2"

# Only capture substantial outputs
if [ ${#OUTPUT} -gt 500 ]; then
    python /path/to/capture.py --text "$OUTPUT" --source "claude-code-$TOOL_NAME"
fi

obsidian_bridge.py 模式

桥接模块提供一个 Python API，供 hooks 和 skills 调用：

# obsidian_bridge.py
from retriever import HybridRetriever

_retriever = None

def get_retriever():
    global _retriever
    if _retriever is None:
        _retriever = HybridRetriever(
            db_path="/path/to/vectors.db",
            vault_path="/path/to/vault",
        )
    return _retriever

def search_vault(query, limit=5, max_tokens=2000):
    """Search vault and return formatted context."""
    retriever = get_retriever()
    results = retriever.search(query, limit, max_tokens)

    if not results:
        return ""

    lines = ["## Vault Context\n"]
    for r in results:
        lines.append(f"**{r['file_path']}** — {r['section']}")
        lines.append(f"> {r['chunk_text'][:500]}")
        lines.append("")

    return "\n".join(lines)

/capture Skill

用于将洞察捕获回库中的 Claude Code skill：

/capture "OAuth token rotation requires both access and refresh token invalidation"
  --domain security
  --tags oauth,tokens

该 skill 会在 00-inbox/ 中创建一条带有正确 frontmatter 的新笔记，并触发增量重新索引，使新笔记立即可搜索。

自定义命令模式

Claude Code skills 可以将库操作封装为具名命令。实践者已经构建了 Obsidian 专用命令库，把库同时作为读取源和写入目标。

信号扫描。 /scan-intel 命令会查询外部来源，根据个人研究兴趣为发现项评分，并将符合条件的信号写成带 frontmatter 的库笔记：

/scan-intel --topics "agent infrastructure, security" --lookback 7d

该命令从配置的来源（arXiv、HN、RSS）抓取内容，应用评分模型（相关性、可执行性、深度、权威性），并将通过筛选的信号写入特定主题的库文件夹。库成为自动化情报流水线的下游使用方。

Captain’s log。 /captains-log 命令会汇总所有仓库的每日 git 活动，将结构化日志条目写入库中，并包含已做出的决策、领悟和未完事项：

/captains-log

该命令从 GitHub 拉取提交历史，按仓库分组，并格式化为叙事型日志条目。久而久之，每日日志会形成一份可搜索的记录，说明交付了什么以及为什么交付。

Obsidian 捕获。 /obsidian-capture 命令会从当前 Claude Code 会话中提取一条洞察，并将其连同正确的 metadata 直接写入库中：

/obsidian-capture "SAST gates in agent loops increase security degradation"
  --folder AI-Tools --tags security,agents

该模式可扩展到任何库操作：创建 MOCs、更新项目状态笔记、链接相关信号，或根据累积的每日日志生成周报。

社区示例。 实践者正在发布自己的命令库。一位开发者分享了 22 条自定义 Obsidian + Claude Code 命令，覆盖每日回顾、项目规划、研究捕获和内容工作流。¹ 另一位开发者构建了一个 “Visual Explainer” skill，可根据代码分析在库中生成图表笔记。² 这些命令各有不同，但架构一脉相承：以 Claude Code skills 作为接口，以库笔记作为存储层，以检索基础设施作为查询引擎。

上下文窗口管理

集成时应注意 Claude Code 的上下文窗口：

• 将每次查询注入的上下文限制在 1,500-2,000 tokens。 超过这个范围会挤占 agent 的工作记忆。
• 包含来源标注。 始终包含文件路径和章节标题，便于 agent 引用来源。
• 截断 chunk 文本。 较长的 chunk 应使用 ... 截断，而不是完全省略。前 300-500 个字符通常包含关键信息。
• 不要在每次工具调用时都注入。 PreToolUse hook 应根据被调用的工具选择性注入上下文。读取操作不需要库上下文。Write 和 Edit 操作则会从中受益。

Codex CLI 集成

Codex CLI 通过 config.toml 连接到 MCP 服务器。其集成模式在配置语法和指令传递方式上不同于 Claude Code。

MCP 配置

添加到 .codex/config.toml 或 ~/.codex/config.toml：

[mcp_servers.obsidian]
command = "python"
args = ["/path/to/obsidian_mcp.py"]

[mcp_servers.obsidian.env]
VAULT_PATH = "/absolute/path/to/vault"
DB_PATH = "/absolute/path/to/vectors.db"

AGENTS.md 模式

Codex CLI 会读取 AGENTS.md 中的项目级指令。加入库搜索指导：

## Available Tools

### Obsidian Vault (MCP: obsidian)
Use the `obsidian_search` tool to find relevant context from the knowledge base.
Search the vault when you need:
- Background on a concept or pattern
- Prior decisions or rationale
- Reference material for implementation

Example queries:
- "authentication patterns in FastAPI"
- "how does the review aggregator work"
- "sqlite-vec configuration"

与 Claude Code 的差异

关键差异： Codex CLI 不支持 hooks。因此无法使用自动上下文注入模式（PreToolUse hook）。应改为在 AGENTS.md 中加入明确指令，要求 agent 在开始工作前搜索库。

Cursor和其他工具

Cursor以及其他支持MCP的AI工具，可以连接到同一个Obsidian MCP服务器。本节介绍常见工具的配置方法。

Cursor

将以下内容添加到项目根目录中的.cursor/mcp.json：

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/vault",
        "DB_PATH": "/absolute/path/to/vectors.db"
      }
    }
  }
}

Cursor的.cursorrules文件可以包含使用库的说明：

When working on implementation tasks, search the Obsidian vault
for relevant context before writing code. Use the obsidian_search
tool with descriptive queries about the concept you're implementing.

兼容性矩阵

非MCP工具的回退方案

对于不支持MCP的工具，可以将检索器封装为CLI：

# Search from command line
python retriever_cli.py search "query text" --limit 5

# Output formatted for copy-paste into any tool
python retriever_cli.py context "query text" --format markdown

该CLI会输出结构化文本，可手动粘贴到任何AI工具的输入中。与MCP集成相比，这种方式不够优雅，但通用可行。

基于结构化笔记的Prompt缓存

库中的结构化笔记可以作为可复用的上下文块，在多次AI交互中减少token用量。本节介绍缓存键设计和token预算管理。

模式

不要在每次交互时都搜索上下文，而是从结构良好的库笔记中预先构建上下文块并缓存：

# cache_keys.py
CONTEXT_BLOCKS = {
    "auth-patterns": {
        "vault_query": "authentication patterns implementation",
        "max_tokens": 1500,
        "ttl_hours": 24,  # Rebuild daily
    },
    "api-conventions": {
        "vault_query": "API design conventions REST patterns",
        "max_tokens": 1000,
        "ttl_hours": 168,  # Rebuild weekly
    },
    "project-architecture": {
        "vault_query": "current project architecture decisions",
        "max_tokens": 2000,
        "ttl_hours": 12,  # Rebuild twice daily
    },
}

缓存失效

缓存失效基于两个信号：

1. TTL过期。每个上下文块都有存活时间。TTL过期后，会通过重新查询库来重建该块。
2. 库变更检测。当索引器检测到对缓存上下文块有贡献的文件发生变化时，该块会立即失效。

Token预算管理

会话开始时会有一个总上下文预算。缓存块会占用其中一部分预算：

Total context budget:    8,000 tokens
├─ System prompt:        1,500 tokens
├─ Cached blocks:        3,000 tokens (pre-loaded)
├─ Dynamic search:       2,000 tokens (on-demand)
└─ Conversation:         1,500 tokens (remaining)

缓存块会在会话开始时加载。动态搜索结果则按每次查询填充剩余预算。这种hybrid方式既能为agent提供常用上下文基线，又能为特定查询保留预算。

缓存前后的Token用量

不使用缓存：每个相关查询都会触发一次库搜索，返回1,500-2,000个token的上下文。一个会话中进行10次查询时，agent会消耗15,000-20,000个token的库上下文。

使用缓存：3个预构建上下文块总共消耗4,500个token。额外搜索会为每个唯一查询增加1,500-2,000个token。如果10次查询中有6次由缓存块覆盖，agent会消耗4,500 + (4 * 1,500) = 10,500个token，约为未缓存用量的一半。

用于上下文压缩的PostToolUse Hook

工具输出可能很冗长：堆栈跟踪、文件列表、测试结果。PostToolUse hook可以在这些输出占用上下文窗口空间之前进行压缩。

问题

运行测试的Bash工具调用可能返回：

PASSED tests/test_auth.py::test_login_success
PASSED tests/test_auth.py::test_login_failure
PASSED tests/test_auth.py::test_token_refresh
PASSED tests/test_auth.py::test_session_expiry
... (200 more lines)
FAILED tests/test_api.py::test_rate_limit_exceeded

完整输出有5,000个token，但真正的信号只有2行：200个通过，1个失败。

Hook实现

#!/bin/bash
# ~/.claude/hooks/post-tool-use/compress-output.sh
# Compress verbose tool outputs to preserve context window

TOOL_NAME="$1"
OUTPUT="$2"
OUTPUT_LEN=${#OUTPUT}

# Only compress large outputs
if [ "$OUTPUT_LEN" -lt 2000 ]; then
    exit 0  # Pass through unchanged
fi

case "$TOOL_NAME" in
    Bash)
        # Compress test output
        if echo "$OUTPUT" | grep -q "PASSED\|FAILED"; then
            PASSED=$(echo "$OUTPUT" | grep -c "PASSED")
            FAILED=$(echo "$OUTPUT" | grep -c "FAILED")
            FAILURES=$(echo "$OUTPUT" | grep "FAILED")
            echo "Tests: $PASSED passed, $FAILED failed"
            if [ "$FAILED" -gt 0 ]; then
                echo "Failures:"
                echo "$FAILURES"
            fi
        fi
        ;;
esac

防止递归触发

如果没有防护，会产生输出的压缩hook可能触发自身：

# Guard against recursive invocation
if [ -n "$COMPRESS_HOOK_ACTIVE" ]; then
    exit 0
fi
export COMPRESS_HOOK_ACTIVE=1

压缩启发式规则

信号摄入与分流流水线

摄入层决定哪些内容进入库中。没有筛选，库会不断积累噪声。本节介绍将信号路由到领域文件夹的评分流水线。

来源

信号来自多个渠道：

• RSS feeds： 技术博客、安全公告、发布说明
• 通过 Web Clipper 添加书签： 官方 Obsidian Web Clipper 扩展（Chrome、Firefox、Safari）是浏览器端捕获中保真度最高的摄入路径。2026年4月的发布周期显著提升了它对 AI 工作流的实用性：²²
  • 1.4.0（4月9日）： 交互式 YouTube 转录 UI——固定视频、浏览转录文本、自动滚动，并高亮当前位置。另有默认“Open in Reader”功能，可将一键捕获直接发送到 Reader 模式。
  • 1.5.0–1.5.1（4月15日）： Highlights 查看器——在整个库中浏览和搜索已捕获的高亮内容。进入 Reader 时带有淡入过渡。YouTube 播放/暂停更加顺畅。1.5.1 修复了 webpack 编译回归问题。
  • 1.6.0–1.6.2（4月21–23日）： 重做 Highlighter UX，并支持移动端。Defuddle 0.18 为 LinkedIn、Threads、Bluesky、Discourse 和 Medium 增加了特定来源提取器。1.6.2 修复了 Safari 嵌入模式下的剪贴板回归问题。 按来源域名配置模板，让 YouTube 转录、GitHub README 和长文分别落入命名合理的笔记，并带有下方评分流水线所需的正确 frontmatter。
• Newsletters： 来自电子邮件 newsletters 的关键摘录
• 手动捕获： 阅读、对话或研究过程中写下的笔记
• 工具输出： 通过 hooks 捕获的重要 AI 工具输出
• iOS Share Extension： Obsidian 的 iOS 应用（2026年初更新）包含 Share Extension，可将 Safari、社交网络和其他应用中的内容直接保存到库中，无需打开 Obsidian。¹⁹ 这形成了一条低摩擦的移动端摄入路径——从 Safari 分享一篇文章，它就会作为库笔记到达，等待评分。
• Obsidian CLI： Shell 脚本和 hooks 可以通过 obsidian file create 创建笔记，或通过 obsidian file append 追加到现有笔记，从而在桌面端启用自动化摄入流水线。

评分维度

每个信号按4个维度评分（每项0.0到1.0）：

综合分数与路由

composite = (relevance * 0.35) + (actionability * 0.25) +
            (depth * 0.25) + (authority * 0.15)

领域路由

分数高于0.55的信号会根据关键词匹配和主题分类，路由到12个领域文件夹之一：

05-signals/
├── ai-tooling/        # Claude, LLMs, AI development tools
├── security/          # Vulnerabilities, auth, cryptography
├── systems/           # Architecture, distributed systems
├── programming/       # Languages, patterns, algorithms
├── web/               # Frontend, backends, APIs
├── data/              # Databases, data engineering
├── devops/            # CI/CD, containers, infrastructure
├── design/            # UI/UX, product design
├── mobile/            # iOS, Android, cross-platform
├── career/            # Industry trends, hiring, growth
├── research/          # Academic papers, whitepapers
└── other/             # Signals that don't fit a domain

生产统计

运行14个月后的数据：

Knowledge Graph 模式

Obsidian 的 wiki-link 图谱编码笔记之间的关系。本节介绍链接语义、用于上下文扩展的图遍历，以及会降低图谱质量的反模式。

Backlink 语义

每个 wiki-link 都会在图中创建一条有向边。Obsidian 同时跟踪正向链接和 backlinks：

• 正向链接： 笔记 A 包含 [[Note B]] → A 链接到 B
• Backlink： 笔记 B 显示笔记 A 引用了它

图谱会根据上下文编码不同类型的关系：

Maps of Content（MOCs）

MOCs 是索引笔记，用于将相关笔记组织成可导航的结构：

---
title: "Authentication & Security MOC"
type: moc
domain: security
---

## Core Concepts
- [[OAuth 2.0 Overview]]
- [[JWT Token Anatomy]]
- [[Session Management Patterns]]

## Implementation Patterns
- [[OAuth Token Rotation]]
- [[Refresh Token Security]]
- [[PKCE Flow Implementation]]

## Failure Modes
- [[Token Expiry Handling]]
- [[Session Fixation Prevention]]
- [[CSRF Defense Strategies]]

MOCs 通过两种方式改善检索：

1. 直接匹配。 搜索“authentication overview”会匹配 MOC 本身，从而为 agent 提供一份经过筛选的相关笔记列表。
2. 上下文扩展。 找到某条具体笔记后，检索器可以检查该笔记是否出现在任何 MOCs 中，并将 MOC 的结构纳入结果，为 agent 提供更大主题范围的地图。

用于上下文扩展的图遍历

检索器的一个未来增强方向：找到排名靠前的结果后，通过跟随链接扩展上下文：

def expand_context(results, depth=1):
    """Follow wiki-links from top results to find related context."""
    expanded = set()
    for result in results:
        # Parse wiki-links from chunk text
        links = extract_wiki_links(result["chunk_text"])
        for link_target in links:
            # Resolve link to file path
            target_path = resolve_wiki_link(link_target)
            if target_path and target_path not in expanded:
                expanded.add(target_path)
                # Include target's most relevant chunk
                target_chunks = get_chunks_for_file(target_path)
                # ... rank and include best chunk
    return results + list(expanded_results)

这尚未在当前检索器中实现，但它是图结构的自然延伸。

反模式

孤立集群。 一组彼此链接但与库中其他部分没有连接的笔记。Obsidian 中的图谱面板会将它们显示为断开的孤岛。孤立集群表明缺少 MOCs，或缺少跨领域链接。

标签蔓延。 标签使用不一致，或创建过多细粒度标签。一个包含5,000条笔记、500个唯一标签的库，平均每10个标签只有1条笔记——这些标签对筛选并无帮助。建议整合为20-50个高层级标签，并映射到您的领域文件夹。

链接密集、内容稀薄的笔记。 完全由 wiki-links 组成、没有正文的笔记。这类笔记索引效果很差，因为 chunker 没有可嵌入的文本。至少添加一段上下文，说明这些链接笔记为什么相关。

凡事都用双向链接。 并非每个引用都需要成为 wiki-link。顺带提到“OAuth”并不需要 [[OAuth 2.0 Overview]]。请将 wiki-links 留给有意图、可导航的关系，也就是点击链接能提供有用上下文的场景。

开发者工作流配方

将知识库检索与日常开发任务结合起来的实用工作流。

早晨上下文加载

通过加载相关上下文开始一天的工作：

Search my vault for notes about [current project] updated in the last week

检索器会返回与当前项目相关的近期笔记，帮助您快速回顾上次进展。相比重新阅读昨天的提交消息，这种方式更高效。

编码过程中的研究捕获

实现功能时，无需离开编辑器即可捕获洞见：

/capture "FastAPI dependency injection with async generators requires yield,
not return. The generator is the dependency lifecycle."
  --domain programming
  --tags fastapi,dependency-injection

捕获的洞见会立即建立索引，并可供后续检索。数月积累下来，这些微型捕获会形成一套针对具体实现的知识语料库。

项目启动

开始新项目或新功能时：

1. 搜索知识库：“我对[technology/pattern]了解什么？”
2. 查看前5条结果，了解以往决策和注意事项
3. 检查该领域是否已有MOC；如果没有，则创建一个
4. 搜索故障模式：“[technology]的问题”

使用知识库搜索进行调试

遇到错误或异常行为时：

Search my vault for [error message or symptom]

以往的调试笔记往往包含根因和修复方法。对于跨项目反复出现的问题，这尤其有价值——知识库会记住您遗忘的内容。

代码审查准备

审查PR之前：

Search my vault for patterns and conventions about [module being changed]

知识库会返回与待审查代码相关的以往决策、架构约束和编码标准。审查基于组织知识，而不仅仅是diff。

性能调优

本节介绍针对不同知识库规模和使用模式的优化策略。

索引大小管理

达到50,000条以上笔记时，可以考虑： - 将批大小从64增加到128，以加快embeddings生成 - 使用WAL模式（默认）支持并发访问 - 在非高峰时段运行完整重建索引

查询优化

WAL模式。 SQLite的Write-Ahead Logging模式允许索引器写入时并发读取：

db.execute("PRAGMA journal_mode=WAL")

当MCP服务器在索引器执行增量更新期间处理查询时，这一点至关重要。

连接池。 MCP服务器应复用数据库连接，而不是每次查询都打开新连接。一个启用WAL模式的长期连接即可支持并发读取。

# MCP server initialization
db = sqlite3.connect(DB_PATH, check_same_thread=False)
db.execute("PRAGMA journal_mode=WAL")
db.execute("PRAGMA mmap_size=268435456")  # 256 MB mmap

内存映射I/O。 mmap_size pragma会指示SQLite对数据库文件使用内存映射I/O。对于83 MB的数据库，将整个文件映射到内存中可以消除大部分磁盘读取。

FTS5优化。 完整重建索引后，运行：

INSERT INTO chunks_fts(chunks_fts) VALUES('optimize');

这会合并FTS5的内部b-tree段，降低后续搜索的查询延迟。

扩展性基准测试

在Apple M3 Pro、36 GB RAM、NVMe SSD上测得：

所有基准测试均包括数据库访问、查询执行和结果格式化。MCP STDIO通信的网络延迟会额外增加1-2ms。

故障排查

索引漂移

症状： 搜索返回过期结果，或漏掉最近新增的笔记。

原因： 添加笔记后未运行增量索引器，或者文件的mtime未更新（例如，从另一台机器同步时保留了时间戳）。

修复： 运行完整重建索引：python index_vault.py --full

Embedding模型切换

症状： 更换embedding模型后，vector搜索返回毫无意义的结果。

原因： 旧向量（来自之前的模型）正在与新的查询向量比较。维度或向量空间语义不兼容。

修复： 索引器应检测模型哈希不匹配，并自动触发完整重建索引。如果没有触发，请手动清空数据库并重建索引：

rm vectors.db
python index_vault.py --full

FTS5维护

症状： 多次增量更新后，FTS5查询返回错误或不完整结果。

原因： 经过大量小规模更新后，FTS5内部段可能变得碎片化。

修复： 重建并优化：

INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild');
INSERT INTO chunks_fts(chunks_fts) VALUES('optimize');

MCP超时

症状： AI工具报告MCP服务器超时。

原因： 第一次查询会触发模型加载（惰性初始化），耗时2-5秒。AI工具的默认MCP超时时间可能更短。

修复： 在服务器启动时预热模型：

# In MCP server initialization
retriever = HybridRetriever(db_path, vault_path)
retriever.search("warmup", limit=1)  # Trigger model load

SQLite文件锁

症状： 出现SQLITE_BUSY或SQLITE_LOCKED错误。

原因： 多个进程同时写入数据库。WAL模式允许并发读取，但只允许一个写入者。

修复： 确保只有一个进程（索引器）写入数据库。MCP服务器和hooks应只读。如果需要并发写入，请使用WAL模式并设置busy timeout：

db.execute("PRAGMA busy_timeout=5000")  # Wait up to 5 seconds

sqlite-vec无法加载

症状： Vector搜索被禁用；检索器以仅BM25模式运行。

原因： sqlite-vec扩展未安装、在库路径中找不到，或与SQLite版本不兼容。

修复：

# Install via pip
pip install sqlite-vec

# Or compile from source
git clone https://github.com/asg017/sqlite-vec
cd sqlite-vec && make

验证扩展是否加载：

import sqlite3
db = sqlite3.connect(":memory:")
db.enable_load_extension(True)
db.load_extension("vec0")
print("sqlite-vec loaded successfully")

大型知识库内存问题

症状： 对大型知识库（50,000条以上笔记）执行完整重建索引时出现内存不足错误。

原因： Embedding批大小过大，或所有文件内容被同时加载到内存中。

修复： 减小批大小，并以增量方式处理文件：

BATCH_SIZE = 32  # Reduce from 64

同时确保索引器逐个处理文件（读取、chunking并为每个文件生成embedding后，再进入下一个文件），而不是将所有文件一次性加载到内存。

迁移指南

从Apple Notes迁移

1. 通过“Export All”选项（macOS）导出Apple Notes，或使用apple-notes-liberator等迁移工具
2. 使用markdownify或pandoc将HTML导出转换为markdown
3. 将转换后的文件移动到知识库的00-inbox/文件夹
4. 检查并为每条笔记添加frontmatter
5. 将笔记移动到合适的领域文件夹

从Notion迁移

1. 从Notion导出：Settings → Export → Markdown & CSV
2. 将导出文件解压到知识库的00-inbox/文件夹
3. 修复Notion特有的markdown痕迹：
4. Notion使用- [ ]表示清单——这些是标准markdown
5. Notion将属性表作为HTML包含在内——转换为YAML frontmatter
6. Notion将图片嵌入为相对路径——将图片复制到附件文件夹
7. 添加标准frontmatter（type、domain、tags）
8. 将Notion页面链接替换为Obsidian wiki-links

从Google Docs迁移

1. 使用Google Takeout导出所有文档
2. 将.docx文件转换为markdown：pandoc -f docx -t markdown input.docx -o output.md
3. 批量转换：for f in *.docx; do pandoc -f docx -t markdown "$f" -o "${f%.docx}.md"; done
4. 移动到知识库，添加frontmatter，并整理到文件夹中

从普通Markdown迁移（非Obsidian）

如果您已经有一个markdown文件目录：

1. 将该目录作为Obsidian知识库打开（Obsidian → Open Vault → Open folder）
2. 如果该目录受版本控制，请将.obsidian/添加到.gitignore
3. 创建frontmatter模板并应用到现有文件
4. 在阅读和整理时，开始使用[[wiki-links]]链接笔记
5. 立即运行索引器——检索系统从第1天起即可工作

从其他检索系统迁移

如果您正从不同的embedding/搜索系统迁移：

1. 不要尝试迁移向量。 不同模型会生成不兼容的向量空间。请使用新模型运行完整重建索引。
2. 迁移内容，而不是索引。 知识库文件才是真实来源。索引只是派生产物。
3. 迁移后进行验证。 运行10-20个您已知答案的查询，并确认结果符合预期。

更新日志

参考资料