别每开一轮重讲项目：把 Obsidian 库做成 Claude Code 的自维护记忆层

源微信页触发了验证码拦截，正文以 eugeniughelbur/obsidian-second-brain 官方 README、references/freshness-policy.md、scripts/freshness_lint.py 以及 v0.14（2026-07，The Harvest）为准，不臆造未公开能力。仓库当前约 4300 Star，协议是 MIT。作者 Eugeniu Ghelbur 把定位写得很直：这不是又一个 Obsidian 社区插件，而是一套跑在 Claude Code（以及 Codex / Gemini / OpenCode 等）里的技能包——笔记库才是跨会话记忆，CLI 只是读写它的器官。

本地已经写过 NoteGen 这种「内置 RAG 的开源笔记本」，也写过一组「给 Obsidian 配 AI Agent Skill」的速查。那些文回答的是 笔记应用本身 或 技能清单。本文换一层：Karpathy 的 LLM Wiki 是追加新页，这套技能是改写旧页；OKM 规定每条事实必须永恒、带日期或做成指针；夜间代理是五阶段巡库，不是口号里的「帮你整理」。

封面：笔记库自己改写

一、两个强工具，中间没有桥

Claude Code 每天都能干活，但每一轮会话默认从零开始。你把项目背景、人、决策、失败记录再讲一遍，上下文窗口一关，这些口头记忆就蒸发。Grok Bot、Codex、Gemini CLI 也一样：模型很强，跨会话记忆几乎为零。

另一边，Obsidian 库里躺着几百上千个 Markdown。它们不会自己改写，也不会在你做了相反决策时跳出来反对。日笔记里的想法腐烂，半年前已经拍板的架构决定，你会再拍一次。库是档案柜，不是记忆系统。

这套技能要接的就是这条缝：你已经有长期记忆（纯 Markdown 库），缺的是一个会读、会写、会改写、会在无人值守时巡库的 Agent。安装之后，日常入口不是 Obsidian 的编辑器，而是 slash 命令。官方 FAQ 写得很清楚：这是 Claude Code skill，不是 Obsidian plugin。 你装进 CLI，不装进 Obsidian；库文件格式不变，只是被更好地调用。Obsidian Sync、iCloud、Syncthing、Git 同步都能继续用，因为写入的就是普通 Markdown。

起步只需要三条：/obsidian-init 初始化，/obsidian-save 捕获，/obsidian-find 召回。其余四十多条按需出现。作者建议在 bootstrap 时选角色预设：builder（开发）、executive（经营）、creator（内容）、researcher（研究），会生成不同的目录、模板和看板。不选也行，得到一份通用库。

uv run python scripts/bootstrap_vault.py \
  --path ~/Documents/MyVault \
  --name "Your Name" \
  --preset builder

二、不是再追加一页，而是改写已经存在的页

Andrej Karpathy 的 LLM Wiki 模式很干净：丢进资料，模型生成 wiki 页，你再提问。这套技能承认这个模式，但把「新资料」的默认动作从 append 改成 rewrite。官方对比表值得原样理解，不要只记住「也能做 wiki」：

维度	Karpathy LLM Wiki	obsidian-second-brain
新资料进来	追加新页，互相交叉引用	改写已有页：人、主张、过期事实被替换
矛盾	标出来，人自己解	`/obsidian-reconcile` 自动裁决并留下记录
模式	你问才浮现	`/obsidian-synthesize` 自己找未命名模式并写综合页
何时跑	你提示才跑	四个定时代理：晨报、夜间整合、周复盘、库健康
笔记形态	给人读的 wiki	AI-first：`## For future agent` 前言 + 给检索用的 frontmatter

/obsidian-ingest 是这条主线的入口。丢一条 URL、一份 PDF、一段音频、一张白板截图，它不会只写一篇摘要。官方演示把流程拆成六步：原文进 raw/（不可变）→ 改写实体页 → 改写概念页 → 模式出现时新建综合页 → 化解矛盾并写明理由 → 更新 index.md、log.md 和当日笔记。一条 YouTube 链接进去，库里可能被碰到 5～15 页。截图走视觉抽取，音频走本地 Whisper 转写后再归因说话人、抽出承诺和待办。

/obsidian-save 是会话侧的对称操作：把当前对话里的决策、任务、人物、想法拆到该去的笔记，而不是再贴进日记末尾。官方还有 Two-Output Rule：你问一个问题，回答本身也要回写相关页。库不是查询缓存，是会代谢的知识体。

Mermaid Diagram

别每开一轮重讲项目：把 Obsidian 库做成 Claude Code 的自维护记忆层

三、四层命令 + 一条常开维护带

仓库把 47 条命令（日历那条依赖 Google Calendar MCP，所以 Codex / Gemini / OpenCode / Hermes / Pi / Agent Skills 构建是 46 条）分成四层，再加一条 Always On：

层	职责	你会碰到的命令
Operations	记住、归档、摄入、对账、导出、维护	`save` / `ingest` / `find` / `reconcile` / `health` / `architect`
Thinking	用库里的历史跟你抬杠、找模式、把想法毕业成项目	`challenge` / `emerge` / `connect` / `graduate` / `brainstorm`
Context	知道你是谁、现在在哪	`world`（L0～L3 渐进加载身份与状态）
Research	把库外知识拉进来	`research` / `research-deep` / `notebooklm` / `youtube` / `x-read`
Always On	你不操作也在代谢	PostCompact 后台代理 + 晨/夜/周/健康四个定时任务

思考层最能说明「记忆」和「档案」的差别。/obsidian-challenge 会在你说「API 要用 Rust 重写」时，翻出你自己 2025 年的复盘和「两年内锁定 TypeScript」的决策记录，用你自己的句子反对你。/obsidian-emerge 扫 30 天日笔记，把你在四个无关项目里都提过、却从未命名的「入职摩擦」写成一条模式。/obsidian-connect 在两团看起来无关的笔记之间找共享概念。/obsidian-graduate 把三周前的碎片想法扩成带阶段和看板的项目规格。

检索层默认是关键词，不装模型也能用。可选语义层走本地 Ollama bge-m3，或任何 OpenAI 兼容嵌入端点。官方在约 2350 篇笔记上测过：关键词 recall@10 为 1.0；改写提问 recall@10 约 77%；非英语查询 recall@5 从 13% 提到 63%。索引不会自动更新，落后超过 5% 会在 stderr 警告；/obsidian-health 会报覆盖率。嵌入走云端就意味着笔记正文离机，要用 OBSIDIAN_EMBED_EXCLUDE 把私密目录留在本地。

插图：四层命令栈

四、夜间五阶段不是「帮你整理」四个字

营销文喜欢把定时任务写成「Claude 半夜替你收拾笔记」。官方 SKILL 把 obsidian-nightly 写成五阶段、可审计的巡库，而且明确：只追加、更新、加链接，不做破坏性修复，不问问题，做完就停。

阶段	做什么
Close the day	读今日笔记，追加 3～5 条日终摘要；把看板已完成项挪到 Done
Reconcile	扫实体页过时角色/公司，扫概念页被新资料打脸的主张；明确胜者自动改，含糊的丢进 `wiki/decisions/`
Synthesize	看今明两天摄入的资料，跨来源出现两次以上的概念就写综合页
Heal	给今日新建、没有入链的笔记补链接；给该关闭的时间线补 `until`；重建 `index.md`
Log	往 `log.md` 追加一行：对账了几条、综合了几页、治愈了几个孤儿

另外三个定时任务更朴素：morning 早 8 点写日笔记并翻出过期任务；weekly 周五 18 点做周复盘；health 周日 21 点跑库审计。调度示例是 Claude Code 的 /schedule obsidian-nightly - daily 10:00 PM。

后台代理挂在 PostCompact：上下文压缩之后，obsidian-bg-agent.sh 拉起 claude -p 无头跑一轮，库被更新，你继续干活。官方把代价写在 README 里，不要跳过：无头写入用了 --dangerously-skip-permissions，所以默认惰性、必须你主动武装。工具面钉死在 Read,Write,Edit,Glob,Grep，不能跑 shell、不能出网，只增改不删除、不合并且。不能接受这个交易就关掉，其它命令不受影响。

还有一个可选的 Bounded Recall：每次提示前，UserPromptSubmit hook 注入最多 4 篇、约 900 字符的相关笔记摘要；置信度低就什么都不注入。只读、失败即关闭，每次注入/弃权都记到 .claude-runs/。用 OBSIDIAN_RECALL_ENABLED=1 打开。

默认不要打开后台代理。它跳过权限确认，换来的是无人值守写入。工具白名单和「永不删除」是补偿，不是免死金牌。先把 /obsidian-save 和 /obsidian-health 跑顺，再决定要不要武装 hook。

插图：夜间五阶段与 OKM

五、OKM：每条事实要么永恒，要么带日期，要么只是指针

维护层有名字：OKM（Open Knowledge Metabolism）。作者把它写成一份存储无关的规范：任何给 AI 当真相源的 Markdown 文件夹都适用，不只是 Obsidian。核心一句：每条被存下来的事实必须是永恒的、带日期的，或只是指向真相所在地的指针。禁止用现在时去断言会变的数字，却不盖戳。

三种合法形态：

1. 永恒（timeless）：「成交记录活在 CRM，发票按月开。」这种不腐烂。

2. 快照（snapshot）：2026-07-13: pipeline 有 13 个进行中的单。 日笔记、带日期的标题、freshness: snapshot 的 frontmatter，整段都是历史，lint 不再追。

3. 指针（pointer）：写清真相住在哪，可选附带「上次观察到的值 + as of 戳」。

非法形态只有一种：对会变的量用现在时、不写日期、也不在日期容器里——「pipeline 现在有 13 个单」到下周二已经是谎，读起来却仍像真相。这就是知识库慢慢变蠢的方式。

/obsidian-health 会跑 scripts/freshness_lint.py。规则可以记成五条：FRESH-1 未盖戳的易变现在时（错误）；FRESH-2 戳超过窗口（默认 7 天，警告）；FRESH-3 类型化指针没有在 .freshness.json 里映射（错误）；FRESH-4 日期容器整段豁免；FRESH-5 没用上的 freshness: example 抑制注释（警告）。过期戳的处理不是删除，而是三选一：重新观测并换戳、改成只留指针、或挪进带日期的笔记变成历史。

freshness: wiring | snapshot | pointer
freshness-window: 7d

研究命令是另一条输入管道，不要和核心库命令绑死。没有 API Key 时，38 条非研究命令全都能用；/research 和 /research-deep 会退回到 Wikipedia、Hacker News、arXiv、Reddit 等免费源。/x-read、/notebooklm、/youtube 才需要各自的 Key。/research-deep 是库优先：先扫你已经知道什么，只补缺口，再给出「该改哪些笔记」的增量报告。

六、安装路径、多 CLI，以及不该踩的坑

Claude Code 推荐走插件市场，仓库本身就是 marketplace：

/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brain

装完在 ~/.claude/settings.json 的 env 里声明库路径：

{
  "env": {
    "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
  }
}

重启后再在库目录里跑 /obsidian-second-brain:obsidian-init。插件命令带命名空间，输入 /obsidian-second-brain: 能看到全表。更新用 /plugin update obsidian-second-brain。

经典脚本安装仍然可用：克隆到 ~/.claude/skills/obsidian-second-brain，跑 install.sh 和 scripts/setup.sh "/path/to/your/vault"。这条路径需要 jq，因为它会改 ~/.claude/settings.json。一键脚本是 scripts/quick-install.sh。没有库时先 bootstrap_vault.py，再 setup.sh。

同一份源码打八套构建：Claude Code、Codex CLI、Gemini CLI、OpenCode、Hermes、Pi、Grok Bot、以及给 Antigravity / Copilot CLI 用的 Agent Skills 树。bash scripts/build.sh --platform agent-skills 之后，可以把 .agents/skills/ 拷进库根。日历命令只在 Claude Code 上完整，因为依赖 Calendar MCP。Grok Bot 没有 hook 运行时，也就没有后台代理和定时任务。Pi 同样没有等价后台，夜间整合要手动 /obsidian-nightly 或自己挂 cron。

坑	实际约束
当成 Obsidian 插件装	装错运行时。命令、hook、MCP 都在 CLI 侧
一装就开后台代理	默认 inert。武装后跳过权限确认
以为研究命令必须有 Key	核心库命令零 Key；`/research` 可走免费源
语义索引一次建完不管	不自动更新，落后会让改写查询失灵
全局一个 `OBSIDIAN_VAULT_PATH`	多仓库可在项目级 `.claude/settings.json` 覆盖；单库内部还没有 `--scope`
让开源小模型跑深度综合	`save` / `find` / 免费 `/research` 还行；`reconcile` / `architect` / `research-deep` 要更强的指令遵循
把 NoteGen、社区 Skill 清单和这套混成一个产品	前者是笔记应用或技能目录，这套是「改写旧页 + OKM + 定时巡库」

/obsidian-architect 值得单独提：它扫描代码库，把模块、入口、决策写进库，生成内容包在哨兵标记里，再跑只替换标记内，手写注释不会被冲掉。这是「项目怎么工作、为什么这样工作」和你的人、想法、决策住在同一个库里的方式。

配套练习在 practice/：一份不依赖官方 vault_scan 的 OKM 教学检查器，对着三份样例笔记跑。它演示的是规范本身——未盖戳的易变现在时必须报错，带日期的文件名整份豁免，指针形态放行。

cd practice
python3 freshness_check.py --path sample-vault

本机实跑 stdout：

[FRESH-1] error: wiki/concepts/pipeline.md:7 undated present-tense claim: The pipeline currently has 13 open deals.
1 error(s), 0 warning(s)

wiki/daily/2026-09-14.md 即使写了现在时数字也不会进报告，因为它是带日期的快照。wiki/entities/crm.md 用指针形态，应当干净。把 pipeline.md 改成 13 open deals (as of 2026-09-14) 再跑，错误应归零。

官方仓库：https://github.com/eugeniughelbur/obsidian-second-brain。命令中英触发短语见项目站点。规范原文在 references/freshness-policy.md，参考实现是 scripts/freshness_lint.py。