62 KiB

Raw Blame History

织忆 (MemoryWeave) — 完整设计方案 v3.8

编程语言：Go + Rust（双二进制架构，详见 Part 7） 向量数据库：LanceDB（Rust lancedb crate 原生集成） 代码生成工具：opencode 定位：Hermes / OpenClaw / 未来 Agent 的统一记忆基础设施 修订日期：2026-05-28 状态：方案锁定，待实施

Part 1：基础
- 1.1 系统定位
- 1.2 四层记忆模型
- 1.3 Agent 记忆隔离
Part 2：存储与检索
- 2.1 存储架构（LanceDB + SQLite + Redis）
- 2.2 LanceDB Schema（memories / episodes / tombstones）
- 2.3 Embedding 升级（bge-m3 1024维，vLLM 本地部署）
- 2.4 Rerank 重排层（bge-reranker-v2-m3，API 细节）
- 2.5 知识图谱（节点/边 Schema、建图来源、多跳导航、修剪、Namespace 隔离）
- 2.6 Recall 完整链路（编码→ANN→重排→MMR→预取推送）
- 2.7 核心 API（全部端点 + WebSocket 事件类型）
Part 3：记忆生命周期
- 3.1 蒸馏引擎（硬规则 + LLM 评估 + 批量 + 成本控制）
- 3.2 自优化引擎
  - 3.2.1 记忆质量评分
  - 3.2.2 知识缺口自动分类
  - 3.2.3 自优化仪表盘（7 项指标）
- 3.3 治理机制
  - 3.3.1 遗忘策略（线性衰减 + 淘汰工序）
  - 3.3.2 冲突检测与解决（自动裁决 + 人工裁决）
  - 3.3.3 记忆溯源链（source + trigger + 信任加权 + volatile 检测）
- 3.4 知识图谱自动更新机制
- 3.5 被动验证机制（PassiveValidator）
- 3.6 自动化流程（5 个完整链路）
- 3.7 深度整合全生命周期
Part 4：部署
- 4.1 多实例与局域网
- 4.2 Go ↔ Rust IPC 设计
- 4.3 运维手册（备份/恢复/监控/限流/端口表）
Part 5：集成
- 5.1 Hermes/OpenClaw Bridge + Go Client SDK
- 5.2 Obsidian 双向同步
Part 6：竞争性架构
- 6.1 评估框架（IR 指标 + 12维金标集 + CI/CD 集成）
- 6.2 行业对标（织忆 vs MemOS 2.0 vs yantrikdb）
- 6.3 V 值反向传播
- 6.4 8 类条件触发器
- 6.5 Skill 结晶管道
- 6.6 L3 世界模型（ℰ/ℐ/C 三元组 + 更新机制）
- 6.7 记忆预取（CO_OCCURS 关系图谱 + WebSocket 推送）
Part 7：实施
- 7.1 Go + Rust 双二进制架构
- 7.2 Go 项目结构
- 7.3 Rust Consolidation Sidecar 结构
- 7.4 vLLM BGE 本地部署
- 7.5 分阶段实施计划（Phase A-H）
- 7.6 性能目标
- 7.7 风险与缓解
- 7.8 Unified Memory 规划（v3.9）
附录
- A. 已知限制
- B. 默认配置值
- C. 未验证思想
- D. 版本变更日志

Part 1：基础

1.1 系统定位

              织忆 (MemoryWeave) — port 7821
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
    Hermes       OpenClaw      未来 Agent
   (飞书对话)    (代码项目)    (任意)

织忆是记忆层，不是行为层。只负责存储、检索、蒸馏、共享和质量审核，不干预 Agent 行为决策。

做：存储/检索/蒸馏/冲突检测/遗忘/知识图谱/跨 Agent 共享/质量自优化。

不做：行为干预/任务调度/权限控制/Agent 决策。

织忆替代 Hermes 和 OpenClaw 各自的本地 lanceDB，成为跨系统的共享记忆层。Hermes/OpenClaw 通过 bridge 插件调用织忆 API，不再各自维护独立的向量存储。

1.2 四层记忆模型

L0: Episodes      — 原始对话日志，不可变（审计锚点）
L1: Distilled     — 蒸馏后的事实/决策/偏好（向量检索主层）
L2: Patterns      — 跨任务重复模式（聚类产出，含 L3 过渡形态）
L3: World Model   — 系统运行环境的心智模型（ℰ/ℐ/C 三元组）

衰减规则：L0 只归档不衰减。L1-L3 均可被修正和衰减。L3 由被动观察驱动更新（Agent 反馈），不是 LLM 凭空生成。

L1/L2 未来合并计划：v3.9 将 L1/L2 合并为 Unified Memory（type 字段区分 fact/pattern/template/preference/constraint/skill），降低蒸馏复杂度。

1.3 Agent 记忆隔离

层级	存储位置	示例
`shared`	跨 Agent 可见	牧尘偏好、系统事实（OS/RAM/GPU）、项目路径
`{agent}-main`	单 Agent 私密	Hermes 飞书修复记录、OpenClaw 代码审查详情
`{agent}-ephemeral`	会话级，关闭即清除	当前对话中间状态

跨 namespace 召回规则：默认只搜自己的 namespace + shared。显式指定 include_namespaces=["openclaw-main"] 时才跨域搜索。

共享范围的判断原则：

系统事实 → shared（所有 Agent 需要知道同一台机器的配置）
牧尘偏好 → shared（话少直接、结论先行，所有 Agent 都应遵循）
项目上下文 → shared（设计文档路径、技术栈决策）
Agent 内部修复记录 → 各自私密（Hermes 的飞书发图修复与 OpenClaw 无关）
代码审查/重构细节 → 各自私密

Agent 注册：所有 Agent 首次连接织忆时必须调用 POST /api/v1/agents/register，系统自动分配 API Key、速率配额、WebSocket 端点，并加入 shared namespace 广播列表。

Part 2：存储与检索

2.1 存储架构

LanceDB（主存储）：向量 + 元数据一体化
  ├── table: memories       ← 蒸馏后的记忆（1024维 bge-m3）
  ├── table: episodes       ← 原始对话日志（按天分区）
  └── table: tombstones     ← 软删除/淘汰记录

SQLite（图索引）：知识图谱节点和边
  └── 独立图结构，与 LanceDB 通过 memory_id 关联

Redis（运行时）：
  ├── 事件流（XADD/XREAD）  ← 跨实例同步
  ├── 心跳（TTL 30s）       ← 服务发现
  ├── 缓存（搜索缓存 TTL 1h）
  ├── 限流计数器（per-agent token bucket）
  └── 自优化指标存储（self_metrics:daily:{date}，90天）

为什么 LanceDB 替代 JSONL + FAISS：JSONL 无法高效向量检索（O(n) 扫描），FAISS 不支持多进程并发写入（单进程锁）。LanceDB 同时解决两者——向量 ANN 搜索（HNSW/PQ）+ 元数据过滤 + 原生多进程并发（基于 Lance 列式格式），并支持增量写入和版本管理。

2.2 LanceDB Schema

memories 表

pa.schema([
    ("id", pa.string()),              # UUID
    ("content", pa.string()),         # 记忆文本
    ("vector", pa.list_(pa.float32(), 1024)),  # bge-m3 L2归一化编码
    ("category", pa.string()),        # fact / decision / preference / constraint / pattern
    ("namespace", pa.string()),       # shared / hermes-main / openclaw-main
    ("agent_id", pa.string()),        # 写入方标识
    ("tier", pa.string()),            # normal / core
    ("importance", pa.float32()),     # 综合重要性：recency_factor × (1 + log(1+recall_count))
    ("quality_score", pa.float32()),  # useful / (useful + not_useful) — 自动维护
    ("freshness", pa.string()),       # fresh / stale / verified
    ("recall_count", pa.int32()),     # 被 recall 次数
    ("useful_count", pa.int32()),     # 被标记 useful 次数
    ("not_useful_count", pa.int32()), # 被标记 not-useful 次数
    ("version", pa.int32()),          # 修改版本号（初始=1）
    ("version_history", pa.string()), # JSON: [{version, content, updated_by, reason, source, trigger}]
    ("source", pa.string()),          # 信息来源：牧尘口头/牧尘飞书/配置解析/LLM蒸馏/Agent推断
    ("volatile_flag", pa.bool_()),    # 修正 ≥3次 → true → 衰减加倍
    ("timestamp", pa.string()),       # ISO 8601
    ("last_recalled_at", pa.string()),
    ("is_deleted", pa.bool_()),       # 软删除标记
    ("depends_on", pa.string()),      # JSON: 引用的其他 memory_id 列表（因果链追踪）
    ("derived_from", pa.string()),    # 蒸馏来源 episode id
])

importance 计算公式：

importance = recency_factor × (1 + log(1 + recall_count))
recency_factor = exp(-0.0077 × days_old)   # half-life = 90天

quality_score 自动维护：

quality_score = useful_count / (useful_count + not_useful_count)
  → > 0.7：权重不受影响
  → < 0.3 且总反馈 ≥5：自动降权（importance *= 0.5），通知 Agent "需审查"
  → 通知后 7 天仍未改善 → 自动 deprecated → 移入 tombstones

episodes 表

pa.schema([
    ("id", pa.string()),
    ("namespace", pa.string()),
    ("agent_id", pa.string()),
    ("content", pa.string()),         # 原始对话文本
    ("chunks", pa.string()),          # JSON: 分块后的对话段落
    ("timestamp", pa.string()),
    ("distilled_to", pa.string()),    # 关联的 distilled memory id（蒸馏完成后回填）
    ("distill_status", pa.string()),  # pending / processing / completed / skipped
])

tombstones 表

pa.schema([
    ("id", pa.string()),
    ("original_id", pa.string()),     # 被淘汰的 memory id
    ("content_snapshot", pa.string()),# 淘汰时的内容快照（供牧尘反查）
    ("namespace", pa.string()),
    ("reason", pa.string()),          # deprecated / quality_low / lru / merged
    ("merged_into", pa.string()),     # 如果是合并淘汰 → 目标 memory id
    ("deleted_at", pa.string()),
])

2.3 Embedding 升级（1024维）

模型选型

项目	旧（废弃）	当前
模型	moka-ai/m3e-base（768维）	bge-m3（1024维）
维度	768	1024
供应商	本地	模力方舟 API → 本地 vLLM
上下文	—	8k

vLLM 本地部署

Go 实施完成后部署。当前生产使用模力方舟 API。

# 模型下载（HuggingFace 格式，非 GGUF，Ollama 的 GGUF 不能复用）
# 方式1：HF 镜像
HF_ENDPOINT=https://hf-mirror.com hf download BAAI/bge-m3 \
  --local-dir /home/muc/models/bge-m3 \
  --exclude "imgs/**" "onnx/**"

# 方式2：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')"

# 启动 vLLM embedding endpoint（int8 量化，RTX 3050 4GB 够用）
python -m vllm.entrypoints.openai.api_server \
  --model /home/muc/models/bge-m3 \
  --task embed \
  --dtype half \
  --host 0.0.0.0 --port 8000

# systemd 管理
sudo tee /etc/systemd/system/vllm-bge.service << 'EOF'
[Unit]
Description=vLLM bge-m3 embedding server
After=network.target
[Service]
Type=simple
User=muc
ExecStart=/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
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now vllm-bge

API 调用

请求：

POST /v1/embeddings
{
  "model": "bge-m3",
  "input": ["文本内容"]
}

响应：

{
  "data": [{
    "embedding": [0.123, -0.456, ...],  // 1024维
    "index": 0,
    "object": "embedding"
  }],
  "model": "bge-m3",
  "usage": {"prompt_tokens": 5, "total_tokens": 5}
}

向量归一化：bge-m3 输出后 L2 归一化后存入 LanceDB（内积=余弦相似度）。

BGE 端点切换：修改环境变量 BGE_ENDPOINT 即可从模力方舟切换到本地 vLLM，API 格式完全兼容。

2.4 Rerank 重排层

模型选型

项目	说明
模型	bge-reranker-v2-m3
端点	`https://ai.gitee.com/v1/rerank`（模力方舟 API）
特点	支持中文重排，多语言优化
备选	jina-reranker-v2-base-en（模力方舟同时支持）

⚠️ vLLM 不支持 rerank 模型（交叉编码器），保持使用模力方舟 API。Python 代码中 jina_rerank.py 为历史遗留命名，实际调用 bge-reranker-v2-m3。Go 实现时命名为 bge_rerank.go。

API 调用

请求：

POST /v1/rerank
Authorization: Bearer ***
{
  "model": "bge-reranker-v2-m3",
  "query": "用户查询",
  "documents": ["文档1内容", "文档2内容", ...],
  "top_n": 10
}

响应：

{
  "results": [
    {"index": 3, "document": {"text": "文档4内容"}, "relevance_score": 0.997},
    {"index": 0, "document": {"text": "文档1内容"}, "relevance_score": 0.891}
  ],
  "usage": {"total_tokens": 150}
}

⚠️ 响应中 document 是对象 {"text": "..."} 不是字符串。Go 实现时需做类型兼容处理。

2.5 知识图谱

2.5.1 节点/边 Schema

-- 节点表
CREATE TABLE graph_nodes (
    id TEXT PRIMARY KEY,
    type TEXT NOT NULL,           -- entity / fact / decision / skill
    label TEXT NOT NULL,          -- 显示名
    namespace TEXT NOT NULL,      -- shared / hermes-main / openclaw-main
    properties TEXT,              -- JSON: 自定义属性
    pagerank REAL DEFAULT 1.0,   -- PageRank（每月深度整合时更新）
    created_at TEXT,
    last_updated_at TEXT
);

-- 边表
CREATE TABLE graph_edges (
    id TEXT PRIMARY KEY,
    source_id TEXT NOT NULL REFERENCES graph_nodes(id),
    target_id TEXT NOT NULL REFERENCES graph_nodes(id),
    relation_type TEXT NOT NULL,  -- DEPENDS_ON/REFERENCES/CONFLICTS_WITH/CO_OCCURS/DERIVED_FROM
    weight REAL DEFAULT 0.5,     -- 0.0-1.0（共访频率归一化 or 信任度）
    namespace TEXT NOT NULL,
    evidence_count INTEGER DEFAULT 1,  -- DEPENDS_ON支持证据数 / CO_OCCURS共现次数
    created_at TEXT
);

-- 多跳导航加速索引
CREATE INDEX idx_edges_source ON graph_edges(source_id);
CREATE INDEX idx_edges_target ON graph_edges(target_id);
CREATE INDEX idx_nodes_namespace ON graph_nodes(namespace);
CREATE INDEX idx_edges_namespace ON graph_edges(namespace);

2.5.2 关系类型

关系	语义	示例	触发条件
`DEPENDS_ON`	A 依赖 B（B变了A需审查）	部署步骤 → nginx配置	LLM蒸馏时判断/配置解析
`REFERENCES`	A 引用 B（B变了A可保留）	设计文档 → 技术选型说明	LLM蒸馏时判断
`CONFLICTS_WITH`	A 和 B 矛盾	Hermes说端口3000, OpenClaw说8080	冲突检测自动创建
`CO_OCCURS`	A 和 B 常一起被 recall	Docker → docker-compose	recall后自动统计
`DERIVED_FROM`	A 从 B 蒸馏生成	L1条目 → L0 episode	蒸馏完成自动创建

2.5.3 建图来源

来源 1：蒸馏时实体抽取

distill → LLM 提取 entities + facts → 遍历实体：
  entity 已存在？→ 更新属性 + 创建 REFERENCES 边
  entity 不存在？→ 创建 graph_nodes 新记录
  fact 引用多个 entity？→ 创建 DEPENDS_ON 边

来源 2：recall 共访统计

每次 recall 后，记录 top-5 结果中任意两条的共现：
  CO_OCCURS 权重 = 共被recall次数 / min(A_recall_count, B_recall_count)
  权重 > 0.6 → 加入 pre-fetch map → 见 6.7 记忆预取
  权重 < 0.3 且 14天无新增共现 → 降为 0 → 下次修剪删除

来源 3：冲突检测

扫描到矛盾 → 自动创建 CONFLICTS_WITH 边（weight = 矛盾检出置信度）
冲突解决后 7 天 → 降为 weight=0，归档

来源 4：蒸馏追溯

每个 L1 条目 → 自动创建 DERIVED_FROM 边指回 L0 episode
用于蒸馏质量回溯：L0 → L1 方向追踪信息损失

2.5.4 多跳导航算法

输入：起始节点 ID、目标节点 ID、最大跳数=3
算法：双向 BFS
  - 从 source 扩展 2 跳（正向）
  - 从 target 扩展 1 跳（反向）
  - 在中间节点汇合 → 取 weight 乘积最高的路径
路径打分 = Π(每个边的 weight)

输出：路径列表（按 score 降序，最多 3 条）

API：POST /api/v1/graph/navigate
  Request:  {"source": "node-xxx", "target": "node-yyy", "max_hops": 3}
  Response: {"paths": [{"nodes": [...], "edges": [...], "score": 0.82}]}

使用场景：

recall 结果少时：从 recall 命中的记忆出发，多跳扩展找相关记忆
因果追溯：从一条被修正的记忆出发，找到所有 DEPENDS_ON 它的记忆
上下文扩展：当前任务涉及某 entity 时，导航找关联 entity

2.5.5 修剪策略

每月深度整合时执行：

策略	条件	动作
孤立节点删除	14 天无任何边且 type ≠ skill	删除（不是 core 记忆，只是图索引节点）
低权重边删除	weight < 0.15 且 evidence_count=1 且 30 天	删除
冗余边合并	A→B 存在多条同类型边	保留 evidence_count 最高的，累加证据数
CONFLICTS_WITH 归档	冲突解决后 7 天	weight=0，保留 30 天用于审计，之后删除
PageRank 更新	每次修剪后	全部节点重新计算，用于全局重要性基准

2.5.6 Namespace 隔离

shared-graph          ← shared namespace 的所有实体和边
hermes-main-graph     ← Hermes 私有的实体和边
openclaw-main-graph   ← OpenClaw 私有的实体和边

跨域边规则：
  若 hermes entity → DEPENDS_ON → shared entity
    → 边存入 hermes-main-graph（边的 namespace = 源节点 namespace）
  shared 内的公共实体 → 存入 shared-graph

recall 时默认从 Agent 自己的图 + shared-graph 联合查询。

2.6 Recall 完整链路

query 进入
  ↓
1. bge-m3 编码（L2归一化，1024维）
  ↓
2. LanceDB ANN 搜索（通过 namespace 过滤，top_k=50，HNSW 索引）
  ↓
3. bge-reranker-v2-m3 重排（取粗排 top-50 → 重排 → top_n=10）
  ↓
4. MMR 多样性去重（diversity=0.5）
     MMR = (1-λ) × relevance + λ × (1 - max_sim_to_selected)
     λ=0.5 平衡相关性与多样性
  ↓
5. 知识图谱多跳扩展（如果结果 < 5 条，双向 BFS 扩展 1 跳）
  ↓
6. 记忆预取（查询 CO_OCCURS 权重 > 0.6 的配套记忆）
     → 通过 WebSocket 主动推送（Agent 不等待）
  ↓
7. 返回 top-10 结果 + 预取推送 + 时间戳 + 来源标注

搜索缓存：相同 query hash → 检查 Redis（TTL 1h）→ 命中直接返回 → 未命中走完整链路。

MMR 参数说明：

diversity=0.0：纯相关性排序
diversity=0.5（推荐）：平衡
diversity=1.0：最大多样性

2.7 核心 API

REST 端点

分类	方法	路径	功能
记忆写入	POST	`/api/v1/commit`	提交记忆 → 队列 → 蒸馏
	POST	`/api/v1/batch-commit`	批量提交
记忆召回	POST	`/api/v1/recall`	混合检索 → 预取推送
	GET	`/api/v1/bootstrap`	冷启动引导（~10 条核心事实）
	GET	`/api/v1/gaps`	知识缺口列表
知识图谱	GET	`/api/v1/graph/stats`	节点数、边数、密度
	POST	`/api/v1/graph/query`	Cypher-like 查询
	POST	`/api/v1/graph/navigate`	多跳导航
冲突管理	GET	`/api/v1/conflicts`	待解决冲突列表
	POST	`/api/v1/conflicts/resolve`	裁决冲突
反馈	POST	`/api/v1/feedback/useful`	标记记忆有用
	POST	`/api/v1/feedback/not-useful`	标记记忆无用
	POST	`/api/v1/feedback/deprecate`	标记过时
	POST	`/api/v1/feedback/correct`	提交修正
管理	DELETE	`/api/v1/distilled/{id}`	软删除
	GET	`/api/v1/memory/{id}/versions`	版本历史
	POST	`/api/v1/admin/forget`	触发遗忘策略
	POST	`/api/v1/admin/backup`	原子备份
	GET	`/api/v1/admin/audit`	审计日志
评估	POST	`/api/v1/eval/run`	运行评估
	GET	`/api/v1/eval/history`	历史评估趋势
	POST	`/api/v1/eval/generate`	生成金标查询集
系统	GET	`/health`	健康检查（无需认证）
	GET	`/api/v1/stats`	记忆/蒸馏/队列统计
	GET	`/api/v1/metrics/self`	自优化仪表盘 7 项指标
	GET	`/metrics`	Prometheus 端点
触发器	GET	`/api/v1/triggers`	活跃触发器状态（urgency 降序）
Skill	GET	`/api/v1/skills`	已结晶 Skill 列表
	POST	`/api/v1/skills/{name}/trial`	记录 trial，更新 η
L3	GET	`/api/v1/l3/worldmodel`	当前 World Model
Agent	POST	`/api/v1/agents/register`	注册（分配 key + quota + WS endpoint）
WebSocket	WS	`/api/v1/ws/{agent_id}`	实时推送

所有业务 API 需 X-API-Key 认证（从环境变量 API_KEY 读取）。/health 豁免。

Rate Limiting

per-agent 令牌桶（Redis 存储）：
  hermes-main:    recall 10 QPS, commit 2 QPS, burst 20/5
  openclaw-main:  recall 10 QPS, commit 2 QPS, burst 20/5
  cron-job:       recall 5 QPS,  commit 1 QPS, burst 10/3
  其他:            recall 5 QPS,  commit 1 QPS, burst 10/3

超限 → 429 Too Many Requests
  Retry-After: <seconds>
  X-RateLimit-Reset: <unix_timestamp>

WebSocket 事件类型

事件	触发条件	Payload
`prefetch.push`	recall 时 CO_OCCURS > 0.6	`{memories: [{id, content, score}]}`
`gap.detected`	连续 3 次 recall miss	`{query, gap_type, suggestion}`
`gap.filled`	缺口被关闭	`{query, filled_count}`
`memory.updated`	DEPENDS_ON 的记忆被修正	`{memory_id, new_version, reason}`
`conflict.detected`	新冲突	`{conflict_id, entity, entries}`
`conflict.resolved`	冲突被裁决	`{conflict_id, resolution}`
`deep.consolidation.done`	深度整合完成	`{report: {clusters_found, pruned,...}}`
`quality.drop`	quality_score < 0.3	`{memory_id, score, suggestion}`

Part 3：记忆生命周期

3.1 蒸馏引擎

两阶段蒸馏

在线蒸馏（每次 commit 触发）：
  rules.go → 硬规则过滤：
    1. 无用户消息 → 跳过
    2. 闲聊/纯知识问答 → 跳过
    3. 内容密度 < 0.3 → 跳过
    4. 任务状态为 skipped/error → 跳过
  → LLM 5维度评估：
    IS (Information Significance)   权重 0.20
    SU (Strategic Utility)         权重 0.20
    PA (Practical Applicability)   权重 0.15
    VD (Validation Durability)     权重 0.25
    RU (Recall Usability)          权重 0.20
  → overall > 0.7 或 VD > 0.8 → 进入 distill queue
  → 队列满 10 条或距最后一次蒸馏 > 5 分钟 → 批量蒸馏
  → 写回 LanceDB + 更新知识图谱

深度整合（条件触发，每天最多一次）：
  触发条件：(新增蒸馏 > 50 且 距上次 > 24h) 或 (距上次 > 48h)
  → DBSCAN 聚类 → 发现新主题和重复模式
  → 知识图谱修剪
  → 衰减模型校准
  → 蒸馏质量回溯
  → 自优化报告生成

成本控制

每日 LLM 蒸馏上限：50 次（主 API 共享额度，Embedding 不计入）
超限降级：跳过 LLM 蒸馏，仅硬规则提取
每周日深度整合：额外 20 次额度
紧急蒸馏（牧尘明确说"记住这个"）：不受限额控制

Consolidation 流水线

每次蒸馏后自动执行：

Step 1: 合并相似记忆（向量相似度 > 0.8 → 保留最新，旧版标记 deprecated）
Step 2: 扫描冲突（同 entity 的矛盾关系）
Step 3: 模式挖掘（连续 3+ 条同类型记忆 → 提取 pattern）
Step 4: 知识图谱更新（实体抽取 + 关系创建）

3.2 自优化引擎

3.2.1 记忆质量评分（Outcome Feedback）

机制：Agent 使用 recall 结果完成任务后 → 自动调用 /api/v1/feedback/useful 或 /not-useful。

quality_score = useful_count / (useful_count + not_useful_count)

动作矩阵：
  score > 0.7 且 总反馈 ≥ 5 → 健康
  score < 0.3 且 总反馈 ≥ 5 → 自动降权（importance *= 0.5）+ 通知 Agent
  通知后 7 天未改善 → 自动 deprecated → 移入 tombstones

Hermes 自动标记逻辑（Hermes Bridge 插件内置）：

任务成功 → 标记所有使用的 recall 结果为 useful
任务失败 → 分析根因 → 若根因与某条 recall 记忆相关 → 标记 not-useful

3.2.2 知识缺口自动分类

Agent 连续 3 次对同一主题 recall 返回 0 条结果 → 触发分类：

1. 与已知记忆向量比较：
   sim > 0.85 且 category 相近 → Type C（召回失败）
      自动调整 top_k + diversity → 自动重试
   sim > 0.75 但 entity 名称不同 → Type B（同义词不匹配）
      自动创建同义词映射 → 重建索引
   max sim < 0.3（全聚类 centroid） → Type A（真未知）
      创建学习任务 → WebSocket 推送 Agent

2. 高层级检查：
   多个 L1 记忆各自部分覆盖 → Type D（碎片化）
      触发整合 → 蒸馏引擎合并

自动路由：
  Type B/C → 自动修复 → 验证 → 关闭 → 更新仪表盘
  Type A/D → WebSocket 推送 → 等人工处理 → 关闭 → 更新仪表盘

缺口闭环率 = 已关闭缺口 / 总检测缺口（目标 → 100%）

3.2.3 自优化仪表盘（7 项指标）

GET /api/v1/metrics/self — 系统自用的质量面板，不是运维面板。

指标	健康值	告警	动作
召回有用率	> 0.7	连续 7 天下降	检查 not_useful 共性 → 自动降权 → 通知牧尘
召回命中率	> 0.8	< 0.5	审查 Embedding/Rerank 管线
缺口闭环率	→ 100%	连续 14 天 = 0	审查缺口分类准确性 → 通知牧尘
修正传播率	> 0.5	—	因果链影响面大 → 追溯审查
垃圾淘汰速度	2-5/天	> 20（异常）或 = 0（遗忘失败）	自动暂停遗忘 → 通知牧尘
蒸馏信息损失率	< 0.15	> 0.3	自动重蒸馏受影响批次
冲突自动裁决率	趋势↑	—	—

数据存储：Redis Hash self_metrics:daily:{date}，每 6 小时更新，保留 90 天趋势。

3.3 治理机制

3.3.1 遗忘策略

线性衰减：score = max(0.1, 1.0 - days × decay_rate)

decay_rate 按记忆类别分层（数据驱动，每月重新拟合）：
  system_fact:  0.003/天  (half-life ≈ 333天，系统信息变化慢)
  user_pref:    0.005/天  (half-life ≈ 200天)
  proj_context: 0.008/天  (half-life ≈ 125天，项目迭代快)
  tool_usage:   0.010/天  (half-life ≈ 100天)
  code_snippet: 0.012/天  (half-life ≈ 83天，代码变更频繁)

豁免：tier=core → 免疫衰减
volatile: volatile_flag=true → decay_rate × 2
freshness=stale → 被 recall 时标注 "⚠️ 可能已过时"

淘汰工序（按优先级）：
  1. quality_score < 0.2 且 ≥ 5 次反馈 → 自动 deprecated → tombstones
  2. 牧尘标记 deprecated → tombstones
  3. 容量 > 10000 → LRU 淘汰（最低 recall_count）
  4. freshness=stale 且 180 天无 recall → importance=0.1
  5. CPU/内存空闲时扫描 → 同上规则批量处理

衰减模型校准（每月深度整合时运行）：

抽样最近 N 条 recall 日志
按记忆类别分组
对数线性回归拟合实际衰减曲线 → 更新 decay_rate
安全约束：新值不得超过旧值 ±50%

3.3.2 冲突检测与解决

检测：每次 commit 的新蒸馏 → 与同 namespace 已有记录比较。

检查类型：
  1. 实体关系冲突：同一 entity，关系目标不同 → ask_user
  2. 事实矛盾：Jaccard < 0.3 且语义方向相反 → ask_user
  3. 重要性冲突：不同 Agent 标记重要性差异 → latest_wins

自动裁决（不触发 ask_user）：
  来源信任度差异 > 0.5 → 自动选可信源
  时间戳差 > 90 天 → latest_wins
  已裁决过同类型冲突且有可信度画像 → 自动裁决
  来源相同且 timestamp 更接近 → latest_wins

冲突解决策略表：

策略	适用场景	说明
`ask_user`	无自动仲裁依据	提交给牧尘裁决（默认）
`latest_wins`	时间戳差 > 90天	最新优先
`primary_wins`	主实例优先	primary 实例记录优先
`keep_both`	不矛盾但不等同	保留双方，标记为"潜在相关"
`auto_merge`	安全合并	当且仅当可安全合并时

3.3.3 记忆溯源链

每条记忆的 version_history 字段记录：

[
  {
    "version": 1,
    "content": "ComfyUI 端口: 8188",
    "updated_by": "hermes-a06",
    "source": "牧尘口头",
    "trigger": "none",
    "reason": "初始记录",
    "timestamp": "2026-05-01T10:00:00Z"
  },
  {
    "version": 2,
    "content": "ComfyUI 端口: 8189",
    "updated_by": "hermes-a06",
    "source": "配置解析",
    "trigger": "端口冲突检测",
    "reason": "8188 被 ComfyUI 默认保留端口占用，实际使用 8189",
    "timestamp": "2026-05-15T14:00:00Z"
  }
]

来源信任加权（用于冲突自动裁决）：

牧尘口头 = 1.0    牧尘飞书 = 0.95
配置解析 = 0.7    Agent推断 = 0.5
LLM蒸馏 = 0.4（有幻觉风险）

volatile 检测：同一条记忆修正 ≥ 3 次 → volatile_flag = true → decay_rate × 2。在响应中标注 "⚠️ 此信息频繁变更，触发原因: {triggers}"

3.3.4 被动验证机制（PassiveValidator）

目的：Agent 在对话中自然引用记忆 → 自动提升该记忆的 confidence，不需要牧尘主动操作。

三层匹配（每次 commit 时检查当前 episode 与已有 distilled）：

P1: Entity/Fact 精确匹配
    当前 episode 的 entity/fact 与 distilled 有交集 → +0.15, 立即验证

P2: 关键词 substring 匹配
    共享 ≥2 个有意义的中文 n-gram 或英文 word → +0.15, 立即验证

P3: Content Overlap Coefficient
    字符级 bigram tokens 求交集/最小值
    ≥0.25 → +0.15, 立即
    ≥0.12 → Redis 计数器+1, 累积3次 → +0.10

confidence 上限: 1.0

3.4 知识图谱自动更新机制

蒸馏完成 → 实体抽取 → 遍历实体：
  entity 已存在？→ 更新属性 + 创建/更新 REFERENCES 边
  entity 不存在？→ 创建 graph_nodes 新记录 + DERIVED_FROM 边

fact 类型 = decision：
  检查引用的 entity 之间的 DEPENDS_ON 关系
  LLM 判断或配置解析发现依赖 → 创建 DEPENDS_ON 边

扫描与现有 fact 的冲突：
  有 → 创建 CONFLICTS_WITH 边
  无 → 完成

召回后 CO_OCCURS 统计：
  A 和 B 同时出现在 top-5 → evidence_count+1
  权重 = 共被recall次数 / min(A_recall_count, B_recall_count)

3.5 自动化流程（5 个完整链路）

流程 1：新记忆 → 知识图谱（commit 触发，全自动）

commit → 蒸馏队列 → 批量蒸馏完成
  → 写回 LanceDB
  → 同时：
      1. 实体抽取 → 图谱节点/边创建/修改
      2. 冲突检测 → 比较同 namespace 已有记录
      3. 被动验证 → 检查当前 episode 是否引用已有记忆
  → 无冲突 → 完成
  → 有冲突 → 检查溯源信任度 → 可自动裁决 → 自动裁决
           → 不可自动裁决 → WebSocket 推送牧尘

流程 2：recall → 反馈闭环（Agent 使用触发，全自动）

Agent recall → 返回 top-10
  → 同时查 CO_OCCURS 权重 > 0.6 → WebSocket 推送预取
  → Agent 使用结果解决问题
  → Hermes Bridge 自动判断 useful/not-useful → 调用反馈 API
  → 更新 quality_score + recall_count + last_recalled_at
  → 更新 CO_OCCURS 共访统计

流程 3：知识缺口 → 关闭（自动 + 人工混动）

Agent 连续 3 次 recall 0 结果 → 标记为知识缺口
  → 分类引擎运行：与已知记忆向量比较
  → Type B/C → 自动修复 → 验证（再次 recall）→ 关闭
  → Type A → WebSocket 推："检测到知识缺口: <topic>"
         → 牧尘提供信息 → 蒸馏 → 填缺口 → 关闭
  → Type D → 碎片化整合 → 蒸馏合并 → 关闭
  → 闭环节点：仪表盘更新成功率

流程 4：记忆修正 → 级联审查（修正 API 触发，全自动）

L1 记忆被修正 → version+1
  → 查询知识图谱：所有 DEPENDS_ON 指向此记忆的边
  → 遍历依赖方，标记 freshness = "stale"
  → 添加 version_history 备注修正原因
  → WebSocket 推送依赖此记忆的 Agent：
     "⚠️ 记忆 <id> 已修改（原因: <reason>）。请审查您基于旧版本的决策。"
  → 不自动修改 → Agent 确认后各自更新

流程 5：深度整合全生命周期（条件触发，自动）

触发：(新增蒸馏 > 50 且 距上次 > 24h) 或 (距上次 > 48h)

Step 1: DBSCAN 聚类（Rust linfa）→ 发现新主题和重复模式
Step 2: 图谱修剪（孤立节点/低权重边/冗余边合并/PageRank更新）
Step 3: 衰减校准（~20 个样本 → 按类别对数线性回归 → 更新 decay_rate）
Step 4: 蒸馏质量回溯（20 个分层样本 → L1→L0 重建 → bge-m3 cosine）
         score < 0.7 → 重蒸馏
         检出幻觉 → 暂停蒸馏 + 通知牧尘
Step 5: 自优化报告（7 项指标 + 退化检测 → WebSocket 推送）

任何步骤失败 → 跳过 → 下次重试
3 次连续同一步骤失败 → 停用该步骤 + 通知牧尘

质量回溯方法：

L0 episode → LLM 蒸馏 → L1 distilled → LLM 反向还原 → L0'
→ bge-m3 cosine(L0, L0') → < 0.8 → 信息损失过大

抽样策略：分层抽样，20 条（新鲜5 / 核心5 / 有用5 / 无用5）。

Part 4：部署

4.1 多实例与局域网

主力机（Deepin 25, RTX 3050, 16GB RAM）：
  ├── zhiyid（Go daemon, port 7821）— primary（读写+蒸馏+深度整合+评估）
  ├── zhiyi-consolidate（Rust binary, systemd oneshot+timer）
  ├── Redis（事件总线 + 缓存 + 限流）
  ├── vLLM BGE（port 8000）
  └── Hermes / OpenClaw / Cron Jobs

局域网其他机器：
  └── zhiyid（Go daemon）— replica（只读，本地 LanceDB 缓存）
      └── 通过 HTTP 调用 primary 的 /recall
          不运行蒸馏或深度整合

同步机制：

Primary commit → 写入本地 LanceDB → XADD Redis Streams "zhiyi:events"
所有 Replica → XREAD "zhiyi:events" → CRDT merge → 更新本地 LanceDB

心跳：每个实例每 10 秒 → Redis SET zhiyi:heartbeat:{instance_id} EX 30
故障检测：30 秒无心跳 → 标记为 DOWN → 从 Nginx upstream 摘除

4.2 Go ↔ Rust IPC 设计

zhiyid (Go daemon, port 7821) ←─→ zhiyi-consolidate (Rust binary)
         Unix Socket (/tmp/zhiyi-ipc.sock)
         Protocol: Protobuf + length-prefixed framing

消息定义：
  message ConsolidateRequest {
    string task = 1;           // "full" | "cluster_only" | "prune_only"
    string lancedb_path = 2;   // ~/projects/zhiyi/data/zhiyi_memory.lance
    string sqlite_path = 3;    // ~/projects/zhiyi/data/graph.db
    int32 llm_budget = 4;      // 本次深度整合可用 LLM 次数
  }

  message ConsolidateResponse {
    string status = 1;         // "ok" | "partial_failure"
    string report_json = 2;    // 5 步结果 + 指标
    string failure_step = 3;   // 如果 partial → 步骤名
    string error_detail = 4;   // 错误详情
  }

zhiyid 中：
  Rust binary 路径：/usr/local/bin/zhiyi-consolidate
  启动参数：--socket /tmp/zhiyi-ipc.sock --lancedb-path ~/projects/zhiyi/data
  超时：10 分钟（深度整合 5 分钟 + 缓冲）
  失败：不重试 → 下次 cron 周期再触发
  Rust binary 不存在/超时/crash → 跳过 → API 继续运行

4.3 运维手册

备份

每天 3:00 cron → POST /api/v1/admin/backup
  → LanceDB checkpoint（Lance 格式版本快照）
  → SQLite .backup
  → Redis BGSAVE

保留策略：最近 7 天每天 + 最近 4 周周日
路径：/backup/zhiyi/backup-{date}.tar.gz

灾难恢复

sudo systemctl stop zhiyid
tar xzf /backup/zhiyi/backup-2026-05-28.tar.gz -C ~/projects/zhiyi/data/
sudo systemctl start zhiyid
curl http://localhost:7821/health      # 验证
curl http://localhost:7821/api/v1/stats # 确认数量

监控（Prometheus `/metrics` 端点）

zhiyi_uptime_seconds
zhiyi_request_duration_seconds{endpoint,quantile}
zhiyi_distill_queue_depth
zhiyi_conflicts_pending
zhiyi_lancedb_vector_count
zhiyi_distill_llm_calls_today
zhiyi_consolidate_last_duration_seconds

告警规则：

队列 > 50 → 🟡 蒸馏积压
冲突 > 5 → 🟡 需审查
p99 > 2s → 🟡 recall 变慢
LLM 调用 > 许限额 85% → 🟡 接近日限
consolidate 连续 3 次失败 → 🔴

端口注册表

端口	服务
3000	new-api（已占用）
6379	Redis（已占用）
7821	织忆主端口（所有 API + WebSocket）
8000	vLLM BGE
8188	ComfyUI（已占用）
8644	Hermes webhook（已占用）

原则：织忆只用 7821，不开其他端口。

Part 5：集成

5.1 Hermes/OpenClaw Bridge

Hermes Agent
    ↓ memory_search → POST /api/v1/recall
    ↓ memory_write  → POST /api/v1/commit
hermes-zhiyi-bridge（Go plugin，~200 行）
    ↓ REST / WebSocket → 织忆 port 7821

Hermes 自动标记 useful/not-useful：

任务成功 → 标记使用的 recall 结果为 useful
任务失败且根因归于某条 recall 记忆 → 标记 not-useful
WebSocket 监听：缺口推送、记忆变更通知、深度整合完成

Go Client SDK（所有 Agent 共享）：

type ZhiYiClient struct {
    baseURL string
    apiKey  string
    wsConn  *websocket.Conn
    mu      sync.RWMutex
}

func NewZhiYiClient(baseURL, apiKey string) *ZhiYiClient
func (c *ZhiYiClient) Commit(content, category, namespace string) (*CommitResponse, error)
func (c *ZhiYiClient) BatchCommit(entries []CommitEntry) (*BatchResponse, error)
func (c *ZhiYiClient) Recall(query string, opts RecallOptions) (*RecallResponse, error)
func (c *ZhiYiClient) FeedbackUseful(memoryID string) error
func (c *ZhiYiClient) FeedbackNotUseful(memoryID string, reason string) error
func (c *ZhiYiClient) FeedbackCorrect(memoryID, newContent, reason string) error
func (c *ZhiYiClient) ListenEvents(ctx context.Context) <-chan WSEvent
func (c *ZhiYiClient) RegisterAgent(agentID, agentType, namespace string) (*RegisterResponse, error)

5.2 Obsidian 双向同步

织忆 carriers/ 目录（~/projects/zhiyi/data/{namespace}/carriers/）
  ├── self-model.md       # 自我认知
  ├── decision-log.md     # 决策记录
  ├── glossary.md         # 术语表
  ├── context.md          # 当前上下文
  ├── tasks.md            # 任务状态
  ├── progress.md         # 进度追踪
  ├── resources.md        # 资源清单
  ├── learnings.md        # 学习成果
  └── relationships.md    # 关系图谱

同步规则：

织忆 → Obsidian：重要决策自动 append（不覆盖历史）
Obsidian → 织忆：牧尘手动编辑 → recall 时将 Obsidian 内容纳入上下文
手动编辑优先 → 织忆检测到 file mtime 变化 → 不自动覆盖

接入时机：Go 实施完成后，carriers/ 目录稳定。

Part 6：竞争性架构

6.1 评估框架

端点：POST /api/v1/eval/run

// Response: EvalReport
{
  "recall_at_5": 0.82,      // 12 个金标查询集的平均值
  "precision_at_5": 0.76,
  "mean_reciprocal_rank": 0.88,

  "recall_at_5_by_tag": {
    "system_fact": 0.92,
    "user_pref": 0.85,
    "proj_context": 0.78,
    "tool_usage": 0.74
  },

  "recall_by_agent": {
    "hermes": 0.84,
    "openclaw": 0.79
  },

  "query_details": [
    {
      "query": "牧尘用什么系统？",
      "expected_ids": ["mem-001"],
      "hits": ["mem-001"],
      "misses": [],
      "recall_at_5": 1.0,
      "precision_at_5": 0.8
    }
  ],

  "consolidation_aware_hits": {
    "total_distilled_used": 45,
    "hits_after_consolidation": 41,
    "consolidation_benefit": 0.09  // 整合后新发现 9% 的命中
  }
}

金标查询集生成：POST /api/v1/eval/generate — LLM 从现有记忆生成，4 类记忆 × 3 个难度等级 = 12 个查询。含预期结果 ID。

CI/CD 集成：每次部署自动运行评估 → 对比上次结果 → 退化则告警。

合成数据测试：LLM 生成已知答案的虚拟对话 → 蒸馏 → 召回 → 验证答案是否仍可检索。

6.2 行业对标

维度	织忆 v3.8	MemOS 2.0	yantrikdb
评估框架	✅ IR指标+12维金标+合成数据	✅ 基准测试分数	✅ eval/harness.py
V值反向传播	✅ Go原生 Trace 追踪	✅ Reflect2Evolve	❌
知识图谱	✅ 双向BFS+PageRank+Namespace	⚠️ 无子图导航	⚠️ 无图结构
语义去重	✅ 三层：哈希→向量→替换类别	⚠️ 缺少替换类别检测	✅ 替换类别完整
Skill结晶	✅ Beta-Bernoulli η	✅ 完整管道	❌
L3世界模型	✅ ℰ/ℐ/C三元组+被动观察	✅ 世界模型+技能	❌
缺口分类	✅ 4类自动分诊+自动修复路由	❌	❌
条件触发器	✅ 8类+冷却+kill-switch	❌	✅ 8类（无冷却）
记忆预取	✅ CO_OCCURS图谱+WS推送	❌	❌
溯源链+信任加权	✅ source+trigger+volatile	❌	❌
多Agent隔离	✅ 三层namespace	✅ namespace	❌
双进程高效架构	✅ Go API + Rust 引擎	—	✅ Rust + Python
实现语言	Go + Rust	TypeScript	Rust + Python

6.3 V 值反向传播

追踪决策链路的价值传导——Agent 做出决策 D → 产生结果 R → 上游贡献记忆回传价值。

V_t(Trace_i) = α · R + (1 - α) · γ · V_{t+1}(Trace_i)

R   = 净收益（每个 useful +1，每个 not-useful -0.5，通过时间衰减加权求和）
α   = 1 / (总有用反馈 + 1)（自适应折扣因子 → 反馈越多 discount 越小）
γ   = 0.95（长期折扣因子）

API：POST /api/v1/trace/vprop
  {"trace_id": "t-xxx", "reward": 0.8}

衰减：V 值 90 天未更新 → 指数衰减（half-life=30天）

6.4 8 类条件触发器

触发器	条件	冷却	动作
`distill`	队列 ≥ 10 或 5 分钟无蒸馏	1 分钟	批量蒸馏
`merge`	向量相似度 > 0.8	10 分钟	合并相似记忆
`prune`	距上次 > 24h	24 小时	图谱修剪
`decay`	—	6 小时	扫描衰减
`回溯`	新增 > 50 蒸馏	24 小时	蒸馏质量回溯
`conflict`	写入同 entity	1 分钟	冲突检测
`gap`	连续 3 次 miss	30 分钟	缺口分类
`consolidation`	新增 > 50 蒸馏或距上次 > 48h	48 小时	深度整合

每个触发器带 kill-switch（POST /api/v1/admin/triggers/{name}/pause）和 urgency 排序（GET /api/v1/triggers 返回 urgency desc）。

连续 3 次失败 → 自动停用 + WebSocket 通知牧尘。

6.5 Skill 结晶管道

L2 模式（pattern）+ 3 次以上验证通过
  ↓
资格评估：
  - 证据 ≥ 3 次有用反馈（即 3 次独立 trial 成功）
  - 无 pending 冲突标记
  - pattern 未标记 deprecated
  ↓ 通过
Skill 结晶：memory_type = "skill"
  ↓
验证期（12 个月）：
  - 每次 trial 记录 → POST /api/v1/skills/{name}/trial {success: bool}
  - η 按 Beta-Bernoulli 更新（alpha = prior + successes, beta = prior + failures）
  - η = alpha / (alpha + beta)（后验成功率）
  ↓
生命周期管理：
  η ≥ 0.8 → active（自动推荐 + 用于自动裁决）
  0.5 ≤ η < 0.8 → probation（可用但标注不确定性）
  η < 0.5 → retired（降级为普通 pattern）

12 个月后停止活跃追踪，仅按需评估。

6.6 L3 世界模型（ℰ/ℐ/C 三元组）

ℰ (Entities)：系统环境的所有实体
  - 硬件：RTX 3050 (4GB VRAM), 16GB RAM, Deepin 25, 192.168.123.12
  - 软件：Hermes v0.13.0, OpenClaw, ComfyUI, new-api (port 3000)
  - 人员：牧尘

ℐ (Interactions)：实体间的交互关系
  - hermes → DEPENDS_ON → openclaw (织忆共享)
  - comfyui → LISTENS_ON → port 8188
  - new-api → PROVIDES → LLM models

C (Constraints)：硬约束和软规则
  - 模型不超 3050 VRAM（硬）
  - 新服务不用 3000/6379/7821/8000/8188/8644 端口（硬）
  - 牧尘讨厌废话（软）
  - 能 opencode 的不手工写代码（软）

更新机制：

蒸馏时 → LLM 提取新 ℰ/ℐ → 与现有比较 → 有变化则更新
配置解析 → C 自动更新（ComfyUI 端口变更 → 更新约束）
牧尘反馈 → C 更新（"不要用端口 xxxx" → 硬约束）
WebSocket 推送 → 所有 Agent 收到 worldmodel.updated 事件

6.7 记忆预取

利用 CO_OCCURS 关系图谱，在 Agent 召回时提前推送常配套使用的记忆。

Agent recall "Docker" 
  → LanceDB 返回 Docker 相关记忆
  → 查询 CO_OCCURS：Docker → docker-compose (0.82), nginx (0.71), 端口 (0.65)
  → 0.82, 0.71, 0.65 都 > 0.6 → WebSocket 推送这三条
  → Agent 可能在需要 Docker 信息的相同上下文中需要这些

预取窗口：14 天
权重阈值：> 0.6（约 60% 的概率一起被使用）
权重计算：共被recall次数 / min(A_recall_count, B_recall_count)
< 0.3 → 14 天窗口期后自动丢弃

Part 7：实施

7.1 Go + Rust 双二进制架构

┌──────────────────────────────────────────┐
│ zhiyid (Go 二进制, port 7821) — daemon  │
│ ├── HTTP API + 中间件（认证/限流/CORS）   │
│ ├── WebSocket（事件推送）                │
│ ├── Redis（事件流+缓存+心跳+限流计数器）  │
│ ├── 蒸馏引擎（硬规则+LLM调用+质量控制）   │
│ ├── 治理（遗忘/冲突/溯源）               │
│ ├── 评估、Skill、L3                     │
│ └── 调用 zhiyi-consolidate 进行深度整合  │
└──────────────┬───────────────────────────┘
               │ Unix Socket + Protobuf
               ▼
┌──────────────────────────────────────────┐
│ zhiyi-consolidate (Rust 二进制)         │
│           systemd oneshot + timer       │
│ ├── LanceDB 原生读写（lancedb crate）    │
│ ├── BGE 编码管线（Candle/ort）           │
│ ├── Rerank 管线（Candle/ort）            │
│ ├── DBSCAN 聚类（linfa crate）           │
│ ├── 衰减校准（statrs 对数线性回归）      │
│ ├── 图谱修剪（SQLite via rusqlite）      │
│ └── LLM 蒸馏质量回溯（reqwest HTTP）     │
└──────────────────────────────────────────┘

为什么 Rust 而非 Python？

LanceDB 是 Rust 原生（lancedb crate 零 FFI 开销，Go 绑定需要 CGo 桥接）
整合引擎是计算密集型（聚类/回归），Rust 比 Python 快 10-50x
两个静态二进制 vs venv+pip+torch → 运维简化
Candle/ort 的推理不需要 Python/CUDA 依赖

7.2 实际项目结构（v3.8 实现）

路径：~/projects/memoryweave/（设计阶段使用 zhiyi-go/zhiyi-rust 作为独立仓库名，实现时统一为 monorepo）

~/projects/memoryweave/
├── DESIGN.md                   # 本设计文档
├── IMPLEMENTATION.md           # 实施日志
├── BENCHMARK.md                # 性能基准
├── README.md
├── VERSION
├── Makefile
├── .github/workflows/ci.yml
├── go/                         # Go API 核心（独立模块）
│   ├── go.mod / go.sum
│   ├── integration_test.go
│   ├── cmd/zhiyid/main.go      # 入口
│   ├── client/sdk.go           # Go SDK（所有 Agent 共用）
│   ├── proto/consolidate.proto # Protobuf 定义
│   └── internal/
│       ├── api/
│       │   ├── server.go           # HTTP/WS 服务器
│       │   ├── middleware/
│       │   │   └── auth.go         # X-API-Key 认证 + per-agent 令牌桶
│       │   └── routes/
│       │       ├── core.go         # 核心：commit / recall / bootstrap
│       │       ├── health.go       # /health 端点
│       │       ├── conflicts.go    # 冲突检测与解析
│       │       ├── feedback.go     # 用户反馈（4 种操作）
│       │       ├── admin.go        # 管理端点 + metrics
│       │       ├── graph.go        # 知识图谱查询
│       │       ├── eval.go         # 评估接口
│       │       ├── triggers.go     # 8 个自优化触发器
│       │       ├── gaps.go + gap_repair.go + gap_full_repair.go  # 缺口检测与修复
│       │       ├── agent.go        # Agent 注册管理
│       │       ├── l3.go           # L3 世界模型
│       │       ├── ws.go + ws_events.go  # WebSocket 推送
│       │       ├── ipc.go          # IPC 触发展示
│       │       ├── consolidate.go  # 单条 consolidation 请求
│       │       ├── consolidation_pipe.go + auto_distill.go + cascade.go  # 蒸馏管线
│       │       ├── skill_bayes.go / tuning.go   # 技能贝叶斯 / 参数自调整
│       │       ├── obsidian.go + obsidian_carrier.go  # Obsidian 集成
│       │       └── client.go       # 客户端工具
│       ├── storage/
│       │   ├── lancedb.go + lancedb_ipc.go  # LanceDB（通过 Rust sidecar IPC）
│       │   ├── sqlite.go           # SQLite 图谱读写（CGO）
│       │   ├── redis.go            # 事件流 + 缓存 + 限流（手写 TCP 客户端）
│       │   ├── embedder.go         # BGE 嵌入（→ localhost:8000 ONNX）
│       │   ├── reranker.go         # Reranker（→ 模力方舟 API）
│       │   ├── recall.go           # 召回管线（向量+全文混合）
│       │   ├── memvector.go        # 内存向量索引
│       │   ├── cooccur.go          # 共现关系引擎
│       │   └── searchcache.go      # 搜索缓存
│       ├── distill/
│       │   ├── engine.go           # 蒸馏引擎
│       │   ├── rules.go            # 蒸馏规则
│       │   ├── consolidation.go    # 记忆整合
│       │   └── cost_control.go     # 成本控制
│       ├── governance/
│       │   ├── governance.go       # 遗忘+冲突+被动验证+可追溯（合并实现）
│       │   ├── eventbus.go         # 事件总线
│       │   ├── graph_store.go      # 图谱存储抽象
│       │   ├── graph_sqlite.go     # SQLite 图谱实现
│       │   ├── graph_mem.go        # 内存图谱（测试用）
│       │   ├── graph_file.go       # 文件图谱（降级）
│       │   ├── graph_auto.go       # 自动图扩展
│       │   └── graph_expander.go   # 图谱扩展器
│       ├── selfoptimize/
│       │   ├── selfoptimize.go     # 自优化引擎核心
│       │   ├── quality_monitor.go  # 7 维度质量仪表盘
│       │   ├── vprop.go            # 向量传播
│       │   ├── pipeline.go         # 优化管线
│       │   ├── executor.go         # 优化执行器
│       │   └── validator.go        # 优化验证器
│       ├── consolidate/
│       │   └── client.go           # Rust sidecar IPC 客户端
│       ├── distributed/
│       │   └── distributed.go      # CRDT 合并 + 事件广播
│       └── models/
│           └── memory.go           # 23 字段 MemoryRecord Schema
├── rust/                        # Rust 数据引擎 sidecar
│   ├── Cargo.toml / Cargo.lock
│   └── src/
│       ├── main.rs              # Unix Socket 监听 + Protobuf 解析
│       ├── lancedb_ops.rs       # LanceDB 读写（lancedb 0.15 crate）
│       ├── embed.rs             # BGE ONNX 推理（占位，实际用 Python ONNX）
│       ├── rerank.rs            # Rerank 推理
│       ├── cluster.rs           # DBSCAN 聚类（linfa）
│       ├── decay_calibrate.rs   # 对数线性回归（statrs）
│       ├── graph_prune.rs       # 图谱修剪（rusqlite）
│       ├── quality_backtrace.rs # 蒸馏质量回溯（reqwest → LLM）
│       └── report.rs            # 自优化报告生成
├── deploy/                      # 部署配置
│   ├── zhiyid.service           # Go API systemd unit
│   ├── zhiyi-consolidate.service + .timer  # Rust sidecar 定时任务
│   ├── bge-embed.service + bge_embed_server.py  # BGE ONNX 嵌入服务
│   ├── nginx-zhiyi.conf         # Nginx 反向代理
│   ├── prometheus-alerts.yml    # Prometheus 告警规则
│   └── M8-MIGRATION.md          # Python→Go 迁移指南
├── scripts/
│   ├── migrate_faiss_to_lance.go  # FAISS → LanceDB 迁移
│   └── migrate_hermes.py          # Hermes → 织忆 迁移脚本
├── carriers/                     # Obsidian Carrier 文件
│   └── shared/  (context / decision-log / glossary / learnings / progress / self-model / tasks)
└── proto/consolidate.proto      # Protobuf 定义（冗余，主定义在 go/proto/）

7.3 设计 vs 实现差异

设计（§7.2 旧版）	实现
独立仓库 `zhiyi-go` + `zhiyi-rust`	Monorepo `memoryweave/go/` + `rust/`
`selfopt/`	`selfoptimize/`
`ipc/consolidate.go`	`consolidate/client.go`
`skill/crystallization.go`、`l3/worldmodel.go`	合并到 `routes/skill_bayes.go`、`routes/l3.go`
治理模块分散多文件	合并到 `governance.go` + graph_*.go
无分布式/模型目录	新增 `distributed/`、`models/`
无 carrier/benchmark	新增 `carriers/`、`BENCHMARK.md`、`IMPLEMENTATION.md`

7.4 BGE 嵌入部署

当前方案：Python ONNX Runtime（bge-embed.service），监听 localhost:8000，兼容 OpenAI /v1/embeddings 格式。后续可选迁移到 Rust ort crate（当前 embed.rs 占位）。

7.5 分阶段实施计划

Phase	内容	工期
A	Go 项目骨架 + `/health` + 认证/限流中间件	1-2天
B	Rust sidecar 骨架 + LanceDB 集成 + BGE/Rerank + Recall 管线	3-5天
C	`/commit` + `/recall` + `/bootstrap` + Python/Go 对比测试	6-9天
D	蒸馏引擎（硬规则+LLM+批量+成本控制）+ 遗忘+PassiveValidator	10-14天
E	知识图谱（SQLite+BFS+修剪+Namespace）+ CRDT+Redis Streams+冲突裁决	15-19天
F	评估框架+金标集+质量评分+缺口分类+V值+预取+Skill+L3	20-25天
G	Rust Consolidation 全功能+Obsidian+WebSocket 事件+触发器系统	26-30天
H	部署切换（7822→7821）+ 备份+监控+SDK+FAISS→LanceDB 迁移	31-34天

Phase F 中的关键技术路径：

评估框架 → 先实现 IR 指标引擎 → 再生成金标集 → 最后 CI/CD 集成
缺口分类 → 先实现向量比较引擎 → 再实现 4 类分诊 → 最后自动修复路由
V值 → 先实现 Trace 存储 → 再实现传播公式 → 最后衰减管理
Skill → 先实现 Beta-Bernoulli 更新 → 再实现资格评估 → 最后生命周期管理
L3 → 先实现 ℰ/ℐ/C 数据模型 → 再实现更新触发 → 最后约束传播

7.6 性能目标

指标	Python 当前	Go+Rust 目标	优化来源
`/recall` 延迟	~500ms	< 200ms	Rust BGE 管线 + LanceDB 原生 ANN
`/commit` 延迟	~200ms	< 100ms	Go 并行管道 + Rust LanceDB 写入
并发 recall QPS	~10	> 100	Go goroutine + LanceDB 多进程
并发写入	不支持（GIL+FAISS锁）	完全支持	LanceDB Rust 原生并发
内存占用	22MB RSS + 162MB swap	< 50MB RSS（零 swap）	Rust 无 GC + Candle 推理在进程内

7.7 风险与缓解

风险	概率	缓解
opencode 限流延迟	中	核心路径优先；关键逻辑手工审查；多轮细粒度生成
LanceDB Go 绑定不稳定	低	Rust `lancedb` crate 作为备选（原生绑定，零 FFI 开销）
bge-m3 向量不一致	中	cosine_sim ≥ 0.99 阈值检验；不一致时对齐编码参数
FAISS 迁移数据丢失	低	备份 → 迁移脚本 → 数目对比 → recall 一致性抽样
Rust Candle 推理与 vLLM 输出不同	中	提前对比 → 不一致则保持 API 调用；Gradual 迁移
Redis 不可用	低	深度整合降级为 24h cron；缓存 miss 走完整链路

7.8 Unified Memory 规划（v3.9）

v3.9 目标：简化四层模型 → 三层

当前：
  L0: Episodes（不可变）
  L1: Distilled（事实）
  L2: Patterns（模式）
  L3: World Model（ℰ/ℐ/C）

v3.9（Go 实施完成后可选升级）：
  L0: Episodes（不可变）
  L1: Unified Memory（添加 type 字段）
      type = "fact" | "pattern" | "template" | "preference" | "constraint" | "skill"
  L2: World Model（ℰ/ℐ/C，单独维护）

收益：消除 L1/L2 双重蒸馏的冗余，一次 LLM 调用代替两次
风险：需要全量重蒸馏（旧 L1+L2 → 新 Unified）

附录

A. 已知限制

限制	缓解
知识图谱 10000 节点阈值	每月深度整合时修剪
Embedding 生成延迟 50-500ms	本地 vLLM + 搜索缓存（1h TTL）
LLM 蒸馏成本 ~$112/月	每日限额 50 次 + 批量 + 降级策略
LanceDB Go 绑定成熟度	Rust `lancedb` crate 备选（原生）
蒸馏质量依赖 LLM 能力	反向测试 + 幻觉检测 + 样本回溯
评估框架缺少已发布分数	Go 实施后首次运行 + 竞品对比
bge-m3 模型下载依赖网络	ModelScope 镜像（国内快）+ 离线备份
多实例同步延迟（秒级，非毫秒）	Redis Streams 为近实时设计

B. 默认配置值

recall.default_top_k: 10
recall.coarse_top_k: 50
recall.mmr_diversity: 0.5
recall.cache_ttl_seconds: 3600

distill.daily_llm_limit: 50
distill.batch_size: 10
distill.batch_timeout_minutes: 5
distill.deep_consolidation_max_llm: 20

decay_rate.system_fact: 0.003
decay_rate.user_pref: 0.005
decay_rate.proj_context: 0.008
decay_rate.tool_usage: 0.010
decay_rate.code_snippet: 0.012

graph.prune.isolated_after_days: 14
graph.prune.low_weight_threshold: 0.15
graph.prune.max_hops: 3
graph.page_rank.update_interval_days: 30

conflict.max_age_for_latest_wins_days: 90
conflict.max_trust_diff_for_auto_resolve: 0.5

gap.detection_threshold: 3          # 连续3次miss → 触发
gap.similarity_threshold_type_c: 0.85
gap.similarity_threshold_type_b: 0.75

prefetch.cooccur_threshold: 0.6
prefetch.decay_window_days: 14

trigger.cooldown_min_minutes: 60
trigger.max_consecutive_failures: 3

C. 未验证思想

思想	验证结果	处理
Abductive 溯因推理	❌ 无生产项目实现	降级为未来探索
UDP Gossip 同步	❌ 生产项目使用 Raft 或 Redis	不采用
指数衰减公式	❌ 生产项目使用线性衰减	不采用
黄金数据集 50 条	❌ 无项目使用手工标注	改用 LLM 自动生成 12 条金标查询

D. 版本变更日志

v2.5：Beta Ready — 四层记忆模型 + 蒸馏引擎 + 遗忘策略
v2.9：目标C完成（bge-m3 1024维 + jina rerank + hermes-zhiyi-bridge）
v3.0：记忆管理增强（知识图谱 + 定时遗忘 + LRU + PassiveValidator + conflict 自动触发）
v3.1：Go 语言 + LanceDB（方案锁定，但 Go 未实施，Python 继续运行）
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）三系统统一为织忆后端，消除三方记忆孤岛。

Appendix E: 统一记忆规划（v3.9）

E.1 当前状态

三个系统各自维护向量记忆：

系统	后端	向量维度	数据位置
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。

Hermes ──→ 织忆 Client (ZHIYI_URL=http://localhost:7821) ──→ MemoryWeave SQLite
OpenClaw ──→ 织忆 Client ────────────────────────────────→ (同一 DB)

E.3 实施步骤

Phase 1: 配置切换（零代码改动）

Hermes 和 OpenClaw 的 commit/recall 调用改走织忆：

# Hermes: ~/.hermes/config.yaml
memory:
  provider: zhiyi
  zhiyi_url: http://localhost:7821
  zhiyi_api_key: ${API_KEY}
  fallback_to_local: true  # 织忆不可用时回退到本地 hermes-lance

// OpenClaw: openclaw.json
{
  "memory": {
    "backend": "zhiyi",
    "zhiyi_url": "http://localhost:7821",
    "api_key": "zhiyi-dev-key-2026"
  }
}

Phase 2: 双写迁移

织忆启动时扫描 Hermes/OpenClaw 现有数据并导入：

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）。恢复后自动同步差异数据。

完整设计方案 v3.8。Part 1-7。Appendices A-E。Go API 核心 + Rust 数据引擎。

62 KiB Raw Blame History Unescape Escape

织忆 (MemoryWeave) — 完整设计方案 v3.8

目录

Part 1：基础

1.1 系统定位

1.2 四层记忆模型

1.3 Agent 记忆隔离

Part 2：存储与检索

2.1 存储架构

2.2 LanceDB Schema

memories 表

episodes 表

tombstones 表

2.3 Embedding 升级（1024维）

模型选型

vLLM 本地部署

API 调用

2.4 Rerank 重排层

模型选型

API 调用

2.5 知识图谱

2.5.1 节点/边 Schema

2.5.2 关系类型

2.5.3 建图来源

2.5.4 多跳导航算法

2.5.5 修剪策略

2.5.6 Namespace 隔离

2.6 Recall 完整链路

2.7 核心 API

REST 端点

Rate Limiting

WebSocket 事件类型

Part 3：记忆生命周期

3.1 蒸馏引擎

两阶段蒸馏

成本控制

Consolidation 流水线

3.2 自优化引擎

3.2.1 记忆质量评分（Outcome Feedback）

3.2.2 知识缺口自动分类

3.2.3 自优化仪表盘（7 项指标）

3.3 治理机制

3.3.1 遗忘策略

3.3.2 冲突检测与解决

3.3.3 记忆溯源链

3.3.4 被动验证机制（PassiveValidator）

3.4 知识图谱自动更新机制

3.5 自动化流程（5 个完整链路）

流程 1：新记忆 → 知识图谱（commit 触发，全自动）

流程 2：recall → 反馈闭环（Agent 使用触发，全自动）

流程 3：知识缺口 → 关闭（自动 + 人工混动）

流程 4：记忆修正 → 级联审查（修正 API 触发，全自动）

流程 5：深度整合全生命周期（条件触发，自动）

Part 4：部署

4.1 多实例与局域网

4.2 Go ↔ Rust IPC 设计

4.3 运维手册

备份

灾难恢复

监控（Prometheus /metrics 端点）

端口注册表

Part 5：集成

5.1 Hermes/OpenClaw Bridge

5.2 Obsidian 双向同步

Part 6：竞争性架构

6.1 评估框架

6.2 行业对标

6.3 V 值反向传播

6.4 8 类条件触发器

6.5 Skill 结晶管道

6.6 L3 世界模型（ℰ/ℐ/C 三元组）

6.7 记忆预取

Part 7：实施

7.1 Go + Rust 双二进制架构

7.2 实际项目结构（v3.8 实现）

7.3 设计 vs 实现差异

7.4 BGE 嵌入部署

7.5 分阶段实施计划

7.6 性能目标

7.7 风险与缓解

62 KiB

Raw Blame History

监控（Prometheus `/metrics` 端点）