# 织忆五步实施计划
> 创建时间：2026-05-30
> 状态：E1/E2/E3 已完成，E4-E5 规划中
> 禁止：偷懒、随意更改变动设计语言

---

## 总览

| 阶段 | 内容 | 优先级 | 预计工期 | 状态 |
|------|------|--------|---------|------|
| **E1** | 图谱导航激活 | 🔴 高 | 1-2 天 | ✅ 完成 |
| **E2** | 多 agent 命名空间激活 | 🔴 高 | 1 天 | ✅ 完成 |
| **E3** | 增量 embedding | 🟡 中 | 1 天 | ✅ 完成 |
| **E4** | 图谱推理 | 🟡 中 | 2-3 天 | ⏳ |
| **E5** | 产品 UI | 🔵 低 | 长期 | ⏳ |

---

## E1：图谱导航激活

### 目标
改造 `/recall` 链路，向量搜索后接图谱 BFS 扩展，让搜索结果融合结构化知识。

### 现状
- 图谱数据：1269 节点 / 31248 边（`graph/stats` 确认）
- `navigate.go` BFS 导航代码已写好，但 `/recall` 没调用
- `/recall` 当前纯语义搜索，不走图谱

### 实施步骤

#### E1.1 确认 navigate.go 接口
- 找到 `navigate.go` 的函数签名和参数
- 确认 BFS 扩展是 1 跳还是 2 跳
- 确认输出格式（节点列表还是边列表）

#### E1.2 改造 recall 链路
修改 `internal/api/routes/recall.go`：
```
语义搜索 → 向量 top-K →
图谱 BFS 扩展（navigate 1跳邻居）→
合并去重 → bge-reranker 重排 →
返回最终结果
```

#### E1.3 测试验证
```bash
# 验证图谱有数据
curl http://localhost:7821/api/v1/graph/stats

# 验证 recall 走图谱（找有图谱关联的记忆）
curl "http://localhost:7821/api/v1/recall?query=织忆图谱导航&top_k=5"

# 对比：图谱激活前 vs 激活后的召回结果差异
# 激活后应该出现更多 1 跳邻居相关结果
```

### 验收标准
- `graph/stats` node_count > 1000（已有，确认不变）
- recall 结果中包含图谱扩展内容（通过日志或响应标记确认）
- 延迟 < 500ms（可接受范围）

---

## E2：多 agent 命名空间激活

### 目标
Hermes 和 OpenClaw 使用独立 namespace，数据物理隔离，互不串味。

### 现状（2026-05-31 验证）
- ✅ Hermes：`agent_id="hermes-a06"` → `namespace="hermes-main"`（Go `deriveNamespace` 自动推导）
- ✅ OpenClaw：`agent_id="openclaw"`，`namespace="openclaw-main"`（zhiyi client 显式传递）
- ✅ Rust sidecar：`search()` / `scan_all()` 均有 `only_if("namespace = '{}'", ns)` namespace 过滤
- ✅ 验证：同一 query 在 hermes-main 和 default-main 返回不同 ID 的记忆，隔离生效
- ℹ️ 历史数据（`agent_id=default`）在 `default-main`，与 hermes-main/openclaw-main 物理隔离

### 实施步骤

#### E2.1 确认当前 namespace 配置（已验证）
- Hermes 插件：`agent_id="hermes-a06"` 硬编码于 `ZhiYiClient.commit/recall`（`~/.hermes/plugins/zhiyi/__init__.py`）
- OpenClaw 插件：`agent_id="openclaw"`, `namespace="openclaw-main"` 硬编码于 `ZhiYiClient`（`/persistent/.../memory-zhiyi/src/client.ts`）

#### E2.2 验收（2026-05-31 通过）
```bash
# Hermes recall → hermes-main
curl -X POST http://localhost:7821/api/v1/recall \
  -H "X-API-Key: zhiyi-dev-key-2026" \
  -d '{"query":"牧尘 小唯","top_k":3,"namespace":"hermes-main"}'
# → 返回 hermes-main 专属记忆

# OpenClaw recall → openclaw-main
curl -X POST http://localhost:7821/api/v1/recall \
  -H "X-API-Key: zhiyi-dev-key-2026" \
  -d '{"query":"牧尘 小唯","top_k":3,"namespace":"openclaw-main"}'
# → 返回 openclaw-main 专属记忆
```

### 验收标准
- [x] `namespace=hermes-main` 查询不到 `namespace=openclaw-main` 的记忆
- [x] `namespace=openclaw-main` 查询不到 `namespace=hermes-main` 的记忆
- [x] Rust sidecar 在 commit/recall 时正确使用 namespace 过滤

---

## E3：增量 embedding

### 目标
commit 时同步调用 vLLM embedding，不等 Rust sidecar batch，延迟从分钟级降到毫秒级。

### 现状（2026-05-31 验证）
- ✅ **已实现**：Go `core.go:79` 在 `Commit()` 中调用 `a.Embedder.EncodeSingle(req.Content)`
- ✅ **BGE HTTP**：连接 `localhost:8000/v1/embeddings`，17ms/条，L2 归一化
- ✅ **IPC 传输**：Go 将 vector + 文本一起发往 Rust `lancedb_insert`，Rust 直接存储（不重编码）
- ✅ **验证**：commit 后立即 recall 测试记忆排第一（score=0.843），无需等待 batch
- ℹ️ embedder.go 有 `MOLIFANG_API_KEY` fallback（当前未启用，环境无此 key）

### 实施步骤

#### E3.1 确认当前 embedding 流程（已验证）
- Go `core.go:79` → `a.Embedder.EncodeSingle(req.Content)` → BGE HTTP 8000 → 1024-dim vector
- Go `core.go:123` → `Vector: vector` 写入 `models.MemoryRecord`
- Go `core.go:129` → `a.LanceDB.InsertMemory(mem)` → IPC `lancedb_insert` 发送到 Rust
- Rust `lancedb_ops.rs:160-163` → 从 JSON 读取 vector，直接写入 LanceDB FixedSizeListArray

#### E3.2 验证结果（2026-05-31）
```bash
# commit 后立即 recall
curl -X POST http://localhost:7821/api/v1/commit \
  -H "X-API-Key: zhiyi-dev-key-2026" \
  -d '{"content":"E3增量embedding测试：验证commit时同步生成vector","namespace":"default-main"}'
# → memory_id: mem_1780211630617301197

curl -X POST http://localhost:7821/api/v1/recall \
  -H "X-API-Key: zhiyi-dev-key-2026" \
  -d '{"query":"E3增量embedding测试","top_k":3,"namespace":"default-main"}'
# → mem_1780211630617301197 排第一，score=0.843 ✅
```

### 验收标准
- [x] commit 响应包含 memory_id（写入成功）
- [x] commit 后立即 recall 能搜到（无需等待 Rust sidecar batch）
- [x] recall 得分 > 0.8（证明向量有效，非零向量）

---

## E4：图谱推理

### 目标
图谱真正参与推理：矛盾检测、跨 agent 共享、遗忘决策参考图谱结构。

### 现状
- 图谱存了 1269 节点/31248 边，只搜不用（2026-05-31 修复了 fmt.Printf debug）
- E4.1: Commit 路径已接入 ConflictDetector，检测率依赖 dedup 搜索覆盖
- E4.2: Recall 结果 < 3 时自动补充 shared namespace
- E4.3: Forgetter.ShouldForget 支持 graphDegree 可变参数

### 实施步骤

#### E4.1 矛盾检测（✅ 已实现，2026-05-31）

**实现位置**：
- `governance/governance.go`: `IsContradiction()` + `DetectContradiction()` 方法（导出供 routes 包调用）
- `routes/core.go:API`: 添加 `ConflictDetector` 字段，构造函数签名更新
- `server.go`: ConflictDetector 提到 NewAPI 之前创建（避免作用域错误）

**Commit 流程**：
```
Commit() → dedup 搜索 top-5 相似记忆
  → 3a: exact match → merge
  → 3b: near-dup (cos ≥ 0.98) → merge
  → 3c: 对其余相似记忆运行 DetectContradiction()
      → 有矛盾 → {"status":"ok","conflicts":["矛盾内容"]}
```

**限制**：依赖 dedup 搜索结果的覆盖率。语义相反的陈述在向量空间中未必是 top-5 最近邻。2026-05-31 修复了 `IsContradiction` 中文感知问题（原用 `strings.Fields` 对中文无效，改用 `unicode.Han` 字符级切分 + `containsNegCN` 否定词检测）。

#### E4.2 跨 agent 知识共享（✅ 已实现，2026-05-31）

**实现位置**：`routes/core.go:Recall()` — `pipeline.Recall()` 结果 < 3 时，补充 shared namespace 搜索

**流程**：
```
Pipeline.Recall(query, ns, limit) → len < 3 && ns != "shared"
  → EncodeSingle(query) → LanceDB.Search("memories", vec, 5, "shared")
  → 去重已出现在 own ns 的记忆 → 追加到 results，Score 降权 0.5
```

#### E4.3 遗忘决策参考图谱（✅ 已实现，2026-05-31）

**实现位置**：`governance/governance.go:ShouldForget()`

**逻辑**（向后兼容，不传 graphDegree 则行为不变）：
```go
// 节点度 > 5 时，每超 1 度 + 0.03 保留分
if len(graphDegree) > 0 && graphDegree[0] > 5 {
    score += float64(graphDegree[0]-5) * 0.03
}
```

**调用方待接入**：`routes/admin.go:71`、`server.go:904` — 需要在遗忘循环中查 GraphStore.GetEntityDegree() 注入 graphDegree 参数。

### 验收标准
- [x] E4.1: Commit 响应包含 `conflicts` 字段（如有矛盾）— ✅ 逻辑已接入
- [x] E4.2: Recall < 3 结果时自动补充 shared — ✅ 已实现
- [x] E4.3: ShouldForget 签名支持 graphDegree — ✅ 已实现，调用方待接

---

## E5：产品 UI（长期）

### 目标
给织忆做一个简单的可视化界面，用于查看记忆、图谱、搜索结果。

### 现状
- 只能 API 调，没有界面
- 个人用足够，但不方便查看图谱结构

### 实施步骤
待定，优先级最低。前 4 个阶段完成后再规划。

### 可能的方案
- 简单 Web UI（React + Go API）
- Obsidian 插件直接可视化
- CLI 增强（tree/graph 可视化）

---

## 阶段推进规则

1. **必须按顺序完成**：E1 → E2 → E3 → E4 → E5
2. **每个阶段必须测试验证后才能进入下一阶段**
3. **禁止跳过测试验证步骤**
4. **禁止偷懒：实施步骤必须逐条执行**
5. **禁止随意更改变动设计语言**：阶段目标和验收标准锁定
6. **如有阻塞，记录到 BLOCKED 章节，继续下一个阶段**

---

## BLOCKED（阻塞记录）

| 时间 | 阶段 | 阻塞原因 | 尝试方案 |
|------|------|---------|---------|
| - | - | 无阻塞 | - |

---

## 进度追踪

| 阶段 | 开始时间 | 完成时间 | 状态 |
|------|---------|---------|------|
| E1 图谱导航激活 | 2026-05-30 | 2026-05-30 | ✅ |
| E2 多 agent 命名空间 | 2026-05-30 | 2026-05-30 | ✅ |
| E3 增量 embedding | 2026-05-30 | 2026-05-30 | ✅ |
| E4 图谱推理 | 2026-05-31 | 2026-05-31 | ✅ E4.1/E4.2/E4.3 已实现，E4.3 调用方待接 graphDegree |
| E5 产品 UI | - | - | ⏳ |

---

*最后更新：2026-05-31*