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

> **编程语言**：Go + Rust（双二进制架构，详见 Part 7）
> **向量数据库**：LanceDB（Rust `lancedb` crate 原生集成）
> **代码生成工具**：opencode
> **定位**：Hermes / OpenClaw / 未来 Agent 的统一记忆基础设施
> **修订日期**：2026-05-28
> **状态**：v3.8 部分实施（共享记忆层 ✅，其他规划中）

---

## 目录

1. [Part 1：基础](#part-1基础)
   - 1.1 系统定位
   - 1.2 四层记忆模型
   - 1.3 Agent 记忆隔离
2. [Part 2：存储与检索](#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 事件类型）
3. [Part 3：记忆生命周期](#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 深度整合全生命周期
4. [Part 4：部署](#part-4部署)
   - 4.1 多实例与局域网
   - 4.2 Go ↔ Rust IPC 设计
   - 4.3 运维手册（备份/恢复/监控/限流/端口表）
5. [Part 5：集成](#part-5集成)
   - 5.1 Hermes/OpenClaw Bridge + Go Client SDK
   - 5.2 Obsidian 双向同步
6. [Part 6：竞争性架构](#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 推送）
7. [Part 7：实施](#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）
8. [附录](#附录)
   - 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 广播列表。

**原始会话 vs 语义记忆（v3.8 实施澄清）**：

| 数据层 | 存储位置 | 是否共享 |
|--------|---------|---------|
| 原始会话（JSONL） | Hermes: `~/.hermes/sessions/`<br>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：存储与检索

### 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 表

```python
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 表

```python
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 表

```python
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。

```bash
# 模型下载（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')"
```

```bash
# 启动 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 调用

**请求**：
```json
POST /v1/embeddings
{
  "model": "bge-m3",
  "input": ["文本内容"]
}
```

**响应**：
```json
{
  "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 调用

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

**响应**：
```json
{
  "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

```sql
-- 节点表
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` 字段记录：

```json
[
  {
    "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
```

#### 灾难恢复

```bash
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 共享）：

```go
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`

```json
// 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/聚类/整合）。**v3.8 共享记忆层已实施**（2026-05-28）：Hermes + OpenClaw 共用 `/var/lib/memoryweave/` LanceDB，原始会话分开存储。
- **v3.9**：统一记忆架构 ~~待实施~~ → **已实施（共享层）**。Hermes（hermes-lance） + OpenClaw（openclaw lancedb） + 织忆（MemoryWeave SQLite）三系统统一为织忆后端，消除三方记忆孤岛。原始会话仍各自存储。

### Appendix E: 统一记忆架构（v3.8 实施完成）

#### E.1 实施状态

✅ **已完成（2026-05-28）**：Hermes + OpenClaw 已统一接入织忆后端，共享语义记忆层。

#### E.2 当前架构

```
┌─────────────────────────────────────────────────────────┐
│              /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/
```

**原始会话（各自独立，不走织忆）：**
- Hermes: `~/.hermes/sessions/`（飞书消息 JSONL）
- OpenClaw: `~/.openclaw/workspace/sessions/`（代码任务 JSONL）

#### E.3 agent_id 分布

| 系统 | agent_id | namespace | 路径 |
|------|----------|-----------|------|
| Hermes | `hermes-a06` | `""`（空） | `~/.hermes/sessions/` |
| OpenClaw | `openclaw` | `openclaw-main` | `~/.openclaw/workspace/sessions/` |

#### E.4 回退策略

若织忆宕机，Hermes/OpenClaw 各自使用本地缓存（fallback）继续运行。恢复后自动重新同步。

---

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