织忆 (MemoryWeave) — 独立记忆基础设施
Go + Rust 双二进制架构 | port 7821 | 版本 v0.1.0-dev
Gitea: http://192.168.123.11:3000/xiaoxue_admin/memoryweave/
织忆是多 Agent 系统的共享记忆层。它提供语义记忆检索、知识图谱导航、自动蒸馏整合三大核心能力，为 Hermes Agent、OpenClaw、Obsidian 等多客户端提供统一的记忆读写接口。
织忆不是 Hermes 的子模块——它是独立的系统级服务，由 4 个平级组件组成，任何组件的独立故障不影响全局。
架构总览
┌──────────────────────────────────────────────────────────────┐
│ Hermes Agent (Plugin) │
│ plugins/memory/zhiyi/ — 7 tools + 自动注入 + 社交关闭 │
└──────────────────────────┬───────────────────────────────────┘
│ HTTP (localhost:7821)
▼
┌──────────────────────────────────────────────────────────────┐
│ zhiyid (Go daemon, port 7821) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ REST API │ │ 蒸馏引擎 │ │ 冲突治理 / 缺口检测 │ │
│ │ ~84 端点 │ │ distill/ │ │ conflict + gap │ │
│ └──────┬──────┘ └──────┬───────┘ └──────────────────────┘ │
│ │ │ │
│ │ ┌──────────▼───────────┐ │
│ │ │ SQLiteGraphStore │ │
│ │ │ (7014 节点/61058 边)│ │
│ │ └──────────────────────┘ │
│ │ │
│ │ Unix Socket (/tmp/zhiyi-ipc.sock) │
└─────────┼─────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ zhiyi-consolidate (Rust sidecar) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ LanceDB 原生 │ │ DBSCAN 聚类 │ │ Embedding + │ │
│ │ 读写 │ │ 衰减回归 │ │ Rerank 管线 │ │
│ └──────┬───────┘ └──────────────┘ └────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ /var/lib/memoryweave/ (LanceDB) │ │
│ │ memories: 3510 条 / episodes: 73 │ │
│ └─────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
┌──────────────────────────┐
│ bge-embed (port 8000) │ ← Python ONNX 推理
│ BGE-M3 embedding 服务 │
└──────────────────────────┘
语言分工
| 组件 |
语言 |
原因 |
| HTTP API + 业务逻辑 |
Go |
goroutine 高并发，单二进制 |
| LanceDB + 向量管线 |
Rust |
原生 lancedb crate，零 FFI |
| Embedding 推理 |
Python (ONNX) |
BGE-M3 模型，最佳推理生态 |
| Hermes 插件 |
Python |
Hermes MemoryProvider 接口 |
功能特性
语义记忆（commit / recall）
POST /api/v1/commit — 提交记忆（需 agent_id + content）
POST /api/v1/recall — 语义检索（支持 hybrid / keyword / semantic 三模式）
- 1024 维向量嵌入（BGE-M3）
- MMR diversity 默认 0.3，结果去重
- freshness 生命周期：
fresh → verified
- 支持 namespace 隔离
知识图谱（Navigate / Stats）
POST /api/v1/graph/navigate — BFS 节点关系遍历
GET /api/v1/graph/stats — 图谱统计
POST /api/v1/graph/query — 精确边查询
GET /api/v1/graph/pagerank — PageRank 排序
- SQLite 存储，7014 节点 / 61058 边
- 自动实体归一化（
n_ 前缀）
- 按关系类型分组 + 推荐探索建议
- 自然语言查询（
nl_query）
P0 — Recall 降级策略
当 bge-embed (8000) 或 Rust IPC sidecar 不可用时，recall 自动降级到 graph.db 关键词搜索（FallbackTextSearch），返回 X-Fallback: graph 响应头。保证单点故障不导致全挂。
P1 — 自动注入钩子 + 社交关闭
queue_prefetch 后台线程自动查织忆 + 缓存（TTL 30s）- 社交关闭检测：短消息、纯社交用语（"好的" / "ok" / "👍"）跳过注入
- 输出标记：
[织忆 Memory] / [织忆 Graph]
- 无缝融入 Hermes 对话流
P2 — 信任评分
graph_edges 表新增三列：
| 列名 |
类型 |
默认值 |
说明 |
trust_score |
REAL |
0.5 |
信任评分（贝叶斯先验） |
retrieval_count |
INTEGER |
0 |
被检索次数 |
helpful_count |
INTEGER |
0 |
被标记有用次数 |
评分公式：trust_score = helpful_count / retrieval_count（retrieval_count > 0 时）
P3 — CREATIVE.md 隔离
~/.hermes/CREATIVE.md 存储织忆工作记忆，插件 system_prompt_block() 自动加载标注为 [织忆 工作记忆]（Ground Truth level 2），解决 memory 工具与织忆 plugin 的双写入冲突。
P4 — Ground Truth Prompt
SOUL.md 定义 4 级权威层级：
- Terminal 实时输出 — curl / 工具调用真实结果
- 注入记忆 —
[织忆 Memory] / [织忆 Graph]（插件注入）
- 项目官方文档 —
docs/ / README / INSTALL
- 训练知识 — 模型权重中存储的通用知识
低层级不可推翻高层级。另有记忆反馈规则确保信任评分闭环。
P5 — Wiki 策展管线
scripts/wiki_curator.py 自动知识库管线：
- 扫描
~/mc/ 下 .md 文件，SHA-256 diff 跟踪
- 启发式提取：headings → 概念，bold / key phrases → 实体
- 写入织忆：概念
/commit（category=wiki），关系 /graph/edge
- 支持
--dry-run（预览）、--force（全量）、--llm（LLM 增强）
- 跳过 <500 字符文件和
_ 前缀文件
H1-H6 精度优化
| 编号 |
优化 |
状态 |
| H1 |
BM25 关键词评分（0.7 向量 + 0.3 关键词融合） |
✅ |
| H2 |
LLM Wiki 策展（--llm 模式，回退启发式） |
✅ |
| H3 |
自动信任评分（recall 后异步 UpdateEdgeTrustScores） |
✅ |
| H4 |
默认 MMR diversity = 0.3 |
✅ |
| H5 |
三模式搜索：hybrid / keyword / semantic |
✅ |
| H6 |
多级存储：LanceDB → SQLite → 内存三级降级 |
✅ |
cli-anything 命令行伴侣
织忆原生集成 cli-anything 框架，将 Go 和 Rust API 封装为 CLI 子命令。支持：
zhiyi commit / zhiyi recall — 记忆操作zhiyi navigate / zhiyi stats — 图谱查询zhiyi health — 健康检查- 详见
cli-anything/ 目录
rag-skill 渐进式检索（新增）
三段式检索架构：
用户查询 → keyword 粗筛 → semantic 精排 → rerank 重排序
- 粗筛层：BM25 关键词倒排索引，快速缩减候选集
- 精排层：BGE-M3 语义嵌入，向量相似度排序
- 重排序层：cross-encoder rerank，微调 top-K 结果
- 默认返回 top-K 结果，支持
top_k 参数调优
快速开始
前置依赖
- Go 1.21+
- Rust 1.75+（仅需构建 zhiyi-consolidate）
- Redis 7.0+（可选，默认降级为内存模式）
- Python 3.10+（bge-embedding 服务）
构建
# 克隆
git clone http://192.168.123.11:3000/xiaoxue_admin/memoryweave.git
cd memoryweave
# 构建 Go daemon（zhiyid）
make build
# 构建 Rust sidecar（可选）
make build-rust
# 构建 CLI 工具
make build-cli
运行
# 方式一：直接运行
~/.local/bin/zhiyid
# 方式二：systemd（用户级，推荐）
systemctl --user enable --now zhiyid
systemctl --user enable --now bge-embed
systemctl --user enable --now zhiyi-consolidate
curl http://localhost:7821/health
# 方式三：Docker
docker compose up -d
curl http://localhost:7821/health
验证完整链路
# 1) 健康检查
curl -s -H "X-API-Key: zhiyi-dev-key-2026" http://localhost:7821/api/v1/health
# 2) 提条记忆试试
curl -s -X POST -H "X-API-Key: zhiyi-dev-key-2026" \
-H "Content-Type: application/json" \
-d '{"agent_id":"a06","content":"Hello 织忆","metadata":{"source":"test"}}' \
http://localhost:7821/api/v1/commit
# 3) 搜一下
curl -s -X POST -H "X-API-Key: zhiyi-dev-key-2026" \
-H "Content-Type: application/json" \
-d '{"query":"织忆","top_k":3}' \
http://localhost:7821/api/v1/recall
# 4) 图谱统计
curl -s -H "X-API-Key: zhiyi-dev-key-2026" http://localhost:7821/api/v1/graph/stats
Hermes 插件安装
cp -r plugins/hermes-zhiyi ~/.hermes/hermes-agent/plugins/memory/zhiyi
uv pip install websocket-client
cd ~/.hermes/hermes-agent
python3 -c "from plugins.memory.zhiyi import HermesZhiYiMemoryProvider; \
p = HermesZhiYiMemoryProvider(); \
print(f'可用: {p.is_available()}, 工具数: {len(p.get_tool_schemas())}')"
配置参考
环境变量
| 变量 |
默认值 |
说明 |
PORT |
7821 |
API 监听端口 |
STORAGE_BACKEND |
lancedb |
存储后端：lancedb / sqlite / memory |
SQLITE_PATH |
/var/lib/memoryweave/memoryweave.db |
SQLite 数据库路径 |
LANCEDB_SOCKET |
/tmp/zhiyi-ipc.sock |
Rust IPC socket 路径 |
GRAPH_PATH |
/var/lib/memoryweave/graph.db |
图谱数据库路径 |
API_KEY |
— |
API 认证密钥 |
VLLM_ENDPOINT |
— |
Embedding 模型端点 |
BGE_MODEL_DIR |
— |
BGE-M3 ONNX 模型目录 |
RERANK_ENDPOINT |
— |
Rerank 模型端点 |
LLM_ENDPOINT |
— |
LLM 端点（蒸馏/自动修复用） |
LLM_MODEL |
— |
LLM 模型名称 |
LLM_API_KEY |
— |
LLM API Key |
STATIC_DIR |
内置静态文件 |
Web UI 静态文件目录 |
ZHIYI_WEB_UI_ROOT |
内置 HTML |
Web UI 入口路径 |
API 速查表
所有 /api/v1/* 接口需要 Header: X-API-Key: ***
健康检查
| 方法 |
路径 |
说明 |
| GET |
/health |
健康检查（无认证） |
| GET |
/api/v1/health |
健康检查（需认证） |
核心记忆
| 方法 |
路径 |
说明 |
| POST |
/api/v1/commit |
提交记忆 |
| POST |
/api/v1/recall |
语义检索（支持 mode=hybrid|keyword|semantic） |
| POST |
/api/v1/batch-commit |
批量提交 |
| GET |
/api/v1/memories |
列出记忆（分页） |
| POST |
/api/v1/feedback |
反馈（useful / not-useful / deprecate） |
统计
| 方法 |
路径 |
说明 |
| GET |
/api/v1/stats |
系统统计（total_memories, episodes 等） |
知识图谱
| 方法 |
路径 |
说明 |
| GET |
/api/v1/graph/stats |
图谱统计（节点数 / 边数 / 密度） |
| POST |
/api/v1/graph/navigate |
BFS 节点遍历（entity + max_hops） |
| POST |
/api/v1/graph/query |
精确边查询 |
| POST |
/api/v1/graph/nl_query |
自然语言图谱查询 |
| POST |
/api/v1/graph/edge |
添加关系边 |
| POST |
/api/v1/graph/edge/feedback |
边信任评分反馈 |
| GET |
/api/v1/graph/pagerank |
PageRank 节点排名 |
| POST |
/api/v1/graph/export |
导出图谱 |
| POST |
/api/v1/graph/cleanup |
脏数据清理（支持 dry_run） |
| GET |
/api/v1/cache/stats |
图谱缓存命中率 |
WebSocket
| 方法 |
路径 |
说明 |
| WS |
/api/v1/ws/{agent_id} |
实时记忆流订阅 |
管理接口
| 方法 |
路径 |
说明 |
| POST |
/api/v1/admin/consolidate |
手动触发记忆整合 |
| POST |
/api/v1/admin/forget |
删除记忆 |
| POST |
/api/v1/admin/backup |
创建备份 |
| GET |
/api/v1/admin/backups |
列出备份 |
| POST |
/api/v1/admin/restore |
恢复备份 |
| POST |
/api/v1/admin/distill/force |
强制蒸馏 |
| GET |
/api/v1/admin/audit |
审计日志 |
冲突治理
| 方法 |
路径 |
说明 |
| GET |
/api/v1/conflicts |
列出记忆冲突 |
| POST |
/api/v1/conflicts/resolve |
解决冲突 |
缺口检测
| 方法 |
路径 |
说明 |
| GET |
/api/v1/gaps |
列出记忆缺口 |
| POST |
/api/v1/gaps/detect |
检测缺口 |
| POST |
/api/v1/gaps/repair |
修复缺口 |
| POST |
/api/v1/gaps/close/{id} |
关闭缺口 |
蒸馏管理
| 方法 |
路径 |
说明 |
| GET |
/api/v1/distill/status |
蒸馏状态 |
| GET |
/api/v1/distill/queue |
蒸馏队列 |
| GET |
/api/v1/distill/quota |
蒸馏配额 |
L3 世界模型
| 方法 |
路径 |
说明 |
| GET |
/api/v1/l3/worldmodel |
获取世界模型 |
| POST |
/api/v1/l3/worldmodel |
更新世界模型 |
目录结构
memoryweave/
├── go/ # Go daemon（zhiyid）
│ ├── cmd/zhiyid/ # 主入口
│ ├── internal/
│ │ ├── api/ # HTTP 路由 + 端点（~84 端点）
│ │ │ └── routes/ # 路由实现（core, graph, ws, l3, ...）
│ │ ├── governance/ # 冲突治理、图谱存储、自动扩展
│ │ ├── storage/ # 存储引擎（lancedb, sqlite, redis, recall, ...）
│ │ ├── models/ # 数据模型
│ │ ├── distill/ # 蒸馏引擎
│ │ ├── consolidate/ # 记忆整合客户端
│ │ ├── selfoptimize/ # 自优化管线
│ │ ├── distributed/ # 分布式支持
│ │ └── metrics/ # 监控指标
│ └── zhiyid-new # 编译产物
├── rust/ # Rust sidecar（zhiyi-consolidate）
│ └── src/
│ ├── main.rs # IPC 监听 + 调度
│ ├── lancedb_ops.rs # LanceDB 原生读写
│ ├── embed.rs # Embedding 推理
│ ├── rerank.rs # Rerank 管道
│ ├── cluster.rs # DBSCAN 聚类
│ ├── decay_calibrate.rs # 衰减校准
│ ├── graph_prune.rs # 图谱剪枝
│ ├── quality_backtrace.rs # 质量回溯
│ └── report.rs # 报告生成
├── plugins/
│ ├── hermes-zhiyi/ # Hermes MemoryProvider 插件（7 工具）
│ │ └── __init__.py # v1.1.0: 自动注入 + 社交关闭
│ └── obsidian/ # Obsidian 侧边栏插件
├── scripts/ # 运维脚本
│ ├── wiki_curator.py # P5 Wiki 策展管线
│ ├── three-way-check.sh # 三方交叉健康检查
│ ├── verify-p0p1p2.sh # P0/P1/P2 一键验证
│ └── daily-check.sh # 每日巡检
├── deploy/ # 部署配置
│ └── systemd/ # systemd service 文件
│ ├── zhiyid.service
│ ├── bge-embed.service
│ └── zhiyi-consolidate.service
├── cli-anything/ # CLI 命令行伴侣集成
├── carriers/ # 载体（Obsidian / 飞书等）
├── proto/ # Protocol Buffers 定义
├── web-ui/ # Web 管理界面
├── docs/ # 设计文档 / 方案文档
├── tests/ # 集成测试
├── backups/ # 备份目录
├── skills/ # Hermes skills 定义
├── docker-compose.yml # Docker 编排
├── Makefile # 构建入口
├── DESIGN.md # 完整架构设计（v3.8）
├── INSTALL.md # systemd 详细安装步骤
├── BENCHMARK.md # 性能基准测试
└── VERSION # 版本文件
运维
进程管理
# 查看所有相关进程
ps aux | grep -E 'zhiyi|bge' | grep -v grep
# 查看端口
ss -tlnp | grep -E '7821|8000'
systemd 操作
# 状态检查
systemctl --user status zhiyid
systemctl --user status bge-embed
systemctl --user status zhiyi-consolidate
# 日志
journalctl --user -u zhiyid -f
journalctl --user -u bge-embed -f
journalctl --user -u zhiyi-consolidate -f
# 重启
systemctl --user restart zhiyid
健康检查
# 一键三方交叉验证（进程 + 端口 + 端点）
bash scripts/three-way-check.sh
# 或手动
curl -s -H "X-API-Key: zhiyi-dev-key-2026" http://localhost:7821/api/v1/health
curl -s http://localhost:8000/health # bge-embed
日志位置
| 进程 |
日志 |
| zhiyid |
/tmp/zhiyid.log / journalctl --user -u zhiyid |
| Rust sidecar |
/tmp/zhiyi-sidecar.log / journalctl --user -u zhiyi-consolidate |
| bge-embed |
journalctl --user -u bge-embed |
相关项目
- Hermes Agent — 织忆的主要消费者。通过
memory.provider: zhiyi 配置自动集成 7 个记忆工具。
- OpenClaw — 第二消费者。通过
openclaw-zhiyi-plugin/ 集成织忆记忆。
- Obsidian — 知识管理前端。通过
plugins/obsidian/ 侧边栏插件交互。
- cli-anything — 命令行伴侣。将织忆 API 封装为 CLI 子命令。
- Memory-OS — 竞品对比参考（7 层记忆架构）。详见
docs/memory-os-7-layer-comparison.md。
文档
1970fb4f06