织忆 (MemoryWeave) — 独立记忆基础设施

Go + Rust 双二进制架构 | port 7821 | 版本 v0.1.0-dev

织忆是多 Agent 系统的共享记忆层。

架构总览

zhiyid (Go daemon, port 7821)
  ├── REST API / WebSocket
  ├── 蒸馏引擎 / 冲突治理
  ├── Redis 事件流
  └── 调用 zhiyi-consolidate

zhiyi-consolidate (Rust binary, systemd timer)
  ├── LanceDB 原生读写
  ├── DBSCAN 聚类 / 衰减回归
  ├── Embedding + Rerank 管线
  └── → 结果写回 LanceDB

目录

• 快速开始
• 安装
• 配置
• API 参考
• 运维

---

快速开始

前置依赖

• Go 1.21+
• Rust 1.75+（仅需构建 zhiyi-consolidate）
• Redis 7.0+（可选，默认降级为内存模式）
• SQLite3（可选，用于持久化图谱）

构建

# 克隆
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
curl http://localhost:7821/health

# 方式三：Docker
docker compose up -d
curl http://localhost:7821/health

---

安装方式

方式一：systemd（推荐）

# 1. 构建
make build build-cli

# 2. 安装 systemd 服务（用户级）
mkdir -p ~/.config/systemd/user
cp deploy/zhiyid.service ~/.config/systemd/user/zhiyid.service
systemctl --user daemon-reload

# 3. 启用并启动
systemctl --user enable --now zhiyid

# 4. 验证
curl http://localhost:7821/health

详细步骤请参考 INSTALL.md。

方式二：Docker Compose（一键）

# 启动全部服务（zhiyid + Redis + 可选 BGE-M3）
docker compose up -d

# 查看日志
docker compose logs -f zhiyid

# 停止
docker compose down

详见 docker-compose.yml。

---

配置

环境变量

变量	默认值	说明
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 模型端点（如 vLLM）
BGE_MODEL_DIR	—	BGE-M3 ONNX 模型目录
RERANK_ENDPOINT	—	Rerank 模型端点
LLM_ENDPOINT	—	LLM 端点（蒸馏/自动修复用）
LLM_MODEL	—	LLM 模型名称
LLM_API_KEY	—	LLM API Key
MOLIFANG_API_KEY	—	魔方API密钥（embedding中转）
STATIC_DIR	内置静态文件	Web UI 静态文件目录
ZHIYI_WEB_UI_ROOT	内置 HTML	Web UI 入口路径

配置示例（.env）

PORT=7821
STORAGE_BACKEND=lancedb
SQLITE_PATH=/var/lib/memoryweave/memoryweave.db
GRAPH_PATH=/var/lib/memoryweave/graph.db
API_KEY=your-secret-key-here
VLLM_ENDPOINT=http://127.0.0.1:8000/v1/embeddings
RERANK_ENDPOINT=https://ai.gitee.com/v1
LLM_ENDPOINT=http://127.0.0.1:3000/v1/chat/completions
LLM_MODEL=qwen/qwen3.5-122b-a10b
LLM_API_KEY=your-llm-api-key

---

API 参考

所有 /api/v1/* 接口需要 Header: X-API-Key: <API_KEY>

健康检查

GET /health

无需认证。返回服务状态。

核心记忆

提交记忆

POST /api/v1/commit
Content-Type: application/json

{
  "namespace": "shared",
  "content": "用户在下午讨论了微服务架构",
  "tags": ["design", "microservice"],
  "episodes": ["ep_001"]
}

检索记忆

POST /api/v1/recall
Content-Type: application/json

{
  "namespace": "shared",
  "query": "微服务设计原则",
  "top_k": 5
}

批量提交

POST /api/v1/batch-commit
Content-Type: application/json

{
  "namespace": "shared",
  "items": [
    {"content": "...", "tags": []},
    {"content": "...", "tags": []}
  ]
}

反馈

POST /api/v1/feedback
POST /api/v1/feedback/useful
POST /api/v1/feedback/not-useful
POST /api/v1/feedback/deprecate

统计

GET /api/v1/stats

返回 total_memories、total_episodes 等统计信息。

图谱

GET  /api/v1/graph/stats     # 图谱统计
POST /api/v1/graph/query     # 图谱查询
POST /api/v1/graph/navigate  # 导航
GET  /api/v1/graph/pagerank  # PageRank
POST /api/v1/graph/export    # 导出图谱

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

---

运维

systemd 操作

# 查看状态
systemctl --user status zhiyid

# 查看日志
journalctl --user -u zhiyid -f

# 重启
systemctl --user restart zhiyid

# 停止
systemctl --user stop zhiyid

Docker 操作

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f zhiyid

# 重启
docker compose restart zhiyid

# 进入容器
docker compose exec zhiyid sh

健康检查

make health
# 或
curl -sf http://localhost:7821/health && echo "OK"

日志位置

• systemd：journalctl --user -u zhiyid
• 直接运行：stdout/stderr
• Docker：docker compose logs zhiyid

---

语言分工

组件	语言	原因
HTTP API + 业务逻辑	Go	goroutine 高并发，单二进制
LanceDB + 向量管线	Rust	原生 lancedb crate，零 FFI
Embedding/Rerank	Rust	Candle/ort 推理

---

文档

• 设计文档 — 完整架构设计 v3.8
• 实施计划 — 里程碑与任务
• INSTALL.md — systemd 详细安装步骤

仓库

Gitea: http://192.168.123.11:3000/xiaoxue_admin/memoryweave