给 Agent 添加基于 Obsidian 的外置大脑

这篇笔记说明如何给 Codex、Claude、Claude Desktop、Reasonix 等 agent 工具接入一个基于 Obsidian 的外置大脑。核心思想是：把长期有效的记忆写进 Obsidian，让不同工具通过明确规则和可验证接口读取同一套知识，而不是把聊天记录、临时过程或敏感信息塞进上下文。

目标

• 让 agent 在重要任务开始时能快速恢复长期背景。
• 让不同工具共享项目路径、用户偏好、排查结论、工作流和未闭环事项。
• 控制 token 消耗，不全量读取整个记忆库。
• 让记忆文件可读、可改、可审计。
• 避免保存 token、cookie、密码、验证码、私密身份信息和敏感日志值。

推荐目录

在 Obsidian vault 里给每类 agent 建独立记忆空间。可以用中文目录，也可以保留现有英文目录；关键是结构稳定、入口统一。

Obsidian Vault/
└── Codex记忆/
    ├── AGENTS.md
    ├── INDEX.md
    ├── TODO.md
    ├── agent/
    │   └── open-loops.md
    ├── 当前/
    ├── 项目/
    ├── 人物/
    ├── 工作流/
    ├── 决策/
    ├── 素材/
    └── archive/

如果是多工具共存，建议每个工具一套入口文件：

_Obsidian/
├── Codex/
│   ├── AGENTS.md
│   ├── INDEX.md
│   └── agent/
├── Claude/
│   ├── AGENTS.md
│   ├── INDEX.md
│   └── agent/
└── Reasonix/
    ├── AGENTS.md
    ├── INDEX.md
    └── agent/

读取规则

重要任务开始时，不要让 agent 扫描整个记忆目录。

默认只读：

• AGENTS.md：记忆规则、写入边界、工具约定。
• INDEX.md：当前有效摘要和文件索引。

然后根据任务关键词，只读取最相关的 1-3 个文件。

大文件只先读“当前有效摘要”或最近更新段落。archive/ 默认不读，除非需要追溯历史。

写入规则

可以写入：

• 用户长期偏好。
• 明确边界。
• 项目稳定路径。
• 关键命令。
• 已验证的排查结论。
• 重要决策。
• 可复用工作流。
• 跨项目未闭环事项。

不要写入：

• 完整聊天记录。
• 流水账和临时过程。
• cookie、token、API key、密码、验证码、私钥。
• 身份证号、银行卡号、私密联系方式。
• 第三方平台账号凭证。
• 敏感日志值。

写入时优先更新已有笔记；没有合适文件再新建。每次只写短小、可检查的 Markdown。事实和推断分开。旧记忆过时，不直接删除，先标注“已过时”。

Markdown 和 Obsidian 标签注意事项

Obsidian 会把 # 紧跟文字的形式识别为标签。写标题时使用 # 这种带空格的 Markdown 标题是可以的。如果只是想表达井号本身，优先写成反引号包裹的形式，例如 `#`。

新建或编辑 Obsidian 记忆笔记时，默认 frontmatter 只放：

---
created: 2026-06-04
updated: 2026-06-04
---

不要默认添加 tags、type、status、view-count、分类字段或工作流状态字段，除非用户明确要求。

Codex 接入

Codex 的关键是把 Obsidian 记忆规则放进项目或工作区指令里，让它在重要任务开始时读取固定入口。

项目里的 AGENTS.md 可以这样写：

Use the Obsidian Codex memory vault as persistent cross-project memory.

Memory root:
`/path/to/Obsidian Vault/_Obsidian/Codex`

At the start of important work sessions, read only:

- `AGENTS.md`
- `INDEX.md`

Then open only the 1-3 most relevant files by task keywords.

Do not read the full memory directory by default.
Do not store secrets, credentials, tokens, passwords, verification codes, private identifiers, or sensitive log values.
Before ending important work, decide whether memory closeout is needed and state which memory files changed.

如果 Codex 有本地文件权限，可以直接写 Obsidian vault 中的 Markdown 文件。如果路径在沙箱外，需要用户批准写入。更稳妥的方式是通过 Obsidian MCP 或 Local REST API 写入，并在写完后读回验证。

推荐验证：

• 读 AGENTS.md 和 INDEX.md。
• 写一个临时测试笔记。
• 读回确认内容一致。
• 删除测试笔记。
• 最后再写正式记忆。

Claude Code 接入

Claude Code 可以使用项目级 CLAUDE.md 或 AGENTS.md 记录同样的外置大脑规则。推荐让 Claude Code 只知道记忆入口和读取策略，不让它默认扫描整个 vault。

示例：

Use Obsidian as the external long-term memory.

Memory root:
`/path/to/Obsidian Vault/_Obsidian/Claude`

Startup rule:
Read `AGENTS.md` and `INDEX.md` first. Then read only the 1-3 most relevant files.

Write rule:
Only persist durable preferences, decisions, stable paths, verified troubleshooting conclusions, reusable workflows, and open loops.

Closeout:
Before ending important work, decide whether to update memory and report changed files.

如果 Claude Code 没有直接文件权限，就通过 MCP 接入 Obsidian。

Claude Desktop 接入

Claude Desktop 更适合通过 Obsidian Local REST API 插件加 MCP bridge 接入。

总体流程：

1. 在 Obsidian 安装并启用 Local REST API 插件。
2. 确认插件提供本地 MCP 或 REST endpoint。
3. 在 Claude Desktop 的配置文件里添加 Obsidian MCP server。
4. 重启 Claude Desktop。
5. 用 tools/list 或一次读写测试验证。

在这台机器上，已验证过的一类可行形态是：

• Obsidian Local REST API HTTP 端口：127.0.0.1:27123
• HTTPS 端口通常是自签证书，Node 客户端可能报证书错误。
• mcp-remote@0.1.38 可作为 stdio bridge。
• token 放在环境变量里，不写进笔记。

配置形态示例：

{
  "mcpServers": {
    "obsidian": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y",
        "mcp-remote@0.1.38",
        "http://127.0.0.1:27123/mcp/",
        "--allow-http",
        "--header",
        "Authorization: Bearer ${OBSIDIAN_API_KEY}"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "put-real-token-in-local-config-only"
      }
    }
  }
}

实际使用时不要把真实 token 写进 Obsidian 笔记。配置前先备份 Claude Desktop 配置文件，并保留已有 mcpServers 项，不要整块覆盖。

推荐验证：

• MCP initialize 成功。
• tools/list 能看到 Obsidian 工具。
• vault_list 能列出 vault 根目录。
• vault_read 能读取记忆入口文件。
• 测试写入临时文件后再删除。

Reasonix 接入

Reasonix 最好同时使用两层记忆：

• 内部长期记忆：影响 Reasonix 自身后续行为。
• Obsidian 外置备份：让用户可读、可审计，也方便跨工具共享。

常见内部路径：

~/.reasonix/REASONIX.md
~/.reasonix/memory/global/*.md
~/.reasonix/memory/global/MEMORY.md

Obsidian 外置路径建议：

Obsidian Vault/_Obsidian/Reasonix/
├── AGENTS.md
├── INDEX.md
├── TODO.md
├── agent/
├── projects/
├── people/
├── workflows/
├── decisions/
└── archive/

Reasonix 的规则应该写进内部记忆：

Use Obsidian as the external memory backup.

Reasonix internal memory controls future Reasonix behavior.
Obsidian memory is the user-readable external brain.

For Obsidian tasks, use Obsidian MCP first.
Do not import sessions, chats, histories, memory, or transcripts from other apps unless the user explicitly asks for that specific import.

At important session closeout, persist only durable preferences, decisions, stable paths, verified conclusions, reusable workflows, and open loops.

如果 Reasonix 支持 Obsidian MCP，优先使用 MCP 的 vault_read、vault_write、vault_append、search_simple、search_query 等工具。不要默认用全盘文件搜索替代 Obsidian MCP。

通用 Agent 接入模板

对任何新 agent，都可以按这个顺序接入：

1. 创建专属记忆目录，例如 _Obsidian/<AgentName>/。
2. 创建 AGENTS.md，写清读取规则、写入边界、closeout 规则。
3. 创建 INDEX.md，写当前有效摘要和高价值入口。
4. 创建 TODO.md 和 agent/open-loops.md。
5. 把 agent 的系统指令、项目指令或内部记忆指向这个目录。
6. 如果工具支持 MCP，配置 Obsidian MCP。
7. 做一次读写 smoke test。
8. 把验证结论写进对应 agent 的记忆文件。

最小 AGENTS.md 模板：

Use this Obsidian folder as the external long-term memory.

Startup:
Read only `AGENTS.md` and `INDEX.md`, then open only the 1-3 most relevant files.

Write:
Persist only durable preferences, decisions, stable paths, verified conclusions, reusable workflows, and open loops.

Do not write:
Transcripts, temporary logs, secrets, credentials, tokens, passwords, verification codes, private identifiers, bank data, private contact details, or sensitive log values.

Closeout:
Before ending important work, decide whether memory should be updated and report changed files.

最小 INDEX.md 模板：

Current effective summary

- Memory root: `/path/to/Obsidian Vault/_Obsidian/<AgentName>`.
- Default startup read set: `AGENTS.md` and `INDEX.md`.
- Read only 1-3 additional files by task keywords.
- Do not read `archive/` by default.

High-value entry points

- `TODO.md`: cross-task follow-ups.
- `agent/open-loops.md`: unresolved long-lived threads.
- `projects/`: durable project context.
- `workflows/`: reusable procedures.
- `decisions/`: important decisions.

验证清单

每接入一个工具，都做以下检查：

• Agent 能找到正确的 Obsidian 记忆根目录。
• Agent 只默认读取 AGENTS.md 和 INDEX.md。
• Agent 不会默认读取整个 vault 或 archive/。
• Agent 能读取 1 个相关记忆文件。
• Agent 能写入一条临时笔记。
• Agent 能读回临时笔记并确认一致。
• Agent 能删除临时笔记。
• Agent 不把 token、cookie、API key、密码或验证码写入笔记。
• Agent 在结束重要任务前会做 memory closeout。

常见问题

问题：Agent 每次都读太多文件。

处理：把 INDEX.md 写短，入口规则写得更硬：只读 AGENTS.md 和 INDEX.md，再按关键词读 1-3 个文件。

问题：记忆越来越像聊天记录。

处理：明确“不写流水账”。只保存长期偏好、稳定路径、验证结论、决策、工作流和 open loops。

问题：多个工具互相污染记忆。

处理：每个工具有自己的目录。跨工具共享内容写到明确的共享笔记，或者由用户指定同步。

问题：Obsidian 里出现意外标签。

处理：避免 # 紧跟文字。标题用 # 带空格；字面井号用反引号包裹。

问题：MCP 工具可见但调用超时。

处理：重启目标 app，开新会话再测。很多桌面 agent 会缓存旧 MCP runtime。

推荐维护节奏

• 每次重要任务结束：做 memory closeout。
• 每周：检查 TODO.md 和 agent/open-loops.md。
• 每月：整理 INDEX.md 的当前有效摘要。
• 发现过时记忆：先标注“已过时”，再决定是否归档。

一句话原则

Obsidian 外置大脑不是聊天记录仓库，而是 agent 可以快速读取、用户可以长期维护的可检查知识库。