enquire-mcp

**分发状态：**此分支记录的是尚未发布的源代码候选版本。下方针对候选版本的 npm 命令和 MCPB 下载 URL 目前无法使用。如需获取可用构建产物，请使用已发布的 GitHub 版本或已发布的 npm 版本。稳定版安装命令与候选版本说明相互独立。

claude mcp add obsidian -- npx -y @oomkapwn/enquire-mcp serve --vault ~/Documents/Obsidian\ Vault

你的 AI 才华横溢，记忆却支离破碎。

每次新聊天都会丢失项目历史、决策、研究成果和来之不易的上下文。供应商提供的记忆功能在自家产品中有所帮助，但切换到其他 Agent 时，记忆便会消失。传统文件连接器只有在已知路径时才能打开笔记；向量搜索可以找到相似段落；但两者都算不上完整的记忆系统。

enquire-mcp 将 Obsidian 变成 Agent 的记忆数据库

安装一次，即可将现有知识库变成任何兼容 MCP 的 Agent 都能使用的持久化、可查询的知识数据库。它在本地建立索引，跨格式检索，结合词法、语义和图谱证据排序，并返回 Agent 可引用的源上下文。即使没有 enquire-mcp，原始文件仍可读取和编辑。

由你掌控的记忆。 大多数对话记忆产品会从聊天中提取事实，存入单独的存储库。enquire-mcp 从你有意保留的知识出发：Markdown、frontmatter、wikilinks、PDF、Canvas 和 Bases。召回内容以源材料为依据，而非隐藏的改写内容。

无需迁移数据的文档智能。 PDF 会进入与 Markdown 相同的本地混合搜索流程，并返回页码引用；OCR 可识别扫描页面。Canvas 会转换为类型化图谱。专用工具可运行受支持的 Dataview LIST/TABLE 子集和 Obsidian Base 筛选器，而不是将这些格式视为不透明附件。

关注时效，而非永久召回。 每条搜索结果都可包含 age_days 和 stale；可选的时效加权可帮助 Agent 优先选择较新的知识，并重新核实旧事实，而不是自信地重复它们。

enquire-mcp 的不同之处：

1. 具备时效感知能力、可引用来源的召回。 搜索结果保留源路径，并显示内容年龄和过时状态；PDF 结果保留页码引用。可选的时效重新排序可帮助 Agent 优先选择较新的知识，并重新核实旧事实。
2. 默认只读。 七种写入工具在启用 --enable-write 之前不可见；隐私筛选器和精确的 Origin HTTP 准入机制可减少暴露面。
3. 原生支持 Obsidian 的文档智能。 Markdown/PDF 混合召回结合了类型化 Canvas 解析、Dataview 风格的 LIST/TABLE 查询，以及受支持的 Base 筛选器执行。
4. 本地全栈检索。 混合 BM25 + TF-IDF + 多语言嵌入通过 RRF 融合，并提供可选的 BGE 交叉编码器重排器和各信号得分；HNSW + int8 量化可扩展密集检索流程。
5. 清晰的数据边界。 enquire 在服务期间不会发起任何外发调用，也不发送遥测数据。它只会将请求的上下文返回给你连接的 MCP 客户端；之后任何云端处理均受该客户端自身的隐私条款约束。请参阅完整的隐私政策。
6. 不依赖厂商的记忆。 你的源知识始终保存在可移植文件中。切换 Agent 或模型提供商，无需重建专有的记忆孤岛。

47 个工具 · 19 个 MCP 提示词 · 声明的测试注册项共 2367 个 · 支持 50 多种语言 · v3.11.x 稳定版 + v4 SDK-v2 预览版 · 遵循语义化版本 · MIT · npm 构建来源证明（SLSA L2）。

🏆 为什么 enquire-mcp 是完整的 Obsidian 智能技术栈

大多数替代方案只解决一个层面：应用内相似度面板、功能强大的搜索引擎，或 MCP 文件访问。enquire-mcp 将完整的本地检索阶梯、Agent 编排、富文档覆盖、时效性、安全性和发布规范整合在一个软件包中。

_{✅ = 完整支持该行内容。✕ = 在所审查的公开产品页面中未说明完整组合；项目可能实现了该行的部分内容，或日后添加。审查日期：2026-07-30。准确的来源快照及逐行边界：竞争产品证据。}

**这就是 TOP-1 的核心论点：**一个真相来源、一个本地智能层、每个 Agent 都能使用——同时不会将你的知识压缩成云端记忆数据块。

enquire-mcp 是开源后端，可在你已有的 Obsidian 知识库基础上构建 Karpathy 风格的大模型 Wiki：知识不断积累，每个答案都可追溯至来源。

⚡ 快速开始

npm install -g @oomkapwn/enquire-mcp
enquire-mcp serve --vault ~/Documents/Obsidian\ Vault

接入任意 MCP 客户端：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@oomkapwn/enquire-mcp", "serve", "--vault", "/path/to/vault"]
    }
  }
}

更偏好可审核的桌面程序包？使用 MCPB Basic

v4.0.0-rc.7 GitHub Release 提供 enquire-mcp-basic-4.0.0-rc.7.mcpb，以及相应的校验和、清单、SBOM、声明文件和来源证明。该程序包包含服务端 JavaScript 和常规 JavaScript 依赖项；兼容的 MCPB 宿主必须提供 Node.js 22.13 或更高版本。在该宿主中打开程序包，检查清单，并选择宿主可以访问的唯一一个 vault 目录。

**Basic 刻意保持精简：**恰好 13 个只读工具、0 个提示词，且不包含写入工具、监视器控制、持久化／磁盘索引、嵌入模型、PDF 或 OCR 功能。其推荐的统一搜索会惰性地对实时 Markdown 使用内存中的 TF-IDF；固定的启动契约还会拒绝发现完整版本已有的嵌入数据库或监视器保护文件。enquire 在提供服务时不会主动发起出站调用；请求的笔记内容仍会传送到你连接的 MCP 客户端，并受该客户端隐私条款的约束。

发布工作流要求在发布前提供程序包的 .sha256、构建／发布来源证明、确定性的逻辑内容清单、CycloneDX SBOM，以及第三方许可／声明清单。由于固定版本的上游打包器会记录打包时的元数据，因此不保证归档的字节流可复现。字节完全一致很重要时，请验证已发布的校验和。真实桌面 GUI 安装、签名、目录审批行为以及任何目录列表功能，仍须通过维护者把关的验收工作。完整的混合检索功能仍可通过下方的 npm／CLI 设置使用。

📂 examples/ 中的配置模板和Agent 生命周期配方——适用于 Claude Desktop、Cursor、ChatGPT 自定义 GPT（通过 HTTP 使用远程 MCP），以及与客户端无关的回忆、证据、新鲜度、综合整理和安全写入操作指南。

**不想手动拼装配置？**让 CLI 为你的 vault 和客户端打印准确的配置片段（无破坏性操作——不会写入任何内容）。自 v3.11.6 起：

enquire-mcp configure --vault <path>                 # prints config for every client
enquire-mcp configure --vault <path> --client cursor # just one (claude-code|cursor|vscode|codex|windsurf|claude-desktop|http)

输出会如实说明每个客户端的安装边界：VS Code 会获取官方审核并安装 URI，Claude Code 和 Codex 会获取复制并运行的命令；而一键流程仅接受 Marketplace／Registry 条目的客户端会标记为仅可复制，并附上准确的备用配置。在保存任何内容之前，生成的 vault 路径和实际程序包入口点都清晰可见，供你检查。

**想要完整的混合检索能力？**完成混合检索预检，然后启动服务：

npm install -g @oomkapwn/[email protected]      # exact prerelease package
enquire-mcp --version
# recommended: preview first, then explicitly apply the same package-coherent plan
enquire-mcp first-run --tier hybrid --client claude-desktop --vault <path>
enquire-mcp first-run --tier hybrid --client claude-desktop --vault <path> --apply
# manual equivalent below: choose this instead of first-run --apply, not in addition
enquire-mcp setup --vault <path>                          # caches embedder; builds FTS5 + embed-db
enquire-mcp install-model rerank-bge                      # caches the offline reranker
enquire-mcp doctor --tier hybrid --vault <path>           # structural/runtime readiness
enquire-mcp configure --tier hybrid --client claude-desktop --vault <path>
enquire-mcp serve --vault <path> --persistent-index --enable-reranker --use-hnsw

🤖 在你的 AI Agent 中设置——复制粘贴提示词

现在，每次连接都会收到与配置相关的 initialize.instructions：推荐的回忆工作流、引用与新鲜度语义、当前的写入状态，以及检索到的 vault 内容属于数据而非指令这一规则。能够显示 MCP 服务端指令的客户端可以自动使用这份约定。下方的复制粘贴提示词仍可作为明确的用户偏好，或供不显示服务端指令的宿主使用。

# Add the MCP server to your Claude Code config (one time)
claude mcp add obsidian -- npx -y @oomkapwn/enquire-mcp serve --vault ~/Documents/Obsidian\ Vault

enquire-mcp configure --client vscode --vault <path>

enquire-mcp configure --client codex --vault <path>

可复用的 Agent 规则（添加到任意 AGENTS.md / CLAUDE.md / .cursorrules，让 Agent 知道何时查阅知识库）：

当我的问题涉及我自己的笔记、决策、项目、人物或研究时，请先通过 obsidian_* 工具搜索我的 Obsidian 知识库（从 obsidian_search 开始），并为每条事实引用来源笔记。对于*概念性 / 跨语言 /“我对 X 说过什么”*的回忆，优先使用 enquire；对于精确的字面字符串，使用普通的 grep / ripgrep。如果没有找到相关内容，请如实说明，不要猜测。

效果良好的查询示例

• “找出我讨论定价策略的所有笔记，并总结其演变过程。” — RRF 融合 + 重排序器可从语义上处理“演变过程”
• “我对 PostgreSQL 和 MongoDB 的选择是什么？请引用每日笔记。” — 融合候选项的 RRF 分数相同时，候选集合中的 wikilink 入度会用于打破平局
• “Анализируй мои заметки о RAG за последние 3 месяца” — 多语言嵌入 + frontmatter 日期筛选
• “LLaMA-3 论文 PDF 的哪些页面讨论了扩展？” — PDF 会与搜索结果融合，并附带 [page: N] 引用
• “展示我的研究知识库中的主题社群——我一直在探索哪些主题？” — obsidian_get_communities（轻量版 GraphRAG）

🧠 使用场景

1 — AI Agent 的长期记忆。 将你的 Obsidian 库接入任何兼容 MCP 的 Agent（Claude Code、Claude Desktop、Cursor、ChatGPT、Codex、OpenClaw）。现在，Agent 能够跨会话、模型和提供商，对你写过的每一篇会议笔记、日记、研究记录和决策文档进行持久的语义检索。你的知识不会被锁定在某一家供应商的记忆层中，而是以你拥有的纯 Markdown 格式存储，可自由迁移。

2 — 个人知识库 / 第二大脑。 混合检索能从 50 多种语言的各种表述中找到合适的笔记。用英语询问 2 年前的俄语日记内容，也能找到正确结果。Wikilink 图谱加权仅在 RRF 分数相同时，才依据候选集中的入度打破平局。轻量 GraphRAG 能展现主题社群，帮你发现自己忘记曾建立的关联。PDF 会融入搜索，并附带 [page: N] 引文，让研究论文和会议记录成为一等记忆。

3 — Agentic RAG / 上下文工程。 obsidian_search 会公开各信号的分数，让 Agent 看出每条结果排名靠前的原因。HyDE 会在检索前，将含糊的查询预先改写为内容丰富的假设性答案。子问题分解可处理多跳问题（“我们的定价策略如何演变？客户对此有何反应？”）：将问题拆分为独立的子查询，再融合结果。内置评测工具（NDCG / Recall / MRR）可让你用自己的查询衡量检索质量，而不是盲信供应商的基准测试。

✅ 专为严肃的本地知识工作流打造

满足以下需求时，请选择 enquire-mcp：

• 让 Obsidian 库继续作为事实来源，而不是将知识复制到另一个专有存储中。
• 在多个 AI Agent 之间共用一个记忆层，这样切换模型就无需从头开始。
• 具备概念理解能力的多语言检索，不受措辞变化影响，而不只是匹配完全相同的字符串。
• 提供带引文且可检查的答案，包含笔记路径、PDF 页码、信号分数和新鲜度元数据。
• 隐私优先的本地体验，默认只读、明确的写入门控、serve 期间 enquire 不会主动发起任何出站调用，并有完整记录的 MCP 客户端信任边界。
• 完整的检索后端，涵盖混合搜索、重排、图谱上下文、Agentic 扩展、丰富的 Obsidian 格式和远程 MCP。

明确的适用范围： enquire-mcp 是面向 Markdown、Canvas、Bases 和 PDF 知识的无头 MCP 服务 / CLI。精确匹配字面字符串时，请同时使用精确搜索工具；Agent 需要远程访问时，请使用内置的 HTTP 传输。

📖 产品网站和 API 参考

产品主页 介绍带引文的记忆体验、证明材料、客户端接入方式和适合 AI 读取的资源。完整的自动生成 API 参考 通过完整的 TSDoc（@param / @returns / @example）记录每个工具、提示词和导出的辅助函数。每次推送到 main 时，都会通过 publish-docs.yml 从源代码重新构建这两份文档；历史的 TypeDoc 深层链接仍然有效。

🏗️ 检索工作原理

graph LR
    Q[Query] --> S[obsidian_search]
    S --> BM25[BM25 / FTS5]
    S --> TFIDF[TF-IDF cosine]
    S --> EMB[ML embeddings<br/>HNSW]
    BM25 --> RRF{RRF fusion<br/>k=60}
    TFIDF --> RRF
    EMB --> RRF
    RRF --> GB[Graph boost<br/>in-degree tie-break]
    GB --> RR[BGE cross-encoder<br/>reranker]
    RR --> R[Ranked hits<br/>per_signal observability]

obsidian_search 会自动检测可用信号，并在必要时平稳降级。Wikilink 图谱增强仅使用候选集入度来打破 RRF 得分相同的平局。可选的交叉编码器重排会对排名靠前的 N 个结果重新评分，据测量可提升 +15.5 NDCG@10。每个命中都会返回 per_signal: { bm25, tfidf, embeddings }，让你了解结果为何排名靠前。

🛠️ 全部 47 个工具

总计 47 个生产级工具：35 个始终启用的读取工具（包括总入口 obsidian_search）+ 4 个可选启用的读取工具 + 7 个受控写入工具 + 1 个闭环反馈工具。完整参考：docs/api.md。

此外，还有 3 个 MCP 资源（obsidian://vault/info、obsidian://note/{path}、obsidian://chunk/{n}/{path}）和 19 个 MCP 提示词（summarize_recent_edits · review_tag · find_orphans · weekly_review · extract_todos · process_inbox · consolidate_tags · find_duplicates · lint_wiki · monthly_review · search_with_query_expansion · vault_synth · vault_wiki_compile · vault_lint_extended · vault_capture · vault_persona_search · vault_automation_setup · vault_research · vault_synthesis_page），适用于常见的知识库工作流。

🛡️ 信任

❓ 常见问题

需要安装 Obsidian 吗？ 不需要。可直接读取 .md、.canvas 和 .pdf 文件。适用于任何 Obsidian 格式的知识库。

会写入我的知识库吗？ 只有传入 --enable-write 才会写入。全部 7 个写入工具均受开关控制；具有破坏性的工具支持 dry_run。

数据会发送到其他地方吗？ enquire 不会发送遥测数据，在服务运行期间也不会发起出站 HTTP 请求。它会将请求的知识库上下文返回给你连接的 MCP 客户端；云端客户端可能会根据自身隐私政策处理这些上下文，任何隧道/代理也是一道信任边界。显式获取命令——setup、build-embeddings 和 install-model——可能会从 Hugging Face 获取 ONNX 权重；混合层级的 first-run --apply 会协调执行这些相同的获取操作，而 install-ocr-lang 会获取 Tesseract 语言包。具体政策请参阅：SECURITY.md。

性能如何？ 这取决于知识库大小、硬件、模型和启用的检索层。公开证据包括一份生产报告：1,771 个分块 / 368 个文件时，BM25 top-10 耗时 50–100ms；以及一项可复现的合成基准测试：在 100–1,000 篇笔记时，FTS5 相较线性扫描快 37–103 倍。设置延迟 SLO 前，请先在自己的知识库上运行内置评估和基准测试命令；参见基准测试和 FTS5 实现说明。

支持哪些语言？ 默认嵌入模型为 paraphrase-multilingual-MiniLM-L12-v2（支持 50 多种语言），已在俄语 + 英语双语知识库上通过端到端验证。默认交叉编码器重排器为 rerank-bge（仅支持英语；它是唯一经过端到端验证的目录别名）；多语言重排器别名目前无法通过 transformers.js 分词器兼容性检查。CJK/泰语/高棉语分词使用 Intl.Segmenter。

可以远程运行吗？ 可以——serve-http 可通过 Streamable HTTP 对外提供相同的服务。在 v4 预览版中，严格的现代 2026-07-28 流量和受支持的旧版客户端分别使用官方 SDK v2 的独立路径，共用一个已注册的接口；格式错误或不受支持的现代协议声明绝不会回退到旧版路径。可通过 Tailscale Funnel 或 Cloudflare Tunnel 提供 HTTPS。适用于 claude.ai 网页版、ChatGPT 自定义 GPT、Cursor HTTP 模式和移动端 MCP 客户端。请参阅 docs/http-transport.md。

🚀 发布

v3.0.0 — 稳定通道。 v2.x 检索路线图已完成，公开接口现已受语义化版本约束。亮点一览：

v2.0 混合检索（通过 RRF 结合 BM25+TF-IDF+嵌入） · v2.6 远程 MCP · v2.7-2.8 混合检索 PDF · v2.9 BGE 重排器 · v2.10 OCR · v2.11 doctor + setup · v2.12 评估工具 · v2.13 HNSW · v2.14 有状态会话 · v2.15 延迟分块 · v2.16 HNSW 持久化 · v2.17 int8 量化 · v3.8.0 稳定版 · v3.8.7 HTTP 传输加固 · v3.9.0 稳定版：OCR 处理的 PDF 观察器嵌入同步、文件变更时 HNSW 内存实时更新、R-10 自适应 HNSW 补充检索（解决排除率超过 66% 时返回结果不足的问题）。· v3.10 稳定版：考虑遗忘的时效性——age_days + stale 标记 + 可选的 --recency-weight 重排 + 识别 frontmatter 的 obsidian_search。

通道：npm install @oomkapwn/enquire-mcp → 最新稳定版（@latest = v3.11.x）。预发布版：npm install @oomkapwn/enquire-mcp@rc → v4 SDK-v2 候选版；指定 @4.0.0-rc.7 可精确安装预览版。完整更新日志：CHANGELOG.md · 后续计划：ROADMAP.md。

🤝 贡献

git clone https://github.com/oomkapwn/enquire-mcp.git
cd enquire-mcp && npm install
npm test       # full suite (2367 declared test registrations)
npm run lint   # zero warnings
npm run build  # tsc → dist/

欢迎提交问题、PR 和创意。有关设置问题、错误报告和私密安全问题反馈渠道，请参阅 SUPPORT.md。

📜 许可证

MIT。由 Alex (@OomkaBear) 构建。名称源自 Tim Berners-Lee 于 1980 年开发的万维网原型——这是网络出现前的原始超文本系统。原始规范是：你可以向系统询问任何问题。enquire-mcp 将这一理念带到你的知识库中。