Example vault location
#
核心要点
上下文工程,而非笔记记录。 Obsidian 库对 AI 的价值不在于笔记本身,而在于使笔记可查询的检索层。一个拥有 16,000 个文件但缺乏检索能力的库只是一个只写数据库。一个拥有 200 个文件但配备混合搜索和 MCP 集成的库就是一个 AI 知识库。检索基础设施才是产品,笔记只是原材料。
混合检索优于纯关键词搜索或纯语义搜索。 BM25 能捕获精确的标识符和函数名。向量搜索能捕获不同术语间的同义词和概念匹配。Reciprocal Rank Fusion(RRF)无需分数校准即可合并两者的结果。任何单一方法都无法覆盖两种失败模式。基于 MS MARCO 段落排序的研究证实了这一规律:混合检索始终优于单独使用任一方法。1 混合检索器深度解析涵盖了 RRF 数学原理、基于真实数据的示例、失败模式分析以及交互式融合计算器。
MCP 使 AI 工具直接访问库。 Model Context Protocol(MCP)服务器将检索器作为工具暴露出来,Claude Code、Codex CLI、Cursor 及其他 AI 工具可以直接调用。智能体查询库后接收带有来源归属的排序结果,并在无需加载整个文件的情况下使用上下文。MCP 服务器是检索引擎的一个轻量封装。
本地优先意味着零 API 成本和完全隐私。 整个技术栈运行在单台机器上:SQLite 用于存储,Model2Vec 用于嵌入(embeddings),FTS5 用于关键词搜索,sqlite-vec 用于向量 KNN 搜索。无需云服务,无需 API 调用,无需网络依赖。个人笔记永远不会离开您的设备。完整重新嵌入 49,746 个分块按 OpenAI API 价格大约花费 $0.30,但真正的成本在于延迟、隐私暴露,以及一个本应离线工作的系统对网络的依赖。2
增量索引使系统在 10 秒内保持最新。 通过文件修改时间比较检测变更,仅对修改过的文件重新分块和重新嵌入。在 Apple M 系列硬件上,完整重建索引大约需要四分钟。对一天中典型编辑量的增量更新在十秒内完成。系统无需人工干预即可保持最新状态。
该架构可从 200 篇笔记扩展至 20,000+ 篇。 相同的三层设计(摄入层、检索层、集成层)适用于任意库规模。从对小型库进行纯 BM25 搜索开始。当关键词冲突成为问题时添加向量搜索。当您需要精确匹配和语义匹配时添加 RRF 融合。每一层都独立可用,也可独立移除。
如何使用本指南
本指南涵盖完整系统。您的起点取决于当前阶段:
| 您的情况… | 从这里开始 | 然后探索 |
|---|---|---|
| Obsidian + AI 新手 | 为什么选择 Obsidian 作为 AI 基础设施、快速入门 | 库架构、MCP 服务器架构 |
| 已有库,希望接入 AI | MCP 服务器架构、Claude Code 集成 | 嵌入模型、全文搜索 |
| 正在构建检索系统 | 完整检索管道、Reciprocal Rank Fusion | 性能调优、故障排除 |
| 团队或企业场景 | 决策框架、知识图谱模式 | 开发者工作流方案、迁移指南 |
标记为合约的章节包含实现细节、配置代码块和失败模式。标记为叙述的章节侧重于概念、架构决策及设计选择背后的推理。标记为方案的章节提供逐步操作流程。
为什么选择 Obsidian 作为 AI 基础设施
本指南的核心论点:Obsidian 库是个人 AI 知识库的最佳基底,因为它们本地优先、纯文本、图结构化,并且用户掌控技术栈的每一层。
Obsidian 提供了其他方案所不具备的 AI 能力
纯文本 Markdown 文件。 每条笔记都是文件系统上的一个 .md 文件。没有专有格式,无需数据库导出,无需 API 即可读取内容。任何能读取文件的工具都能读取您的库。grep、ripgrep、Python 的 pathlib、SQLite FTS5——它们都能直接处理源文件。当您构建检索系统时,您索引的是文件,而非 API 响应。由于源即文件系统,索引始终与源保持一致。
本地优先架构。 库存储在您的设备上。没有服务器,不依赖云同步,没有 API 速率限制,没有限制您处理自有内容方式的服务条款。您无需任何外部服务即可对笔记进行嵌入、索引、分块和搜索。这对 AI 基础设施至关重要,因为检索管道的运行速度取决于您的磁盘速度,而非 API 端点的响应速度。这对隐私同样重要:包含凭证、健康数据、财务信息和私人反思的个人笔记永远不会离开您的设备。
通过 wiki-link 实现图结构。 Obsidian 的 [[wiki-link]] 语法在笔记之间创建有向图。一条关于 OAuth 实现的笔记链接到关于令牌轮换、会话管理和 API 安全的笔记。图结构编码了人工策划的概念间关系。向量嵌入捕获语义相似性,而 wiki-link 捕获的是作者在思考主题时建立的有意关联。图是嵌入无法复制的信号。
插件生态系统。 Obsidian 拥有 1,800+ 个社区插件。Dataview 让您像查询数据库一样查询库。Templater 使用 JavaScript 逻辑从模板生成笔记。Git 集成将库同步到代码仓库。Linter 强制执行格式一致性。这些插件在不改变底层纯文本格式的情况下为库添加结构。检索系统索引的是这些插件的输出,而非插件本身。
500 万以上用户。 Obsidian 拥有庞大的活跃社区,产出模板、工作流、插件和文档。当您遇到库组织或插件配置问题时,很可能已有人记录了解决方案。社区还产出 Obsidian 周边工具:MCP 服务器、索引脚本、发布管道和 API 封装器。
纯文件系统无法提供的能力
一个 Markdown 文件目录具有纯文本优势,但缺少 Obsidian 添加的三项能力:
-
双向链接。 Obsidian 自动追踪反向链接。当您从笔记 A 链接到笔记 B 时,笔记 B 会显示笔记 A 引用了它。图面板可视化展示连接集群。这种双向感知是原始文件系统无法提供的元数据。
-
带插件渲染的实时预览。 Dataview 查询、Mermaid 图表和标注块实时渲染。写作体验比纯文本编辑器更丰富,而存储格式仍然是纯文本。您在富编辑环境中写作和组织;检索系统索引的是原始 Markdown。
-
社区基础设施。 插件发现、主题市场、同步服务(可选)、发布服务(可选)以及文档生态系统。您可以用独立工具复制任何单独功能,但 Obsidian 将它们打包成一个连贯的工作流。
Obsidian 不做的事(以及您需要构建的部分)
Obsidian 不包含检索基础设施。它具有基础搜索功能(全文、文件名、标签),但没有嵌入管道、向量搜索、融合排序、MCP 服务器、凭证过滤、分块策略,也没有外部 AI 工具的集成钩子。本指南涵盖您在 Obsidian 之上构建的基础设施。 库是基底。检索管道、MCP 服务器和集成钩子是基础设施。
此处描述的架构是Markdown 优先,而非 Obsidian 专属。 如果您使用 Logseq、Foam、Dendron 或纯 Markdown 文件目录,检索管道的工作方式完全相同。分块器读取 .md 文件。嵌入器处理文本字符串。索引器写入 SQLite。这些组件都不依赖 Obsidian 特有功能。Obsidian 的贡献在于提供了写作和组织环境,产出检索器所索引的 Markdown 文件。
快速入门:首个AI连接的知识库
本节将在五分钟内将知识库连接到AI工具。您将安装Obsidian、创建知识库、安装MCP服务器,并运行首次查询。快速入门使用社区MCP服务器以获得即时结果。后续章节将介绍如何构建用于生产环境的自定义检索管道。
前置条件
- macOS、Linux或Windows
- Node.js 18+(用于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年间有了显著发展:
| 服务器 | 作者 | 传输方式 | 需要插件 | 核心功能 |
|---|---|---|---|---|
| obsidian-mcp-server | StevenStavrakis | STDIO | 否 | 轻量级,基于文件 |
| mcp-obsidian | MarkusPfundstein | STDIO | Local REST API | 通过REST实现完整的知识库CRUD |
| obsidian-mcp-tools | jacksteamdev | STDIO | 是(插件) | 语义搜索 + Templater |
| obsidian-claude-code-mcp | iansinnott | WebSocket | 是(插件) | Claude Code自动发现 |
| obsidian-mcp-server | cyanheads | STDIO | Local REST API | 标签、frontmatter管理 |
对于快速入门,最简单的选择是直接读取.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服务器,该服务器搜索您的知识库并返回匹配的内容。您应该能看到包含文件路径和相关摘录的结果。
您刚刚构建了什么
您通过一个标准协议将本地知识库连接到了AI工具。MCP服务器读取您的知识库文件,执行基础搜索,并返回结果。这是最小可行版本。
此快速入门未提供的功能: - 混合检索(BM25 + 向量搜索 + RRF融合) - 基于嵌入(embeddings)的语义搜索 - 凭据过滤 - 增量索引 - 基于Hook的自动上下文注入
本指南的其余部分将逐一介绍如何构建这些功能。快速入门验证了概念可行性,而完整管道则提供生产级别的检索质量。
决策框架: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 | Notion | Apple Notes | 纯文件系统 | CLAUDE.md |
|---|---|---|---|---|---|
| 本地优先 | 是 | 否(云端) | 部分(iCloud) | 是 | 是 |
| 纯文本 | 是(markdown) | 否(块结构) | 否(专有格式) | 是 | 是 |
| 图谱结构 | 是(wiki-links) | 部分(提及) | 否 | 否 | 否 |
| AI可索引 | 直接文件访问 | 需要API | 需要导出 | 直接文件访问 | 已在上下文中 |
| 插件生态 | 1,800+插件 | 集成方案 | 无 | 不适用 | 不适用 |
| 离线可用 | 完全支持 | 仅缓存只读 | 部分支持 | 完全支持 | 完全支持 |
| 支持10K+笔记 | 是 | 是(需API) | 性能下降 | 是 | 否(单文件) |
| 费用 | 免费(核心版) | $10/月起 | 免费 | 免费 | 免费 |
何时Obsidian过于复杂
- 单项目上下文。 如果AI只需要当前代码库的上下文,将其放入
CLAUDE.md、AGENTS.md或项目级文档中即可。这些文件随代码库一起分发,并会自动加载。 - 结构化数据。 如果内容是表格、记录或模式定义,请使用数据库。Obsidian笔记以散文为主。Dataview可以查询frontmatter字段,但真正的数据库在处理结构化查询方面更为出色。
- 临时性研究。 如果笔记在项目结束后将被丢弃,使用包含markdown文件的临时目录更为简单。不要为短期内容构建检索基础设施。
何时Obsidian是正确选择
- 跨月份或年份的知识积累。 价值随语料库增长而复合递增。一个包含200篇笔记、每天查询持续六个月的知识库,比一个包含5,000篇笔记但只查询过一次的知识库提供更多价值。
- 单一语料库中的多领域内容。 一个包含编程、架构、安全、设计和个人项目笔记的知识库,受益于跨领域检索能力,而项目级
CLAUDE.md无法提供这种能力。 - 隐私敏感内容。 本地优先意味着检索管道永远不会将内容发送到外部服务。知识库中包含您存入的任何内容,包括您不愿上传到云服务的内容。
心智模型:三层架构
该系统由三个独立运行但协同增效的层组成。每一层关注不同的问题,也有不同的故障模式。
┌─────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────┘
摄入层(Intake)决定了什么内容进入知识库。如果缺乏筛选,知识库会积累噪音:推文截图、未加注释的复制粘贴文章、缺乏上下文的半成品想法。摄入层负责在入口处进行质量控制。评分流水线、标签规范或人工审核流程——任何能够确保知识库只包含值得检索的内容的机制。
检索层(Retrieval)使知识库变得可查询。这是核心引擎:将笔记分块为搜索单元,将分块嵌入向量空间,建立关键词和语义搜索索引,通过 RRF 融合结果。检索层将一个文件目录转化为可查询的知识库。没有这一层,知识库只能通过手动浏览和基础搜索来导航,无法被 AI 工具以编程方式访问。
集成层(Integration)将检索层连接到 AI 工具。MCP 服务器将检索功能暴露为可调用工具。钩子(hooks)自动注入上下文。技能(skills)将新知识回写到知识库中。集成层是知识库与使用它的 AI 代理之间的接口。
这些层在设计上是解耦的。摄入评分流水线不了解嵌入(embeddings)。检索器不了解信号路由规则。MCP 服务器不了解笔记是如何创建的。这种解耦意味着您可以独立改进任何一层。替换嵌入模型无需更改摄入流水线。添加新的 MCP 功能无需修改检索器。更改信号评分策略无需触碰索引。
面向 AI 消费的知识库架构
为 AI 检索优化的知识库与为个人浏览优化的知识库遵循不同的规范。本节涵盖文件夹结构、笔记模式、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 文件
在知识库根目录创建 .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/
索引器在扫描前读取此文件,并完全跳过匹配的路径。被排除路径中的文件永远不会被分块、不会被嵌入,也不会出现在搜索结果中。
笔记模式
每条笔记都应包含 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——在 FTS5 标题上下文中以 0.3 权重索引,即使正文使用不同术语也能提供关键词匹配
可选但有价值的字段:
domain——支持按领域限定查询(”仅搜索安全相关笔记”)source——为采集内容提供出处;检索器可以在结果中包含来源 URLstatus——允许将已归档或草稿笔记从活跃搜索中排除
分块规范
检索器在 H2(##)标题边界处进行分块。这意味着您的笔记结构直接影响检索粒度:
有利于检索的写法:
## 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...
三个 H2 部分产生三个可独立搜索的分块。每个分块包含足够的上下文,使嵌入能够捕捉其语义。关于”过期令牌处理”的查询会精确匹配第三个分块。
不利于检索的写法:
# 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 标题的长段落只会产生一个大分块。嵌入会在该段落的所有主题上取平均值。对任何子主题的查询都会以相同的相关度匹配整条笔记。
经验法则:如果一个段落涵盖了不止一个概念,就将其拆分为 H2 子节。分块器会处理剩下的工作。
不应放入笔记的内容
会降低检索质量的内容:
- 未加注释的整篇文章复制粘贴。检索器会索引原始文章的关键词,用您未撰写的内容稀释您的知识库。请添加摘要、提取要点,或直接链接到来源 URL。
- 没有文字描述的截图。检索器索引的是 Markdown 文本。没有替代文本或周围描述的图片对 BM25 和向量搜索都是不可见的。
- 凭证字符串。API 密钥、令牌、密码、连接字符串。即使有凭证过滤机制,最安全的做法是永远不要将密钥粘贴到笔记中。请通过名称引用它们(例如”
~/.env中的 Cloudflare API 令牌”)。 - 未经整理的自动生成内容。如果某个工具生成了笔记(会议记录、Readwise 高亮、RSS 导入),请在其进入永久知识库之前进行审核和注释。未经整理的自动导入只增加数量,不增加可检索的价值。
AI工作流的插件生态系统
能够提升知识库质量以优化AI检索效果的Obsidian插件主要分为三类:结构类(确保一致性)、查询类(暴露元数据)和同步类(保持知识库内容最新)。
必备插件
Dataview。 利用frontmatter字段像数据库一样查询您的知识库。创建动态索引:”所有标记为security且在过去30天内更新的笔记”或”所有状态为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用于子章节)能确保分块器产生可预测的结果。对检索有影响的Linter规则:
- 标题递增:强制使用连续的标题层级(不允许从H1直接跳到H3)
- YAML标题:与文件名保持一致
- 尾随空格:移除(避免FTS5分词产生异常)
- 连续空行:限制为1行(产生更整洁的分块)
Git集成。 为您的知识库提供版本控制。追踪历史变更、在多台设备间同步,以及从误删中恢复。Git还提供mtime数据,索引器利用该数据进行增量变更检测。
有助于索引的插件
Smart Connections。 这是一个在Obsidian内部提供AI驱动语义搜索的插件。Smart Connections v4默认在本地创建embeddings——一旦您的知识库完成索引,语义关联和查找功能完全可以离线运行,无需任何API调用。21 虽然本指南中的检索系统是独立于Obsidian运行的(作为Python管道运行),但Smart Connections在写作过程中探索语义关系时非常有用。两个系统索引相同的内容,但服务于不同的使用场景:Smart Connections用于编辑器内的发现,外部检索器则通过MCP实现AI工具集成。
Metadata Menu。 提供结构化的frontmatter编辑功能,支持字段值的自动补全。减少type、domain和tags字段中的拼写错误。一致的元数据能提升检索过滤的准确性。
不利于索引的插件
Excalidraw。 将绘图存储为嵌入在markdown文件中的JSON。该JSON在语法上是合法的markdown,但在分块和生成embeddings时会产生无意义的内容。请通过.indexignore排除Excalidraw文件,或按文件扩展名进行过滤。
Kanban。 将看板状态存储为特殊格式的markdown。该格式是为看板渲染而设计的,并非用于文本检索。分块器会产生卡片标题和元数据的碎片,这些碎片无法生成有效的embeddings。请从索引中排除看板文件。
Calendar。 创建内容极少的每日笔记(通常只有一个日期标题)。空白或近乎空白的笔记会产生低质量的分块。如果您使用每日笔记,请在其中撰写实质性内容,或将每日笔记文件夹从索引中排除。
重要的插件配置
文件恢复→启用。 防止笔记被意外删除。虽然与检索无直接关系,但对于您所依赖的知识库来说至关重要。
严格换行→禁用。 标准markdown换行方式(双换行表示段落)比Obsidian的严格模式(单换行表示<br>)能产生更整洁的分块。
新文件默认位置→指定文件夹。 将新文件路由到00-inbox/,避免未分类的笔记污染领域文件夹。收件箱是一个暂存区;文件经过整理后移动到对应的领域文件夹。
Wiki-link格式→尽可能使用最短路径。 较短的链接目标便于检索器在索引链接结构时进行解析。
Embedding 模型:选择与配置
Embedding 模型将文本块转换为数值向量,用于语义搜索。模型的选择决定了检索质量、索引大小、embedding 速度和运行时依赖。本节解释为何 Model2Vec 的 potion-base-8M 是默认选择,以及何时应选择其他替代方案。
为何选择 Model2Vec potion-base-8M
模型: minishlab/potion-base-8M
参数量: 760万
维度: 256
大小: 约30 MB
依赖: model2vec(仅需 numpy,无需 PyTorch)
推理: 仅CPU,静态词 embeddings(无注意力层)
Model2Vec 将句子转换器的知识蒸馏为静态 token embeddings。与 BERT、MiniLM 及其他 transformer 模型对输入运行注意力层不同,Model2Vec 通过对预计算的 token embeddings 进行加权平均来生成向量。3 其实际效果是:embedding 速度比基于 transformer 的模型快50至500倍,因为不存在序列计算。
在 MTEB 基准测试套件中,potion-base-8M 达到了 all-MiniLM-L6-v2 性能的89%(平均分50.03 vs 56.09)。4 11%的质量差距是速度和简洁性优势所付出的代价。对于较短的 markdown 块(典型知识库中平均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]
延迟加载。 模型在首次使用时加载,而非在导入时加载。当检索器以仅 BM25 回退模式运行时(例如未安装 embedding 虚拟环境),导入 embedder 模块不会产生任何开销。
隔离虚拟环境。 模型在专用虚拟环境中运行(例如 ~/.claude/venvs/memory/),以避免与工具链其他部分产生依赖冲突。_activate_venv() 函数在运行时将虚拟环境的 site-packages 添加到 sys.path 中。
# Create isolated venv
python3 -m venv ~/.claude/venvs/memory
~/.claude/venvs/memory/bin/pip install model2vec
批量处理。 Embedder 以64个为一批处理文本,以分摊 Model2Vec 的开销。索引器将块送入 embed_batch() 而非逐个进行 embedding。
何时选择替代方案
| 模型 | 维度 | 大小 | 速度 | 质量(MTEB) | 适用场景 |
|---|---|---|---|---|---|
| potion-base-8M | 256 | 30 MB | 500x | 50.03 | 默认:本地、快速、无需 GPU |
| potion-base-32M | 256 | 120 MB | 400x | 52.46 | 更高质量,仍为静态模型 |
| potion-retrieval-32M | 256 | 120 MB | 400x | 36.35(检索) | 针对检索优化的静态模型 |
| all-MiniLM-L6-v2 | 384 | 80 MB | 1x | 56.09 | 更高质量,仍为本地运行 |
| nomic-embed-text-v1.5 | 768 | 270 MB | 0.5x | 62.28 | 最佳本地质量 |
| text-embedding-3-small | 1536 | API | N/A | 62.30 | 基于 API,最高质量 |
选择 potion-base-32M,当您希望获得比 potion-base-8M 更好的质量,同时不脱离静态 embedding 模型家族时。该模型于2025年1月发布,使用从 baai/bge-base-en-v1.5 蒸馏的更大词汇表,MTEB 平均分达到52.46(比 potion-base-8M 提升5%),同时保持相同的256维输出和仅依赖 numpy 的特性。18 4倍大的模型文件会增加内存使用,但 embedding 速度仍比 transformer 模型快数个数量级。
选择 potion-retrieval-32M,当您的主要用途是检索时(知识库搜索正是如此)。此变体基于 potion-base-32M 专门针对检索任务进行微调,在 MTEB 检索基准测试中得分36.35,而基础模型为33.52。18 总体 MTEB 平均分降至49.73,因为微调以牺牲通用性能换取了检索专项性能的提升。
选择 all-MiniLM-L6-v2,当检索质量比速度更重要且已安装 PyTorch 时。384维向量与256维向量相比,SQLite 数据库大小增加约50%。在 M 系列硬件上,对15,000个文件进行完整重索引时,embedding 速度从不到1分钟下降到约10分钟。
选择 nomic-embed-text-v1.5,当您需要最佳的本地检索质量并能接受较慢的索引速度时。768维向量使数据库大小大约增加到三倍。需要 PyTorch 和现代CPU或 GPU。
选择 text-embedding-3-small,当网络延迟和隐私是可接受的代价时。API 能生成最高质量的 embeddings,但引入了云端依赖、按 token 计费(每百万 token 0.02美元),且会将您的内容发送到 OpenAI 的服务器。
在所有其他情况下,请继续使用 potion-base-8M。 速度优势对迭代索引至关重要(开发过程中的重索引),仅依赖 numpy 的特性避免了 PyTorch 安装的复杂性,256维向量使数据库保持紧凑。
量化与降维
Model2Vec v0.5.0+ 支持以降低精度和维度的方式加载模型。18 这对于在受限硬件上部署或在不切换模型的情况下减小数据库大小非常有用:
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可将向量存储减半,对短文本检索的质量损失极小。
截至2025年5月,Model2Vec 还支持 BPE 和 Unigram 分词器(在 WordPiece 之外),这扩展了可被蒸馏为静态模型的句子转换器的范围。20
针对知识库的自定义 Embedding 微调
Model2Vec v0.4.0+ 支持在静态 embeddings 之上训练自定义分类模型,v0.7.0 新增了词汇量化和可配置的蒸馏池化。20 这对于包含专业词汇的知识库(医学笔记、法律参考、特定领域术语)尤为相关,因为默认的 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 能够产生足够的检索质量。仅当检索持续遗漏通用模型无法捕捉的特定领域关联时,微调才有价值。
模型哈希追踪
索引器存储由模型名称和词汇表大小派生的哈希值。如果您更改了 embedding 模型,索引器会在下一次增量运行时检测到不匹配,并自动触发完整重索引。
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 下载模型。如果下载失败(网络问题、企业防火墙),检索器将回退到仅 BM25 模式。模型在首次下载后会缓存到本地。
维度不匹配。 如果您在未清除数据库的情况下切换模型,已存储的向量维度将与新 embeddings 不同。索引器通过模型哈希检测此情况并触发完整重索引。如果哈希检查失败(未设置正确哈希的自定义模型),sqlite-vec 将在维度不匹配的 KNN 查询中报错。
大型知识库的内存压力。 在单个批次中对50,000+个块进行 embedding 可能消耗大量内存。索引器以64个为一批进行处理,以限制峰值内存使用。如果内存仍然是问题,请减小批量大小。
使用FTS5进行全文搜索
SQLite的FTS5扩展提供了基于BM25排名的全文搜索功能。FTS5是混合检索(hybrid retrieval)管道中的关键词搜索组件。本节涵盖FTS5的配置、BM25的优势场景及其特定的失败模式。
FTS5虚拟表
CREATE VIRTUAL TABLE chunks_fts USING fts5(
chunk_text,
section,
heading_context,
content=chunks,
content_rowid=id
);
内容同步模式。content=chunks参数指示FTS5直接引用chunks表,而非存储文本的副本。这将存储需求减半,但意味着在插入、更新或删除chunks时必须手动同步FTS5。
列配置。三个列被索引:
- 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%
这些权重可调。如果您的知识库拥有描述性强且能准确预测内容质量的标题,可以增加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” → 知识库中包含关于”login error recovery”和”session expiration handling”的笔记。BM25无法匹配,因为关键词不同。
- 查询:”what is the best way to manage state” → 知识库中包含关于”Redux store patterns”和”context providers”的笔记。BM25无法命中,因为”状态管理”通过具体的技术名称来表达。
BM25在大规模场景下还会遇到关键词碰撞问题。在一个包含15,000个文件的知识库中,搜索”configuration”会匹配数百个笔记,因为几乎每个项目笔记都提到了configuration。结果在技术上是正确的,但实际上毫无用处——排名无法确定哪个”configuration”笔记与当前查询相关。
FTS5分词器
FTS5默认使用unicode61分词器,可处理ASCII和Unicode文本。对于包含大量CJK(中文、日文、韩文)内容的知识库,建议使用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倍)。
维护
当底层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进行向量搜索
sqlite-vec扩展将向量KNN(K-Nearest Neighbors,K近邻)搜索引入SQLite。本节涵盖sqlite-vec的配置、从笔记到可搜索向量的嵌入(embedding)管道,以及具体的查询模式。
sqlite-vec虚拟表
CREATE VIRTUAL TABLE chunk_vecs USING vec0(
id INTEGER PRIMARY KEY,
embedding float[256]
);
vec0模块将256维浮点向量存储为打包的二进制数据。id列与chunks表一一对应,支持向量结果与chunk元数据之间的关联查询。
嵌入管道
管道从笔记流向可搜索向量:
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查询
向量搜索查询首先对输入查询进行嵌入,然后按余弦距离(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列包含余弦距离(0 = 完全相同,2 = 完全相反)。
向量搜索的优势场景
向量搜索在概念比具体用词更重要的查询中表现出色:
- 查询:”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”的笔记(相同概念通过实现细节表达)
向量搜索的失败场景
向量搜索在处理精确标识符时表现不佳:
- 查询:
_rrf_fuse→ 返回关于”fusion algorithms”和”rank merging”的笔记,但可能将实际的函数定义排在概念性讨论之后 - 查询:
PostToolUse→ 返回关于”tool lifecycle hooks”和”post-execution handlers”的笔记,而非特定的hook名称
向量搜索在处理结构化数据时也表现不佳。JSON配置文件、YAML块和代码片段生成的嵌入捕获的是结构模式而非语义含义。一个包含"review": true的JSON文件与一篇关于代码审查的散文讨论的嵌入结果截然不同。
优雅降级
如果sqlite-vec加载失败(缺少扩展、平台不兼容、库文件损坏),检索器将回退到仅使用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
检索器在尝试向量查询前检查vec_available。禁用时,所有搜索仅使用BM25,RRF融合步骤将被跳过。
Reciprocal Rank Fusion(RRF)
RRF将两个排名列表合并,无需进行分数校准。本节涵盖算法原理、一个完整的查询追踪示例、k参数的调优,以及为何选择RRF而非其他替代方案。如需使用可编辑排名的交互式计算器、场景预设和可视化架构探索器,请参阅hybrid retriever深度解析。
算法原理
RRF仅根据文档在每个列表中的排名位置来分配分数:
score(d) = Σ (weight_i / (k + rank_i))
其中:
- k是平滑常数(60,遵循Cormack等人的研究1)
- rank_i是文档在结果列表i中从1开始的排名
- weight_i是可选的每个列表的权重乘数(默认1.0)
在多个列表中排名靠前的文档将获得更高的融合分数。仅出现在一个列表中的文档只从该单一来源获得分数。
为何选择RRF而非其他替代方案
加权线性组合需要将BM25分数与cosine similarity距离进行校准。BM25分数是无界的,且随语料库规模而变化。Cosine距离的范围是[0, 2]。将两者组合需要归一化处理,而归一化参数依赖于具体数据集。RRF仅使用排名位置,无论评分方法如何,排名始终是从1开始的整数。
学习型融合模型需要标注的训练数据——查询-文档相关性对。对于个人知识库而言,这样的训练数据并不存在。您需要手动判断数百个查询-文档对才能训练出有用的模型。RRF无需任何训练数据即可工作。
Condorcet投票方法(Borda计数、Schulze方法)在理论上很优雅,但实现和调优更为复杂。RRF原始论文证明,RRF在TREC评估数据上优于Condorcet方法。1
融合实践
查询:”how does the review aggregator handle disagreements”
BM25将review-aggregator.py排在第3位(”review”、”aggregator”、”disagreements”精确关键词匹配),但将两个配置文件排在更前面(它们更突出地匹配了”review”)。向量搜索将同一块排在第1位(语义匹配冲突解决)。经过RRF融合后:
| 块 | BM25 | Vec | 融合分数 |
|---|---|---|---|
| review-aggregator.py “Disagreement Resolution” | #3 | #1 | 0.0323 |
| code-review-patterns.md “Multi-Reviewer” | #4 | #2 | 0.0317 |
| deliberation-config.json “Review Weights” | #1 | — | 0.0164 |
在两个列表中都排名靠前的块会浮到顶部。仅出现在一个列表中的块获得单一来源分数,排名低于双列表命中的结果。实际的分歧解决逻辑胜出,因为两种方法都找到了它——BM25通过关键词,向量搜索通过语义。
如需查看包含逐排名RRF数学计算的完整追踪步骤,请尝试不同的k值,使用交互式RRF计算器。
实现
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数据集上表现稳健。仅在您根据自己的查询分布测量到失败案例后再进行调优。
平局处理
当两个块具有相同的RRF分数时(罕见,但在一个列表中排名相同且未出现在另一个列表中时可能发生),按以下规则打破平局:
- 优先选择同时出现在两个列表中的块,而非仅出现在一个列表中的块
- 对于同时出现在两个列表中的块,优先选择组合排名较低的块
- 对于仅出现在一个列表中的块,优先选择在该列表中排名较低的块
完整的检索管道
本节追踪一个查询从输入到输出的完整管道过程: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
总延迟:约23毫秒,基于Apple M3 Pro硬件上包含49,746个分块的数据库。
搜索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排名已经按相关性对结果进行了排序。
数据库模式(完整版)
-- 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个分块、83 MB SQLite数据库的知识库上测量,硬件为Apple M3 Pro:
| 指标 | 值 |
|---|---|
| 文件总数 | 16,894 |
| 分块总数 | 49,746 |
| 数据库大小 | 83 MB |
| BM25查询延迟(p50) | 12ms |
| 向量查询延迟(p50) | 8ms |
| RRF融合延迟 | 3ms |
| 端到端搜索延迟(p50) | 23ms |
| 完整重建索引时间 | 约4分钟 |
| 增量重建索引时间 | <10秒 |
| Embedding模型 | potion-base-8M(256维) |
| BM25候选池 | 30 |
| 向量候选池 | 30 |
| 默认结果限制 | 10 |
| 默认token预算 | 4,000 tokens |
内容哈希与变更检测
索引器需要知道自上次索引运行以来哪些文件发生了变更。本节介绍变更检测机制和哈希策略。
文件修改时间比较
索引器在chunks表中为每个分块存储mtime_ns(以纳秒为单位的文件修改时间)。在增量运行时,索引器执行以下步骤:
- 扫描知识库中允许文件夹内的所有
.md文件 - 从文件系统读取每个文件的
mtime_ns - 与数据库中存储的
mtime_ns进行比较 - 识别三类文件:
- 新文件:路径存在于文件系统中但不在数据库中
- 已变更文件:路径在两者中都存在但
mtime_ns不同 - 已删除文件:路径存在于数据库中但不在文件系统中
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仅需不到100毫秒。
权衡如下:mtime比较偶尔会触发对未变更文件的不必要重新索引(假阳性),但绝不会遗漏实际变更。假阳性的代价仅是每次运行多几次embedding调用。速度差异(100毫秒对比3秒)使得mtime成为在每次AI交互时运行的系统的务实选择。
处理删除操作
当文件从知识库中删除时,索引器会移除数据库中该文件的所有分块:
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],
)
FTS5内容同步表需要通过INSERT INTO chunks_fts(chunks_fts, rowid, ...) VALUES('delete', ?, ...)对每个被删除的行进行显式删除操作。索引器在文件移除过程中自动处理此步骤。
增量索引与完整重建索引
索引器支持两种模式:增量索引(快速,日常使用)和完整重建索引(较慢,偶尔使用)。本节介绍每种模式的适用场景、幂等性保证以及损坏恢复。
增量索引
适用场景: 编辑笔记后的日常索引。这是默认模式。
工作流程: 1. 扫描仓库中的文件变更(mtime 比较) 2. 删除已删除文件的分块 3. 对变更文件重新分块和重新生成 embeddings 4. 为新文件插入新的分块 5. 同步 FTS5 索引
典型耗时: 在16,000个文件的仓库上,一天的编辑量通常不到10秒。
python index_vault.py --incremental
完整重建索引
适用场景: - 更换 embedding 模型后(检测到模型哈希不匹配) - 架构迁移后(新增列、变更索引) - 数据库损坏后(完整性检查失败) - 增量索引产生异常结果时
工作流程: 1. 删除所有现有数据(分块、向量、FTS5 条目) 2. 扫描整个仓库 3. 对所有文件进行分块 4. 对所有分块生成 embeddings 5. 从头构建 FTS5 索引
典型耗时: 在 Apple M3 Pro 上处理16,894个文件约需4分钟。
python index_vault.py --full
幂等性
两种模式都具有幂等性:对同一命令运行两次会产生相同的结果。索引器在插入新分块之前会先删除该文件的现有分块,因此对已经是最新状态的数据库重新运行增量索引不会产生任何变更。重新运行完整重建索引则会生成一个完全相同的数据库。
损坏恢复
如果 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 模式运行时:
- 模型哈希检查。 将存储的模型哈希与当前模型进行比较。如果不同,自动切换到完整重建索引模式并向用户发出警告。
- 文件扫描。 遍历允许的文件夹,收集文件路径和 mtime。
- 变更检测。 与已存储的数据进行比较。
- 批量处理。 以64个为一批对变更文件重新分块和重新生成 embeddings。
- 进度报告。 输出已处理文件数量和耗时。
- 优雅关闭。 处理 SIGINT 信号时,先完成当前文件再停止。
凭证过滤与数据边界
个人笔记中包含敏感信息:API 密钥、Bearer 令牌、数据库连接字符串、调试时粘贴的私钥。凭证过滤器可防止这些内容进入检索索引。
问题所在
一篇关于调试 OAuth 集成的笔记可能包含以下内容:
The token was: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
I used this curl command:
curl -H "Authorization: Bearer sk-ant-api03-abc123..."
如果不进行过滤,JWT 和 API 密钥都会被分块、生成 embeddings 并存储在数据库中。搜索”authentication”会返回包含真实密钥的分块。更糟糕的是,如果检索器通过 MCP 将结果传递给 AI 工具,这些密钥就会出现在 AI 的上下文窗口中,甚至可能出现在工具的日志中。
基于模式的过滤
凭证过滤器在每个分块存储前运行,匹配25种供应商特定模式以及通用模式:
供应商特定模式:
| 模式 | 示例 | 正则表达式 |
|---|---|---|
| OpenAI API 密钥 | sk-... |
sk-[a-zA-Z0-9_-]{20,} |
| Anthropic API 密钥 | sk-ant-api03-... |
sk-ant-api\d{2}-[a-zA-Z0-9_-]{20,} |
| GitHub PAT | ghp_... |
gh[ps]_[a-zA-Z0-9]{36,} |
| AWS Access Key | AKIA... |
AKIA[0-9A-Z]{16} |
| Stripe 密钥 | sk_live_... |
[sr]k_(live\|test)_[a-zA-Z0-9]{24,} |
| Cloudflare 令牌 | ... |
多种模式 |
通用模式:
| 模式 | 检测方式 |
|---|---|
| JWT 令牌 | eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+ |
| Bearer 令牌 | Bearer\s+[a-zA-Z0-9_\-\.]+ |
| 私钥 | -----BEGIN (RSA\|EC\|OPENSSH) PRIVATE KEY----- |
| 高熵 base64 | 每字符熵值大于4.5比特、40个字符以上的字符串 |
| 密码赋值 | password\s*[:=]\s*["'][^"']+["'] |
过滤器实现
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
关键设计决策:
-
在生成 embeddings 之前过滤。 清理后的文本才会被用于生成 embeddings。向量表示永远不会编码凭证模式。搜索”API key”会返回讨论 API 密钥管理的笔记,而非包含实际密钥的笔记。
-
替换而非删除。
[REDACTED:pattern-name]标记保留了周围文本的语义上下文。embedding 能够捕捉到”此处曾存在类似凭证的内容”,但不会编码凭证本身。 -
记录模式而非值。 过滤器会记录匹配到的模式(例如,”Scrubbed 2 credential(s) from oauth-debug.md [jwt, bearer-token]”),但绝不会记录凭证的实际值。
基于路径的排除
.indexignore 文件提供基于路径的粗粒度排除。凭证过滤器则对已索引文件中的内容进行细粒度清洗。两者缺一不可:
.indexignore用于排除您明确知道包含敏感内容的整个文件夹(健康笔记、财务记录、职业文档)- 凭证过滤器用于清洗意外嵌入在可索引内容中的密钥
数据分类
对于包含多类内容的仓库,建议按敏感程度对笔记进行分类:
| 级别 | 示例 | 是否索引? | 是否过滤? |
|---|---|---|---|
| 公开 | 博客草稿、技术笔记 | 是 | 是 |
| 内部 | 项目计划、架构决策 | 是 | 是 |
| 敏感 | 薪资数据、健康记录 | 否(.indexignore) | 不适用 |
| 受限 | 凭证、私钥 | 否(.indexignore) | 不适用 |
MCP 服务器架构
Model Context Protocol(MCP)服务器将检索器作为工具暴露给 AI 代理调用。本节涵盖服务器设计、功能接口和权限边界。
协议选择: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 服务运行。适用于远程访问、多客户端配置,或仓库位于共享服务器的团队配置场景。
{
"mcpServers": {
"obsidian": {
"url": "http://localhost:3333/mcp"
}
}
}
建议:个人仓库请使用 STDIO。它更简单、更安全(无网络暴露),且服务器生命周期由 AI 工具管理。仅当多个工具或多台机器需要并发访问同一仓库时才使用 HTTP。
MCP 规范演进。2025年6月的 MCP 规范新增了 OAuth 2.1 授权、结构化工具输出(类型化返回模式)和引导式交互(服务器发起的用户提示)。2025年11月的版本发布了 Streamable HTTP 作为一等传输模式、
.well-knownURL 发现机制用于自动浏览服务器能力、声明工具是只读还是可变更的结构化工具注解,以及 SDK 层级标准化系统。1619 下一版规范(暂定2026年中)提议支持长时间运行任务的异步操作、面向医疗和金融等行业的领域特定协议扩展,以及多代理工作流的代理间通信标准。19 对于个人仓库服务器,STDIO 仍是最简单的选择。Streamable HTTP 传输和.well-known发现机制主要有利于需要多租户路由和负载均衡的企业级 HTTP 部署。请关注 MCP 路线图 以获取影响您传输选择的更新。
功能设计
MCP 服务器应暴露最小化的工具集:
search — 主要工具。执行混合检索并返回排序结果。
{
"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 — 通过路径读取特定笔记的完整内容。当代理需要查看搜索结果的完整上下文时使用。
{
"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 — 列出匹配过滤条件的笔记(按文件夹、标签、类型或日期范围)。当代理没有特定查询需要进行探索时使用。
{
"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 服务器应强制执行严格的边界:
-
只读。服务器读取仓库和索引数据库,不创建、修改或删除笔记。写入操作(捕获新笔记)由单独的钩子或技能处理,而非 MCP 服务器。
-
仓库范围限定。服务器仅读取配置的仓库路径内的文件。必须拒绝路径遍历尝试(
../../etc/passwd)。 -
凭证过滤输出。即使数据库包含预过滤的内容,也应在输出时应用凭证过滤作为纵深防御措施。
-
令牌限制响应。对所有工具响应强制执行
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 配置、钩子集成和 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 等)。
钩子集成
钩子在定义的生命周期节点扩展 Claude Code 的行为。两个钩子与 Obsidian 集成相关:
PreToolUse 钩子 — 在代理处理工具调用之前查询仓库,自动注入相关上下文。
#!/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 钩子 — 将重要的工具输出捕获回仓库,供未来检索使用。
#!/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,供钩子和技能调用:
# 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 技能
一个用于将洞察捕获回仓库的 Claude Code 技能:
/capture "OAuth token rotation requires both access and refresh token invalidation"
--domain security
--tags oauth,tokens
该技能在 00-inbox/ 中创建带有正确 frontmatter 的新笔记,并触发增量重新索引,使新笔记立即可搜索。
上下文窗口管理
集成时应注意 Claude Code 的上下文窗口:
- 将每次查询注入的上下文限制在1,500-2,000个令牌。超过此数量会与代理的工作记忆竞争。
- 包含来源归属。始终包含文件路径和章节标题,以便代理可以引用来源。
- 截断块文本。长块应使用
...截断而非完全省略。前300-500个字符通常包含关键信息。 - 不要在每次工具调用时都注入。PreToolUse 钩子应根据所调用的工具选择性注入上下文。读取操作不需要仓库上下文,写入和编辑操作则受益于此。
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的差异
| 功能 | Claude Code | Codex CLI |
|---|---|---|
| MCP配置 | settings.json |
config.toml |
| 钩子 | ~/.claude/hooks/ |
不支持 |
| 技能 | ~/.claude/skills/ |
不支持 |
| 指令文件 | CLAUDE.md |
AGENTS.md |
| 审批模式 | --dangerously-skip-permissions |
suggest / auto-edit / full-auto |
关键差异:Codex CLI不支持钩子。自动上下文注入模式(PreToolUse钩子)不可用。作为替代,请在AGENTS.md中包含明确的指令,告知代理在开始工作前搜索知识库。
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支持 | 传输方式 | 配置位置 |
|---|---|---|---|
| Claude Code | 完整 | STDIO | ~/.claude/settings.json |
| Codex CLI | 完整 | STDIO | .codex/config.toml |
| Cursor | 完整 | STDIO | .cursor/mcp.json |
| Windsurf | 完整 | STDIO | .windsurf/mcp.json |
| Continue.dev | 部分 | HTTP | ~/.continue/config.json |
| Zed | 开发中 | STDIO | 设置界面 |
非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集成优雅,但具有通用性。
从结构化笔记实现提示缓存
知识库中的结构化笔记可以作为可复用的上下文块,减少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
},
}
缓存失效
缓存失效基于两个信号:
- TTL过期。每个上下文块都有生存时间。当TTL过期时,系统会重新查询知识库来重建该块。
- 知识库变更检测。当索引器检测到参与构建缓存上下文块的文件发生变更时,该块会立即失效。
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)
缓存块在会话启动时加载。动态搜索结果按查询填充剩余预算。这种混合方式为代理提供了常用上下文的基线,同时为特定查询保留了预算空间。
缓存前后的Token使用对比
不使用缓存:每次相关查询都会触发知识库搜索,返回1,500-2,000个token的上下文。在一个会话中进行10次查询,代理会消耗15,000-20,000个token的知识库上下文。
使用缓存:三个预构建的上下文块总共消耗4,500个token。额外的搜索每次唯一查询增加1,500-2,000个token。在10次查询中,如果有6次被缓存块覆盖,代理消耗4,500 +(4 × 1,500)= 10,500个token——大约是未缓存使用量的一半。
PostToolUse钩子实现上下文压缩
工具输出可能非常冗长:堆栈跟踪、文件列表、测试结果。PostToolUse钩子可以在这些输出消耗上下文窗口空间之前对其进行压缩。
问题描述
运行测试的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个失败。
钩子实现
#!/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
防止递归触发
压缩钩子如果不加防护,其输出可能会触发自身:
# Guard against recursive invocation
if [ -n "$COMPRESS_HOOK_ACTIVE" ]; then
exit 0
fi
export COMPRESS_HOOK_ACTIVE=1
压缩策略
| 输出类型 | 检测方式 | 压缩策略 |
|---|---|---|
| 测试结果 | PASSED / FAILED关键词 |
统计通过/失败数量,仅显示失败项 |
| 文件列表 | 命令中包含ls或find |
截断为前20条 + 总数 |
| 堆栈跟踪 | Traceback关键词 |
保留首尾帧 + 错误信息 |
| Git状态 | modified: / new file: |
按状态汇总数量 |
| 构建输出 | warning: / error: |
过滤信息行,保留警告/错误 |
信号采集与分类管道
采集层决定了哪些内容进入知识库。如果缺乏筛选管理,知识库将积累大量噪音。本节介绍将信号路由到领域文件夹的评分管道。
来源
信号来自多个渠道:
- RSS 订阅: 技术博客、安全公告、版本发布说明
- 书签: 通过 Obsidian Web Clipper 或书签工具保存的浏览器书签
- 新闻通讯: 电子邮件通讯中的关键摘要
- 手动采集: 在阅读、交流或研究过程中撰写的笔记
- 工具输出: 通过钩子捕获的重要 AI 工具输出
评分维度
每个信号在四个维度上进行评分(每项 0.0 到 1.0):
| 维度 | 问题 | 低分(0.0-0.3) | 高分(0.7-1.0) |
|---|---|---|---|
| 相关性 | 是否与我的活跃领域相关? | 边缘性,超出范围 | 与当前工作直接相关 |
| 可操作性 | 我能使用这些信息吗? | 纯理论,无法应用 | 可以应用的具体技术或模式 |
| 深度 | 内容有多充实? | 标题党,浅层摘要 | 附带示例的深入分析 |
| 权威性 | 来源有多可信? | 匿名博客,未经验证 | 一手资料、同行评审、公认专家 |
综合评分与路由
composite = (relevance * 0.35) + (actionability * 0.25) +
(depth * 0.25) + (authority * 0.15)
| 分数范围 | 操作 |
|---|---|
| 0.55+ | 自动路由到领域文件夹 |
| 0.40 - 0.55 | 排队等待人工审核 |
| < 0.40 | 丢弃(不存储) |
领域路由
评分超过 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 个月的统计数据:
| 指标 | 值 |
|---|---|
| 已处理信号总数 | 7,771 |
| 自动路由(>0.55) | 4,832(62%) |
| 排队审核(0.40-0.55) | 1,543(20%) |
| 已丢弃(<0.40) | 1,396(18%) |
| 活跃领域文件夹 | 12 |
| 平均每日信号数 | ~18 |
知识图谱模式
Obsidian 的 wiki-link 图谱编码了笔记之间的关系。本节介绍链接语义、用于上下文扩展的图遍历,以及降低图谱质量的反模式。
Backlink 语义
每个 wiki-link 在图中创建一条有向边。Obsidian 同时追踪正向链接和 backlink:
- 正向链接: 笔记 A 包含
[[笔记 B]]→ A 链接到 B - Backlink: 笔记 B 显示笔记 A 引用了它
图谱根据不同的上下文编码不同类型的关系:
| 链接模式 | 语义 | 示例 |
|---|---|---|
| 内联链接 | “与……相关” | “See [[OAuth Token Rotation]] for details” |
| 标题链接 | “包含子主题” | ”## Related\n- [[Token Rotation]]\n- [[Session Management]]” |
| 标签式链接 | “被归类为” | ”[[type/reference]]” |
| MOC 链接 | “属于” | 一个 Maps of Content 笔记,列出相关笔记 |
Maps of Content(MOC)
MOC 是将相关笔记组织成可导航结构的索引笔记:
---
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]]
MOC 通过两种方式增强检索效果:
- 直接匹配。 搜索”authentication overview”时匹配到 MOC 本身,为代理提供一份精心策划的相关笔记列表。
- 上下文扩展。 找到特定笔记后,检索器可以检查该笔记是否出现在任何 MOC 中,并将 MOC 的结构包含在结果中,为代理提供更广泛主题的导航地图。
图遍历实现上下文扩展
检索器的一个未来增强方向:找到最佳结果后,通过跟踪链接扩展上下文:
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 的图谱面板将这些显示为断开的孤岛。孤立集群表明缺少 MOC 或缺少跨领域链接。
标签泛滥。 不一致地使用标签或创建过多细粒度标签。一个拥有 5,000 篇笔记和 500 个唯一标签的知识库,平均每 10 个标签只有 1 篇笔记——这些标签对过滤没有实际用处。应整合为 20-50 个高级标签,与您的领域文件夹相对应。
链接多、内容少的笔记。 完全由 wiki-link 组成、没有正文的笔记。这类笔记索引效果差,因为分块器没有可用于生成 embedding 的文本。至少添加一段文字来解释这些关联笔记之间的关系。
对所有内容都使用双向链接。 并非每个引用都需要成为 wiki-link。顺带提及”OAuth”时不需要使用 [[OAuth 2.0 Overview]]。请将 wiki-link 保留给有意图的、可导航的关系——即点击链接能够提供有用上下文的场景。
开发者工作流秘诀
将知识库检索与日常开发任务相结合的实用工作流。
每日上下文加载
通过加载相关上下文开始一天的工作:
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
捕获的洞察会立即被索引,可供未来检索使用。经过数月的积累,这些微捕获将构建出一个特定于实现的知识语料库。
项目启动
启动新项目或新功能时:
- 搜索知识库:”关于[技术/模式]我了解什么?”
- 查看前 5 条结果中的先前决策和踩坑记录
- 检查该领域是否存在 MOC;如不存在,则创建一个
- 搜索故障模式:”[技术]的常见问题”
借助知识库搜索进行调试
遇到错误或异常行为时:
Search my vault for [error message or symptom]
以往的调试笔记通常包含根本原因和修复方案。这对于跨项目的重复性问题尤其有价值——知识库会记住您遗忘的内容。
代码审查准备
审查 PR 之前:
Search my vault for patterns and conventions about [module being changed]
知识库返回与待审查代码相关的先前决策、架构约束和编码规范。审查过程基于积累的知识,而不仅仅是代码差异。
性能调优
本节介绍针对不同仓库规模和使用模式的优化策略。
索引大小管理
| 仓库规模 | 分块数 | 数据库大小 | 全量重建索引 | 增量更新 |
|---|---|---|---|---|
| 500 篇笔记 | ~1,500 | 3 MB | 15 秒 | <1 秒 |
| 2,000 篇笔记 | ~6,000 | 12 MB | 45 秒 | 2 秒 |
| 5,000 篇笔记 | ~15,000 | 30 MB | 2 分钟 | 4 秒 |
| 15,000 篇笔记 | ~50,000 | 83 MB | 4 分钟 | <10 秒 |
| 50,000 篇笔记 | ~150,000 | 250 MB | 15 分钟 | 30 秒 |
当笔记数量超过 50,000 时,建议: - 将批处理大小从 64 增加到 128 以加快 embedding 生成速度 - 使用 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 指令告诉 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:
| 操作 | 500 篇笔记 | 5K 篇笔记 | 15K 篇笔记 | 50K 篇笔记 |
|---|---|---|---|---|
| BM25 查询 | 2ms | 5ms | 12ms | 25ms |
| 向量查询 | 1ms | 3ms | 8ms | 20ms |
| RRF 融合 | <1ms | <1ms | 3ms | 5ms |
| 完整搜索 | 3ms | 8ms | 23ms | 50ms |
所有基准测试包含数据库访问、查询执行和结果格式化。MCP STDIO 通信的网络延迟额外增加 1-2ms。
故障排除
索引漂移
症状: 搜索返回过期结果,或遗漏近期添加的笔记。
原因: 添加笔记后增量索引器未运行,或文件的修改时间未更新(例如从另一台机器同步时保留了原始时间戳)。
解决方法: 运行全量重建索引:python index_vault.py --full
Embedding 模型切换
症状: 更换 embedding 模型后,向量搜索返回无意义的结果。
原因: 旧向量(来自之前的模型)正在与新的查询向量进行比较。两者的维度或向量空间语义不兼容。
解决方法: 索引器应检测到模型哈希不匹配并自动触发全量重建索引。如果未自动触发,请手动清除数据库并重新索引:
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 服务器和钩子应仅执行读取操作。如果需要并发写入,请使用 WAL 模式并设置繁忙超时:
db.execute("PRAGMA busy_timeout=5000") # Wait up to 5 seconds
sqlite-vec 无法加载
症状: 向量搜索被禁用;检索器回退到仅 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
同时确保索引器逐个处理文件(读取、分块、为每个文件生成 embedding 后再处理下一个),而非将所有文件一次性加载到内存中。
迁移指南
从 Apple Notes 迁移
- 通过”全部导出”选项(macOS)导出 Apple Notes,或使用
apple-notes-liberator等迁移工具 - 使用
markdownify或pandoc将 HTML 导出文件转换为 markdown - 将转换后的文件移动到仓库的
00-inbox/文件夹 - 检查每篇笔记并添加 frontmatter
- 将笔记移动到相应的领域文件夹
从 Notion 迁移
- 从 Notion 导出:Settings → Export → Markdown & CSV
- 将导出的压缩包解压到仓库的
00-inbox/文件夹 - 修复 Notion 特有的 markdown 问题:
- Notion 使用
- [ ]作为清单格式——这是标准 markdown 语法 - Notion 将属性表导出为 HTML——需转换为 YAML frontmatter
- Notion 使用相对路径嵌入图片——需将图片复制到您的附件文件夹
- 添加标准 frontmatter(
type、domain、tags) - 将 Notion 页面链接替换为 Obsidian wiki-link
从 Google Docs 迁移
- 使用 Google Takeout 导出所有文档
- 将
.docx文件转换为 markdown:pandoc -f docx -t markdown input.docx -o output.md - 批量转换:
for f in *.docx; do pandoc -f docx -t markdown "$f" -o "${f%.docx}.md"; done - 移入仓库,添加 frontmatter,按文件夹整理归类
从纯 Markdown(非 Obsidian)迁移
如果您已有一个 markdown 文件目录:
- 将该目录作为 Obsidian 仓库打开(Obsidian → Open Vault → Open folder)
- 如果目录使用版本控制,将
.obsidian/添加到.gitignore - 创建 frontmatter 模板并应用到现有文件
- 在阅读和整理过程中,使用
[[wiki-links]]开始关联笔记 - 立即运行索引器——检索系统从第一天起即可工作
从其他检索系统迁移
如果您正在从其他 embedding/搜索系统迁移:
- 不要尝试迁移向量数据。 不同模型产生的向量空间不兼容。请使用新模型运行全量重建索引。
- 迁移内容,而非索引。 仓库文件是唯一的数据源。索引是派生产物。
- 迁移后验证。 运行 10-20 个您已知答案的查询,验证结果是否符合预期。
更新日志
| 日期 | 变更内容 |
|---|---|
| 2026-03-03 | 更新 MCP 规范演进(2025年11月发布:Streamable HTTP、.well-known、工具注解)。新增 Model2Vec 微调及 BPE/Unigram 分词器支持。新增社区 MCP 服务器对比表。将 Smart Connections 更新至 v4。 |
| 2026-03-02 | 新增 potion-base-32M 和 potion-retrieval-32M 到模型对比中。新增量化/降维章节。新增 MCP 规范演进说明。 |
| 2026-03-01 | 初始发布 |
参考文献
-
Cormack, G.V., Clarke, C.L.A., and Buettcher, S. Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods。SIGIR,2009。提出了以k=60作为无参数方法的RRF,用于合并排序列表。 ↩↩↩
-
OpenAI Embeddings Pricing。text-embedding-3-small:每百万token $0.02。估算知识库完整重索引成本:约$0.30。 ↩
-
van Dongen, T. et al. Model2Vec: Turn any Sentence Transformer into a Small Fast Model。arXiv,2025。描述了从句子变换器生成静态嵌入向量(embeddings)的蒸馏方法。 ↩
-
MTEB: Massive Text Embedding Benchmark。potion-base-8M平均得分50.03,而all-MiniLM-L6-v2为56.09(保留率89%)。 ↩
-
SQLite FTS5 Extension。FTS5提供带有BM25排序和可配置列权重的全文搜索功能。 ↩
-
sqlite-vec: A vector search SQLite extension。在SQLite中提供用于KNN向量搜索的
vec0虚拟表。 ↩ -
Robertson, S. and Zaragoza, H. The Probabilistic Relevance Framework: BM25 and Beyond。Foundations and Trends in Information Retrieval,2009。 ↩
-
Karpukhin, V. et al. Dense Passage Retrieval for Open-Domain Question Answering。EMNLP,2020。密集表示在开放域问答任务上比BM25高出9-19%。 ↩
-
Reimers, N. and Gurevych, I. Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks。EMNLP,2019。密集语义相似度的奠基性工作。 ↩
-
Luan, Y. et al. Sparse, Dense, and Attentional Representations for Text Retrieval。TACL,2021。混合检索(hybrid retrieval)在MS MARCO上始终优于单一模态方法。 ↩
-
SQLite Write-Ahead Logging。WAL模式支持多读者与单写者的并发访问。 ↩
-
Gao, Y. et al. Retrieval-Augmented Generation for Large Language Models: A Survey。arXiv,2024。RAG架构与分块(chunking)策略的综述。 ↩
-
Thakur, N. et al. BEIR: A Heterogeneous Benchmark for Zero-shot Evaluation of Information Retrieval Models。NeurIPS,2021。 ↩
-
Model2Vec: Distill a Small Fast Model from any Sentence Transformer。Minish Lab,2024。 ↩
-
Obsidian Documentation。Obsidian官方文档。 ↩
-
Model Context Protocol Specification。MCP标准,用于将AI工具连接到数据源。 ↩
-
作者的生产数据。16,894个文件,49,746个分块,83.56 MB SQLite数据库,14个月内处理了7,771个信号。查询延迟通过
time.perf_counter()测量。 ↩ -
Model2Vec Potion Models。Minish Lab,2025。Potion-base-32M(MTEB 52.46),potion-retrieval-32M(MTEB检索36.35),以及v0.5.0+量化/降维功能。 ↩↩↩
-
Update on the Next MCP Protocol Release。2025年11月发布版本引入了Streamable HTTP传输、.well-known URL发现、结构化工具注解和SDK层级标准化。下一版本暂定于2026年中期发布,将包含异步操作、领域特定扩展和代理间通信。 ↩↩
-
Model2Vec Releases。v0.4.0(2025年2月):训练/微调支持。v0.5.0(2025年4月):后端重写、量化、降维。v0.7.0(2025年10月):词汇量化、BPE/Unigram分词器支持。 ↩↩
-
Smart Connections for Obsidian。Smart Connections v4:本地优先的AI嵌入向量,语义搜索在初始索引后可离线使用。 ↩