obsidian-memory — 跨项目长期记忆（Obsidian brain vault）

Outcome Contract

• Outcome: 任务开始前从 vault 召回相关背景；任务结束后把「未来有用」的结论沉淀回对应项目 sub-vault，并维护索引。
• Done when: 召回的笔记已作为线索并入当前上下文（并经现状复核），或新增/更新的笔记已落盘且 sub-vault index.md 同步。
• 权威模型（不可违反）: repo 内 artifact（tasks/、docs/、MEMORY.md、代码）是各项目的 source of truth；vault 只是跨项目聚合投影层，方向恒为 repo → brain。vault 与现状冲突时，现状赢，且顺手修正 vault。
• 双读者: vault 的读者是 agent 和用户本人。笔记必须是人能直接阅读学习的成文——完整句子、讲清 why 与 tradeoff，不写 agent 速记、不堆原始日志；index.md 是人的阅读入口。
• 边界: 本 skill 只能由模型或用户显式调用。hooks 永不执行它——hook 层最多发 [BrainPromote] 类建议文本，不读写 vault 状态。

Vault 解析（fail-closed，且 vault 本身是可选的）

1. 读 ~/.repo-harness/config.json 的 brainRoot。
2. 未配置或路径不存在 → 停止并说明，不扫描磁盘猜 vault、不临时新建 vault root。
3. 项目 sub-vault 为 <brainRoot>/<project-slug>/；<project-slug> 取 repo 目录名或用户指定名。

没有配置 brainRoot 是一个合法的稳态，不是待修复的故障。 未配置就意味着这台机器不使用 vault 层：repo 内 artifact 依然是完整可用的权威记忆，收口时把结论写进 tasks/lessons.md、docs/researches/ 等既有槽位即可，不要为了让本 skill 能跑而去创建 vault。仅当用户明确表示要启用 vault 层时，才指路 repo-harness install --brain-root <path> 或 repo-harness update --brain-root <path>。

Phase init · 建立项目 sub-vault

仅在 sub-vault 不存在或用户明确要求时执行：

1. 创建 <brainRoot>/<project-slug>/，内含 index.md 与按需的 decisions/、patterns/、notes/、references/、runbooks/（对齐 vault 既有分类，不发明新分类学）。
2. index.md 记项目一句话背景、长期偏好、当前进度指针、各子目录链接；用 wiki-link 挂进 vault 根 index.md。
3. 依赖官方 Obsidian skills（硬依赖）：任何创建或修改 vault 内 .md 的动作必须同时调用官方 obsidian-markdown skill（frontmatter、wiki-links、callouts 等格式权威）；需要对运行中 vault 做搜索/打开/任务操作时用官方 obsidian-cli skill。本 skill 只负责判断与索引（写什么、何时写、如何组织），不自定 Markdown 方言。两个官方 skill 缺失时 fail-closed 报告，不降级手写格式。

Phase recall · 任务前召回

1. 先读 sub-vault index.md，再按任务关键词 rg 该 sub-vault（必要时扩到相邻 domain），选出最相关的 ≤3 篇笔记读全文。
2. 召回内容一律当待复核线索，不当事实：涉及文件、命令、版本的记忆先对现状验证再采用。
3. sub-vault 不存在 → 报告无记忆可召回，询问是否 init；不静默跳过也不硬造背景。

Phase persist · 任务后沉淀

1. 提取候选：关键决策及理由、踩坑根因与解法、可复用方案/模式、失败方案及拒因、进度里程碑。
2. 排除式写入门槛（先过这一条）——凡是 git、包管理 registry、代码托管平台、CI 或任一可重跑命令已经权威记录的事实，vault 只写指针，不写正文。据此明确排除：commit SHA、PR/issue 编号、merge commit、CI run ID、tag、release URL、main == origin/main == <sha> 之类的同步状态、worktree 干净与否、测试通过计数、某次命令的快照输出。这些写下去那一刻就开始腐烂，而且原本就有权威源。
3. 价值闸门——过了排除规则后还要同时满足：未来会再用到（对 agent 复用或对用户学习二者居其一即可）；不是 repo artifact 已记录内容的复述（已有的写一行 wiki-link 指回 repo 路径，不复制正文）；不是一次性/临时信息。
4. 敏感闸门——写盘前扫描内容：密码、API key、token、私钥、真实 env 值一律不落 vault；命中即改写为占位符或放弃该条。
5. 绝对路径慎写——机器改名、家目录迁移、checkout 位置变化都会让硬编码路径静默失效。能写 repo 相对路径或让工具自行解析根路径的，就不要写绝对路径。
6. 写入对应子目录并更新 sub-vault index.md；同类主题已有笔记则更新原文件，不另开重复页；发现过时结论直接改掉。

目录所有权边界

在 repo-harness 管理的仓库里，.ai/harness/brain-manifest.json 声明的 brain_path 是 repo-harness brain sync 的机器投影，手写内容会被下次 sync 覆盖。本 skill 永远不写 manifest 声明过的路径；记忆笔记落在 notes/、decisions/ 这类 manifest 不拥有的子目录。docs/reference-configs/ 类文档的外化走既有 brain promote/sync 通道，本 skill 不与其重复搬运。

与既有记忆层的分工

同一事实只在权威层写正文，其余层写指针。

Gotchas

Provenance

• 2026-08-16 由用户的「Obsidian 作为跨项目 AI 知识库大脑」提案落地；经评审否决 hook 实现路线，采用 skill + 显式收口，对齐 repo-harness brain-manifest.json 的既有 invariant（hooks 不读写外部 vault 状态）。
• 2026-08-18 修订：加入排除式写入门槛与 manifest 目录所有权边界，并把 vault 层明确为可选——未配置 brainRoot 时 repo 内 artifact 独立成立，不再把「没有 vault」当成待修复状态。
• 双侧安装：~/.claude/skills/obsidian-memory/ 与 ~/.codex/skills/obsidian-memory/ 内容一致，用 cmp 校验。