From 190e700876339af5db2c4782a72f443c244052fe Mon Sep 17 00:00:00 2001 From: xiaowei Date: Sun, 31 May 2026 06:46:10 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20DESIGN.md=20?= =?UTF-8?q?=E2=80=94=20=E5=90=8C=E6=AD=A5=20v3.8=20=E5=AE=9E=E6=96=BD?= =?UTF-8?q?=E7=8A=B6=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Appendix E（统一记忆规划）→ 改为「v3.8 实施完成」状态 - 新增「原始会话 vs 语义记忆」澄清（Section 1.3） - 版本日志标记 v3.8/v3.9 已实施 - 状态改为「v3.8 部分实施」 - 原始会话各自存储路径（Hermes: ~/.hermes/sessions/, OpenClaw: ~/.openclaw/workspace/sessions/） --- DESIGN.md | 115 +++++++++++++++++++----------------------------------- 1 file changed, 41 insertions(+), 74 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 6d66728..f503185 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -5,7 +5,7 @@ > **代码生成工具**：opencode > **定位**：Hermes / OpenClaw / 未来 Agent 的统一记忆基础设施 > **修订日期**：2026-05-28 -> **状态**：方案锁定，待实施 +> **状态**：v3.8 部分实施（共享记忆层 ✅，其他规划中） --- @@ -122,6 +122,17 @@ L3: World Model — 系统运行环境的心智模型（ℰ/ℐ/C 三元组） **Agent 注册**：所有 Agent 首次连接织忆时必须调用 `POST /api/v1/agents/register`，系统自动分配 API Key、速率配额、WebSocket 端点，并加入 shared namespace 广播列表。 +**原始会话 vs 语义记忆（v3.8 实施澄清）**： + +| 数据层 | 存储位置 | 是否共享 | +|--------|---------|---------| +| 原始会话（JSONL） | Hermes: `~/.hermes/sessions/`
OpenClaw: `~/.openclaw/workspace/sessions/` | ❌ 各自独立 | +| 语义记忆（L1 蒸馏） | `/var/lib/memoryweave/memories.lance` | ✅ 共享（agent_id 区分） | +| 知识图谱 | `/var/lib/memoryweave/graph.db` | ✅ 共享（namespace 隔离） | +| 片段摘要（L0） | `/var/lib/memoryweave/episodes.lance` | ✅ 共享（agent_id 区分） | + +织忆是**语义记忆共享层**，不是行为日志聚合层。各 Agent 的原始会话由各自平台管理，织忆只负责从中提取、蒸馏、存储有价值的语义记忆。 + ## Part 2：存储与检索 @@ -1544,91 +1555,47 @@ trigger.max_consecutive_failures: 3 - **v3.5**：行业对标完成（评估框架+V值+三层语义去重+8类触发器+Skill+L3） - **v3.6**：缺口自动分类+记忆预取+溯源链 - **v3.7**：文档重组（24 章按功能域聚类，消除重复） -- **v3.8（当前）**：完整重写。知识图谱完整设计（5 节全 Schema+来源+算法+修剪+隔离）+ 5 个自动化流程 + Go↔Rust IPC + 被动验证 + 全部 API 端点 + WebSocket 事件类型 + 配置默认值 + 分阶段实施 + vLLM 部署细节 + Consolidation 完整设计。Go（API/业务）+ Rust（LanceDB/BGE/聚类/整合）。Python 完全移除 -- **v3.9**：统一记忆架构。Hermes（hermes-lance） + OpenClaw（openclaw lancedb） + 织忆（MemoryWeave SQLite）三系统统一为织忆后端，消除三方记忆孤岛。 +- **v3.8（当前，部分实施）**：完整重写。知识图谱完整设计（5 节全 Schema+来源+算法+修剪+隔离）+ 5 个自动化流程 + Go↔Rust IPC + 被动验证 + 全部 API 端点 + WebSocket 事件类型 + 配置默认值 + 分阶段实施 + vLLM 部署细节 + Consolidation 完整设计。Go（API/业务）+ Rust（LanceDB/BGE/聚类/整合）。**v3.8 共享记忆层已实施**（2026-05-28）：Hermes + OpenClaw 共用 `/var/lib/memoryweave/` LanceDB，原始会话分开存储。 +- **v3.9**：统一记忆架构 ~~待实施~~ → **已实施（共享层）**。Hermes（hermes-lance） + OpenClaw（openclaw lancedb） + 织忆（MemoryWeave SQLite）三系统统一为织忆后端，消除三方记忆孤岛。原始会话仍各自存储。 -### Appendix E: 统一记忆规划（v3.9） +### Appendix E: 统一记忆架构（v3.8 实施完成） -#### E.1 当前状态 +#### E.1 实施状态 -三个系统各自维护向量记忆： +✅ **已完成（2026-05-28）**：Hermes + OpenClaw 已统一接入织忆后端，共享语义记忆层。 -| 系统 | 后端 | 向量维度 | 数据位置 | -|------|------|---------|---------| -| Hermes | hermes-lance (LanceDB) | 1024 | `~/.hermes/data/lance/` | -| OpenClaw | openclaw lancedb (LanceDB) | 1024 | `~/.openclaw/data/lancedb/` | -| 织忆 | MemoryWeave SQLite + CGO | 1024 | `/var/lib/zhiyi/data/memoryweave.db` | - -问题： -- Hermes 和 OpenClaw 各自维护独立记忆，互不共享 -- 织忆无法直接读取 Hermes/OpenClaw 的记忆 -- 牧尘对 Hermes 说的话，OpenClaw 不知道 - -#### E.2 目标 - -**单一记忆源**：Hermes 和 OpenClaw 不再各自存储记忆，统一走织忆 API。 +#### E.2 当前架构 ``` -Hermes ──→ 织忆 Client (ZHIYI_URL=http://localhost:7821) ──→ MemoryWeave SQLite -OpenClaw ──→ 织忆 Client ────────────────────────────────→ (同一 DB) +┌─────────────────────────────────────────────────────────┐ +│ /var/lib/memoryweave/（共享） │ +│ memories.lance │ graph.db │ episodes.lance │ tombstones │ +│ ↑ ↑ ↑ ↑ │ +└────────┼──────────────┼───────────┼───────────────┼────────┘ + │ │ │ │ + agent_id= namespace agent_id= (软删除 + hermes-a06 shared openclaw 标记) + ↑ ↑ + Hermes Bridge OpenClaw Memory + ~/.hermes/plugins/ ZhiYi Plugin + zhiyi/ ~/.openclaw/workspace/ + plugins/memory-zhiyi/ ``` -#### E.3 实施步骤 +**原始会话（各自独立，不走织忆）：** +- Hermes: `~/.hermes/sessions/`（飞书消息 JSONL） +- OpenClaw: `~/.openclaw/workspace/sessions/`（代码任务 JSONL） -**Phase 1: 配置切换（零代码改动）** +#### E.3 agent_id 分布 -Hermes 和 OpenClaw 的 commit/recall 调用改走织忆： +| 系统 | agent_id | namespace | 路径 | +|------|----------|-----------|------| +| Hermes | `hermes-a06` | `""`（空） | `~/.hermes/sessions/` | +| OpenClaw | `openclaw` | `openclaw-main` | `~/.openclaw/workspace/sessions/` | -```yaml -# Hermes: ~/.hermes/config.yaml -memory: - provider: zhiyi - zhiyi_url: http://localhost:7821 - zhiyi_api_key: ${API_KEY} - fallback_to_local: true # 织忆不可用时回退到本地 hermes-lance -``` +#### E.4 回退策略 -```json -// OpenClaw: openclaw.json -{ - "memory": { - "backend": "zhiyi", - "zhiyi_url": "http://localhost:7821", - "api_key": "zhiyi-dev-key-2026" - } -} -``` - -**Phase 2: 双写迁移** - -织忆启动时扫描 Hermes/OpenClaw 现有数据并导入： - -```bash -zhiyid --migrate-hermes=/home/muc/.hermes/data/lance -zhiyid --migrate-openclaw=/home/muc/.openclaw/data/lancedb -``` - -迁移完成后，Hermes/OpenClaw 的本地记忆目录标记为只读备份。 - -**Phase 3: 移除本地存储** - -Hermes 和 OpenClaw 移除本地 LanceDB 依赖，纯客户端模式。织忆成为唯一记忆源。 - -#### E.4 API 兼容性 - -织忆已完全实现 Hermes/OpenClaw 原有接口的超集： - -| Hermes 接口 | 织忆接口 | 状态 | -|------------|---------|------| -| memory.save() | POST /api/v1/commit | ✅ | -| memory.search() | POST /api/v1/recall | ✅ | -| memory.delete() | DELETE /api/v1/distilled/{id} | ✅ | -| memory.bootstrap() | GET /api/v1/bootstrap | ✅ | -| memory.feedback() | POST /api/v1/feedback/* | ✅ | - -#### E.5 回退策略 - -织忆进程宕机时，Hermes/OpenClaw 自动回退到本地 LanceDB（`fallback_to_local: true`）。恢复后自动同步差异数据。 +若织忆宕机，Hermes/OpenClaw 各自使用本地缓存（fallback）继续运行。恢复后自动重新同步。 ---