From 25a1bb52dcbf82724679c50747ac61d17565eb46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=94=AF?= Date: Wed, 8 Jul 2026 12:26:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BB=87=E5=BF=86=E7=B3=BB=E7=BB=9F?= =?UTF-8?q?=E5=8A=9F=E8=83=BD=E7=94=A8=E6=B3=95=E8=AF=B4=E6=98=8E=EF=BC=88?= =?UTF-8?q?v3.9=E5=85=A8=E5=8A=9F=E8=83=BD=E9=80=9F=E6=9F=A5=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/织忆系统功能用法说明.md | 154 +++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/织忆系统功能用法说明.md diff --git a/docs/织忆系统功能用法说明.md b/docs/织忆系统功能用法说明.md new file mode 100644 index 0000000..fa101e9 --- /dev/null +++ b/docs/织忆系统功能用法说明.md @@ -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`