docs: 织忆系统功能用法说明（v3.9全功能速查）
This commit is contained in:
小唯
parent
25151bfda2
commit
25a1bb52dc
|
|
@ -0,0 +1,154 @@
|
|||
# 织忆 (MemoryWeave) 系统功能用法说明
|
||||
|
||||
> **版本**：v3.9（2026-07-08）
|
||||
> **文档位置**：Gitea `memoryweave` 仓库
|
||||
> **Gitea**：http://192.168.123.11:3000/xiaoxue_admin/memoryweave
|
||||
> **API**：http://localhost:7821
|
||||
|
||||
---
|
||||
|
||||
## 一、系统架构
|
||||
|
||||
```
|
||||
Hermes Agent ──HTTP──┐ ┌── 07-Wiki (data_structure.md)
|
||||
OpenClaw ──HTTP──┤ │
|
||||
cli-anything──CLI───┼── zhiyid (7821) ──┤── bge-embed (8000) ── 向量编码
|
||||
│ Go Daemon │── Rust IPC sidecar ── LanceDB
|
||||
│ │── SQLite ── 知识图谱 (7421节点/64391边)
|
||||
│ └── 降级链: LanceDB → SQLite → 内存
|
||||
└── rag-skill skill ── 渐进式文件检索
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、核心功能速查
|
||||
|
||||
### 2.1 语义记忆（Recall / Commit）
|
||||
|
||||
| 操作 | 命令 | 说明 |
|
||||
|------|------|------|
|
||||
| 提交记忆 | `POST /api/v1/commit` + `{"agent_id":"a06","content":"..."}` | 写入一条新记忆 |
|
||||
| 语义搜索 | `POST /api/v1/recall` + `{"query":"...","top_k":5}` | 语义搜索，自动降级 |
|
||||
| 切换模式 | 加 `"mode":"hybrid"` / `"keyword"` / `"semantic"` | 三模式搜索 |
|
||||
|
||||
**三模式搜索说明**：
|
||||
- `hybrid`（默认）：0.7 向量 + 0.3 BM25 关键词，通用场景
|
||||
- `keyword`：BM25 纯关键词，精准术语匹配
|
||||
- `semantic`：纯向量搜索，模糊概念查找
|
||||
|
||||
### 2.2 知识图谱（Navigate / Stats）
|
||||
|
||||
| 操作 | 命令 | 说明 |
|
||||
|------|------|------|
|
||||
| 图谱统计 | `GET /api/v1/graph/stats` | 节点数/边数/密度 |
|
||||
| 导航 | `POST /api/v1/graph/navigate` + `{"entity":"织忆","max_hops":2}` | 探索实体关系网 |
|
||||
| 自然语言查询 | `POST /api/v1/graph/nl_query` + `{"query":"织忆和牧尘的关系"}` | 直接问 |
|
||||
| 添加关系 | `POST /api/v1/graph/edge` + `{"from":"A","to":"B","relation":"USES"}` | 建立关联 |
|
||||
| 反馈 | `POST /api/v1/graph/edge/feedback` + `{"edge_id":"...","helpful":true}` | 训练信任评分 |
|
||||
|
||||
### 2.3 已部署特性
|
||||
|
||||
| 特性 | 说明 |
|
||||
|------|------|
|
||||
| **P0 降级策略** | bge-embed 挂了自动走 SQLite 关键词搜索，返回 `X-Fallback: graph` 头 |
|
||||
| **P1 自动注入** | Hermes 插件在每个用户消息前自动查织忆 + 社交关闭检测（"好的"/"ok"跳过） |
|
||||
| **P2 信任评分** | `trust_score = helpful_count / retrieval_count`，反馈 API 训练 |
|
||||
| **P3 CREATIVE.md** | 工作记忆隔离文件，插件自动加载标记 `[织忆 工作记忆]` |
|
||||
| **P4 Ground Truth** | SOUL.md 4 级权威层级（终端 > 注入 > 文档 > 训练） |
|
||||
| **P5 Wiki 策展** | `wiki_curator.py` 自动提取 Wiki 概念写入织忆 |
|
||||
| **H1 BM25 混合** | 向量 0.7 + BM25 0.3 融合 |
|
||||
| **H5 三模式** | hybrid / keyword / semantic 搜索模式 |
|
||||
|
||||
### 2.4 健康检查
|
||||
|
||||
```bash
|
||||
# 一键三方交叉验证
|
||||
bash ~/.hermes/skills/zhiyi/zhiyi/scripts/three-way-check.sh
|
||||
|
||||
# P0/P1/P2 专项验证
|
||||
bash ~/.hermes/skills/zhiyi/zhiyi/scripts/verify-p0p1p2.sh
|
||||
|
||||
# Wiki 策展预览
|
||||
hermes skills run zhiyi scripts/wiki_curator.py --dry-run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、rag-skill 渐进式检索（新增）
|
||||
|
||||
### 适用场景
|
||||
|
||||
从本地知识库（07-Wiki、文档目录）检索精确信息时。
|
||||
|
||||
### 工作流程
|
||||
|
||||
```
|
||||
1. data_structure.md 导航 → 了解目录结构
|
||||
2. 判断相关目录 → 读子目录索引
|
||||
3. grep 搜索关键词 → 定位文件
|
||||
4. read_file offset+limit 局部读（200-500行）
|
||||
5. 不够？换关键词 → 最多5轮
|
||||
6. 输出 + 来源引用
|
||||
```
|
||||
|
||||
### 调用方式
|
||||
|
||||
```bash
|
||||
# 加载 skill
|
||||
# 需要时自动调用，或者：
|
||||
# 问题 → 我会自动判断是否走渐进式检索
|
||||
```
|
||||
|
||||
### 与织忆协同
|
||||
|
||||
| 场景 | 先 | 后 |
|
||||
|------|----|----|
|
||||
| "P0 降级怎么实现的" | 织忆语义搜索 → context | rag-skill 搜代码注释 |
|
||||
| "07-Wiki 有哪些织忆文档" | data_structure.md 导航 | 逐篇读摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 四、Gitea 仓库内容
|
||||
|
||||
| 目录 | 内容 |
|
||||
|------|------|
|
||||
| `go/` | Go API daemon（zhiyid） |
|
||||
| `rust/` | Rust IPC sidecar（LanceDB） |
|
||||
| `plugins/hermes-zhiyi/` | Hermes 织忆插件（__init__.py） |
|
||||
| `plugins/obsidian/` | Obsidian 笔记插件 |
|
||||
| `plugins/openclaw-zhiyi/` | OpenClaw 记忆插件 |
|
||||
| `skills/zhiyi/` | 织忆 Hermes skill（SKILL.md + scripts + references） |
|
||||
| `skills/rag-progressive-search/` | rag-skill 渐进式检索 skill |
|
||||
| `cli-anything/` | 命令行伴侣 |
|
||||
| `docs/` | 设计文档（v3.8+v3.9）+ 实施计划 + 进度快照 + data_structure.md |
|
||||
| `deploy/` | systemd service 文件 + bge-embed server |
|
||||
| `scripts/` | 运维脚本（备份/迁移/验证/策展） |
|
||||
|
||||
---
|
||||
|
||||
## 五、快速部署（新机器）
|
||||
|
||||
```bash
|
||||
# 1. 克隆
|
||||
git clone http://192.168.123.11:3000/xiaoxue_admin/memoryweave.git /tmp/memoryweave
|
||||
|
||||
# 2. 部署 4 组件
|
||||
cd /tmp/memoryweave/deploy
|
||||
# 详见 deploy/ 下 systemd service 文件
|
||||
|
||||
# 3. 安装 Hermes 插件
|
||||
cp -r /tmp/memoryweave/plugins/hermes-zhiyi ~/.hermes/hermes-agent/plugins/memory/zhiyi/
|
||||
|
||||
# 4. 安装 skill
|
||||
# skills/ 目录下 skill 复制到 ~/.hermes/skills/
|
||||
|
||||
# 5. 验证
|
||||
bash scripts/three-way-check.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、织忆系统 Gitea 仓库 仓库 地址
|
||||
|
||||
**HTTP**：http://192.168.123.11:3000/xiaoxue_admin/memoryweave
|
||||
**Clone**：`git clone http://192.168.123.11:3000/xiaoxue_admin/memoryweave.git`
|
||||
Loading…
Reference in New Issue