catalog/repos/adamtylerlynch--obsidian-agent-memory-skills.md

# 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