280 lines
12 KiB
Markdown
280 lines
12 KiB
Markdown
# Obsidian 持久化智能体记忆
|
||
|
||
`智能体` `Obsidian` `知识库` `记忆管理` `Claude Code`
|
||
|
||
# obs-memory — 基于 Obsidian 的智能体持久记忆
|
||
|
||
通过 [Obsidian](https://obsidian.md) 知识库，为你的编程智能体提供跨会话的持久记忆。
|
||
|
||
智能体在会话开始时自动定位上下文，通过图谱遍历导航项目架构，将发现写回知识库，并支持创建会话摘要、脚手架项目、搜索知识库内容以及管理组件关系等命令。
|
||
|
||
兼容所有支持 [Agent Skills](https://agentskills.io) 规范的**智能体** —— Claude Code、Cursor、Cline、Windsurf、GitHub Copilot 以及 [35+ 更多](https://agentskills.io/compatible-products)。
|
||
|
||
## 功能特性
|
||
|
||
- **自动会话定向** — 会话开始时无需提示，自动读取 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 安装（推荐）
|
||
|
||
```bash
|
||
npx skills add adamtylerlynch/obsidian-agent-memory-skills
|
||
```
|
||
|
||
安装后技能立即对智能体可用。
|
||
|
||
### 通过 Claude Code 插件安装（仅限 Claude Code）
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
或直接运行安装脚本：
|
||
|
||
```bash
|
||
./setup.sh ~/Documents/AgentMemory
|
||
```
|
||
|
||
此命令会创建具有所需结构、模板和 Obsidian 配置的知识库。若当前处于 git 仓库中，`init` 还会自动为当前项目生成脚手架。完成后，在 Obsidian 中打开知识库目录即可。
|
||
|
||
### 知识库路径配置
|
||
|
||
技能按以下优先级自动解析知识库路径：
|
||
|
||
1. `OBSIDIAN_VAULT_PATH` 环境变量（最高优先级）
|
||
2. 从智能体配置中解析（查找 "Obsidian Knowledge Vault" 部分）
|
||
3. `~/Documents/AgentMemory`（默认值）
|
||
|
||
在 shell 配置文件中添加以下内容可设置环境变量：
|
||
```bash
|
||
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 规范](https://agentskills.io/specification) 的智能体 |
|
||
|
||
对于不支持 skills.sh 的智能体，可手动将 `skills/obs-memory/SKILL.md` 的内容添加到智能体的指令文件（如 `.cursorrules`、`.windsurfrules`、`.clinerules`）。
|
||
|
||
## 使用示例
|
||
|
||
### 自动定向（主动触发）
|
||
|
||
在任意项目目录中开始会话。如果该项目在知识库中有笔记，智能体会自动：
|
||
1. 读取你的活跃 TODO
|
||
2. 读取项目概览
|
||
3. 获取架构、组件和模式的完整上下文
|
||
|
||
### 会话结束摘要
|
||
|
||
让智能体写入会话摘要（或在 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 |