Phase 0-2: Schema cleanup, typed relations, event-driven automation

- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
2026-07-01 08:05:43 +08:00
parent e544d6e04a
commit a6f05ab2d5
1067 changed files with 522992 additions and 819 deletions
@@ -0,0 +1,186 @@
+---
+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` 结构检查