189 lines
6.8 KiB
Markdown
189 lines
6.8 KiB
Markdown
---
|
||
categories:
|
||
- '[[LLM Wiki]]'
|
||
tags:
|
||
- wiki
|
||
- tool
|
||
- opencode
|
||
- memory
|
||
- automation
|
||
- 记忆系统
|
||
created: 2026-04-20
|
||
source: '[[AGENTS.md]]'
|
||
type: tool
|
||
aliases:
|
||
- opencode-mem
|
||
- 记忆系统
|
||
---
|
||
|
||
# opencode-mem 人机协同流程
|
||
|
||
> opencode-mem 是 opencode 的持久记忆插件（v2.13.0），使用 SQLite + USearch 向量数据库实现跨会话经验积累。
|
||
|
||
## 基本信息
|
||
|
||
| 属性 | 值 |
|
||
|
|
||
------|
|
||
-----|
|
||
| 仓库 | [tickernelz/opencode-mem](https://github.com/tickernelz/opencode-mem) |
|
||
| 版本 | 2.13.0 |
|
||
| 存储 | `~/.opencode-mem/data/memories.db` |
|
||
| Web UI | `http://127.0.0.1:4747` |
|
||
| 配置 | `~/.config/opencode/opencode-mem.jsonc` |
|
||
| 本项目 container_tag | `project_0f39be4f` |
|
||
|
||
## 三层记忆架构
|
||
|
||
opencode-mem 通过 `container_tag` 字段在单个 SQLite 数据库中实现三层隔离：
|
||
|
||
| 层级 | container_tag 前缀 | 作用域 | 示例 |
|
||
|------|-------------------|--------|------|
|
||
| **系统级** | `system_*` | 全局通用知识 | Git 操作、编程语言技巧 |
|
||
| **用户级** | `user_*` | 用户偏好和习惯 | 偏好中文输出、特定工作流 |
|
||
| **项目级** | `project_*` | 项目专属知识 | vault 架构、frontmatter 规范 |
|
||
|
||
container_tag 由项目路径的 MD5 哈希前 8 位生成，例如：
|
||
|
||
- `D:\Applications\app\kepano-obsidian-main` → `project_0f39be4f`
|
||
- `D:\TC_UP\2023card` → `project_7d38e4b1`
|
||
|
||
## 工作流程
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[用户通过 obsidian-opencode 发起对话] --> B[opencode-mem hook 自动触发]
|
||
B --> C[向量检索：在 memories.db 中查找相关记忆]
|
||
C --> D[注入 system prompt：agent 获得历史经验]
|
||
D --> E[agent 执行任务]
|
||
E --> F[对话结束]
|
||
F --> G[LLM 自动提取有价值信息]
|
||
G --> H[去重 + 存入 memories.db]
|
||
H --> I[下次对话时 C 步骤检索到新记忆]
|
||
```
|
||
|
||
### 1. 自动捕获（Auto Capture）
|
||
|
||
- 配置：`autoCaptureEnabled: true`
|
||
- 时机：每次对话结束后
|
||
- 流程：LLM 判断对话中哪些信息值得长期记住 → 提取 → 去重 → 存储
|
||
- 语言：`autoCaptureLanguage: "auto"`（自动检测）
|
||
|
||
### 2. 记忆注入（Memory Injection）
|
||
|
||
- 配置：`chatMessage.enabled: true`, `maxMemories: 10`
|
||
- 时机：每次对话开始时
|
||
- 流程：向量搜索与当前话题相关的记忆 → 注入 agent 的 system prompt
|
||
- 注入位置：`injectOn: "first"`（首次注入）
|
||
|
||
### 3. 用户画像（User Profile）
|
||
|
||
- 配置：`injectProfile: true`, `userProfileAnalysisInterval: 10`
|
||
- 作用：每 10 次对话自动分析用户偏好，生成/更新用户画像
|
||
- 画像会随记忆一起注入，让 agent 更了解用户习惯
|
||
|
||
### 4. 压缩合并（Compaction）
|
||
|
||
- 配置：`compaction.enabled: true`, `memoryLimit: 10`
|
||
- 触发：当记忆条数超过限制时
|
||
- 流程：LLM 自动合并相似条目，减少冗余
|
||
|
||
## 与其他记忆系统的关系
|
||
|
||
| 维度 | opencode-mem | AGENTS.md | WorkBuddy |
|
||
|------|-------------|-----------|-----------|
|
||
| **存储** | SQLite 向量数据库 | Markdown 文件 | Markdown 文件 |
|
||
| **检索** | 语义向量搜索 | 加载到上下文 | 文本 grep |
|
||
| **自动化** | Hook 自动捕获 | 手动维护 | TOML 定时任务 |
|
||
| **跨项目** | ✅ container_tag 隔离 | ✅ 仓库根目录 | ❌ 项目内独立 |
|
||
| **持久性** | ✅ 对话间持久 | ✅ 文件级持久 | ✅ 文件级持久 |
|
||
| **可见性** | Web UI（4747端口） | 直接编辑 | 直接编辑 |
|
||
| **适合内容** | 隐式经验、解决方案 | 显式规范、模板 | 任务状态、项目进度 |
|
||
|
||
> [!important] 核心原则
|
||
> **AGENTS.md = 显式规范**（所有人/agent 都能直接读）
|
||
> **opencode-mem = 隐式经验**（跨会话自动积累）
|
||
> 两者互补，不能互相替代。重要规范应同时写在 AGENTS.md 中。
|
||
|
||
## 人机协同分工
|
||
|
||
| 职责 | 人类 | opencode-mem（自动） | AGENTS.md（手动） |
|
||
|------|------|---------------------|-------------------|
|
||
| 制定规范 | ✅ 编写/审核 | — | ✅ 显式记录 |
|
||
| 积累经验 | — | ✅ 自动捕获 | — |
|
||
| 记忆维护 | ✅ Web UI 审查 | ✅ 自动去重/压缩 | ✅ 手动更新 |
|
||
| 纠错 | ✅ 删除/修改错误记忆 | — | ✅ 修正规范 |
|
||
| 质量保障 | ✅ 定期审查 | ✅ 向量去重 | ✅ Lint 检查 |
|
||
|
||
## 注意事项
|
||
|
||
> [!warning] 记忆质量需要人工审查
|
||
> 自动捕获可能产生低质量或过时记忆。建议每周通过 Web UI（`http://127.0.0.1:4747`）查看一次，删除不准确的内容。
|
||
|
||
> [!warning] 压缩可能丢失细节
|
||
> compaction 自动合并相似条目时可能丢失细节。重要规范务必同时写在 [[AGENTS.md]] 中。
|
||
|
||
> [!tip] 向量模型依赖
|
||
> 当前使用智谱 Embedding-3（1024维），依赖 `ZHIPUAI_API_KEY` 环境变量。如果 API key 过期，记忆检索会降级。
|
||
|
||
> [!tip] 项目迁移时需更新 container_tag
|
||
> 项目路径改变时，container_tag 会变化，需手动迁移记忆（参考本页「迁移记录」节）。
|
||
|
||
## 汇报规则
|
||
|
||
每次对话结束时，agent 必须简要汇报 opencode-mem 记忆更新情况：
|
||
|
||
- **有变更**：说明新增/修改/删除了哪些记忆
|
||
- **无变更**：说明"本次无记忆变更"
|
||
|
||
汇报示例：
|
||
|
||
> 📋 **opencode-mem 记忆汇报**：本次对话新增 1 条记忆（工具目录约定），修改 0 条，删除 0 条。
|
||
|
||
## 本项目当前记忆清单
|
||
|
||
| 记忆 ID | 类型 | 内容摘要 |
|
||
|---------|------|---------|
|
||
| `mem_*_d06fbcb2` | best_practice | MEMORY.md 精简经验：动态内容与长期规范分离 |
|
||
| `mem_*_fcb1713f` | knowledge_gap | 教育AI研究项目状态跟踪（待确认） |
|
||
| `mem_*_vault_structure` | best_practice | 双层架构：PARA 层 + LLM Wiki 层 |
|
||
| `mem_*_tools_convention` | best_practice | 工具文件统一存放 tools/ 目录 |
|
||
| `mem_*_obsidian_skills` | best_practice | Skills 优先级 + 布尔值 frontmatter 规则 |
|
||
| `mem_*_frontmatter_rules` | best_practice | Frontmatter 编写规范（created、wikilink、引号） |
|
||
|
||
## 配置参考
|
||
|
||
当前配置（`~/.config/opencode/opencode-mem.jsonc`）：
|
||
|
||
```jsonc
|
||
{
|
||
"storagePath": "C:\\Users\\hhhh2024\\.opencode-mem\\data",
|
||
"embeddingApiUrl": "https://open.bigmodel.cn/api/paas/v4",
|
||
"embeddingApiKey": "env://ZHIPUAI_API_KEY",
|
||
"embeddingModel": "embedding-3",
|
||
"embeddingDimensions": 1024,
|
||
"autoCaptureEnabled": true,
|
||
"autoCaptureLanguage": "auto",
|
||
"webServerEnabled": true,
|
||
"webServerPort": 4747,
|
||
"userProfileAnalysisInterval": 10,
|
||
"injectProfile": true,
|
||
"opencodeProvider": "zhipuai-coding-plan",
|
||
"opencodeModel": "glm-4.5-air",
|
||
"maxMemories": 10
|
||
}
|
||
```
|
||
|
||
## 相关页面
|
||
|
||
- [[AGENTS.md]] — 仓库级 agent 操作指南
|
||
- [[Obsidian-skills]] — Obsidian 插件生态
|
||
- [[教育AI研究项目]] — WorkBuddy 自动化项目
|
||
- [[opencode]] — opencode 工具本身
|
||
|
||
## 来源
|
||
|
||
- [[AGENTS.md]] — 仓库规范（含 opencode-mem 汇报规则）
|
||
- opencode-mem README — 插件官方文档
|
||
- 实际数据库分析 — `~/.opencode-mem/data/memories.db` 结构检查
|