Obsidian + MCP：把本地知识库变成 AI Agent 的长期记忆中枢

一、场景描述（痛点）

你有没有这种感觉：每次打开一个新的 AI 聊天窗口，它都像失忆一样，得把项目背景、客户名单、技术栈从头讲一遍。我自己的 Obsidian 仓库（PARA 结构，300+ 条笔记）里其实什么都有，但过去只能手动复制几段贴给 AI——能用，但没法规模化。

这不是我一个人的问题。标准 Agent 是无状态的：会话一关，上下文清零，第二天接着聊又得重新铺垫。这层"失忆"是 AI 生产力最大的隐形损耗。根因不是模型不够强，而是它没有一处能持久读写、且你完全掌控的记忆仓库。

二、解决方案（怎么做）

核心思路就一句话：把 Obsidian 当 Agent 的"第二大脑"，用 MCP（Model Context Protocol，模型上下文协议）让 Agent 直接读、写你的 Vault。

MCP 是 Anthropic 于 2024 年 11 月推出的开放协议，用于标准化 AI 应用与外部数据源、工具之间的通信，你可以把它理解成一个通用插座——Agent 不需要为每个工具单独造一套连接方式，只要通过统一的插口就能调用能力（来源：Anthropic 官方，2024-11；致网科技《MCP 实现方式全攻略》，2026-07）。2025 年 12 月，Anthropic 将 MCP 捐赠给 Linux 基金会旗下 Agentic AI Foundation 托管，公开 MCP 服务器超过 10,000 个，官方 SDK 月下载量近亿次（97M+，检索于 2026-08）——协议已经从"新概念"走向"基础设施"。

接入之后，Agent 的角色从"旁观者"变成"操作者"——它不再只处理你贴给它的片段，而是能自己翻库、找资料、建笔记、回写结论。最关键的是：记忆留在你本地硬盘的 Markdown 文件里，隐私可控、可检索、可用 Graph View 可视化。

⚠️ 重申：Obsidian 不是腾讯产品，IMA（腾讯云端知识管家）才是。

三、关键步骤（具体实施）

3.1 选插件：三条主流路径

路径 A：Obsidian MCP Server（社区插件，Leonezz/obsidian-mcp-server） 在 Obsidian 内起一个本地 MCP 服务，把整个 Vault 暴露给外部 Agent。官方文档列出的工具包括 read_note、search_notes、search_content、create_note、edit_note、append_note 等（来源：community.obsidian.md/plugins/mcp-server，检索于 2026-08）。

📷 截图占位 1：Obsidian「设置 → Obsidian MCP Server」界面，红框标出 Server Port（默认 27123） 与 Auth Token，并提示本地开发可关鉴权但有风险。

路径 B：Vault Operator（社区插件，Sebastian Hanke） 自带 Agent 循环，且设计了三层记忆：短期会话摘要、跨重置保留的持久事实、以及记录你写作习惯的 soul 档案；同时它本身也能作为 MCP Server 运行，让你的其他 AI 客户端读到同一份记忆（来源：community.obsidian.md/plugins/vault-operator，检索于 2026-08）。社区页显示下载约 1.1 万（2026-08 检索，仅供参考，非能力证明）。

路径 C：Local REST API with MCP（社区插件，coddingtonbear） 这是目前最主流的方案之一。内置 MCP 服务器（3.x 版本起），默认监听本机回环地址 127.0.0.1:27124/mcp/（外网访问不到），通过 Bearer Token 鉴权。它能直接调用 Obsidian 内部命令——相当于你手动按 Ctrl+P——还支持通过 API 创建 Daily/Weekly Note、更新 frontmatter、运行 Dataview 查询（来源：community.obsidian.md/plugins/local-rest-api，检索于 2026-08）。优势在于调用的是 Obsidian 内部接口：改文件名不断双链、创建笔记不绕过索引机制，比第三方 CLI 方案稳定得多。此外，社区还有若干同类的 Obsidian MCP 服务方案，可供技术型用户按需选择。

中文库优化项：obsidian-mcp-tools（jacksteamdev）对中文笔记搜索做了分词优化，纯中文库为主可选它而非官方 MCP Server（来源：第三方实测文，今日头条 2026）。中英混排则优先官方 MCP Server。

3.2 最小可运行示例（以 Obsidian MCP Server 为例）

① 记下插件给的端口与 Token；② 在 Claude Code / Cursor 的 .mcp.json 加一段（vault 路径用占位，勿填真实绝对路径）：

{
"mcpServers": {
"obsidian": {
"type": "http",
"url": "http://localhost:27123/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}

📷 截图占位 2：.mcp.json 配置片段，红框标出 url 与 Authorization 两处需替换的占位。

③ 连上后，下指令让 Agent 检索并回写（这是对话指令，非可运行代码，按你实际库名改）：

读取我 Vault 里昨天 daily note，总结"Q3 选题"项目进度，列出今天 Top 3 优先级。

把这次会话的关键决定写入 Log/2026-08-18.md，供下次会话调用。

④ 验证：问"我有哪些关于 RAG 的笔记？"——Agent 应直接找到、读取并基于你的库作答，而非从零编造。

📷 截图占位 3：Agent 在 Obsidian 内检索/写入笔记的对话界面，红框标出"调用 read_note / append_note"的工具调用记录。

3.3 第三种形态：Agent Client（可选）

部分社区方案还能把 Claude Code / Codex CLI / Gemini CLI 等命令行 Agent 接入 Obsidian 侧边栏，让 Agent 看到你当前打开的笔记与选中内容。适合"在 Obsidian 里写文、就地让 Codex 改结构"的流，但前提是本机已装对应 CLI Agent。

四、实施效果（量化成果）

讲效果我尽量克制，只说本人实测，不编行业均值：

• 跨会话不丢上下文：早上问 Agent"昨天进度"，从手动翻 10+ 分钟笔记，变成一句话从 Vault 调取，体感从"重新 briefing"降级成"续聊"。
• 记忆可审计：所有回写都是 Markdown 文件，能 git 跟踪、能用 Graph View 看连接，哪条记忆哪天写的清清楚楚。
• 隐私可控：数据全在本地，不上任何云；这与云端知识管家形成互补（详见后续内容 36 的 IMA × WorkBuddy 组合打法）。

注意：以上为个人工作流体感，非基准测试，不构成"效率提升 X%"的断言。

如果你把 Obsidian 当作 Agent 的长期记忆仓库，还有几层客观优势值得强调（来源：本人实测 + Obsidian 官方设计，检索于 2026-08）：

• 无限容量：只受硬盘限制，不像向量数据库有固定容量上限。
• 100% 语义兼容：存的是原始 Markdown，不是向量 embedding，任何模型都能直接读取，没有格式转换损耗。
• 永久可读性：纯文本格式，十年后依然可打开，零迁移成本。
• 可追溯性：配合 Git 可以完整跟踪每个知识的来龙去脉。
• 多 Agent 共享：未来多个 Agent（运维、开发、搜索）可共用同一个 Obsidian 知识库协同工作。

五、经验教训（避坑）

1. 权限默认 fail-closed：Vault Operator 每次写库都需你批准，敏感文件夹用 .obsidian-agentignore 把关。别为了省事全局开"自动批准"，记忆库一旦被误写很难追溯。

📷 截图占位 4：Vault Operator 权限面板 / .obsidian-agentignore 配置，红框标出"write 类别开关"与忽略规则。

1. 本地优先 ≠ 绝对安全：MCP 服务若禁用鉴权，同网段任何能访问端口的进程都能读你库。只在纯本地开发环境关鉴权，正式用务必留 Bearer Token。
2. 别神话"自动化记忆"：Agent 仍是被动的——除非你显式触发 handoff / 回写指令，否则会话结束记忆不更新。我踩过的坑：以为装了插件就自动记，结果一周后才发现日志空空。记忆中枢要你喂，不是它自己长。
3. 中文分词选型：纯中文库选 obsidian-mcp-tools，中英混排选官方 MCP Server，否则检索召回率会明显掉。

六、最佳实践：让记忆真正可复用

6.1 召回协议（Recall Protocol）

记忆系统能不能起作用，关键在什么时候该查库。建议在 Agent 的系统提示词或项目级指导文件中显式写下召回触发条件（来源：Obsidian as long-term memory for LLMs via MCP 实践，2026）：

• 涉及指定项目的问题（如"Q3 选题"的进度）；
• "我们决定/进行到哪了"这类需要回顾历史的问法；
• 模糊续接——只有结合先前上下文才说得通的任务；
• 当用户说出的信息与 Agent 当前记忆矛盾时——此时应当查记录核实，而不是凭模糊印象争论。

6.2 记忆文件组织规范

记忆文件不是越多越好，关键是结构化和可路由。推荐用两层骨架（来源：第三方实践文，2026）：

• AGENTS.md：规则文件，控制在 100 行以内。核心规则包括：重要会话开始时先读 AGENTS.md 和 INDEX.md；只读取当前任务相关的记忆文件，不扫描整个 vault；只保存长期可复用信息，不存临时聊天；每个记忆文件控制在 50-100 行；单次会话加载的记忆文件不超过 3-5 个；发现过期/重复/冲突记忆时先提醒，不擅自删除；写入记忆前先列出候选内容等用户确认；记忆与最新指令冲突时以最新指令为准；不保存密码、客户隐私等敏感信息。
• INDEX.md：路由表，告诉 Agent 不同类型任务应读取哪些文件。示例格式：

| 任务类型 | 建议读取 |
|:---|:---|
| 写文章 | user.md, workflows/writing.md |
| 做项目开发 | user.md, projects/当前项目.md |
| 做决策 | user.md, decisions/ 相关文件 |

这套规范的核心思路是：让 Agent 只加载必要的记忆，而不是每次把整个库都翻一遍。

七、Q&A

Q1：Obsidian 是腾讯的产品吗？ A：不是，是第三方本地知识库。本文是"本地知识库 + Agent 记忆中枢"这一类型的示例，与手册里 IMA / Miora 形成类型互补，不代表在专项展开某产品。

Q2：一定要会编程才能接吗？ A：用 Vault Operator 走插件 GUI 配置即可；接 Claude Code / Cursor 才需改 .mcp.json，官方文档给了可直接套用的示例，复制改 Token 就行。

Q3：我的笔记会泄露吗？ A：数据全在本地 Markdown，默认不上云。风险点在 MCP 服务端口——只要开着鉴权、不暴露到公网，基本可控。

Q4：这和 IMA 知识库什么关系？ A：IMA 是腾讯的云端知识管家（见内容 31），Obsidian 是本地仓库。一个管"云上协作 + copilot 记忆"，一个管"本地私有 + Agent 读写"，两者可互补；组合打法放在内容 36 展开。

Q5：为什么不用向量数据库？ A：Obsidian 存的是原始 Markdown，任何模型都能直接读取，语义兼容性 100%，且永久可读、零迁移成本。向量数据库通常会设置容量或条数上限（部分记忆系统的长期记忆仅约 1500 条、工作记忆约 20 条），且存入时要做 embedding 转换，存在格式损耗；而 Obsidian 本身就是最通用、最开放的格式。对"长期记忆"来说，原始文本永远比向量优先。

参考资料（来源标注 · 数据源铁律）

• Obsidian 社区插件：Vault Operator — community.obsidian.md/plugins/vault-operator（检索 2026-08）
• Obsidian 社区插件：Obsidian MCP Server（Leonezz）— community.obsidian.md/plugins/mcp-server（检索 2026-08）
• Obsidian 社区插件：Local REST API with MCP — community.obsidian.md/plugins/local-rest-api（检索 2026-08）
• obsidian-mcp-tools（jacksteamdev）— github.com/jacksteamdev/obsidian-mcp-tools（引自第三方实测文，今日头条 2026）
• MCP 官方生态数据（10,000+ 公开服务器、97M+ SDK 月下载量）— Anthropic 捐赠 Linux Foundation 报道，2025-12 / 2026-08
• 本人实测：Obsidian 仓库（PARA 结构，300+ 条笔记）接 MCP 工作流，效果描述为个人体感，非基准数据