Obsidian Mind：给 Coding Agent 装一个不会忘事的大脑
你让 Claude Code 写了一个星期的代码，第二天重启——Agent 忘了昨天为什么这么设计、上周你跟产品经理定下的三个决策、以及那次踩坑是怎么翻车复盘的。
Obsidian Mind 就是来解决这个问题的。
这不是一个记忆插件，也不是一个简单的 context 加载器。它是一个完整的 工作流系统：用 Obsidian Vault 做载体，通过 5 个生命周期 Hooks + QMD 语义搜索 + 多个专用 Subagent，让 AI Coding Agent 真正拥有跨会话、跨天的持久记忆。
作者 Brenno Ferrari 是柏林的一位 Senior iOS 工程师，他在 2026 年 2 月开源了这个项目。到今天已经积累了近 4K Stars、480 Forks。它的定位很清晰：
Claude Code / Codex CLI / Gemini CLI —— Agent 只管说话，Obsidian Vault 负责记住一切。
🧠 为什么你需要它
所有主流 Coding Agent 目前都有一个共同问题：每次会话从零开始。你让 Agent 写代码、修 Bug、重构，这些操作产生的上下文——决策依据、架构取舍、团队反馈——全随着会话结束而消散。你不得不反复重述相同的背景信息。
Obsidian Mind 的做法不是「给 Agent 加一段持久化 memory」，而是把一个 Obsidian Vault 变成 Agent 的第二大脑。Vault 里记录了你的 North Star 目标、活跃项目、人员关系、会议记录、事故复盘、决策文档、技能清单。Agent 通过 Hooks 自动读取、写入、索引、索引、索引这个 Vault。
核心架构：两半分工
📌 流程化代码负责环境，Agent 负责内容。 Vault 中的 Hooks 处理分类、验证、索引和生命周期注入——确定性的、可测试的。笔记撰写、归档、链接，这些判断交给 Agent。两者在小交接处汇合：Hooks 注入上下文，Agent 读取 Vault。
具体来说，整个系统分为四层：
- Vault 层（文件夹结构）—— work/ 管理活跃和已归档项目；org/ 管理团队和人；perf/ 追踪个人绩效和能力证据；brain/ 存放核心记忆（North Star、Key Decisions、Patterns、Gotchas）
- Hooks 层（5 个生命周期钩子）—— 自动在 SessionStart、消息提交、文件写入、上下文压缩前、会话结束时介入
- 检索层（QMD + fallback）—— 语义搜索优先，没有就回退到 grep + Obsidian CLI
- Subagent 层（9 个专用 agent）—— 每个负责不同的专项任务，隔离在独立上下文窗口中运行
⚙️ 五个生命周期 Hooks
这是 Obsidian Mind 的技术核心。它们不依赖任何 AI——全是确定性的 TypeScript/Node.js 脚本，跑在你的 Agent 配置里：
| Hook | 触发时机 | 做什么 |
|---|---|---|
| 🚀 SessionStart | Agent 启动/恢复时 | 重新索引 QMD + 自我修复，注入 North Star 目标、活跃项目、最近 git 变更、待办任务和 Vault 文件列表。控制 token 预算，最终输出一个注入尺寸计量表。 |
| 💬 UserPromptSubmit | 每条用户消息 | 自动分类内容类型（决策、事故、胜利、1:1、架构、人员、项目更新），并注入路由提示。 |
| ✍️ PostToolUse | 每次写入 .md 后 | 校验 frontmatter + wikilinks，阻止误放的记忆文件，标记超大笔记（建议拆分而非裁剪）。 |
| 💾 PreCompact | 上下文压缩之前 | 将会话转录备份到 thinking/session-logs/。 |
| 🏁 Stop | 会话结束时 | 执行完整性检查，输出漂移发现结果（同样使用卫生扫描）。 |
你不用手动记任何东西。你说「start session」，Agent 自动加载你的 North Star、检查活跃项目和最近的记忆。
You: "start session"
Agent: *reads North Star, checks active projects, scans recent memories*
Agent: "You're working on Project Alpha, blocked on the BE contract.
Last session you decided to split the coordinator. Your 1:1
with Sarah is tomorrow — review brief is ready."🔍 QMD 语义搜索（可选但强烈建议）
Tobi Lütke（Shopify CEO）写的 QMD 是 Obsidian Mind 的检索引擎。
它的核心作用：当你说"缓存迁移我们之前怎么决定的？"时，Agent 不会因为标题里没有"缓存"二字就找不到决策记录。语义向量搜索能跨越标题和正文的表达差异，找到真正相关的笔记。
💡 首次 qmd embed 会下载 ~328MB 嵌入模型，qmd query（带 LLM reranking）还会再下载 ~1.28GB 模型。如果你不想等，可以用 qmd search（BM25）或 qmd vsearch（纯语义）作为轻量级替代。
如果没有安装 QMD，一切照常工作——Agent 降级到 grep + Obsidian CLI，只是少了语义召回能力。这意味着你可以先用起来，再按需增强。
🤖 9 个 Subagent 专岗专责
Subagent 是 Obsidian Mind 里最聪明的设计之一。它们运行在隔离的上下文窗口中，不会污染主对话的 token：
| Subagent | 职责 | 触发方式 |
|---|---|---|
| brag-spotter | 找出未记录的成就和能力差距 | /om-wrap-up, /om-weekly |
| context-loader | 加载关于某人/项目/概念的所有 Vault 上下文 | 手动调用 |
| cross-linker | 查找缺失的 wikilink、孤儿笔记、断开的反向链接 | /om-vault-audit |
| people-profiler | 批量创建/更新人员笔记 | /om-incident-capture |
| review-prep | 聚合绩效评估期的全部证据 | /om-review-brief |
| slack-archaeologist | 从 Slack 重建完整事故时间线 | /om-incident-capture |
| vault-librarian | 深度 Vault 维护（孤儿、断链、过期笔记） | /om-vault-audit |
| review-fact-checker | 验证评审草稿中每条声明的来源 | /om-self-review, /om-review-peer |
| vault-migrator | 从旧 Vault 分类、转换、迁移内容 | /om-vault-upgrade |
每个 Subagent 的定义都在 .claude/agents/ 下，你可以按自己的需求自定义或添加新的。这也是我推荐 Obsidian Mind 的一个重要原因：它的架构是 extensible 的，不是那种封闭的一锤子买卖。
🚀 上手指南
方式一：ShardMind 一键安装（推荐）
# 安装 ShardMind 包管理器
npm install -g shardmind
# 创建新目录并安装
mkdir my-vault && cd my-vault
shardmind install github:breferrari/obsidian-mindWizard 会收集你的姓名、组织、Vault 用途、要接入的 Agent 等信息，然后自动初始化 Git、配置 QMD、个性化 North Star。
方式二：直接 Clone
git clone https://github.com/breferrari/obsidian-mind.git
cd obsidian-mind通用后续步骤
- 把安装目录当作一个 Obsidian Vault 打开
- 在 Settings → General 中启用 Obsidian CLI（需要 Obsidian 1.12+）
- 在这个目录下启动你的 Agent：
claude/codex/gemini - 开始聊工作——Vault 会替你记住一切
💰 Token 成本控制
Obsidian Mind 不是一次性倾倒整个 Vault 到上下文中。它采用分层加载策略：
| 层级 | 内容 | 何时加载 | Token 消耗 |
|---|---|---|---|
| Always（始终） | CLAUDE.md + SessionStart 上下文（North Star 摘要、git 统计、任务列表） | 会话启动 | ~2K tokens |
| On-Demand（按需） | 根据 Subagent 请求加载特定话题笔记 | Subagent 调用时 | 取决于笔记大小 |
| Never（永不） | 历史归档（除非明确搜索） | — | 0 |
这使得即使 Vault 里有几百篇笔记，日常运行的 Token 开销也极低。Agent 不会因为你记了太多东西就烧钱加速。
⚡ 亮点功能一览
除了核心的持久记忆，Obsidian Mind 还内置了一系列非常实用的工具：
- Morning Standup —
/om-standup加载所有上下文，回顾昨天，发现阻塞点 - Brain Dump —
/om-dump自由叙述，自动分类归档到你的笔记中 - Incident Response —
/om-incident-capture贴一个 Slack 链接，自动生成事故时间线和 RCA - Performance Tracking — 能力笔记 + 成就文档，Review 季直接读 backlinks 面板
- Vault Hygiene —
/om-tidy自动归档、分组、拆分；/om-vault-audit检查索引、孤儿链接 - Vault Upgrade — 把任何 Obsidian Vault 的内容自动迁移到 Obsidian Mind 格式
📊 和竞品对比
在「给 Coding Agent 加记忆」这个赛道上，其实已经有不少玩家了。来看看 Obsidian Mind 的定位：
| 维度 | Obsidian Mind | Beads | ai-memory | Planning-with-Files |
|---|---|---|---|---|
| Stars | 3,961 | 25,641 | 1,233 | 24,000+ |
| 存储方式 | Obsidian Vault (Markdown) | Dolt Git 数据库 | Rust CLI + File | 3 个 Markdown 文件 |
| 记忆机制 | Vault + QMD + 5 Hooks | 图结构 Issue 追踪 | 长期记忆 CLI | CODING_GUIDE + TODO + KNOWLEDGE |
| 语义搜索 | ✅ QMD 向量检索 | ❌ | ❌ | ❌ |
| Subagent 系统 | ✅ 9 个内置 | ❌ | ❌ | ❌ |
| 跨 Agent 支持 | ✅ Claude/Codex/Gemini | ✅ | ✅ | ❌ Claude-only |
| 绩效追踪 | ✅ Built-in | ❌ | ❌ | ❌ |
| 学习成本 | 中高（需 Obsidian） | 低 | 低 | 极低 |
| 核心理念 | Vault-first 记忆图谱 | 图结构 issue tracking | CLI-first 长期记忆 | 三个文件搞定 |
简单总结：如果你的 Agent 只需要记住 TODO 和知识，用 Planning-with-Files 就够了。但如果你希望 Agent 像一个真正的人类同事那样「认识你、了解你过去的项目、记得你们之前的对话」，Obsidian Mind 是目前最成熟的方案。
🕳️ 你可能踩到的坑
- Obsidian 版本要求：需要 Obsidian 1.12+，且要在 General 设置中手动开启 Obsidian CLI。这不是默认选项。
- Node 22+ 必须：Hook 脚本直接用
--experimental-strip-types跑 TypeScript，老版本的 Node 不支持。 - QMD 首次建立索引很慢：一个 200 个文件的 Vault 可能需要几分钟才能完成向量化索引，期间 Agent 会用 fallback 模式。
- Vault 不是 Git clone 那么简单：它是动态系统，笔记之间靠 wikilink 互联。写笔记如果不 link，Agent 会觉得这是个 bug。
- 记忆膨胀：如果你频繁 dump 会议记录但不整理，vault 会越来越大。建议定期用
/om-tidy做卫生维护。
🎯 适合谁
强烈推荐：你至少有两个以上活跃的编码项目，每周用 Claude Code / Codex 写代码超过 5 小时，并且受够了每次重启 Agent 都要从头讲一遍背景。
不推荐：你只有一个小项目，Agent 一天只聊三五句。这个工具的完整性和 Obsidian 的引入成本对你是浪费。
🏷️ Tags: