# 织忆 (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