1603 lines
63 KiB
Markdown
1603 lines
63 KiB
Markdown
# 织忆 (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 数据引擎。*
|