354 lines
6.8 KiB
Markdown
354 lines
6.8 KiB
Markdown
# 织忆 (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 参考](#api-参考)
|
||
- [运维](#运维)
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 前置依赖
|
||
|
||
- Go 1.21+
|
||
- Rust 1.75+（仅需构建 zhiyi-consolidate）
|
||
- Redis 7.0+（可选，默认降级为内存模式）
|
||
- SQLite3（可选，用于持久化图谱）
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
# 克隆
|
||
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
|
||
```
|
||
|
||
### 运行
|
||
|
||
```bash
|
||
# 方式一：直接运行
|
||
~/.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（推荐）
|
||
|
||
```bash
|
||
# 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](INSTALL.md)。
|
||
|
||
### 方式二：Docker Compose（一键）
|
||
|
||
```bash
|
||
# 启动全部服务（zhiyid + Redis + 可选 BGE-M3）
|
||
docker compose up -d
|
||
|
||
# 查看日志
|
||
docker compose logs -f zhiyid
|
||
|
||
# 停止
|
||
docker compose down
|
||
```
|
||
|
||
详见 [docker-compose.yml](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）
|
||
|
||
```bash
|
||
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 操作
|
||
|
||
```bash
|
||
# 查看状态
|
||
systemctl --user status zhiyid
|
||
|
||
# 查看日志
|
||
journalctl --user -u zhiyid -f
|
||
|
||
# 重启
|
||
systemctl --user restart zhiyid
|
||
|
||
# 停止
|
||
systemctl --user stop zhiyid
|
||
```
|
||
|
||
### Docker 操作
|
||
|
||
```bash
|
||
# 查看状态
|
||
docker compose ps
|
||
|
||
# 查看日志
|
||
docker compose logs -f zhiyid
|
||
|
||
# 重启
|
||
docker compose restart zhiyid
|
||
|
||
# 进入容器
|
||
docker compose exec zhiyid sh
|
||
```
|
||
|
||
### 健康检查
|
||
|
||
```bash
|
||
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 推理 |
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
- [设计文档](DESIGN.md) — 完整架构设计 v3.8
|
||
- [实施计划](IMPLEMENTATION.md) — 里程碑与任务
|
||
- [INSTALL.md](INSTALL.md) — systemd 详细安装步骤
|
||
|
||
## 仓库
|
||
|
||
Gitea: http://192.168.123.11:3000/xiaoxue_admin/memoryweave |