把 Obsidian Vault 变成 AI Agent 的持久记忆：CLAUDE.md + MCP 完整教程

副标题：每次打开 Claude 都要重新解释一遍你的项目？这是最蠢的重复劳动——我花了两周找到了根治方法

引子：我计算过这个损失

2025年底，我做了一件让自己不舒服的事：认真统计了一下我在 AI 对话里花了多少时间在重新解释上下文。

结果是：每次新对话，平均要花8到12分钟，把项目背景、代码规范、架构约束、命名习惯重新告诉 Claude 一遍。

每天开5到8次新对话。

一周下来，这是将近一个小时，什么实质性工作都没做，纯粹在喂背景信息。

每次对话从零开始。你粘贴同样的文件，重新解释同样的上下文，不断重复自己——而且当你关掉聊天窗口，一切就消失了。这是当今 LLM Agent 的核心局限：它们擅长推理，但在 Session 之间没有持久记忆。

我把这个问题叫做「Session 失忆症」。

这篇文章，是我找到的根治方案。

一、诊断：你的 AI 没有失忆，是它没有地方存记忆

先说清楚一件事：Claude 不是因为「模型差」才每次都忘记你的项目。

它是因为没有一个稳定的地方存储你的项目上下文。

Claude Code 没有内置的持久记忆。这套方案里的记忆，来自写入你 Obsidian Vault 的 Session 日志。在每次 Session 开始时，你（或你的 CLAUDE.md 指令）告诉 Agent 在做任何事之前先读取最近的 Session 日志。这通过结构化文档而非模型内部记忆创造了连续性。

换句话说：记忆不是存在模型里的，而是存在文件里的。

这个洞察，是整套解决方案的基础。

而 Obsidian，恰好是存储这些文件最好的地方——因为它天生就是本地优先的纯 Markdown 文件系统。

二、两个概念，一张图搞清楚关系

在动手之前，先把两个核心概念分清楚：

CLAUDE.md = AI 的操作手册（宪法） MCP = AI 访问 Vault 的通道（接口）

text

你的 Obsidian Vault（本地 .md 文件）
        │
        ├── CLAUDE.md  ←── AI 每次 Session 必读的「操作手册」
        │                  定义：你是谁、Vault 结构、操作边界、禁止行为
        │
        ├── .claude/
        │   └── skills/
        │       └── obsidian-skills/  ←── 教 AI 写 OFM 格式
        │
        └── [你的所有笔记]
                │
                │  AI 访问 Vault 的通道
                │
        ┌───────┴────────┐
        ▼                ▼
   MCP 协议          直接文件读写
（Claude Desktop）  （Claude Code CLI）

Claude Code 在项目根目录寻找 CLAUDE.md 文件。这是你的 Agent 的常驻指令——它每次 Session 都会读取这个文件。把它想象成你的第二大脑的宪法。

三、第一步：写一份真正有效的 CLAUDE.md

这是最多人做错的地方。大多数教程给的 CLAUDE.md 模板太空洞，AI 读完还是不知道该怎么做。

一份强大的 CLAUDE.md 包含：关于你是谁和你做什么的2-3句话介绍、Vault 结构指南（描述你的文件夹结构和命名规范，让 Agent 知道去哪里找、去哪里写），以及 Session 协议（定义 Agent 在每次 Session 开始时该做什么——读取今天的日记笔记、检查 Inbox 文件夹、复查未完成事项，以及结束时做什么——写 Session 摘要到 /AI/sessions/、更新日记笔记的 Agent 日志）。

下面是我实际在用的完整版本，可以直接 fork 使用：

Markdown

# CLAUDE.md
# 版本：2026-06-21
# 每次 Session 开始前，请完整读取本文件
## 我是谁
我是一名 AI 部署架构师，专注于：
- FDE（Forward Deployed Engineer）实践
- RAG 系统生产化和 Multi-Agent 编排
- 知识工程（Obsidian + LLM Wiki）
- 面向程序员的 AI 工具教育内容创作

Vault 结构（你的地图）

vault/ ├── CLAUDE.md # 你正在读的这个文件 ├── .claude/ │ └── skills/ # obsidian-skills 安装位置 ├── 00-Inbox/ # 所有新内容先进这里，未整理 ├── 01-Projects/ # 活跃项目，每个项目一个子文件夹 │ ├── [项目名]/ │ │ ├── README.md # 项目概述 │ │ ├── DECISIONS.md # 架构决策记录 │ │ └── notes/ # 项目相关笔记 ├── 02-Areas/ # 持续关注的领域 │ ├── fde-skills/ # FDE 技能追踪 │ ├── writing/ # 写作和内容创作 │ └── reading/ # 读书笔记 ├── 03-Resources/ # 参考资料，按主题组织 ├── 04-Archive/ # 已完成或不活跃内容 ├── AI-sessions/ # Session 日志存放位置 └── Templates/ # 笔记模板
text

Session 开始协议（每次必执行）

1. 读取 AI-sessions/ 最近3个 Session 日志，了解上次做了什么
2. 读取今天的 Daily Note（00-Inbox/daily/YYYY-MM-DD.md）
3. 检查 02-Areas/open-loops.md，了解未完成事项
4. 用一句话告诉我：你理解了哪些上下文

Session 结束协议（每次必执行）

1. 在 AI-sessions/YYYY-MM-DD-HH.md 写一份 Session 摘要
   格式：
• 做了什么
• 关键决策（如果有）
• 修改了哪些文件
• 未完成事项
2. 更新 02-Areas/open-loops.md

写作规范（严格遵守）

• 所有内部链接使用 [[双中括号]] 格式
• 所有笔记必须包含 frontmatter（见下方模板）
• 标签使用小写字母和连字符：#rag-production，不是 #RAGProduction
• 文件名使用小写字母和连字符：rag-evaluation.md

标准 Frontmatter 模板

---
created: YYYY-MM-DD
modified: YYYY-MM-DD
tags:[]
project:""# 如果属于某个项目，填写 [[项目文件]]
status: active       # active / archived / draft
type: note           # note / decision / resource / meeting / daily
---

你可以做的操作 ✅

• 读取任何笔记
• 在 00-Inbox/ 创建新笔记
• 更新 01-Projects/ 中现有项目的 DECISIONS.md
• 在 02-Areas/ 中追加内容（不覆盖）
• 在 AI-sessions/ 写 Session 日志
• 移动文件到 04-Archive/

你不可以做的操作 ❌

• 删除任何文件（移动到 Archive 代替删除）
• 覆盖已有内容（追加或创建新版本）
• 修改 Templates/ 目录（除非明确被要求）
• 修改任何 frontmatter 中的 created 字段
• 在未搜索重复内容的情况下直接创建新笔记 （在创建前必须先用 [[关键词]] 搜索是否已有相关笔记）

敏感内容处理

我的 Vault 可能包含客户信息和私人内容。 如果你在任务中遇到明显敏感的内容， 询问我是否应该在 API 调用中包含它， 而不是自动处理。

四、第二步：配置 MCP——让 Claude 真正「进入」你的 Vault

MCP（Model Context Protocol）是 AI 访问你 Vault 的通道。

MCP 是一个开放标准，让 AI Agent 连接到外部工具和数据源。在这里，它让 Claude 可以直接在你的 Obsidian Vault 里实时读写文件，而不需要把任何内容粘贴到聊天窗口。

有两种主要方式。我从最简单的开始讲：

方式 A：文件系统 MCP（推荐新手）

特点：不需要安装插件，Obsidian 不需要开着，直接读写文件。

# 步骤1：安装 obsidian-mcp（注意包名，有两个相似的包）
# obsidian-mcp（by StevenStavrakis）= 直接文件访问，用 vault 路径
# mcp-obsidian（by MarkusPfundstein）= REST API，需要 uvx
# 找到你的 Vault 路径（包含 .obsidian 子文件夹的那个目录）
ls ~/Documents/my-vault/.obsidian   # 确认这是 Vault 根目录
# 步骤2：在 Claude Code 的 MCP 配置文件里添加
# 配置文件位置（运行这个命令查看确切位置）：
claude /mcp

配置文件内容：

JSON

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp",
        "/Users/你的用户名/Documents/my-vault"
      ]
    }
  }
}

Bash

# 步骤3：重启 Claude Code，验证连接
# 在 Claude Code 里运行：
/mcp
# 应该看到 obsidian 服务器显示为 connected

Claude Code 配置文件的位置随版本变化，文档经常过时。运行 claude /mcp 并查找 MCP Config Diagnostics 部分——它会告诉你 Claude Code 到底读的是哪个文件。 

常见陷阱：有多个名称相似的 npm 包。npx mcp-obsidian 和 npx obsidian-mcp 安装的是不同的包。obsidian-mcp（by StevenStavrakis）需要 vault 路径参数，直接访问文件；mcp-obsidian（by MarkusPfundstein）使用 REST API，需要 uvx（Python），不是 npx。

方式 B：Claudian 插件（推荐想要深度集成的用户）

Claudian 值得单独介绍，因为它做了所有 MCP 服务器都没做到的事：它把完整的 Claude Code CLI 作为侧边栏聊天面板嵌入 Obsidian 内部。你的 Vault 就是工作目录。Claude 可以用你在终端里获得的同等 Agentic 能力来读、写、编辑和搜索文件。 

内联编辑配有 diff 预览。当 Claude 建议修改一篇笔记时，你会在接受前看到逐词的 diff 对比。曾经被 AI Agent 静默改写笔记烧过的人，光是这一点就值得一试。

五、第三步：验证连接——四个「Aha Moment」测试

配置完成后，用这四个测试验证你的系统真正工作了：

测试1：Session 记忆测试

text

你好，请先执行 Session 开始协议：
读取 AI-sessions/ 的最近3个日志，
然后告诉我上次我们做了什么。

如果 Claude 能正确描述你上次的工作内容，Session 失忆症已被根治。

测试2：跨文件关联测试

text

搜索我的 Vault，找出所有提到「RAG 评估」的笔记，
把它们的主要观点整合成一篇新笔记，
保存到 03-Resources/rag-evaluation-synthesis.md，
包含到每篇源笔记的 [[wikilinks]]。

当天晚些时候，你要求 AI 搜索 Vault 里所有关于某个主题的内容。它找到了跨多个项目的四篇笔记，读取它们，创建了一篇综合摘要笔记，链接回原始笔记。然后它在你的日记笔记里追加了一行：「已创建迁移摘要——见 Projects/db-migration-summary.md」。

测试3：图像分析测试（如果使用 MCPBundles）

text

读取 Vault 里 Attachments/ 目录下最近的截图，
告诉我图片里展示的是什么。

你在头脑风暴后拍了白板照片并放入 Vault。你告诉 AI 来读取它。它看到了照片——不是文件引用，是实际图像——读取了便利贴，并在新的项目笔记里创建了结构化任务，附有指向头脑风暴 Session 的 wikilinks。

测试4：Vault 健康检查

text

请对我的 Vault 做一次健康检查，
找出：孤立笔记（没有任何链接指向它们）、
损坏的 wikilinks、以及跨文件的未完成任务。

你让 AI 运行健康检查。它找出了23篇没有任何链接指向它们的孤立笔记、7个指向已重命名或删除笔记的损坏 wikilinks，以及散落在12个不同项目文件里的45个未完成任务。

六、第四步：Session 记忆自动化

手动写 Session 摘要太麻烦。把它自动化：

Markdown

<!-- 在 CLAUDE.md 里添加这段 -->
## Session 结束命令（使用 /compress 触发）
当我说「/compress」时，请执行：
1. 总结本次 Session 的完整内容
2. 在 AI-sessions/[YYYY-MM-DD]-[HH:MM].md 创建结构化日志：
---
created: [日期时间]
tags: [session-log, 相关项目标签]
duration: [大概时长]
---
## Session 摘要
### 完成的工作
- [条目]
### 关键决策
- [决策 + 原因]
### 修改的文件
- [文件路径]: [修改内容]
### 未完成事项
- [ ] [任务]
### 下次建议起点
[一句话描述下次应该从哪里开始]
3. 在 02-Areas/open-loops.md 更新未完成事项
4. 返回确认：「Session 已归档至 AI-sessions/[文件名]」

用一行提示总结整个 Session 并保存到 Obsidian Vault：包含带标签的 frontmatter、完成内容摘要、关键决策、修改的文件、任何需要跟进的未完成事项。Claude 会使用 MCP 连接直接把笔记写进你的 Vault。打开 Obsidian——你会看到新文件实时出现。

七、三个真实踩坑记录

坑1：AI 静默覆盖了你的笔记内容

症状：你的原始段落消失了，被 AI「更简洁的版本」替换。

原因：你没有在 CLAUDE.md 里明确说明「追加而不是替换」。

根治方案：在 CLAUDE.md 里加入 Git 工作流：

Bash

# 在 Vault 根目录初始化 Git
cd ~/Documents/my-vault
git init
git add -A
git commit -m "initial vault backup"
# 创建自动提交钩子
cat > .git/hooks/post-commit << 'EOF'
#!/bin/sh
# 每次提交后自动备份
echo "Vault backed up: $(date)" >> .vault-backup.log
EOF
chmod +x .git/hooks/post-commit
# 建议在 CLAUDE.md 里加入：
# 在任何编辑操作前，先用 git diff 确认修改范围
# 不确定时，宁可创建新版本文件，不要覆盖原文件

这取决于你的 Vault 内容和你的威胁模型。Claude Code 在本地运行——你的文件默认不会被上传到服务器（尽管 API 调用会向 Anthropic 发送你的提示和任何包含的文件内容）。对大多数人的个人和工作笔记来说，这没问题。如果你的 Vault 包含高度敏感的材料（法律、医疗、财务），请判断在查询中应该包含什么。

坑2：两个相似名称的 npm 包搞混了

obsidian-mcp 和 mcp-obsidian 是两个完全不同的包，有不同的安装方式。这是导致80%人配置失败的原因。

根治方案：参照上一节的对比，决定用哪个架构，然后严格使用对应的包名。

坑3：Obsidian 打开时文件锁冲突

文件系统 MCP 服务器直接访问 Markdown 文件。Obsidian 不需要运行。 但如果 Obsidian 在写文件时你也在 AI 写同一个文件，可能会有短暂的冲突。

根治方案：把批量操作（如整理 Inbox）放在 Obsidian 没有打开的时间段运行，或者使用带 upsert_file 语义的 MCP 服务器（写入后如果已存在则更新，而不是直接覆盖）。

八、进阶：给 Vault 加上「搜索前置」规则

Vault 越大，AI 创建重复笔记的概率越高。

加入这条规则：

Markdown

<!-- 在 CLAUDE.md 的「操作规则」里加入 -->
## 防重复规则（必须遵守）
在创建任何新笔记之前，必须：
1. 搜索现有笔记是否已覆盖相同主题
   使用：Grep/搜索关键词 + 相关 [[wikilinks]]
2. 如果找到相关笔记：
   → 选项A：更新现有笔记（追加新内容）
   → 选项B：创建补充笔记，用 [[wikilinks]] 链接到原笔记
3. 只有在确认无相关笔记时，才创建全新笔记
违反此规则会导致 Dead Vault 综合症——
数千个独立存在、互不关联的重复笔记。

结语：从「每次重头来过」到「每次站在巨人肩上」

这是 Obsidian + AI Agent 工作流的真正承诺：一个随时间对你的特定上下文越来越了解的 AI。设置只需10分钟。知识永远复利。

你今天写的 Session 日志，是六个月后 Claude 理解你整个项目史的基础。

你今天配置的 CLAUDE.md，是未来每一个 AI Agent 进入你知识系统的导航手册。

这不是「用 AI 做笔记」。这是让你的知识系统变成一个能工作的实体。