Obsidian Mind：给 AI 编程 Agent 装上持久记忆

Obsidian Mind 项目 Logo

痛点：一群天才，却全是金鱼

你一定有过这种体验：和 Claude Code、Codex 或 Gemini CLI 合作了一个月，好不容易把项目的架构、数据层、API 契约都摸清楚了，下一次新会话——全部归零。Agent 不记得你上周做的决策，不记得你删掉的方案为什么失败，不记得 Sarah 在 1:1 里到底提了什么要求。

这不是 AI 的错。传统架构里，Agent 的「记忆」只存在于当前上下文窗口，会话结束，一切消散。团队里一个程序员失忆，大家还能靠文档交接；一个 AI 编程 Agent 失忆，你每次都要从零解释项目背景。

这就是 Obsidian Mind 试图解决的问题：一个专为 AI Agent 设计的 Obsidian 知识库，让 Agent 在每次新会话开始时都能「想起来」——上一次做了什么决定、当前项目卡在哪里、你的个人目标和团队动态是什么。

解决思路：把 Obsidian 当作 Agent 的外脑

Obsidian Mind 的核心思路非常直接：把一个 Obsidian 知识库当作 AI Agent 的外部记忆系统。这个仓库不是给人看的（虽然人也可以看），主要是给 Claude Code/Codex/Gemini CLI 读取的。

项目作者 Bruno Ferrari 本身是长期使用 Obsidian 做个人知识管理（PKM）的开发者，2024 年开始频繁使用 Claude Code 时，被「每次会话都要重新解释项目上下文」这件事困扰，于是把 Obsidian 的层级笔记系统和 Claude Code 的 Hook 机制结合起来，产生了这个项目。

安装方式极其简单——一行 shardmind install 或一次 git clone，把仓库当 Obsidian vault 打开，配置好 Obsidian CLI，在仓库目录里运行 claude 或 codex，Agent 就能自动读取 vault 里的记忆文件了。

核心机制：Hook Pipeline + QMD 语义搜索

Obsidian Mind 不是一个 AI 应用，而是一个工程化的记忆基础设施。它的架构分三层：

第一层：Obsidian 仓库本身——纯 Markdown 文件，wikilinks，前端 YAML，全部通过 git 追踪，可以正常用 Obsidian 的图形界面浏览。目录结构也很清晰：brain/ 存记忆和目标、work/ 存工作笔记和项目状态、org/ 存人员和团队信息、perf/ 存个人成就记录和绩效证据。

第二层：Hook Pipeline（钩子管道）——这是整个系统的核心。Claude Code 支持在会话生命周期里触发自定义脚本（SessionStart、UserPromptSubmit、PostToolUse、PreCompact、Stop），Obsidian Mind 利用这些钩子，在关键节点自动执行 TypeScript 脚本，把当前会话里产生的信息写入 vault。例如：

• /om-standup：Agent 读取 brain/North Star.md、扫描 work/active/ 里的项目状态、查看最近的 git 变更，生成一份「今日站会」摘要，包含你当前的项目进展和待办。

• /om-dump <信息>：Agent 把会议纪要、决策记录、成就亮点自动分类写入对应的 vault 文件（人员笔记、1:1 记录、Brag Doc 等）。

• 会话结束（Stop Hook）：Agent 检查所有新建笔记是否有正确的 wikilinks、更新索引、发现未记录的成就。

第三层：QMD 语义搜索层——如果你问「我们当时关于缓存迁移做了什么决策」，仅靠标题匹配可能找不到「Redis Migration ADR」这篇笔记。QMD（@tobi/qmd）基于嵌入向量做语义搜索，即使笔记标题和查询词语面不一致，也能找到相关内容。QMD 有独立的 SQLite 索引和 MCP Server，与 vault 通过 vault-manifest.json 里的 qmd_index 字段协调。

多 Agent 支持：Claude / Codex / Gemini 三合一

Obsidian Mind 最初为 Claude Code 设计，但通过 .codex/ 和 .gemini/ 配置目录，也支持 OpenAI Codex CLI 和 Google Gemini CLI。三个 Agent 共享同一个 vault，各自的 hook 脚本在对应目录下独立配置，但所有 Agent 写入的笔记都进入同一个 Obsidian 仓库，实现记忆共享。

这一点非常实用——如果你在团队里同时用多个 Agent 工具，它们不再是独立运作的信息孤岛，而是共同维护一份团队记忆。

使用门槛：CLI 工具，非 GUI

需要明确的是：Obsidian Mind 是一个本地 CLI 工具，没有 Web 界面，也不支持 Docker 部署。它需要：

• Node.js >= 22（hook 脚本和 shardmind 安装器需要）

• Git（vault 通过 git 管理历史）

• Obsidian 桌面应用 1.12+（用于浏览 vault，以及启用 Obsidian CLI）

• 配合 Claude Code / Codex CLI / Gemini CLI 使用

部署难度极低（git clone 即可），但上手门槛在于用户需要熟悉这些 Agent 工具本身的用法。如果你不了解 Claude Code 的 hook 机制，直接使用可能效果有限。

局限与争议

Obsidian Mind 本质上是一个个人知识管理工具的变体，而不是一个 AI 应用。它的局限性也很明显：

1. 记忆质量取决于使用频率：如果用户不坚持在每次会话后执行 /om-dump，vault 里没有足够内容，Agent 也就「想不起来」什么。记忆是双向的——用户需要配合维护。

2. 多 Agent 写入冲突：三个 Agent 同时操作 vault，如果在同一会话里写了冲突的笔记，目前没有冲突解决机制，依赖 git 来追踪变更历史。

3. 中文社区生态有限：README 有中日韩三语翻译，但核心文档（ARCHITECTURE.md、CLAUDE.md）仍为英文，中文用户上手需要一定英语阅读能力。

行业意义：Agent 记忆系统的新范式

Obsidian Mind 运行演示：/om-standup 和 /om-dump 命令的实际效果

Obsidian Mind 的价值在于它用了一个开发者非常熟悉的工具（Obsidian）来解决一个新兴问题（AI Agent 记忆缺失），而不是发明一套全新的系统。这让它的学习曲线相对平缓。

从更宏观的视角看，这类「外部记忆层」方案正在成为 AI Agent 架构的主流方向——不依赖模型本身的上下文窗口，而是通过向量数据库或知识图谱给 Agent 提供长期记忆。Obsidian Mind 选择了 Obsidian + git + QMD 这套轻量组合，在易用性和功能性之间找到了一个不错的平衡点。

项目目前 Star 数超过 2800，虽然还没有形成大型社区生态，但它代表了一个值得关注的方向：未来 AI 编程工具的进化方向，不仅是让模型本身更强，还包括如何让 Agent 与人类的工作流程、知识体系更深度地整合。