docs: 重写 README.md — 完整项目说明(架构图/特性清单/API速查表/目录结构)
This commit is contained in:
@@ -1,32 +1,178 @@
|
||||
# 织忆 (MemoryWeave) — 独立记忆基础设施
|
||||
|
||||
> **Go + Rust 双二进制架构** | port 7821 | 版本 v0.1.0-dev
|
||||
> Gitea: http://192.168.123.11:3000/xiaoxue_admin/memoryweave/
|
||||
|
||||
织忆是多 Agent 系统的共享记忆层。
|
||||
织忆是多 Agent 系统的共享记忆层。它提供**语义记忆检索**、**知识图谱导航**、**自动蒸馏整合**三大核心能力,为 Hermes Agent、OpenClaw、Obsidian 等多客户端提供统一的记忆读写接口。
|
||||
|
||||
织忆不是 Hermes 的子模块——它是独立的系统级服务,由 4 个平级组件组成,任何组件的独立故障不影响全局。
|
||||
|
||||
---
|
||||
|
||||
## 架构总览
|
||||
|
||||
```
|
||||
zhiyid (Go daemon, port 7821)
|
||||
├── REST API / WebSocket
|
||||
├── 蒸馏引擎 / 冲突治理
|
||||
├── Redis 事件流
|
||||
└── 调用 zhiyi-consolidate
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 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 │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
|
||||
zhiyi-consolidate (Rust binary, systemd timer)
|
||||
├── LanceDB 原生读写
|
||||
├── DBSCAN 聚类 / 衰减回归
|
||||
├── Embedding + Rerank 管线
|
||||
└── → 结果写回 LanceDB
|
||||
┌──────────────────────────┐
|
||||
│ bge-embed (port 8000) │ ← Python ONNX 推理
|
||||
│ BGE-M3 embedding 服务 │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
## 目录
|
||||
### 语言分工
|
||||
|
||||
- [快速开始](#快速开始)
|
||||
- [安装](#安装方式)
|
||||
- [配置](#配置参考)
|
||||
- [API 参考](#api-参考)
|
||||
- [运维](#运维)
|
||||
| 组件 | 语言 | 原因 |
|
||||
|------|------|------|
|
||||
| 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 级权威层级:
|
||||
|
||||
1. **Terminal 实时输出** — curl / 工具调用真实结果
|
||||
2. **注入记忆** — `[织忆 Memory]` / `[织忆 Graph]`(插件注入)
|
||||
3. **项目官方文档** — `docs/` / README / INSTALL
|
||||
4. **训练知识** — 模型权重中存储的通用知识
|
||||
|
||||
低层级不可推翻高层级。另有记忆反馈规则确保信任评分闭环。
|
||||
|
||||
### 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` 参数调优
|
||||
|
||||
---
|
||||
|
||||
@@ -37,7 +183,7 @@ zhiyi-consolidate (Rust binary, systemd timer)
|
||||
- Go 1.21+
|
||||
- Rust 1.75+(仅需构建 zhiyi-consolidate)
|
||||
- Redis 7.0+(可选,默认降级为内存模式)
|
||||
- SQLite3(可选,用于持久化图谱)
|
||||
- Python 3.10+(bge-embedding 服务)
|
||||
|
||||
### 构建
|
||||
|
||||
@@ -62,8 +208,10 @@ make build-cli
|
||||
# 方式一:直接运行
|
||||
~/.local/bin/zhiyid
|
||||
|
||||
# 方式二:systemd(用户级)
|
||||
# 方式二:systemd(用户级,推荐)
|
||||
systemctl --user enable --now zhiyid
|
||||
systemctl --user enable --now bge-embed
|
||||
systemctl --user enable --now zhiyi-consolidate
|
||||
curl http://localhost:7821/health
|
||||
|
||||
# 方式三:Docker
|
||||
@@ -71,48 +219,42 @@ docker compose up -d
|
||||
curl http://localhost:7821/health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 安装方式
|
||||
|
||||
### 方式一:systemd(推荐)
|
||||
### 验证完整链路
|
||||
|
||||
```bash
|
||||
# 1. 构建
|
||||
make build build-cli
|
||||
# 1) 健康检查
|
||||
curl -s -H "X-API-Key: zhiyi-dev-key-2026" http://localhost:7821/api/v1/health
|
||||
|
||||
# 2. 安装 systemd 服务(用户级)
|
||||
mkdir -p ~/.config/systemd/user
|
||||
cp deploy/zhiyid.service ~/.config/systemd/user/zhiyid.service
|
||||
systemctl --user daemon-reload
|
||||
# 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. 启用并启动
|
||||
systemctl --user enable --now zhiyid
|
||||
# 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 http://localhost:7821/health
|
||||
# 4) 图谱统计
|
||||
curl -s -H "X-API-Key: zhiyi-dev-key-2026" http://localhost:7821/api/v1/graph/stats
|
||||
```
|
||||
|
||||
详细步骤请参考 [INSTALL.md](INSTALL.md)。
|
||||
|
||||
### 方式二:Docker Compose(一键)
|
||||
### Hermes 插件安装
|
||||
|
||||
```bash
|
||||
# 启动全部服务(zhiyid + Redis + 可选 BGE-M3)
|
||||
docker compose up -d
|
||||
|
||||
# 查看日志
|
||||
docker compose logs -f zhiyid
|
||||
|
||||
# 停止
|
||||
docker compose down
|
||||
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())}')"
|
||||
```
|
||||
|
||||
详见 [docker-compose.yml](docker-compose.yml)。
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
## 配置参考
|
||||
|
||||
### 环境变量
|
||||
|
||||
@@ -124,119 +266,64 @@ docker compose down
|
||||
| `LANCEDB_SOCKET` | `/tmp/zhiyi-ipc.sock` | Rust IPC socket 路径 |
|
||||
| `GRAPH_PATH` | `/var/lib/memoryweave/graph.db` | 图谱数据库路径 |
|
||||
| `API_KEY` | — | API 认证密钥 |
|
||||
| `VLLM_ENDPOINT` | — | Embedding 模型端点(如 vLLM) |
|
||||
| `VLLM_ENDPOINT` | — | Embedding 模型端点 |
|
||||
| `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 速查表
|
||||
|
||||
> 所有 `/api/v1/*` 接口需要 Header: `X-API-Key: <API_KEY>`
|
||||
> 所有 `/api/v1/*` 接口需要 Header: `X-API-Key: ***`
|
||||
|
||||
### 健康检查
|
||||
|
||||
```
|
||||
GET /health
|
||||
```
|
||||
|
||||
无需认证。返回服务状态。
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/health` | 健康检查(无认证) |
|
||||
| GET | `/api/v1/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
|
||||
```
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| 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
|
||||
```
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/api/v1/stats` | 系统统计(total_memories, episodes 等) |
|
||||
|
||||
返回 `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 # 导出图谱
|
||||
```
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| 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}
|
||||
```
|
||||
|
||||
实时记忆流订阅。
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| WS | `/api/v1/ws/{agent_id}` | 实时记忆流订阅 |
|
||||
|
||||
### 管理接口
|
||||
|
||||
@@ -245,110 +332,170 @@ 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` | 列出备份 |
|
||||
| GET | `/api/v1/admin/backups` | 列出备份 |
|
||||
| POST | `/api/v1/admin/restore` | 恢复备份 |
|
||||
| POST | `/api/v1/admin/distill/force` | 强制蒸馏 |
|
||||
| GET | `/api/v1/admin/audit` | 审计日志 |
|
||||
| GET | `/api/v1/admin/audit` | 审计日志 |
|
||||
|
||||
### 冲突治理
|
||||
|
||||
```
|
||||
GET /api/v1/conflicts # 列出冲突
|
||||
POST /api/v1/conflicts/resolve # 解决冲突
|
||||
```
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| 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/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
|
||||
```
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| 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` | 更新世界模型 |
|
||||
|
||||
---
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
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 # 版本文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 运维
|
||||
|
||||
### 进程管理
|
||||
|
||||
```bash
|
||||
# 查看所有相关进程
|
||||
ps aux | grep -E 'zhiyi|bge' | grep -v grep
|
||||
|
||||
# 查看端口
|
||||
ss -tlnp | grep -E '7821|8000'
|
||||
```
|
||||
|
||||
### systemd 操作
|
||||
|
||||
```bash
|
||||
# 查看状态
|
||||
# 状态检查
|
||||
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
|
||||
|
||||
# 停止
|
||||
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"
|
||||
# 一键三方交叉验证(进程 + 端口 + 端点)
|
||||
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
|
||||
```
|
||||
|
||||
### 日志位置
|
||||
|
||||
- systemd:`journalctl --user -u zhiyid`
|
||||
- 直接运行:stdout/stderr
|
||||
- Docker:`docker compose logs zhiyid`
|
||||
| 进程 | 日志 |
|
||||
|------|------|
|
||||
| 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` |
|
||||
|
||||
---
|
||||
|
||||
## 语言分工
|
||||
## 相关项目
|
||||
|
||||
| 组件 | 语言 | 原因 |
|
||||
|------|------|------|
|
||||
| HTTP API + 业务逻辑 | Go | goroutine 高并发,单二进制 |
|
||||
| LanceDB + 向量管线 | Rust | 原生 `lancedb` crate,零 FFI |
|
||||
| Embedding/Rerank | Rust | Candle/ort 推理 |
|
||||
- **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`。
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
- [设计文档](DESIGN.md) — 完整架构设计 v3.8
|
||||
- [实施计划](IMPLEMENTATION.md) — 里程碑与任务
|
||||
- [DESIGN.md](DESIGN.md) — 完整架构设计 v3.8
|
||||
- [INSTALL.md](INSTALL.md) — systemd 详细安装步骤
|
||||
|
||||
## 仓库
|
||||
|
||||
Gitea: http://192.168.123.11:3000/xiaoxue_admin/memoryweave
|
||||
- [Makefile](Makefile) — 构建入口(`make build` / `make build-rust` / `make build-cli`)
|
||||
- [docker-compose.yml](docker-compose.yml) — Docker 编排
|
||||
- [BENCHMARK.md](BENCHMARK.md) — 性能基准
|
||||
- [docs/](docs/) — 方案文档与竞品分析
|
||||
|
||||
Reference in New Issue
Block a user