memoryweave/REPAIR-FULL.md

织忆 v3.8 — 完整修复计划

版本：1.0 | 2026-05-30 设计文档：~/mc/小唯/07-Wiki/concepts/织忆(MemoryWeave)-v3.8-完整定稿.md 项目路径：~/projects/memoryweave/ 作战模式：我（规划+验收）→ opencode（执行）→ openclaw（UAT） 禁止偷懒，禁止更改设计语言，逐条对照设计方案实施

---

当前状态基线

Go/Rust 服务: zhiyid:7821 ✅ running | sidecar ✅ running | Redis ✅
Hermes 插件: ✅ memory_search/write/stats 全部可用
数据: 20 memories, 3 episodes, 82节点/135边
蒸馏: ✅ LLM 5维评估 + 实体提取
触发器: ✅ 8个全部激活
L3世界模型: ✅ 已填充
自优化指标: ⚠️ 全部为0 (无数据反馈)

---

Phase G1: Recall 管线完整化

目标：补齐 2.6 Recall 管线的缺失步骤，达到设计文档的 7 步完整链路 当前状态：只到 Step 3 (Rerank)，缺 MMR/多跳扩展/预取/WebSocket 优先级：⚠️ 高（recall 是整个系统的核心路径）

G1.1 MMR 多样性去重

设计依据：§2.6 Step 4 — MMR = (1-λ) × relevance + λ × (1 - max_sim_to_selected)，λ=0.5

项目	内容
文件	go/internal/storage/recall.go
改动	在 rerank 结果之后，添加 MMR 去重步骤
输入	rerank 后的 top-N 结果 (content + score)
输出	MMR 去重后的 top-K 结果
核心逻辑	mmrDiversify(results []Result, lambda float64) []Result
参数	mmr_diversity 从 config 读取，默认 0.5
引用的记忆	取 content 做 bge-m3 编码比较相似度；或简单版用 Jaccard 字符 bigram
边界	结果 ≤ 3 条时不触发 MMR（太少没必要）
验收	recall 返回的相邻结果 content 相似度 < 0.85

G1.2 多跳图谱扩展

设计依据：§2.5.4 — recall 结果 < 5 条时从结果出发做双向 BFS 扩展

项目	内容
文件	go/internal/api/routes/core.go + go/internal/storage/recall.go
改动	recall 返回结果 < 5 时，自动调用图谱 navigate 扩展
逻辑	取 recall 结果中的实体 → navigate 扩展 1 跳 → 去重 → 加入结果末尾
参数	max_hops=1（只扩展 1 跳，避免漂移），max_extra=3
触发	recall 结果 count < 5 且图谱有节点
边界	扩展结果质量不降级 — 标注为 "graph_expanded" 并排在原始结果之后
验收	搜索冷门实体时，返回图谱关联结果

G1.3 图谱导航双向 BFS

设计依据：§2.5.4 — POST /api/v1/graph/navigate 使用 source/target 参数

项目	内容
文件	go/internal/api/routes/graph.go
改动	新增 source/target 参数支持（不删 entity 兼容旧格式）
参数	{"source": "node-id", "target": "node-id", "max_hops": 3}
算法	双向 BFS：从 source 扩展 2 跳 + 从 target 扩展 1 跳 → 汇合
路径打分	Π(每个边的 weight)
旧兼容	entity 参数继续支持，内部转为 source=entity/target=""
验收	两个已知实体之间返回路径

G1.4 搜索缓存确认

设计依据：§2.6 — 搜索缓存 Redis TTL 1h

项目	内容
文件	go/internal/storage/searchcache.go
检查	确认 query hash → Redis GET/SET 逻辑正确
修复	如果 key 没设 TTL → 加 EXPIRE 3600
验收	相同 query 2次请求，第2次比第1次快 > 100ms

---

Phase G2: Embedding 本地化

目标：从模力方舟 API 切换到本地 vLLM，消除外网依赖 当前状态：BGE_ENDPOINT=https://ai.gitee.com/v1/embeddings 优先级：⚠️ 高（依赖外网，延迟高）

G2.1 下载 bge-m3 模型

设计依据：§2.3

# ModelScope 国内快
pip install modelscope
python -c "from modelscope.hub.snapshot_download import snapshot_download; \
  snapshot_download('BAAI/bge-m3', cache_dir='/home/muc/models/bge-m3')"

必须排除 onnx/ 子目录以节省空间：--exclude "imgs/**"

G2.2 部署本地 vLLM (port 8000)

设计依据：§2.3 — vLLM --task embed --dtype half --host 0.0.0.0 --port 8000

项目	内容
方式	systemd 管理 /etc/systemd/system/vllm-bge.service
二进制	/home/muc/.local/bin/python -m vllm.entrypoints.openai.api_server
参数	--model /home/muc/models/bge-m3 --task embed --dtype half --host 0.0.0.0 --port 8000
量化	half (float16)，RTX 3050 4GB 够用
验证	POST /v1/embeddings {"model":"bge-m3","input":["测试"]} → 返回 1024 维向量

G2.3 切换环境变量 + 验证一致性

项目	内容
改动	~/.hermes/.env 或 zhiyi 启动环境：BGE_ENDPOINT=http://127.0.0.1:8000/v1
一致性检查	用同一段文本分别请求模力方舟和本地 vLLM，cosine_sim ≥ 0.99
回滚方案	如果一致性 < 0.99，保持模力方舟，排查编码参数差异
验收	commit/recall 全部走本地 vLLM，响应时间 < 200ms

G2.4 更新 deploy/ 配置

设计依据：§7.4

• 创建 deploy/vllm-bge.service（如果不存在）
• 更新 deploy/nginx-zhiyi.conf（如果需代理）
• 更新 systemd 依赖：zhiyid.service After=vllm-bge.service

---

Phase G3: 治理闭环

目标：激活遗忘、冲突自动裁决、PassiveValidator、版本历史溯源 当前状态：全部代码存在但从未运行（0 次触发） 优先级：高

G3.1 遗忘策略激活

设计依据：§3.3.1

项目	内容
文件	go/internal/governance/governance.go + go/internal/scheduler/scheduler.go
当前	衰减扫描器 (t_decay 每 6h) 已在调度器注册，但 applyDecay 可能没加载实际数据
修复-1	确认 t_decay trigger 的 handler 调用 applyDecay() 时传入所有记忆列表
修复-2	applyDecay 的实现需读 LanceDB memories 表，按 category 分组应用不同 decay_rate
修复-3	淘汰工序按优先级执行，从 quality_score < 0.2 开始扫描
边界	tier=core 免疫衰减；volatile_flag=true 加倍
验收	GET /api/v1/metrics/self 中 deprecated_per_day > 0

G3.2 冲突自动裁决

设计依据：§3.3.2

项目	内容
文件	go/internal/api/routes/conflicts.go + go/internal/governance/governance.go
当前	冲突检测器 detectConflicts 在 OnDistillComplete 回调中接收空切片
修复-1	OnDistillComplete 加载当前 namespace 的实际记忆列表
修复-2	检测到冲突后，自动检查自动裁决条件（信任差异 >0.5 / 时间戳差 >90天 / 已裁决过同类冲突）
修复-3	可自动裁决 → 执行裁决 + 写入 version_history + 创建 CONFLICTS_WITH 边
修复-4	不可自动裁决 → 创建冲突记录等待人工裁决
验收	写入两条矛盾事实 → 自动创建冲突且 auto_resolve_rate > 0

G3.3 PassiveValidator 激活

设计依据：§3.3.4 — 三层匹配 (P1/P2/P3)

项目	内容
文件	go/internal/governance/governance.go
修改	确认每次 commit 后调用 passiveValidate
逻辑	检查当前 episode 内容与已有 distilled 的匹配度
验收	commit 后某些记忆的 quality_score 自动上升

G3.4 版本历史溯源

设计依据：§3.3.3 — version_history 字段 JSON 数组

项目	内容
文件	go/internal/storage/lancedb_ipc.go + go/internal/api/routes/core.go
当前	version_history 字段在所有记忆中都为空
修复-1	commit/feedback/correct 等修改操作时，检查是否有已有版本 → 追加 version_history 条目
修复-2	GET /api/v1/memory/{id}/versions 端点解析并返回 version_history
验收	修改一条记忆后，versions 端点返回 2 条历史

G3.5 衰减校准

设计依据：§3.3.1 衰减模型校准

项目	内容
文件	Rust sidecar rust/src/decay_calibrate.rs
当前	代码存在但从未执行（Rust sidecar 只被 consolidate.timer 触发，而 timer 条件不满足）
修复-1	确认 Rust sidecar 的 decay_calibrate 实现是否可单独调用
修复-2	改为 Go 端每周运行一次，或通过 IPC 触发 Rust 执行
验收	衰减率 decay_rate 按类别更新

---

Phase G4: 共现 + 预取 + WebSocket

目标：打通 CO_OCCURS 图谱 + 记忆预取 + WebSocket 8 种事件推送 当前状态：全部未实现 优先级：中高（依赖 G1 完成 recall 管线）

G4.1 CO_OCCURS 共现追踪

设计依据：§2.5.3 来源 2 + §6.7

项目	内容
文件	go/internal/storage/cooccur.go
当前	代码存在但 cocoour 模块没有任何触发器调用它
修复-1	每次 recall 后，取 top-5 结果 → 任意两条记录共现 → evidence_count+1
修复-2	CO_OCCURS 权重 = 共被recall次数 / min(A_recall_count, B_recall_count)
修复-3	权重 > 0.6 → 加入预取 map；< 0.3 且 14 天无更新 → 修剪
存储	知识图谱边，relation_type=CO_OCCURS

G4.2 记忆预取管道

设计依据：§6.7

项目	内容
位置	go/internal/storage/recall.go 或新文件 prefetch.go
逻辑	recall 完成后 → 查询 CO_OCCURS 权重 > 0.6 的记忆 → 放入预取队列
预取窗口	14 天
当前推送	先实现 HTTP 回调方式（WebSocket 后续推），即 recall 返回中带 prefecth 字段
验收	recall 结果中返回 prefetch 字段（非空时有相关内容）

G4.3 WebSocket 8 种事件推送

设计依据：§2.7 — 8 种事件类型

项目	内容
文件	go/internal/api/routes/ws.go + go/internal/api/routes/ws_events.go
当前	WS 端点存在 (/api/v1/ws/{agent_id})，返回 400 因为无 Agent 通过 WebSocket 连接
修复-1	确认 WS handler 实现完整（升级、读、写、心跳）
修复-2	实现 8 种事件的推送点和序列化
修复-3	实现事件队列（防止 Agent 掉线丢失事件）
事件列表	prefetch.push, gap.detected, gap.filled, memory.updated, conflict.detected, conflict.resolved, deep.consolidation.done, quality.drop
验收	测试程序通过 WebSocket 连接 → 触发事件 → 收到推送

---

Phase G5: 评估 + 金标 + V值

目标：评估框架可运行、金标集 12 维、V 值反向传播打通 当前状态：端点存在但 0 次运行 优先级：中（依赖数据积累 → 需要 Hermes 日常使用产生数据后才有意义）

G5.1 评估框架跑通

设计依据：§6.1

项目	内容
文件	go/internal/api/routes/eval.go
当前	POST /api/v1/eval/run 返回 400 "at least one query required"
修复-1	确认 eval/run 需要提交 query 列表才能执行
修复-2	先确保 eval/generate 能生成足够多的金标查询（当前只生成 2 条）
修复-3	执行 eval 时：对每个金标 query 执行 recall → 检查 expected_id 是否出现在结果中
指标	recall_at_5, precision_at_5, mean_reciprocal_rank
验收	eval/run 返回含 recall_at_5 等指标的完整报告

G5.2 金标集 12 维

设计依据：§6.1 — 4 类记忆 × 3 个难度等级 = 12 个查询

项目	内容
方式	POST /api/v1/eval/generate → LLM 从现有记忆生成
分类	system_fact / user_pref / proj_context / tool_usage
难度	简单（直接关键词）/ 中等（同义改写）/ 困难（推理需要），各 1 条
当前	只生成 2 条（因为记忆分类不全）
修复	增强 eval/generate 的 LLM prompt，确保覆盖 4 类×3 级 = 12 条
验收	generate 返回 12 条金标查询，每条含 query + expected_ids

G5.3 V 值反向传播

设计依据：§6.3

项目	内容
文件	go/internal/selfoptimize/vprop.go + go/internal/api/routes/core.go
当前	POST /api/v1/trace/vprop 返回 429
修复-1	确认 vprop 端点和 handler 实现
修复-2	V = α·R + (1-α)·γ·V_{t+1}，从最终结果反向传播到上游记忆
修-3	trace 存储 + 衰减管理
验收	写入 trace 后调用 vprop → 上游记忆 quality_score 变化

---

Phase G6: 聚类 + 蒸馏深化

目标：DBSCAN 聚类跑通、蒸馏质量回溯、缺口分类、L2 Patterns 层 优先级：中（依赖足够数据，约 100+ 条记忆后可运行）

G6.1 DBSCAN 聚类

设计依据：§3.1 深度整合 Step 1

项目	内容
文件	Rust sidecar rust/src/cluster.rs
当前	代码存在但从未被调用（consolidate.timer 条件不满足）
修复-1	t_consolidation 触发器应改为 Go 端直接触发 Rust 调用，而不是等 systemd timer
修复-2	通过 Unix Socket IPC 发送 ConsolidateRequest 触发 Rust 执行 DBSCAN
修复-3	DBSCAN eps/ min_points 参数：默认 eps=0.5, min_points=3（可调）
验收	聚类发现至少 1 个 cluster（当数据量足够时）

G6.2 蒸馏质量回溯

设计依据：§3.1 深度整合 Step 4

项目	内容
文件	Rust sidecar rust/src/quality_backtrace.rs
当前	代码存在但从未执行
修复	确认 Rust 实现可独立调用，或改为 Go 端直接 LLM 调用
抽样	分层 20 条（新鲜5/核心5/有用5/无用5）
方法	L0→LLM→L1→LLM→L0' → bge-m3 cosine(L0, L0') < 0.8 → 信息损失过大
验收	质量回溯报告生成

G6.3 知识缺口分类

设计依据：§3.2.2

项目	内容
文件	go/internal/api/routes/gaps.go + gap_repair.go + gap_full_repair.go
当前	GET /api/v1/gaps 返回 0 缺口（从未触发过检测）
修复-1	确认 t_gap trigger → handler 调用 detectGaps → 读取 recall miss 日志
修复-2	连续 3 次 miss → 执行分类：Type A (真未知) / B (同义词) / C (召回失败) / D (碎片化)
修复-3	Type B/C 自动修复 → 验证 → 关闭
边界	recall miss 的定义：recall 返回 0 条或最高分 < 0.3
验收	搜索不存在的主题 3 次 → GET /api/v1/gaps 返回 1 条缺口

G6.4 L2 Patterns 层

设计依据：§1.2 四层模型

项目	内容
当前	L2 完全不存在
实现	蒸馏 consolidation Step 3 "模式挖掘" 的输出 → 存为 category="pattern" 的记忆
触发	连续 3+ 条同类型蒸馏 → 提取 pattern → 写入 L2
验收	有 category="pattern" 的记忆条目

---

Phase G7: Skill + 自动化流程

目标：Skill 结晶 (Beta-Bernoulli)、5 个自动化流程端到端打通 优先级：低（依赖前面所有阶段完成）

G7.1 Skill 结晶

设计依据：§6.5

项目	内容
文件	go/internal/api/routes/skill_bayes.go + tuning.go
当前	POST /api/v1/skills/{name}/trial 返回 400
修复-1	确认 skill 注册 + trial 记录 + Beta-Bernoulli 更新逻辑
修复-2	资格评估：证据 ≥ 3 次有用反馈 + 无冲突
修复-3	η ≥ 0.8 → active, 0.5≤η<0.8 → probation, η<0.5 → retired
验收	创建 skill → 记录 3 次 trial → η 更新

G7.2 5 个自动化流程端到端

设计依据：§3.6

流程	当前状态	所需组件
流程1: commit→图谱	⚠️ 半成	需冲突自动裁决 + PassiveValidator
流程2: recall→反馈闭环	❌	需 CO_OCCURS + 预取 + Hermes 自动标记
流程3: 缺口→关闭	❌	需缺口分类引擎
流程4: 修正→级联审查	❌	需 DEPENDS_ON 追踪 + WebSocket
流程5: 深度整合	❌	需 DBSCAN + 质量回溯 + 衰减校准

实施策略： 每个流程单独验收，不追求一次全通。验收标准：手动触发该流程的所有步骤 → 观察各步骤按设计执行 → 仪表盘指标更新。

---

Phase G8: 基础设施加固

目标：备份、监控、反向代理、数据迁移 优先级：中（运维安全）

G8.1 备份自动化

设计依据：§4.3

项目	内容
备份目录	/backup/zhiyi/（不存在，需创建）
执行	POST /api/v1/admin/backup 端点存在（返回 200），但从未系统调用
操作	创建 systemd timer zhiyi-backup.timer 每天 3:00 触发
保留	最近 7 天每天 + 最近 4 周周日
格式	backup-{date}.tar.gz，含 LanceDB checkpoint + SQLite .backup + Redis BGSAVE
验收	/backup/zhiyi/ 存在备份文件

G8.2 Prometheus 告警

设计依据：§4.3

项目	内容
当前	deploy/prometheus-alerts.yml 存在但未加载
操作	检查 deploy/prometheus.yml 并部署 prometheus 服务
告警规则	> 5 冲突 / p99 > 2s / LLM 调用 > 85% 日限 / consolidate 3 次连续失败
验收	prometheus /metrics 端点可达，告警规则加载

G8.3 Nginx 反向代理

设计依据：§4.3

项目	内容
操作	部署 deploy/nginx-zhiyi.conf 到 nginx
路由	7821 不可直接访问，通过 nginx 代理（如果牧尘需要）
验收	通过 nginx 端口访问织忆正常工作

G8.4 FAISS → LanceDB 迁移

设计依据：Part 7 + 附录

项目	内容
当前	~/projects/zhiyi/data/ 下仍有旧 FAISS 数据（sbert_index.faiss 等）
操作	scripts/migrate_faiss_to_lance.go 执行迁移
迁移	读取 FAISS 索引 + sbert_docs.jsonl → 批量写入 LanceDB
验证	迁移后总数 vs 原 FAISS 数量一致，recall 部分抽样一致性
完成	旧数据目录归档，不删除

---

Phase G9: 集成拓展

优先级：低（功能完善后的增值项）

G9.1 Hermes 自动标记 (useful/not-useful)

设计依据：§5.1

项目	内容
位置	~/.hermes/plugins/zhiyi/__init__.py
逻辑	任务成功 → 标记 recall 结果为 useful；任务失败 → 分析根因 → 标记
验收	Hermes 完成任务后自动调用 feedback API

G9.2 Obsidian 双向同步

设计依据：§5.2

项目	内容
当前	carriers/shared/ 目录存在但为空
实现	Go 端 obsidian.go + obsidian_carrier.go 代码存在但未激活
操作	确认同步逻辑、触发条件、防止冲突覆盖
验收	carriers 目录有内容，Obsidian 能看到

G9.3 Go SDK + 多实例文档

• 确认 go/client/sdk.go 完整
• 多实例方案留作文档，暂不部署

---

执行顺序与依赖

G1 (Recall管线)  ← Hermes 日常使用数据量 → G3 (治理) ← → G4 (共现/WS)
     ↓                                      ↓
G2 (Embedding)                          G5 (评估/V值)
     ↓                                      ↓
G6 (聚类/蒸馏深化) ← 数据量 100+ ← G3+G5 数据反馈
     ↓
G7 (Skill + 自动化流程)
     ↓
G8 (基础设施) ← 可并行
G9 (集成)    ← 可并行

关键路径：G1 → G3 → G6 → G7（功能链） 非阻塞：G2（独立）、G8（运维、可并行）、G9（增值、可并行）

---

验收标准总表

Phase	验收指标	检查方式
G1	recall 结果含 MMR 去重 + 图谱扩展 + navigate 双向 BFS	API 测试
G2	本地 vLLM BGE 响应 < 200ms，cosine ≥ 0.99	端点测试 + 一致性测试
G3	self-metrics 的 deprecated_per_day > 0, auto_resolve_rate > 0	GET /metrics/self
G4	recall 返回含 prefetch 字段；WS 收到事件	端到端测试
G5	eval/run 返回完整 IR 报告；V值可传播	API 测试
G6	cluster 发现 ≥1；质量回溯报告；gap 分类 Type A/B/C/D	API + 日志
G7	skill η 更新；5 个流程可手动触发走通	端到端测试
G8	每日备份存在；prometheus 可访问；FAISS 迁移完成	文件检查 + curl
G9	Hermes 自动反馈；carriers 有内容	观察

---

失忆恢复锚点

如果 session 丢失，按以下顺序恢复：

1. 文件锚: ~/projects/memoryweave/REPAIR-FULL.md
2. 进度文件: ~/projects/memoryweave/IMPLEMENTATION.md（实时记录当前 Phase 和进度）
3. 记忆锚: memory_search("织忆 v3.8 修复计划 当前阶段")
4. 设计锚: ~/mc/小唯/07-Wiki/concepts/织忆(MemoryWeave)-v3.8-完整定稿.md
5. 状态锚: curl http://localhost:7821/api/v1/stats

---

计划版本 1.0。逐条对照设计文档 v3.8 制定。