12 KiB
12 KiB
Obsidian 持久化智能体记忆
智能体 Obsidian 知识库 记忆管理 Claude Code
obs-memory — 基于 Obsidian 的智能体持久记忆
通过 Obsidian 知识库，为你的编程智能体提供跨会话的持久记忆。
智能体在会话开始时自动定位上下文，通过图谱遍历导航项目架构，将发现写回知识库，并支持创建会话摘要、脚手架项目、搜索知识库内容以及管理组件关系等命令。
兼容所有支持 Agent Skills 规范的智能体 —— Claude Code、Cursor、Cline、Windsurf、GitHub Copilot 以及 35+ 更多。
功能特性
- 自动会话定向 — 会话开始时无需提示，自动读取 TODO 和项目概览
- CLI 优先的图谱遍历 — 优先使用 Obsidian CLI 读取属性、反向链接、链接、标签和搜索，而非直接读取文件
- 双向关系管理 —
relate命令管理depends-on/depended-on-by、extends/extended-by、implements/implemented-by、consumes/consumed-by，支持 BFS 树遍历 - 结构化查询 —
lookup子命令支持依赖项、消费者、关联笔记、类型/层级筛选、关键文件和全文搜索 - 自动行为 — 会话结束检测、组件发现提示、首次运行引导
- 项目分析 —
analyze命令扫描仓库，从 README、CLAUDE.md、ADR 和源码结构中提取内容填充知识库 - Token 优化 — 前置 frontmatter 扫描，优先 CLI 而非文件读取，范围化导航
安装
通过 skills.sh 安装（推荐）
npx skills add adamtylerlynch/obsidian-agent-memory-skills
安装后技能立即对智能体可用。
通过 Claude Code 插件安装（仅限 Claude Code）
git clone https://github.com/adamtylerlynch/obsidian-agent-memory-skills.git \
~/.claude/plugins/cache/obs-memory
# 或从本地目录创建符号链接
ln -s /path/to/obsidian-agent-memory-skills ~/.claude/plugins/cache/obs-memory
初始化知识库
安装完成后，让智能体初始化知识库：
Initialize my Obsidian memory vault
或在 Claude Code 中：
/obs init
或直接运行安装脚本：
./setup.sh ~/Documents/AgentMemory
此命令会创建具有所需结构、模板和 Obsidian 配置的知识库。若当前处于 git 仓库中，init 还会自动为当前项目生成脚手架。完成后，在 Obsidian 中打开知识库目录即可。
知识库路径配置
技能按以下优先级自动解析知识库路径：
OBSIDIAN_VAULT_PATH环境变量（最高优先级）- 从智能体配置中解析（查找 "Obsidian Knowledge Vault" 部分）
~/Documents/AgentMemory（默认值）
在 shell 配置文件中添加以下内容可设置环境变量：
export OBSIDIAN_VAULT_PATH="$HOME/Documents/AgentMemory"
内容说明
主动技能：obs-memory
当智能体检测到与知识库相关的上下文时自动加载，处理以下内容：
- 会话开始定向 — 读取 TODO 和项目概览（最多 2 个文件）
- 项目自动检测 — 将 git 仓库名与知识库项目进行匹配
- 图谱导航 — 按需跟踪 wikilinks，从不批量读取
- 知识写入 — 创建组件笔记、ADR、模式和领域知识
- 关系管理 — 使用 BFS 树遍历进行双向依赖跟踪
- Token 优化 — 前置 frontmatter 扫描，CLI 查询，范围化读取
自动行为
无需显式命令即可触发：
- 会话开始：自动从知识库定向（TODO + 项目概览）
- 会话结束信号：当你说"done"或"wrapping up"时，提示写入会话摘要
- 组件发现：当智能体深度分析一个未归档的组件时，提示创建知识库笔记
- 首次运行：引导完成
init并自动为当前项目生成脚手架
命令列表
| 命令 | 说明 |
|---|---|
init [path] |
从内置模板初始化新知识库 |
analyze |
分析当前项目并用填充内容更新知识库 |
recap |
根据 git 历史写入会话摘要，更新 TODO |
project [name] |
在知识库中创建新的（空）项目脚手架 |
note component [name] |
从模板创建组件笔记 |
note adr [title] |
创建架构决策记录 |
note pattern [name] |
创建模式笔记 |
todo [action] |
查看和更新项目 TODO |
lookup deps <name> |
查询某组件的依赖项 |
lookup consumers <name> |
查询反向依赖 |
lookup related <name> |
所有关联笔记（双向） |
lookup type <type> [project] |
按类型查找笔记 |
lookup layer <layer> [project] |
按架构层级查找组件 |
lookup files <component> |
组件的关键文件 |
lookup <freetext> |
知识库全文搜索 |
relate <source> <target> [type] |
创建双向关系 |
relate show <name> |
显示某笔记的所有关系 |
relate tree <name> [depth] |
BFS 遍历依赖树 |
在 Claude Code 中，这些命令以 /obs <command> 形式调用。在其他智能体中，使用自然语言描述（例如"将会话摘要写入知识库"）。
智能体兼容性
| 智能体 | 工作方式 |
|---|---|
| Claude Code | 完全支持 — 主动技能 + /obs 斜杠命令 |
| Cursor | 通过 skills.sh 加载技能，响应自然语言命令 |
| Cline | 通过 skills.sh 加载技能，响应自然语言命令 |
| Windsurf | 通过 skills.sh 加载技能，响应自然语言命令 |
| GitHub Copilot | 通过 skills.sh 加载技能，响应自然语言命令 |
| 其他 | 任何支持 Agent Skills 规范 的智能体 |
对于不支持 skills.sh 的智能体，可手动将 skills/obs-memory/SKILL.md 的内容添加到智能体的指令文件（如 .cursorrules、.windsurfrules、.clinerules）。
使用示例
自动定向（主动触发）
在任意项目目录中开始会话。如果该项目在知识库中有笔记，智能体会自动：
- 读取你的活跃 TODO
- 读取项目概览
- 获取架构、组件和模式的完整上下文
会话结束摘要
让智能体写入会话摘要（或在 Claude Code 中使用 /obs recap）。智能体会检查 git 日志和 diff，写入会话笔记并更新 TODO。
创建新项目脚手架
让智能体在知识库中创建项目（或在 Claude Code 中使用 /obs project my-app）。创建空白脚手架如下：
projects/my-app/
├── my-app.md # 项目概览（占位内容）
├── architecture/
├── components/
└── patterns/
分析项目
在 Claude Code 中运行 /obs analyze（或说"分析此项目并填充知识库"）。智能体扫描仓库中的 README、CLAUDE.md、包清单、ADR 和源码结构，然后写入填充好的知识库笔记：
projects/my-app/
├── my-app.md # 含架构、依赖、领域链接的完整概览
├── architecture/
│ └── ADR-0001 Use React Query.md # 从仓库导入
├── components/
│ ├── API Layer.md # 从源码结构提取
│ └── Auth Module.md
└── patterns/
├── Error Handling.md # 从 CLAUDE.md 约定提取
└── Testing Strategy.md
搜索知识库
让智能体搜索知识库（或在 Claude Code 中使用 /obs lookup PKCS12）。支持目标子命令：
/obs lookup deps AuthMiddleware # 它依赖什么？
/obs lookup consumers AuthMiddleware # 什么依赖它？
/obs lookup type component my-app # 项目中所有组件
/obs lookup layer api # 所有 API 层组件
管理关系
跟踪组件间的依赖关系（或在 Claude Code 中使用 /obs relate）：
/obs relate AuthMiddleware SessionStore # depends-on（默认）
/obs relate AuthMiddleware OAuth2Provider implements # implements 关系
/obs relate show AuthMiddleware # 查看所有关系
/obs relate tree AuthMiddleware 3 # 依赖树，深度 3
工作原理
┌─────────────────────────────────────────────────┐
│ 会话开始 │
│ 智能体读取：TODO → 项目概览 │
│ （2 个文件，约 100 行 — 最小 Token 消耗） │
├─────────────────────────────────────────────────┤
│ 工作过程中 │
│ 项目概览 ──链接──→ 组件笔记 │
│ │ │ │
│ └──链接──→ 模式 ──链接──→ 领域知识 │
│ 笔记 │
│ 智能体按需跟踪链接 │
├─────────────────────────────────────────────────┤
│ 会话结束 │
│ 智能体写入：会话摘要，更新 TODO， │
│ 创建/更新组件和模式笔记 │
└─────────────────────────────────────────────────┘
知识库结构
知识库初始化后的目录结构如下：
AgentMemory/
├── Home.md # 仪表盘
├── projects/
│ ├── Projects.md # 项目索引
│ └── {name}/
│ ├── {name}.md # 项目概览 — 智能体从这里开始
│ ├── architecture/ # ADR 和设计决策
│ ├── components/ # 各组件笔记
│ └── patterns/ # 项目专属模式
├── domains/
│ ├── Domains.md # 领域索引
│ └── {tech}/ # 跨项目知识
├── patterns/
│ └── Universal Patterns.md # 语言无关的通用模式
├── sessions/
│ └── Session Log.md # 会话时间线
├── todos/
│ └── Active TODOs.md # 当前工作项
├── templates/ # 笔记模板
│ ├── Project.md
│ ├── Component Note.md
│ ├── Session Note.md
│ └── Architecture Decision.md
└── inbox/ # 未整理内容
包内容
obsidian-agent-memory-skills/
├── .claude-plugin/
│ └── plugin.json # 插件元数据（Claude Code + skills.sh）
├── skills/
│ └── obs-memory/
│ └── SKILL.md # 智能体无关的技能定义（唯一可信来源）
├── commands/
│ └── obs.md # Claude Code 斜杠命令（/obs）
├── vault-template/ # 内置知识库模板
│ ├── Home.md
│ ├── projects/Projects.md
│ ├── domains/Domains.md
│ ├── patterns/Universal Patterns.md
│ ├── sessions/Session Log.md
│ ├── todos/Active TODOs.md
│ └── templates/
│ ├── Project.md
│ ├── Component Note.md
│ ├── Session Note.md
│ └── Architecture Decision.md
├── setup.sh # Shell 知识库安装脚本
└── examples/
└── populated-vault.md # 实际使用后的知识库示例
许可证
MIT