---
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` 结构检查