@modusensus/dsh-mneme 0.7.0 → 0.7.2

package/dsh-mneme/docs/MIGRATION.md

@@ -1,127 +0,0 @@
-# dsh-mneme v0.3.x → v0.4.0（系统级睡眠 Sleep Mode）升级说明
-
-- **日期**：2026-08-17
-- **适用范围**：从 v0.3.9（审计加固）升级到 v0.4.0（Sleep Mode）
-- **目标**：**零配置迁移、零数据损失**。升级后默认不启用 Sleep（opt-in），原行为完全不变。
-
-## 1. 数据兼容（自动迁移，无需手工操作）
-
-### 1.1 SQLite 记忆库
-
-- **memories 表新增两列**（幂等迁移，`PRAGMA table_info` 检查 + `ALTER TABLE ... ADD COLUMN`）：
-  - `last_accessed_at TEXT` — 最后召回时间戳（搜索/注入路径自动 touch）
-  - `_full_content TEXT` — 冷记忆降级时的原文存档（压缩后内容可在原处恢复）
-- **dream_runs 表新增一列**：`run_type TEXT NOT NULL DEFAULT 'auto'` — `auto`（autoDream）/ `sleep`（睡眠周期）审计区分
-- 已有数据不受影响；降级/归档只在 `sleepModeEnabled: true` 后按阈值触发
-
-### 1.2 镜像与审计
-
-- Markdown 镜像格式不变；`demoteToSummary`/`restoreContent` 走正常写钩子（镜像重渲染），`touchLastAccess` 是读戳（不触发写钩子，避免脏镜像）
-- 既有 `dream_runs` 审计记录保留；睡眠周期新增 `run_type='sleep'` 记录，与 autoDream 共用审计表
-
-## 2. 配置变更（全部 opt-in）
-
-### 2.1 新增配置项
-
-| 键 | 默认值 | 说明 |
-|----|--------|------|
-| `sleepModeEnabled` | `false` | 总开关，开启后才激活睡眠调度器 |
-| `sleepIdleMinutes` | `5` | 连续空闲多少分钟触发睡眠周期 |
-| `sleepMinIntervalHours` | `8` | 两次睡眠周期的最小间隔（小时） |
-| `sleepConflictStrictness` | `'normal'` | 冲突消解严格度：`gentle`(0.92) / `normal`(0.85) / `aggressive`(0.75) |
-| `sleepArchiveDays` | `30` | 多少天未召回 → 压成摘要（`_full_content` 存档） |
-| `sleepCompressDays` | `90` | 多少天未召回 → 完全归档 |
-| `sleepPatternMinMemories` | `100` | 模式发现扫描的最近记忆条数 |
-| `sleepPatternLookbackDays` | `30` | 模式发现回溯天数 |
-| `sleepMaxPatternPerRun` | `3` | 单次睡眠周期最多产出的模式数 |
-| `sleepProvider` / `sleepModel` | `''` | 睡眠专用 LLM 路由（留空复用默认） |
-
-### 2.2 行为变更说明
-
-- **零配置升级**：不设任何 sleep 配置 → 与 v0.3.9 行为完全一致，无新增后台任务
-- **首次启用**：设 `sleepModeEnabled: true` 后，系统空闲 `sleepIdleMinutes` 分钟触发首次深度维护
-- **推荐起步**：`sleepConflictStrictness: 'gentle'` 观察裁决质量后再收紧
-
----
-
-# dsh-mneme v0.1 → v0.2（语义增强）升级说明
-
-- **日期**：2026-08-15
-- **适用范围**：从 npm `@modusensus/dsh-mneme` v0.1.x（LIKE 搜索 + 可选 OpenAI 兼容向量）升级到 v0.2（本地语义引擎）
-- **目标**：**零配置迁移、零数据损失**。升级后不设置任何新配置项，行为与 v0.1 完全一致；想要本地语义能力只需新增几行配置。
-
-## 1. 数据兼容（自动迁移，无需手工操作）
-
-### 1.1 SQLite 记忆库
-
-- **不重建、不导出**：沿用同一 `~/.dsh/memory/memory.db`，现有 `memories` 表直接复用
-- **schema 迁移幂等**：v0.1 已通过 `PRAGMA table_info` 检查 + `ALTER TABLE ... ADD COLUMN` 幂等补齐 `embedding` / `archived` 等列；v0.2 沿用同一机制，重复启动/旧版本回退都不会重复加列或破坏数据
-- **现有向量兼容**：`memories.embedding` 存 JSON 向量（TEXT 列），v0.2 直接读取，已嵌入的记忆**无需重新嵌入**
-- **用户设置保留**：v0.1 在 `user_settings` 表配置的向量端点（baseUrl/apiKey/model）保留，作为降级路径继续可用
-
-### 1.2 Markdown 镜像
-
-- 五个 `.md` 镜像文件（`preferences.md` / `projects.md` / `decisions.md` / `history.md` / `summary.md`）格式不变，双向同步、人工优先的规则不变
-- 升级后首次启动仍执行"读取人工编辑 → 合并回库"，无竞态（先全量读取再统一合并）
-
-### 1.3 dream_runs 审计表
-
-- 既有审计记录保留；新格式与 v0.1 兼容（snapshot digest + 决策清单 + receipt），无需迁移
-
-## 2. 配置变更
-
-### 2.1 新增配置项
-
-| 键 | 默认值 | 说明 |
-|----|--------|------|
-| `embedProvider` | `openai` | 嵌入后端：`local`（ONNX）\| `ollama` \| `openai` |
-| `embedModel` | 空 | 模型名：local=HF 模型 id（`Xenova/bge-small-zh-v1.5`），ollama=Ollama 模型，openai=API 模型 |
-| `embedDimension` | 空 | 向量维度；不填则按后端推断（local 默认 512，ollama/openai 首次响应推断） |
-| `embedDevice` | `cpu` | 仅 local 生效：`cpu` \| `wasm` \| `gpu` |
-| `embedBatchSize` | `8` | 分批嵌入条数（local/openai 生效） |
-| `embedCacheDir` | `""` | 仅 local 生效：模型缓存目录，空=HF 默认缓存 |
-| `embedBaseUrl` | `""` | ollama 默认 `http://localhost:11434`；openai 必填 |
-| `embedApiKey` | `""` | 仅 openai 生效 |
-| `rerankEnabled` | `false` | 是否启用 Rerank 精排（Phase 2） |
-| `rerankModel` | `Xenova/bge-reranker-base` | Rerank 模型 |
-
-### 2.2 默认值 = 保持 v0.1 行为
-
-- `embedProvider` 默认 `openai`，且 `embedBaseUrl` / `embedApiKey` / `embedModel` 为空时，**行为与 v0.1 完全一致**：使用 `user_settings` 表里通过 Web/API 配置的 `vector-config`（若配置过），否则 LIKE 关键词搜索
-- 也就是说：**什么都不改，升级后一切照旧**；想让语义搜索离线化，把 `embedProvider` 改成 `local` 或 `ollama` 即可
-
-### 2.3 行为变化
-
-| 场景 | v0.1 | v0.2 |
-|------|------|------|
-| 未配置任何向量 | LIKE 子串搜索 | LIKE 子串搜索（不变） |
-| 配置 OpenAI 兼容端点 | 调 `/embeddings`，失败返回 null 静默 | 同，但 `OpenAIEmbedder` 批量嵌入、抛错由降级链处理 |
-| 本地模型 | 不支持 | `embedProvider: local` / `ollama` |
-| 向量初筛结果 | 直接返回 | 可经 `rerankEnabled` 精排后返回 |
-| 搜索模式 | `auto` / `keyword` / `vector` | 不变，`auto` 新增混合召回 |
-
-## 3. 向后兼容保证
-
-1. **数据兼容**：SQLite、Markdown 镜像、审计表全部沿用，升级与回退都不丢数据
-2. **配置兼容**：v0.1 的全部配置键（`memoryDir`、`autoInject`、`autoDream` 等）不变；新增键全部带默认值
-3. **API 兼容**：`memory_*` 工具、Web 面板路由、`vector-config` 端点不变；`memory_search` 返回结构不变（额外多出可选 `score`）
-4. **降级兼容**：本地 Embedder 加载失败 / 下载失败 / 推理异常，自动降级到 Ollama → OpenAI → LIKE 关键词，**任何失败都不阻断记忆读写**
-5. **索引一致**：`modelHash` 与向量维度不匹配时拒绝混算，提示重建索引（不静默产生错误结果）
-6. **回滚安全**：卸载 v0.2 装回 v0.1.x，库文件仍可正常读写（v0.1 能识别 `embedding` 列）
-
-## 4. 升级步骤
-
-```bash
-# 1. 升级插件
-dsh plugin --profile web update @modusensus/dsh-mneme
-
-# 2. （可选）启用本地语义：编辑 ~/.dsh/profiles/web/cordis.patch.yml
-#    - id: dsh-mneme
-#      config:
-#        embedProvider: local
-#        embedModel: Xenova/bge-small-zh-v1.5
-
-# 3. 重启并验证
-dsh web
-# 首次本地使用自动下载模型；确认日志出现 "local embedder ready"
-```

package/dsh-mneme/docs/SEMANTIC.md

@@ -1,256 +0,0 @@
-# dsh-mneme 语义增强架构 — 设计文档
-
-- **日期**：2026-08-15
-- **状态**：进行中（分支 `feat/local-semantic`）
-- **范围**：为 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`）：
-
-```
-                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 行为）、`embedModel`、`embedDimension`、`embedDevice`、`embedBatchSize`、`embedCacheDir`、`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/dsh-mneme/docs/SLEEP.md

@@ -1,163 +0,0 @@
-# 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（显式优先，留空回退 `dreamProvider` → agent 默认） |
-| `sleepModel` | `''` | 睡眠模式专用 LLM Model（同上回退顺序） |
-| `sleepReasoningEffort` | `'none'` | 睡眠 LLM 推理强度透传：`low` / `medium` / `high` / `none`。`none`（默认）= 不传该字段，使用模型默认；思考型模型预算被推理耗尽时可设 `low`（与 `dreamReasoningEffort` 语义一致） |
-
-## 四阶段详解
-每个阶段独立包裹 `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` 按需恢复。