@modusensus/dsh-mneme 0.8.14 → 0.8.16

package/docs/LOCAL_MODEL.md

@@ -0,0 +1,222 @@
+# dsh-mneme 本地模型部署指南
+
+- **日期**：2026-08-15
+- **范围**：为 dsh-mneme 配置完全离线的本地语义模型（Embedding + Rerank），覆盖 ONNX（transformers.js）与 Ollama 两种路径
+
+## 1. 前置要求
+
+| 项目 | 要求 | 说明 |
+|------|------|------|
+| Node.js | ≥ 22.5（建议 24+） | 插件依赖 `node:sqlite`（22.5 起可用，24 稳定） |
+| 磁盘空间 | ≥ 300MB（推荐 1GB+） | bge-small-zh-v1.5 量化约 100MB，bge-reranker-base 约 250MB；Ollama 模型另计 |
+| 内存 | ≥ 1GB 可用 | 纯 CPU 推理亦可运行 |
+| GPU（可选） | 显存 ≥ 2GB | 开启 `localEmbedDevice: "gpu"`（onnxruntime 需要额外安装 cuda 后端） |
+| 网络 | 仅首次下载模型需要 | 已下载后可完全离线（默认走 Hugging Face，可换镜像源） |
+
+> 依赖解析分三层：① **插件自管运行时目录**（`~/.dsh/mneme/runtime/`，见 §2.5，优先）；② 宿主 profile 里已装的 `@huggingface/transformers`；③ 都没有则本地推理不可用，检索自动降级为关键词/BM25（读写在任何情况下都不受影响）。
+>
+> 从本版起 `@huggingface/transformers` 已从 `dependencies` 降为**可选 peer**（`peerDependenciesMeta.optional`），安装插件时不会再带上它和它那套原生闭包；第 ② 层因此只对「自己装过这份依赖」或「从旧版本升级上来、尚未被 prune」的环境有效。**正在使用本地嵌入的用户请在升级前按 §2.5 收编一份**，否则升级后本地嵌入不可用（读写信道不受影响）。
+>
+> `onnxruntime-node` 作为可选原生后端列在 `allowScripts`（首次安装需确认脚本），无需手动额外安装。
+
+## 2. 模型安装 / 下载
+
+### 2.1 自动下载（默认，推荐）
+
+首次使用本地 Embedder 时会**自动从 Hugging Face Hub 下载**对应模型到本地缓存，无需手动操作：
+
+```bash
+node scripts/benchmark-embed.js --provider local --model Xenova/bge-small-zh-v1.5
+# 首次运行会显示下载进度 → 加载模型 → 输出基准表格
+```
+
+默认缓存目录：`~/.dsh/mneme/models`（用户级，重装/升级依赖不丢；`embedModelCacheDir` 留空时启用）。transformers.js 把模型存成 `<cacheDir>/<org>/<name>/`（实测 4.2.0，例如 `~/.dsh/mneme/models/Xenova/bge-small-zh-v1.5/`）：
+
+- Linux/macOS：`~/.dsh/mneme/models/`
+- Windows：`%USERPROFILE%\.dsh\mneme\models\`
+
+> 实测 transformers.js 4.2.0 在离线加载（`allowRemoteModels=false`）时按 `<cacheDir>/<org>/<model>/` 解析模型文件，例如 `<cacheDir>/Xenova/bge-small-zh-v1.5/config.json`。与本段上面描述的 `hub/models--…` 布局不一致时，以实际报错里给出的路径为准；缓存不在默认位置时按 §2.5 用 `--cache-dir` 指过去。
+
+### 2.2 手动指定缓存目录
+
+内存受限/离线机器可把模型缓存放到指定位置（迁移、共享缓存）：
+
+```js
+// 配置示例（插件配置里设置 embedModelCacheDir）
+const embedder = createEmbedderByProvider("local", {
+  cacheDir: "/data/hf-models",   // 模型缓存目录
+  model: "Xenova/bge-small-zh-v1.5"
+});
+```
+
+### 2.3 Ollama 路径
+
+如果本机已有 Ollama：
+
+```bash
+ollama pull nomic-embed-text   # 或 bge-m3（多语言）
+```
+
+Ollama Embedder 走 `/api/embeddings`，**不下载任何文件到插件缓存**，模型由 Ollama 管理。
+
+### 2.4 断点续传
+
+下载基于 Hugging Face Hub 缓存协议，**中断后重试自动续传**（按分片断点续传，不重新下载已完成部分）。若反复中断导致缓存损坏，删除对应模型的缓存目录后重跑即可：
+
+```bash
+rm -rf ~/.dsh/mneme/models/hub/models--Xenova--bge-small-zh-v1.5
+```
+
+### 2.5 自管运行时（收编 / 校验 / 排查）
+
+本地推理真正要用的是一整套依赖闭包：`@huggingface/transformers` + `onnxruntime-node` + `sharp`（本机实测从宿主 node_modules 收编时是 **49 个包、3203 个文件、约 393MB**）。插件支持把它收编到自管目录 `~/.dsh/mneme/runtime/`，与宿主 profile 的依赖图解耦；收编**优先使用硬链接**，同盘时几乎不额外占盘。
+
+**为什么要独立出来**：这份闭包此前留在插件 `dependencies` 里，而 profile 是所有插件共用的依赖图，于是「装任何插件」都要替它重走一遍整条链，弱网下极慢。摘掉该声明后，运行时由自管目录承接——所以要**先收编、再升级**，否则升级后本地嵌入不可用。
+
+**三条取件来源，按可用性依次尝试**（面板按钮、`memory_runtime` 工具、CLI 三者共用同一套编排）：
+
+| 顺序 | 来源 | 特点 |
+|---|---|---|
+| ① | 收编本机 profile 的 `node_modules` | **零网络**；同盘硬链接，几乎不占额外空间 |
+| ② | `runtimeTarballDir` 指向的本地 `.tgz` 目录 | 某个包网络下不到时用（文件名按 npm 约定 `<basename>-<version>.tgz`） |
+| ③ | npm registry（`runtimeMirror` 可换镜像） | 按随包发布的 `runtime-manifest.json` 逐个取，**每个 tarball 先校验 sha512 再落盘** |
+
+走 ③ 时体积是 **win32-x64 实测约 33 个包、2142 个文件、数百 MB**（各平台不同，故不写死数值）——比①少，因为清单剔除了 `onnxruntime-web`（127.7MB，占全量三分之一）：transformers 的 Node 构建从不 import 它（把一个空的 `onnxruntime-web` 打桩进去，嵌入结果逐字节相同），风险由 `verify` 的真实推理兜底。清单本身**平台无关**（数据源是 `package-lock.json` 里所有平台的条目），下载时按各包的 `os`/`cpu` 过滤，所以 win32 / darwin / linux × x64 / arm64 都被覆盖 —— 不需要谁在某个系统上先跑一次生成脚本。
+
+```bash
+# 在插件目录下运行（例如 node_modules/@modusensus/dsh-mneme）
+
+# 1) 看状态：在哪、来源、结构完不完整（不加载模型，秒回）
+node scripts/mneme-runtime.mjs status
+
+# 2) 收编宿主里已有的那份（只读源、只写自管目录，不安装任何东西）
+node scripts/mneme-runtime.mjs adopt --from ~/.dsh/profiles/<profile>/node_modules
+
+# 3) 真加载运行时并跑一次推理，确认可用
+node scripts/mneme-runtime.mjs verify --cache-dir ~/.dsh/mneme/models
+```
+
+- 退出码：`0` 健康 / `1` 不健康或失败 / `2` 用法错误（便于脚本直接 gate，区分「没装」和「装坏了」看输出里的 `status`）。加 `--json` 得到机器可读结果。
+- `verify` 的功能验证**不触网**（`allowRemoteModels=false`）：模型必须已在缓存目录里，否则会明确失败——这是有意的，验证不该偷偷触网。缓存不在默认位置时用 `--cache-dir` 指到与 `embedModelCacheDir` 一致的位置。
+- 三条入口（CLI / 面板 / `memory_runtime`）的判据是同一份：缓存目录取 `embedModelCacheDir`（**留空即用户级默认目录**，与真实嵌入同一处解析），探针模型取 `localEmbedModel`（留空即默认小模型）。也就是说验证用的就是真实推理用的那份模型——CLI 不需要额外 `--cache-dir`，面板也不会跑到包内去找（#387 修的就是这个不一致）。
+- 收编来的目录没有可比对的原始产物，完整性如实标 `unverified`，不假装验过；结构检查通过 ≠ 功能可用，两者分开报。
+- `status` 只做结构检查，所以 `functional` 恒为 `unknown`——要看真实推理结果就跑 `verify`。
+- 运行时不可用时插件不会崩：检索降级为关键词/BM25，读写在任何情况下都不受影响；错误信息会带上 `adopt` 的具体命令。
+- 同一份状态也能从 `GET /api/dsh-mneme/semantic` 的 `localRuntime` 字段读到（面板与 CLI 同源）。
+
+#### 不用命令行也可以
+
+- **面板**：记忆面板的「向量索引」卡片在本地 provider 且运行时不就绪时，会显示**代价说明**（要额外一份运行时、解包后数百 MB）、先试收编、没有再下载，并按实际走的那一档分开报结果。卡片下面还有一个「取回本地运行时」按钮，点一下即完成。
+- **让 agent 代做**：`memory_runtime` 工具提供三个动作——`status`（只读，**返回里带代价说明**，便于 agent 先告知你再动手）、`provision`（走上面三档来源）、`verify`（真跑一次推理）。所以即便你不看面板，也可以直接让 agent 处理。
+- **这条路由与其它写路由走同一道门**：`POST /api/dsh-mneme/runtime/provision` 是唯一会联网拉数百 MB 并写盘的写面，鉴权规则与其他写路由完全一致——配了 `apiToken` 就必须带 token，**没配就等于不校验**（这是插件既有的鉴权模型，不是这条路由特有的）。本机默认部署下它开箱可用；但若这个端口能被别的页面/机器够到，请照第 3.1 节配上 `apiToken`。面板按钮与 `memory_runtime` 都走这道门，不需要额外配置。
+- **平台过滤的取向是「宽松优先」**：清单是平台无关的一份（含所有平台的包），下载时按本机 `os`/`cpu` 过滤；Linux 上如果**确认**了本机是 glibc，还会剔掉另一套 libc 的变体（`sharp` 与 `libvips` 的 musl 包，十几 MB）。拿不到 libc 证据时一律不过滤——多下十几兆，好过赌错方向装出一份跑不起来的运行时。
+- **宿主那份 transformers 会被版本门禁**：第 ② 层（宿主裸 specifier）只接受 `>=4.2.0` 且 `<5` 的版本；宿主装到 v5 时不会被静默使用，而是明确报出「版本越界」并退到第 ③ 层的可操作提示。版本读不到（某些打包形态）时不拦，以免这层对老用户整体失效。
+
+```yaml
+# 两个可选配置键（默认留空 = 不改变任何行为）
+runtimeTarballDir: ""   # 本地 .tgz 目录：有它就优先于联网
+runtimeMirror: ""       # registry 镜像前缀，例如 https://npmmirror.com/mirrors/npm/
+```
+
+#### 升级前必做（否则本地嵌入会断）
+
+如果你正在使用本地嵌入（`embedProvider: local`），**在升级到已摘掉 `dependencies` 声明的版本之前**先执行一次 `adopt` + `verify`。顺序不能反：升级时 pnpm 会 prune 掉宿主里那份依赖，那之后就没有可收编的源了，只剩联网下载一条路。
+
+#### 自己取一份来收编（相对上面的手动路径）
+
+上面的面板按钮 / `provision` 已经能在没有可收编副本时自行下载。但如果你希望**完全掌控取件过程**（例如用自己的镜像、或先在一处统一缓存），仍然可以手工取一份再收编——不必逐个下载包：
+
+```bash
+# Windows（PowerShell / cmd）
+mkdir %TEMP%\mneme-fetch && cd /d %TEMP%\mneme-fetch
+npm i @huggingface/transformers@^4.2.0
+node "<插件目录>\scripts\mneme-runtime.mjs" adopt --from "%TEMP%\mneme-fetch\node_modules"
+
+# Linux / macOS
+mkdir -p /tmp/mneme-fetch && cd /tmp/mneme-fetch
+npm i @huggingface/transformers@^4.2.0
+node "<插件目录>/scripts/mneme-runtime.mjs" adopt --from /tmp/mneme-fetch/node_modules
+```
+
+- **安装脚本必须能执行**：npm 默认会执行生命周期脚本，而 `onnxruntime-node` / `sharp` 正是靠 postinstall 取原生二进制；加 `--ignore-scripts` 会得到一个装不起来的闭包。pnpm 10+ 默认拦截构建脚本，所以这里用 npm 更省事。
+- 收编完那个临时目录可以直接删掉：闭包已经在 `~/.dsh/mneme/runtime/` 里了（硬链接时几乎不额外占盘）。
+- 收编后**仍然建议跑一次 `verify`**——结构完整不等于能推理。
+
+## 3. 配置
+
+### 3.1 插件配置（`~/.dsh/profiles/web/cordis.patch.yml`）
+
+```yaml
+- id: dsh-mneme
+  name: '@modusensus/dsh-mneme'
+  config:
+    # ── Embedding ──────────────────────────────
+    embedProvider: local        # local | ollama | openai（默认 openai，保持 v0.1 行为）
+    localEmbedModel: Xenova/bge-small-zh-v1.5
+    localEmbedDimension: 512    # 与模型匹配的向量维度
+    localEmbedDevice: cpu       # cpu | gpu（仅 local 生效）
+    localEmbedBatchSize: 8      # 分批嵌入条数，内存紧张调小
+    embedModelCacheDir: ""      # 模型缓存目录（空=用户级 ~/.dsh/mneme/models；注意：不做 ~ 展开，要指别处必须写绝对路径）
+    ollamaBaseUrl: "http://localhost:11434"   # 仅 ollama 生效
+    ollamaModel: "nomic-embed-text"           # 仅 ollama 生效（openai 端点走面板 vector-config）
+    # ── Rerank（Phase 2，可选）─────────────────
+    rerankEnabled: false        # 开启向量召回后的精排
+    rerankModel: Xenova/bge-reranker-base
+```
+
+### 3.2 环境变量（可选）
+
+| 变量 | 作用 |
+|------|------|
+| `HF_ENDPOINT` | Hugging Face 镜像源，例如 `https://hf-mirror.com`（国内加速） |
+| `HF_HUB_CACHE` | 覆盖默认缓存目录 |
+
+### 3.3 各后端配置对照
+
+| 配置 | local (ONNX) | ollama | openai |
+|------|--------------|--------|--------|
+| `localEmbedModel` | HF 模型 id（如 `Xenova/bge-small-zh-v1.5`） | —（用 `ollamaModel`） | —（用面板 vector-config） |
+| `ollamaBaseUrl` | — | `http://localhost:11434`（默认） | — |
+| `ollamaModel` | — | Ollama 模型名（如 `nomic-embed-text`） | — |
+| `localEmbedDevice` | ✅ | — | — |
+| `localEmbedBatchSize` | ✅ | — | — |
+| `embedModelCacheDir` | ✅ | — | — |
+
+## 4. 首次使用
+
+1. 配置 `embedProvider`（或保持 `openai` 不动）
+2. 保存配置并重启 DSH，或直接跑 `scripts/benchmark-embed.js` 验证
+3. 首次触发本地模型时，transformers.js 自动下载 → `init()` 打印 `local embedder ready: <model> (dim=512, device=cpu)`
+4. 之后所有 `memory_save` 写入自动补向量；已有记忆可用「重建索引」批量补建
+
+> 注意：切换 `localEmbedModel` 或 `embedDimension` 后，旧向量与新向量维度不同、无法混算，需**重建索引**（复用 v0.1 的 `reindexMissing` 机制）。
+
+## 5. 常见问题
+
+### Q1：模型下载失败 / 下载超慢
+
+- 国内网络：设置镜像源 `HF_ENDPOINT=https://hf-mirror.com`（或 `export HF_ENDPOINT=https://hf-mirror.com`）
+- 公司代理拦截：检查 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量
+- 磁盘不足：清理缓存或用 `embedModelCacheDir` 换目录
+
+### Q2：`Xenova/bge-small-zh-v1.5` 加载报错 / 显存不足（OOM）
+
+- 默认 `device: cpu`、`dtype: q8`，内存占用已最小化
+- 尝试 `embedBatchSize` 调小（如 4/2）降低峰值内存
+- 显存不足：`device: gpu` 时改回 `cpu`；或检查 onnxruntime-node 是否安装了 GPU 后端
+
+### Q3：中英文混排 / CJK 文本处理
+
+- `bge-small-zh-v1.5` 对中文与中英混排均优化良好；纯英文场景可换 Ollama 的 `nomic-embed-text`
+- 单条文本上限 8000 字符（与 v0.1 一致），超长自动截断
+- 检索时 query 与记忆正文走同一 Embedder、同一归一化（mean pooling + L2），余弦分数才可比
+
+### Q4：换模型后结果变差 / 向量混乱
+
+- 换模型（尤其维度不同）后旧向量不可复用，必须重建索引
+- 若在 Web 面板/API 配置过 v0.1 的 `vector-config`，v0.2 会优先采用插件配置，旧配置仅作降级路径
+
+### Q5：本地模型加载很慢（首次/每次启动）
+
+- 首次含下载，属正常；已缓存后每次启动仅加载进内存（数百 ms 级）
+- 大模型（如 bge-m3）可考虑换用更小的 `Xenova/bge-small-zh-v1.5`（量化 q8 约 100MB）

package/docs/SEMANTIC.md

@@ -0,0 +1,256 @@
+# dsh-mneme 语义增强架构 — 设计文档
+
+- **日期**：2026-08-15
+- **状态**：✅ 已实现（本地 Embedding / Rerank / 聚类随 v0.2+ 落地；本文档转为历史设计存档，当前能力以 [README](../README.md) 正文为准）
+- **范围**：为 dsh-mneme 增加"完全离线的语义记忆引擎"，覆盖本地 Embedding、Rerank 精排、autoDream 向量聚类三个阶段
+- **相关文档**：[本地模型部署指南](LOCAL_MODEL.md) · [从 v0.1 升级说明](MIGRATION.md)
+
+## 1. 背景与目标
+
+dsh-mneme v0.1 已具备**可选的向量搜索**：通过 `/api/dsh-mneme/vector-config` 配置 OpenAI 兼容 `/embeddings` 端点，命中"字面不同但语义相近"的记忆；未配置或失败时降级为 LIKE 子串搜索。
+
+v0.2 的目标是把这条**可选、依赖外部 API** 的向量链路升级为**默认可用、完全离线**的语义记忆引擎：
+
+1. **本地 Embedding**：ONNX（`Xenova/bge-small-zh-v1.5`）或 Ollama，记忆向量不再依赖外网 API
+2. **Rerank 精排**：向量初筛后交叉编码精排，把 Top-K 准确率再抬一档
+3. **autoDream 语义增强**：对记忆向量做聚类，让自动巩固（去重/合并/冲突裁决）从"主题相近"升级为"语义相近"
+
+## 2. 总体架构
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    语义引擎（v0.2，完全离线可选）                 │
+├──────────────────────────────────────────────────────────────┤
+│ ① Embedder 层（三选一，统一接口，可自动降级）                     │
+│   LocalEmbedder(ONNX) │ OllamaEmbedder │ OpenAIEmbedder       │
+│   init() / embed(texts) / embedSingle() / dimension / hash    │
+├──────────────────────────────────────────────────────────────┤
+│ ② VectorIndex 层                                               │
+│   SQLite memories.embedding 列（JSON 向量）                     │
+│   + 余弦相似度检索（score 0..1）+ 缺失向量增量补建 reindex       │
+├──────────────────────────────────────────────────────────────┤
+│ ③ Rerank 层（可选）                                            │
+│   LocalReranker（Xenova/bge-reranker-base，交叉编码）            │
+│   召回候选 → 精排 → Top-K                                       │
+├──────────────────────────────────────────────────────────────┤
+│ ④ autoDream 聚类（可选）                                       │
+│   clusterMemories(向量 K-Means) / findPotentialConflicts       │
+│   语义分组 + 疑似矛盾检测 → 巩固决策更精准                       │
+└──────────────────────────────────────────────────────────────┘
+```
+
+- **① Embedder**：`src/local-embedder.js`，三后端统一接口，`createEmbedderByProvider(provider, opts)` 按名创建
+- **② VectorIndex**：复用 v0.1 的 `memories.embedding` 列与 `store.js` 的余弦检索，无新存储层
+- **③ Rerank**：`src/reranker.js`（Phase 2），可选开启
+- **④ 聚类**：`src/dream/clustering.js`（Phase 3），autoDream 调度器集成
+
+### 目录结构（新增/变化部分）
+
+```
+src/
+├── local-embedder.js   # [新增] Local/Ollama/OpenAI 三 Embedder + createEmbedderByProvider
+├── reranker.js         # [新增·Phase2] LocalReranker 交叉编码精排
+├── dream/
+│   └── clustering.js   # [新增·Phase3] clusterMemories / findPotentialConflicts / kMeans
+└── embedding.js        # [保留] v0.1 OpenAI 兼容客户端（作为降级路径之一复用）
+scripts/
+├── benchmark-embed.js  # [新增] Embedding 吞吐量基准
+└── benchmark-rerank.js # [新增] Rerank 延迟基准
+docs/
+├── SEMANTIC.md         # 本文档
+├── LOCAL_MODEL.md      # 本地模型部署指南
+└── MIGRATION.md        # 从 v0.1 升级说明
+```
+
+## 3. 搜索流水线
+
+`memory_search` 在 v0.2 的完整链路（对应 `src/tools.js` 的 `mode: auto | keyword | vector | hybrid`）：
+
+```
+                query
+                  │
+      ┌───────────┴───────────┐
+      ▼                       ▼
+ keyword 召回               vector 召回
+ (LIKE 子串 title/        (Embedder.embed(query)
+  content/tags)             → 余弦相似度 top-N
+                            → 缺失向量自动补建)
+      │                       │
+      └───── 混合融合 ─────────┘
+        (auto: 关键词命中优先 + 向量补足；分数归一化合并)
+                  │
+                  ▼
+         [Rerank 开启？]
+          ├─ 是 → LocalReranker.rerank(query, candidates, topK)
+          │       交叉编码精排，取 topK
+          └─ 否 → 按 importance/score 直接截取 topK
+                  │
+                  ▼
+           memory_search 结果
+```
+
+- **召回阶段（候选）**：混合召回，宁多勿漏，候选集通常取向量 top-N（默认远超 Top-K，供精排筛选）
+- **精排阶段（Rerank）**：对候选逐条打分（query 与候选的交互编码），取 Top-K
+- **结果阶段**：返回条目 + `score`（召回分/精排分）+ `source` 时间戳，与 v0.1 返回结构保持一致
+
+## 4. 模块接口
+
+### 4.1 Embedder 统一接口（`src/local-embedder.js`）
+
+三个后端共享同一接口，方法失败**抛错**，由上层编排降级链（与 v0.1 `embedding.js` 的"失败返回 null"不同）。
+
+| 成员 | 说明 |
+|------|------|
+| `init()` | 加载模型 / 探测服务，失败抛错 |
+| `embed(texts: string[])` | 批量嵌入，返回 `number[][]`（本地模型 mean pooling + L2 归一化） |
+| `embedSingle(text)` | 单条嵌入 → `number[]` |
+| `dimension` | 向量维度（getter） |
+| `modelHash` | 模型指纹（`<model>#<hash>`），用于向量索引一致性校验，模型换名/换维度时提示重建索引 |
+| `dispose()` | 释放模型资源 |
+
+**LocalEmbedder（ONNX）**
+
+```js
+new LocalEmbedder({
+  model: "Xenova/bge-small-zh-v1.5", // 默认；中文优化，全离线
+  dimension: 512,                    // 默认与模型匹配
+  device: "cpu",                     // cpu | wasm | gpu（onnxruntime 后端）
+  batchSize: 8,                      // 分批嵌入，控制峰值内存
+  cacheDir: "",                      // 自定义模型缓存目录，空则用 HF 默认缓存
+  useDtype: "q8",                    // 量化精度 q8/fp32/fp16
+  logger: null
+})
+```
+
+**OllamaEmbedder**
+
+```js
+new OllamaEmbedder({
+  baseUrl: "http://localhost:11434", // 默认
+  model: "nomic-embed-text",         // 默认；维度从首次响应自动推断
+  logger: null
+})
+```
+
+**OpenAIEmbedder（兼容 v0.1 行为）**
+
+```js
+new OpenAIEmbedder({
+  baseUrl: "",      // 例如 https://api.openai.com/v1，也支持 SiliconFlow/智谱/Ollama 代理
+  apiKey: "",
+  model: "",
+  timeoutMs: 15000
+})
+```
+
+**工厂**
+
+```js
+import { createEmbedderByProvider } from "../src/local-embedder.js";
+const embedder = createEmbedderByProvider("local", { device: "cpu" }); // local | ollama | openai
+await embedder.init();
+const vecs = await embedder.embed(["你好", "记忆库"]);
+```
+
+### 4.2 Reranker（`src/reranker.js`，Phase 2）
+
+| 成员 | 说明 |
+|------|------|
+| `constructor({ model, device, batchSize, cacheDir, logger })` | `model` 默认 `Xenova/bge-reranker-base` |
+| `init()` | 加载交叉编码模型 |
+| `rerank(query, candidates, topK?)` | 对候选逐条打分，返回按相关性降序的候选（附 `score`），`topK` 缺省返回全量排序 |
+
+示例：
+
+```js
+import { LocalReranker } from "../src/reranker.js";
+const reranker = new LocalReranker({ model: "Xenova/bge-reranker-base" });
+await reranker.init();
+const top = await reranker.rerank("怎么部署本地模型", candidates, 5);
+```
+
+### 4.3 autoDream 聚类（`src/dream/clustering.js`，Phase 3，已实现）
+
+| 成员 | 说明 |
+|------|------|
+| `cosineSimilarity(a, b)` | 余弦相似度，零向量/长度不齐返回 0，数值稳定 |
+| `kMeans(vectors, k, opts)` | K-Means（k-means++ 播种 + 空簇修复），返回每簇索引数组 |
+| `clusterMemories(memories, vectors, k)` | 按向量把记忆分组，返回簇（保留原对象引用） |
+| `findPotentialConflicts(memories, vectors, threshold = 0.85)` | 同类型、高相似（可能矛盾）的记忆对 |
+
+autoDream 调度器在触发巩固时：对候选记忆做 `clusterMemories` 分组 → 每组送 LLM 决策（merge/archive/conflict），并用 `findPotentialConflicts` 预先标出疑似矛盾对，减少漏判。
+
+## 5. 降级策略
+
+```
+       首选                   回退 1                  回退 2                 兜底
+LocalEmbedder(ONNX) ──失败──► OllamaEmbedder ──失败──► OpenAIEmbedder ──失败/未配置──► 关键词 LIKE
+```
+
+- Embedder 方法**抛错**，由上层 `createEmbedderByProvider` 编排的降级链逐级捕获切换；全链路失败则回退到 v0.1 的 LIKE 子串关键词搜索（本库无 FTS5，关键词召回即 LIKE 子串扫描）
+- **原则**：语义链路任何一环失败都**静默降级、不阻断记忆读写**——写入照常落库，只是当次不补向量
+- **降级是每请求动态的**：同一会话内 ONNX 偶发失败，下一次请求自动重试首选路径，不固化到降级档
+- **索引一致性**：Embedder 的 `modelHash` 变化（换模型/换维度）时，旧向量与新向量不可混算余弦，需触发「重建索引」（复用 v0.1 的 `reindexMissing` 补建缺失向量）
+
+## 6. 模型清单
+
+| 用途 | 模型 | 后端 | 维度 | 说明 |
+|------|------|------|------|------|
+| Embedding | `Xenova/bge-small-zh-v1.5` | ONNX（默认） | 512 | 中文优化，全离线，体积小 |
+| Embedding | `bge-m3` | Ollama | 1024 | 多语言（中/英/日等），质量高 |
+| Embedding | `nomic-embed-text` | Ollama | 768 | 英文为主，通用 |
+| Embedding | `text-embedding-3-small` | OpenAI 兼容 | 1536 | v0.1 云端默认，升级后仍可用 |
+| Rerank | `Xenova/bge-reranker-base` | ONNX（Phase 2） | — | 交叉编码，首候选精排 |
+| Rerank | `bge-reranker-v2-m3` | 云/本地 | — | 更强精排，多语言 |
+
+> 维度随模型而定：换用不同维度的模型后，已存向量与模型指纹不匹配，需重建索引。
+
+## 7. 配置新增项
+
+见 [MIGRATION.md](MIGRATION.md) 完整表格。核心：`embedProvider`（`local` / `ollama` / `openai`，默认 `openai` 保持 v0.1 行为）、`localEmbedModel`、`localEmbedDimension`、`localEmbedDevice`、`localEmbedBatchSize`、`ollamaBaseUrl`、`ollamaModel`、`embedModelCacheDir`、`rerankEnabled`、`rerankModel`。
+
+## 8. 测试与基准
+
+- 单元：`src/local-embedder.js` 三后端接口一致性、`clustering.js` 聚类正确性（node:test）
+- 降级链：mock 各后端抛错，断言逐级回退到 LIKE
+- 基准：`scripts/benchmark-embed.js`（嵌入延迟/吞吐）、`scripts/benchmark-rerank.js`（Rerank 延迟 vs 候选规模）
+
+## 9. 反思更新（v0.2.1 `update` 决策 + 失败追踪）
+
+### 9.1 `update` 决策类型
+
+autoDream 整理时，LLM 可输出第 5 种决策 `update`，直接修正单条记忆的过时/错误内容：
+
+- **约束**：`ids` 只能含一个 id；必须产生实际字段变化；不能更新 `summary`；新建 < 24h 的记忆不可 update
+- **频率限制**：每次 autoDream 最多 `reflectionUpdateMaxPerRun`（默认 2）个 update，超限整单拒绝
+- **幂等**：字段已与目标一致时跳过（可重放无副作用）
+- **审计**：`dream_runs` 记录 update 的 `_before` 快照，可回溯变更前内容
+- **向量同步**：update 后删除旧向量、按新内容重嵌入，保持索引一致
+
+### 9.2 失败追踪（failure_memories）
+
+`failure_memories` 表记录记忆纠正/失败事件，为后续反思进化积累数据：
+
+```sql
+CREATE TABLE failure_memories (
+  id TEXT PRIMARY KEY,
+  query TEXT,           -- 用户原始查询/意图（可选）
+  expected TEXT,        -- 期望结果
+  actual TEXT,          -- 实际结果
+  failure_type TEXT,    -- outdated / miss / wrong / user_correction
+  memory_id TEXT,       -- 关联的记忆 id
+  created_at TEXT NOT NULL
+);
+```
+
+- **触发**：用户调用 `memory_update` 且内容变化时，若 `reflectionFailureTracking` 开启则记录 `user_correction` 行（actual=旧值、expected=新值）
+- **查询**：`store.listFailures`（过滤/分页）、`store.getFailureStats`（按类型计数）
+
+### 9.3 配置项
+
+```javascript
+reflectionUpdateEnabled: true,       // update 决策总开关
+reflectionFailureTracking: true,     // 失败追踪总开关
+reflectionUpdateMaxPerRun: 2,        // 每次整理最多 update 数
+reflectionUpdateMinAgeHours: 24      // 新建记忆保护期（小时）
+```

package/docs/SLEEP.md

@@ -0,0 +1,164 @@
+# dsh-mneme Sleep Mode 系统级睡眠设计文档
+
+## 概述
+从被动整理到主动维护：在系统空闲时段自动执行深度记忆压缩、冲突消解、模式发现与关系补全，实现知识库的长效健康治理。
+
+## 动机与设计原则
+- **非侵入性**：仅在用户空闲（Idle）时触发，不干扰正常读写与实时推理。
+- **可中断**：用户一旦产生活动，立即中止当前睡眠周期，保障实时体验。
+- **分层压缩**：按访问热度与时间衰减进行阶梯式降级，保留核心语义，释放存储压力。
+- **模式发现**：利用 LLM 挖掘长期记忆中的隐性规律，生成结构化 Pattern 实体。
+- **审计延续**：与 `autoDream` 共享 `dream_runs` 审计表，通过 `run_type` 区分，保障全链路可追溯。
+
+## 架构图
+```mermaid
+flowchart TD
+    User[用户写入/读取] -->|noteWrite| Scheduler[SleepScheduler]
+    Scheduler -->|clearTimeout + 重置计时器| Timer[Idle Timer]
+    Timer -->|>= sleepIdleMinutes| Check[maybeSchedule]
+    
+    Check -->|条件满足| Queue[service.enqueue]
+    Check -->|条件不满足| Wait[等待下一次 noteWrite]
+    
+    subgraph Sleep Run [串行执行]
+        Q[Queue] --> P1[Phase 1: conflict_resolution]
+        P1 --> P2[Phase 2: archival_demotion]
+        P2 --> P3[Phase 3: pattern_discovery]
+        P3 --> P4[Phase 4: relation_completion]
+    end
+    
+    P4 -->|独立 try/catch 隔离| Receipt[buildReceipt]
+    Receipt -->|saveDreamRun run_type='sleep'| Audit[(dream_runs)]
+    
+    User -->|活动触发| Abort[AbortController.abort]
+    Abort -->|中断当前 Run| Scheduler
+    
+    AutoDream[autoDream 实时轻量触发] -.共享队列不重叠.-> Queue
+```
+
+## 配置项说明
+| 配置项 | 默认值 | 说明 |
+|:---|:---|:---|
+| `sleepModeEnabled` | `false` | 全局开关（Opt-in），开启后激活调度器 |
+| `sleepIdleMinutes` | `5` | 连续无操作触发睡眠的阈值（分钟） |
+| `sleepMinIntervalHours` | `8` | 两次 Sleep Run 的最小时间间隔（小时） |
+| `sleepConflictStrictness` | `'normal'` | 冲突消解严格度：`'gentle'`(0.92) / `'normal'`(0.85) / `'aggressive'`(0.75) |
+| `sleepArchiveDays` | `30` | 进入冷存储/摘要降级的天数阈值 |
+| `sleepCompressDays` | `90` | 进入完全归档（Archive）的天数阈值 |
+| `sleepPatternMinMemories` | `100` | 模式发现阶段扫描的最近记忆条数下限 |
+| `sleepPatternLookbackDays` | `30` | 模式发现回溯的时间窗口（天） |
+| `sleepMaxPatternPerRun` | `3` | 单次运行最多创建的模式数量上限 |
+| `sleepProvider` | `''` | 睡眠模式专用 LLM Provider（留空则复用默认） |
+| `sleepModel` | `''` | 睡眠模式专用 LLM Model（留空则复用默认） |
+| `sleepReasoningEffort` | （未配置） | 睡眠 LLM 推理强度透传：`off` / `low` / `medium` / `high` / `none`。未配置 = 自动取模型支持的最低档（#135：避免思考模型用自带默认档烧光预算返回空体）；显式 `none` = 不传该字段，使用模型默认（与 `dreamReasoningEffort` 语义一致） |
+| `sleepMaxTokens` | `8192` | 冲突消解与模式发现阶段的 LLM 输出预算上限（token，#257：原硬编码 2048——`sleepActionSet: full` 实测 24 对需约 7000，截断即整轮裁决失败）。流式计费按实际用量，调大不增加成本 |
+
+## 四阶段详解
+每个阶段独立包裹 `try/catch`，任一阶段失败仅跳过该阶段，不阻塞后续流程。
+
+### 1. `conflict_resolution`（冲突消解）
+- **目标**：清理向量空间中的重复、矛盾或过时记忆。
+- **输入**：全量/增量记忆向量索引、`sleepConflictStrictness` 阈值。
+- **算法**：
+  1. 向量检索 `findPotentialConflicts` 获取高相似度对。
+  2. LLM 仲裁：基于严格度阈值生成 `keep/merge/discard` 决策。
+  3. `validateDecisions`：严格校验决策合法性，缺省策略为 `keep`。
+  4. `applyDecisions`：批量执行状态变更。
+- **输出**：冲突消解报告（决策明细）。
+- **验收**：无合法记忆被误删；仲裁结果符合配置的严格度阈值；决策可回滚。
+
+### 2. `archival_demotion`（归档降级）
+- **目标**：按时间衰减对记忆进行分层压缩，释放热存储压力。
+- **输入**：`last_accessed_at` 排序的记忆列表、`sleepArchiveDays`、`sleepCompressDays`。
+- **算法**（纯规则、无 LLM，确定性执行）：
+  - `>= sleepCompressDays`：调用 `setArchived` 完全归档。
+  - `>= sleepArchiveDays && < sleepCompressDays`：调用 `demoteToSummary(m.id, 摘要, {minRefTimeMs: archiveCut})` 转为摘要态——原内容存入 `_full_content`，摘要由前 120 字截断生成（LLM 未配置时的 fallback）。
+  - `< sleepArchiveDays`：保持原状不动。
+  - **minRefTimeMs 关键点**：传入快照时刻 `archiveCut`，`demoteToSummary` 在事务内复查 `last_accessed_at`——快照后被召回 touch 的记忆视为"重新活跃"，跳过不降级。
+- **输出**：降级操作清单与状态快照。
+- **验收**：严格遵循分层阈值；`minRefTimeMs` 机制生效，防止快照后 `touch` 导致的误降级；摘要保留 `_full_content` 可无损恢复。
+
+### 3. `pattern_discovery`（模式发现）
+- **目标**：从近期记忆中提炼可复用的隐性规律或知识模式。
+- **输入**：最近 `sleepPatternLookbackDays` 内的 `sleepPatternMinMemories` 条记忆。
+- **算法**：
+  1. LLM 扫描分析，提取候选模式。
+  2. **证据校验**：强制 `evidence` 列表与数据库真实 ID 求交集（`intersect`），过滤伪造/幻觉引用。
+  3. 输出 `type=pattern` 创建指令，受 `sleepMaxPatternPerRun` 限制。
+- **输出**：新创建的 Pattern 实体及关联证据链。
+- **验收**：无孤立证据；Pattern 创建数不超上限；证据 100% 可溯源。
+
+### 4. `relation_completion`（关系补全）
+- **目标**：修复知识图谱中的断链与孤立节点。
+- **输入**：`listEntities` 获取的实体列表、关系图谱。
+- **算法**：
+  1. 筛选 `getRelations` 返回为空的孤立实体。
+  2. 基于上下文推断关系：
+     - 语义/实体共现 → `related_to`
+     - 同属项目/模块 → `part_of`
+     - 技术栈/流程依赖 → `depends_on`
+  3. 批量写入关系边。
+- **输出**：新增关系边列表。
+- **验收**：关系推断符合领域常识；不引入循环依赖；图谱连通性提升。
+
+## 分层压缩策略表
+| 记忆层级 | 判定条件 (`last_accessed_at`) | 处理策略 | 存储形态 |
+|:---|:---|:---|:---|
+| **活跃 (Active)** | `< sleepArchiveDays` | 保持原状，正常搜索可见 | 全文索引 + 向量 |
+| **冷 (Cold)** | `>= sleepArchiveDays` 且 `< sleepCompressDays` | `demoteToSummary` 压成摘要，原文进 `_full_content` | 摘要 + `_full_content` 分离 |
+| **睡眠 (Archived)** | `>= sleepCompressDays` | `setArchived` 移出热查询域 | 仅保留元数据与归档标记 |
+
+## 调度器与可中断机制
+- **`noteWrite()` 心跳重置**：每次用户写入/读取记忆时触发。必须先 `clearTimeout` 清除旧计时器，再重新设置 Idle Timer，彻底杜绝 Stale Timer 导致的误触发。
+- **`maybeSchedule()` 准入控制**：串行检查 `sleepModeEnabled` → 空闲时长 `>= sleepIdleMinutes` → 距上次运行 `>= sleepMinIntervalHours` → 状态非 `running/disposed`。任一不满足则放弃调度。
+- **`service.enqueue` 串行队列**：所有 Sleep Run 必须进入全局串行队列执行，与 `autoDream` 严格互斥，避免并发写入冲突与资源争抢。
+- **`AbortController` 可中断**：调度器持有 AbortController 实例。一旦检测到用户活动（`noteWrite` 或显式交互），立即调用 `abort()` 中断当前 `runSleep` 的执行上下文，保证实时性优先。
+
+## 数据迁移与存储层变更
+- **幂等迁移**：
+  - `memories` 表新增列：`last_accessed_at` (DATETIME)、`_full_content` (TEXT/BLOB)。
+  - `dream_runs` 表新增列：`run_type` (VARCHAR, 默认 'auto'，用于区分 'sleep')。
+  - 迁移脚本需保证幂等（`IF NOT EXISTS` / 检查列是否存在）。
+- **Store 新增方法**：
+  - `demoteToSummary(id, summary, opts)`：执行降级并记录 `minRefTimeMs`。
+  - `restoreContent(id)`：按需从归档/摘要恢复原文。
+  - `touchLastAccess(id)`：更新 `last_accessed_at` 至当前时间。
+  - `getUnrecalledSince(days)`：按时间窗口拉取未召回记忆。
+  - `listEntities()`：获取实体列表用于关系分析。
+- **Service 扩展**：
+  - `enqueue(task)`：串行任务队列入口。
+  - `setSleepHook(fn)`：注入 `noteWrite` 钩子。
+  - `touchRecalled(id)`：在召回路径中自动更新访问时间。
+
+## 与 autoDream 的协作关系
+| 维度 | autoDream (实时) | Sleep Mode (系统级) |
+|:---|:---|:---|
+| **触发时机** | 写入阈值/实时事件 | 系统空闲 + 定时周期 |
+| **执行深度** | 轻量级、局部关联补全 | 深度扫描、全局压缩与模式提炼 |
+| **资源占用** | 低延迟、短时 | 允许较高延迟、长时运行 |
+| **队列关系** | 共享 `service.enqueue` 串行队列 | 共享 `service.enqueue` 串行队列（严格互斥不重叠） |
+| **审计记录** | 共用 `dream_runs`，`run_type='auto'` | 共用 `dream_runs`，`run_type='sleep'` |
+
+## 实现要点与避坑（v0.4.1 教训）
+1. **Stale Timer 防护**：`noteWrite()` 中必须严格遵循 `clearTimeout(oldTimer) -> setNewTimer()` 顺序，否则快速连续写入会累积多个 Timer 导致频繁误触发。
+2. **`minRefTimeMs` 防误降级**：调用 `demoteToSummary` 时必须传入快照时刻 `{minRefTimeMs: archiveCut}`。否则在 Sleep Run 执行期间被用户 `touch` 的记忆会因时间窗口漂移被错误降级。
+3. **证据强过滤**：Pattern Discovery 阶段 LLM 返回的 `evidence` 必须与 DB 真实 ID 列表求交集。未通过 `intersect` 校验的证据一律丢弃，严防幻觉伪造关联。
+4. **严格串行化**：所有 Sleep Run **必须**走 `service.enqueue`。禁止直接调用异步函数启动，确保与 `autoDream` 绝对不重叠，避免写入锁冲突。
+5. **Fail-Safe 阶段隔离**：四阶段必须各自独立 `try/catch`。LLM 服务抖动或网络异常时，仅跳过当前阶段（如跳过 Pattern 发现），后续阶段（如 Demotion、Relation）必须继续执行并记录 Receipt。
+6. **无 LLM 降级路由**：当 `resolveSleepRoute` 返回 `undefined`（如 Provider 未配置或模型不可用）时，系统应自动跳过所有依赖 LLM 的阶段，但 `archival_demotion`（纯规则）仍需照常执行，保障基础压缩能力不丢失。
+
+## 测试清单
+- [ ] **调度器**：验证 `sleepIdleMinutes` 触发准确性；验证 `clearTimeout` 防 Stale；验证 `sleepMinIntervalHours` 冷却生效。
+- [ ] **中断机制**：运行中触发 `noteWrite`，验证 `abort()` 立即终止 Run 且状态回滚至安全点。
+- [ ] **阶段隔离**：Mock LLM 500 错误，验证仅对应阶段跳过，Receipt 仍生成且 `run_type='sleep'`。
+- [ ] **降级策略**：构造不同 `last_accessed_at` 的记忆，验证 `minRefTimeMs` 防误降级逻辑及分层归档正确性。
+- [ ] **模式发现**：注入含虚假 ID 的 LLM 响应，验证 `intersect` 过滤生效且创建数 `<= sleepMaxPatternPerRun`。
+- [ ] **迁移幂等**：重复执行迁移脚本，验证无报错、无重复列/数据。
+- [ ] **队列互斥**：并发触发 `autoDream` 与 Sleep，验证 `service.enqueue` 串行执行无重叠。
+
+## 启用指南（Opt-in）
+1. **配置开启**：在 `config.js` 或环境变量中设置 `sleepModeEnabled: true`。
+2. **资源评估**：建议生产环境配置独立的 `sleepProvider` 与 `sleepModel`，避免与实时推理争抢额度/并发。
+3. **初始运行**：首次启用后，系统将在首次空闲 `>= sleepIdleMinutes` 时触发全量扫描。可通过查看 `dream_runs` 表中 `run_type='sleep'` 的记录监控执行结果。
+4. **调优建议**：初期可设置 `sleepConflictStrictness: 'gentle'`，观察 `conflict_resolution` 决策准确率后再逐步收紧至 `'normal'` 或 `'aggressive'`。
+5. **关闭恢复**：设置 `sleepModeEnabled: false` 后，调度器将在 `dispose()` 阶段清理 Timer 并释放 Hook，已归档数据可通过 `restoreContent` 按需恢复。