# 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 ` | 查询某组件的依赖项 | | `lookup consumers ` | 查询反向依赖 | | `lookup related ` | 所有关联笔记（双向） | | `lookup type [project]` | 按类型查找笔记 | | `lookup layer [project]` | 按架构层级查找组件 | | `lookup files ` | 组件的关键文件 | | `lookup ` | 知识库全文搜索 | | `relate [type]` | 创建双向关系 | | `relate show ` | 显示某笔记的所有关系 | | `relate tree [depth]` | BFS 遍历依赖树 | 在 Claude Code 中，这些命令以 `/obs ` 形式调用。在其他智能体中，使用自然语言描述（例如"将会话摘要写入知识库"）。 ## 智能体兼容性 | 智能体 | 工作方式 | |---|---| | **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