@modusensus/dsh-mneme 0.8.13 → 0.8.15

package/bin/dsh-mneme-serve.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// bin/dsh-mneme-serve.mjs —— mneme 独立服务(daemon)入口。
+//
+// 为什么独立成 bin 而不是 cli.mjs 的子命令:CONTRIBUTING「The CLI is dependency-free
+// by contract」禁止给 bin/cli.mjs 加 import,而 serve 必须挂载 lib/serve.js;命名循
+// dsh-mneme-mcp 先例。数据面 = src/api-standalone.js 同一工厂,路由与鉴权零新面。
+//
+// 生命周期:bind 失败(含 strictPort 下端口被占)→ stderr 清错 + exit 1;
+// SIGINT/SIGTERM → dispose + exit 0。Windows 下 kill() 是硬终止、handler 不跑:
+// 已提交事务由 WAL 回放兜底(node:sqlite 未 finalize 语句的 close 抛错同理),不丢数据。
+//
+// 日志纪律:进度/错误全走 stderr;stdout 只在就绪时打一行机器可读的 listening 行
+// (脚本/测试从中解析实际端口),其余时刻保持干净——serve 是常驻进程,stdout 常被
+// 重定向进监控管道。
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { createServeRuntime } from "../lib/serve.js";
+
+const BIN_NAME = "dsh-mneme-serve";
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const PKG = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
+
+const USAGE = `${BIN_NAME} — run the mneme data plane as a standalone service (no DSH required)
+
+Usage: dsh-mneme-serve [--memory-dir <dir>] [--port <n>] [--host <addr>] [--embed <provider>]
+
+Options:
+  --memory-dir <dir>  data directory (default: ~/.dsh/memory, same as the plugin)
+  --port <n>          HTTP port (default: persisted external_api port, else 8790)
+  --host <addr>       bind address (default: persisted external_api host, else 127.0.0.1)
+  --embed <provider>  semantic retrieval: local (default, downloads the ONNX runtime
+                      + embedding model on first boot) | ollama | openai (uses the
+                      vector-config saved by the DSH panel) | off (keyword + BM25 only)
+  -h, --help          show this help
+  -V, --version       print version
+
+Auth: Bearer token is shared with the DSH panel / CLI (kv "external_api" in
+memory.db); it is generated on first boot. A busy configured port is a hard
+error — the DSH external API and this daemon must not share a port (pick one).
+
+Environment (runtime provisioning, local provider only):
+  DSH_MNEME_MEMORY_DIR            data directory override
+  DSH_MNEME_RUNTIME_DIR           self-managed runtime dir (default ~/.dsh/mneme/runtime)
+  DSH_MNEME_RUNTIME_TARBALL_DIR   offline .tgz dir preferred over the network
+  DSH_MNEME_RUNTIME_MIRROR        npm registry mirror prefix (e.g. npmmirror)`;
+
+/** 极简 argv 解析(--k=v / --k v / 旗标);够用即可,完整 CLI 在 bin/cli.mjs。 */
+function parseArgv(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") out.help = true;
+    else if (a === "-V" || a === "--version") out.version = true;
+    else if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq > -1) out[a.slice(2, eq)] = a.slice(eq + 1);
+      else {
+        const v = argv[i + 1];
+        // 本 bin 的旗标全部取值（无泛用布尔旗标）：值缺失或下一个 token 是旗标
+        // 都按「缺值」报错退出——不能落成 true（Number(true)=1 会把 --port 变成
+        // 绑端口 1，报 EACCES 让用户查错方向）。帮助/版本在上方分支已提前返回。
+        if (v !== undefined && !v.startsWith("-")) { out[a.slice(2)] = v; i++; }
+        else fail(`${a} 缺少参数值`);
+      }
+    } else {
+      fail(`未知参数: ${a}\n运行 \`${BIN_NAME} --help\` 查看用法。`);
+    }
+  }
+  return out;
+}
+
+function fail(msg) {
+  console.error(`[${BIN_NAME}] ${msg}`);
+  process.exit(1);
+}
+
+// api-standalone 的 logger 契约:info/warn/error 收单字符串。全走 stderr(见头部纪律)。
+const logger = {
+  info: (msg) => console.error(`[dsh-mneme] ${msg}`),
+  warn: (msg) => console.error(`[dsh-mneme] warn: ${msg}`),
+  error: (msg) => console.error(`[dsh-mneme] error: ${msg}`)
+};
+
+async function main(argv) {
+  const args = parseArgv(argv);
+  if (args.help) { process.stdout.write(USAGE + "\n"); return; }
+  if (args.version) { console.log(PKG.version); return; }
+
+  // memoryDir:CLI > env > serve.js 缺省(~/.dsh/memory)。相对路径按 CWD 解;
+  // 前导 ~ 留给 serve.js 展开(与宿主 index.js:192-194 同一口径)。
+  const rawDir = typeof args["memory-dir"] === "string" ? args["memory-dir"]
+    : (typeof process.env.DSH_MNEME_MEMORY_DIR === "string" && process.env.DSH_MNEME_MEMORY_DIR ? process.env.DSH_MNEME_MEMORY_DIR : undefined);
+  const memoryDir = rawDir && !rawDir.startsWith("~") ? resolve(rawDir) : rawDir;
+
+  let port;
+  if (args.port !== undefined) {
+    port = Number(args.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+      fail(`--port 需要合法端口(0-65535),收到: ${args.port}`);
+    }
+  }
+  const host = typeof args.host === "string" && args.host ? args.host : undefined;
+
+  let embed = "local";
+  if (args.embed !== undefined) {
+    if (typeof args.embed !== "string" || !["off", "local", "ollama", "openai"].includes(args.embed)) {
+      fail(`--embed 需要 off|local|ollama|openai,收到: ${String(args.embed)}`);
+    }
+    embed = args.embed;
+  }
+
+  let rt;
+  try {
+    // 装配是异步的:embed=local 时可能要先取件 runtime(download 档,失败内部降级)
+    rt = await createServeRuntime({ memoryDir, port, host, logger, embed });
+  } catch (err) {
+    fail(`启动失败: ${err?.message ?? err}`);
+  }
+  try {
+    await rt.api.ready;
+  } catch (err) {
+    fail(`数据面启动失败: ${err?.message ?? err}\n` +
+      `  端口 ${rt.api.port} 被占通常意味着另一个 mneme 数据面正在运行` +
+      `(DSH 的「外部访问」或另一份 ${BIN_NAME})——二选一,或用 --port 换端口。`);
+  }
+  const addr = rt.api.server.address();
+  // stdout 唯一一行:机器可读就绪行(测试/脚本解析端口用)。
+  console.log(`${BIN_NAME} listening on http://${addr?.address ?? rt.api.host}:${addr?.port ?? rt.api.port} (pid ${process.pid})`);
+  if (!rt.tokenExisted) {
+    console.error(`[dsh-mneme] 首次启动已生成 Bearer token(已持久化,与 DSH 面板/CLI 共用):\n` +
+      `  ${rt.api.token}`);
+  }
+
+  let closing = false;
+  const shutdown = async (signal) => {
+    // 第二次信号 = 强制退出（dispose 里 server.close 等 in-flight 收尾，极端情况下会挂）
+    if (closing) process.exit(0);
+    closing = true;
+    console.error(`[dsh-mneme] ${signal} received, closing...`);
+    try { await rt.dispose(); } catch { /* dispose 各步自吞 */ }
+    process.exit(0);
+  };
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err?.stack ?? String(err));
+  process.exit(1);
+});

package/cordis.patch.yml

@@ -1,21 +1,21 @@
-# dsh-mneme bundle patch — the layer applied when a profile lists this bundle.
-# Installed via: dsh plugin --profile <name> add @modusensus/dsh-mneme
-- insert:
-    - id: dsh-mneme
-      name: '@modusensus/dsh-mneme'
-      config:
-        memoryDir: ~/.dsh/memory
-        autoInject: true
-        autoSummarize: true
-        maxInjectedItems: 5
-        importanceThreshold: 3
-        autoDream: true
-        dreamThresholdCount: 10
-        dreamThresholdChars: 5000
-        dreamDelayMs: 2000
-        # 巩固默认压低推理：思考型模型（如方舟 v4 系）会把 dreamMaxTokens
-        # 预算花在推理上、正文空体 → "no json array in llm output"。low 让
-        # provider 封顶推理；拒绝 effort 字段的 provider 由 runAuditedLlm
-        # 自动去掉重试，行为安全（v0.7.16 机制）。
-        dreamReasoningEffort: low
-        entityExtractionEnabled: true
+# dsh-mneme bundle patch — the layer applied when a profile lists this bundle.
+# Installed via: dsh plugin --profile <name> add @modusensus/dsh-mneme
+- insert:
+    - id: dsh-mneme
+      name: '@modusensus/dsh-mneme'
+      config:
+        memoryDir: ~/.dsh/memory
+        autoInject: true
+        autoSummarize: true
+        maxInjectedItems: 5
+        importanceThreshold: 3
+        autoDream: true
+        dreamThresholdCount: 10
+        dreamThresholdChars: 5000
+        dreamDelayMs: 2000
+        # 巩固默认压低推理：思考型模型（如方舟 v4 系）会把 dreamMaxTokens
+        # 预算花在推理上、正文空体 → "no json array in llm output"。low 让
+        # provider 封顶推理；拒绝 effort 字段的 provider 由 runAuditedLlm
+        # 自动去掉重试，行为安全（v0.7.16 机制）。
+        dreamReasoningEffort: low
+        entityExtractionEnabled: true

package/docs/CONFIGURATION.md

@@ -0,0 +1,263 @@
+# 配置说明（全键参考）
+
+> 正本是 `src/config.js` 的 schema——本文与其同步维护，键名、默认值、取值范围以代码为准；
+> 行为动机与踩坑出处在 schema 注释里（含 issue 编号），本文只保留「怎么配、配了会怎样」。
+> 改 schema 时顺手更新对应行（新改动自查清单第 2 条）。
+
+**怎么读这张表**
+
+- 「默认」列即 `config.js` schema 的解析默认值；默认值本身 = 未配置时的行为。
+- 标 **light** 的键会被 lightMode 预设强制关闭（文末附完整清单）；lightMode 是预设不是
+  强制——用户显式写在 feature_flags 里的值优先于预设。
+- 行为开关（布尔键）默认关的即 opt-in：不开 = 行为与该键存在之前逐字节一致。
+- 绝大多数行为开关与部分阈值/路由键在 `settings.js` 的白名单里，可在面板「功能开关」
+  逐项启停（线上回滚开关）；未入白名单的键（路径、词典、枚举外的杂项）只能改 bundle 配置。
+
+## 全局与存储
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `language` | `zh` | 记忆语言：生成条目、注入标题、后台提示词所用语言（`zh`/`en`） | 切换后重启生效 |
+| `memoryDir` | `~/.dsh/memory` | SQLite 记忆库目录 | WAL + busy_timeout 已为多进程就绪；两个宿主共用库时 `externalApiEnabled` 与 `autoDream` 只能一边开 |
+| `lightMode` | `false` | 轻量档总闸：一键关掉全部重型路径，保留核心循环（见文末清单） | 面板 `panel_mode=light` 等效为 `true` 且优先于 bundle 配置 |
+
+## scope 隔离（issue #17）
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `scopeEnabled` | `false` | 存储层总开关：写入标注 agent_scope / workspace_scope，去重键扩展；检索与注入排序按当前会话作用域加权（命中 ×1.25、他 scope ×0.5 保留可见，issue #339 补齐注入通道） | opt-in；关 = 写入不标注、行为与 A1 前逐字节一致 |
+| `strictScope` | `false` | 硬过滤模式（A3）：他 scope 完全不可见、未标注恒可见（fail-closed）；硬过滤先于软加权执行 | 依赖 `scopeEnabled` 打开才有意义；关 = A2 软隔离（他 scope 降权保留可见，检索与注入同权重） |
+
+## 审计
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `llmAudit.enabled` | `true` | 后台 LLM 调用全量落 `llm_audit_logs`（tokens / 时长 / 状态 / 触发源） | 覆盖 autoDream / autoSummarize / sleep / entityExtract 与写入准入测量点；关 = 一行不写 |
+| `llmAudit.retentionDays` | `90` | 审计表滚动清理保留天数（≤3650） | 启动时清理旧行 |
+
+## 写入准入（#254）
+
+写入前判定「这条该不该进库」，与 `memoryQualityFilter` 的分工是**时点**不是判据：那个是写入后打分归档（扣分可以错，只影响排序与归档），这个是写入前判定（硬拒不能错）。两个键都默认关，分层是为了把「先观察」和「开始拦」分成两次上线。
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `writeAdmission.enabled` | `false` | 跑第 1 级确定性判据：空白 / 纯噪声 + 密钥 / PII（判据来源是 #164 A2，经 `sensitiveScan` 注入） | 关 = 不判定、不拒绝，`evaluate` 返回与只计量阶段逐字段一致。命中 → 审计行带 `metadata.deny` |
+| `writeAdmission.enforce` | `false` | 命中时真的拒绝（`store.save` 之前返回） | 关 = 仅告警：判据照跑、审计照留、写入不拦（读审计时「`deny` 非空且 `decision=allow`」即这一档的指纹）。被拒写入不落库、不通知、不排嵌入，`memory_save` 返回 `action:"denied"` + `reason` |
+
+第 1 级的判据面刻意收窄：**去重键命中不进第 1 级**（归 write-update 放行——同步近重复门跑在异步矛盾检测之前会把本该被裁决的矛盾直接拒掉），G1/G2 阈值也只是计量。两个键都走 feature_flags 白名单（面板可启停）。
+
+## 注入前判定（#380）
+
+每帧注入候选出池后、进入 system prompt 前，一次**池级** LLM 调用判出「会向本次请求注入意见/立场」的记忆（判定协议与 E12 实验同源；实验依据：D1 判定+过滤把谄媚率 26.9%→2.5%，判定+标记比过滤差 +17.6pp——判定结果**只给闸门用，绝不进模型上下文**）。两级语义与 writeAdmission 同构，落点在注入面而非写入面。
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `preInjectGate.enabled` | `false` | 跑池级判定。判定 async prefetch + cache、渲染帧同步消费（宿主 systemPrompt 渲染是同步回调） | 关 = 注入行为与现状逐字节一致。**冷缓存首帧降级**：新查询的第一帧原样注入，下一轮同 key 渲染生效；判定完成落 `llm_audit_logs`（`trigger_source=preInjectGate`，真实 token 用量，`related_memory_ids`=被标记记忆）——先观察真实负载的意见占比分布 |
+| `preInjectGate.enforce` | `false` | 缓存命中帧真的滤除被标记候选 | 关 = 仅观察：候选集不动。**enforce 无 enabled 时无效果**。pin 池（constraint/preference，#249 逐字保真）与 graphHint 线索行豁免——判定与过滤只作用于一般记忆槽 |
+
+降级路径：判定失败/超时/不可解析 → 本帧原样注入 + 审计行 `degraded:true` 且不缓存（下一帧重试）——防线故障永不阻塞注入；连续失败 3 次熔断一个冷却期（判定器系统性坏掉时不再逐帧花钱，到期自动恢复）。**整池被标记**时放弃本帧 enforce（fail-open）：记忆正文是判定模型的可影响输入，一条指令型记忆不该让整个记忆块静默失明——该形态在审计行里就是 `n_flagged == n_pool`（判定与审计按原样保留，只有滤除让位）。判定 LLM 走 `agentDefaultModel` 当前选择（entity adapter 同款装配，无独立 provider/model 键；审计行带实际模型与用量，无默认模型路由时 `model_id` 落 `unknown` 占位——判定生效就必有账；成本痛了再加覆盖键）。缓存键 = 查询 + 候选 `id:内容` 集，候选集变化（轮换/新记忆）或候选内容被就地修正（`updateMemory`）即重新判定，不吃旧判定；命中刷新序（LRU，容量 8）。`llmAudit.enabled=false` 时本闸不运行（无账目的判定不可见也不该花钱）。lightMode 强制关（LLM-per-turn 附加路径与低资源档互斥）。
+
+## 蒸馏（会话 → 记忆）
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `autoSummarize` | `true` | 会话/回合结束自动蒸馏记忆。E10 EdgeMem 考卷（#339）实测：对「未来才问的具体值」类细节，零 LLM 原样写入保真 100% 而蒸馏丢 17/120——蒸馏的归纳收益在别的口径，二者是并存关系而非替代（原样写入并存的产品化见讨论 #361） | 关 = 只剩工具与命令写入口 |
+| `summarizeProvider` / `summarizeModel` | 空 | 蒸馏专用模型路由 | 两者都非空才生效；空 = 用会话当前模型 |
+| `distillMaxChars` | `24000` | 喂给蒸馏 LLM 的完整转录上限（字符，1000–200000） | 调大更完整、更贵 |
+| `summarizeMinIntervalMinutes` | `0` | 同会话两次蒸馏的最小间隔（分钟，≤10080） | 0 = 不限（#127 节流三键之一） |
+| `summarizeMaxEntriesPerRun` | `0` | 单次蒸馏最多落库条数（≤50） | 0 = 不限 |
+| `summarizeMinWindowChars` | `0` | 窗口可蒸馏文本下限（字符），不足直接跳过 LLM（#239） | 被挡窗口照常消费游标并留 skip 审计 |
+| `summarizeMaxRunsPerSession` | `0` | 每会话蒸馏次数预算，只计真实发起的调用（≤1000） | 0 = 不限；进程内计数，重启清零 |
+| `summarizePeakHours` | `""` | 高峰时段串（`"09:00-18:00"` / `"mon-fri 08:00-12:00,14:00-18:00"`，支持跨零点） | 命中高峰不调 LLM、顺延补跑；任一写法非法整串按未配置处理 |
+| `summarizePeakMaxDeferMinutes` | `120` | 高峰顺延上限（分钟，≤1440） | 0 = 不设上限；到点仍处高峰照跑（bypassPeak） |
+| `summarizeDedupeMode` | `off` | 落库前去重档位：`off` / `title`（拦完全同名）/ `vector`（同会话语义近邻） | `vector` 复用已有 embedding 列，无 LLM 调用 |
+| `summarizeDedupeMinSim` | `0.92` | `vector` 档并入阈值（0.5–0.99） | 仅 `vector` 档生效 |
+| `summarizeDedupeWindowHours` | `24` | `vector` 档回看窗口（小时，≤168） | 仅 `vector` 档生效 |
+| `distillRateLimitIntervalMs` | `1000` | 蒸馏请求全局串行排队的相邻间隔（毫秒） | 0 = 关闭排队（默认开的 429 保护随之失效） |
+| `distillRateLimitRetries` | `3` | 命中 429 的指数退避重试次数（≤10） | 重试全程对用户透明 |
+| `distillRateLimitBaseDelayMs` | `1000` | 429 退避基数（毫秒，100–60000） | 1s→2s→4s… |
+| `summarizeReasoningEffort` | `none` | 蒸馏 LLM 推理档位：`off`/`low`/`medium`/`high`/`none`（#315） | `none` = 不发字段用服务商默认；思考模型建议 `off`/`low` 防推理烧光输出预算 |
+| `codingRetrospect` | `false` | 编码记忆蒸馏：rejected_solution / pitfall / constraint 三类 | opt-in；开启后蒸馏上下文为整轮完整对话 |
+| `codingKeywords` | 内置词表 | 编码任务识别词表（读取侧门控） | 命中才注入编码记忆 |
+| `codingBoostFactor` | `2` | 编码任务时编码记忆的 importance 加权系数（1–5） | — |
+| `memoryQualityFilter.enabled` | `true` | 写入质量打分：≥60 正常 / 30–60 降权 / <30 归档打 low_quality 标 | 归档行仍可显式搜到 |
+| `memoryQualityFilter.archiveThreshold` | `30` | 自动归档线 | 与 `exemptImportance` 联动 |
+| `memoryQualityFilter.degradeThreshold` | `60` | 降权线（注入排序乘 quality_score） | — |
+| `memoryQualityFilter.minContentLength` | `10` | 最短内容长度（字符） | — |
+| `memoryQualityFilter.exemptImportance` | `4` | importance ≥ 此值豁免静默自动归档（#135） | 设 1 = 等效关自动归档 |
+
+## 注入
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `autoInject` | `true` | 每轮自动注入记忆块的父总闸 | 关 = 两个子开关一并失效（持久值保留，不重置） |
+| `maxInjectedItems` | `5` | 注入条数上限（1–20） | — |
+| `importanceThreshold` | `3` | 注入候选的 importance 下限（1–5） | 低于该值的记忆不进注入面 |
+| `injectRotationTurns` | `0` | 跨轮轮换：最近 N 轮注入过的不再优先（#205） | opt-in；会话边界自动重置 |
+| `injectContentMaxChars` | `300` | 单条正文截断上限（60–4000，#164①） | 截断带「上限/原长/全文指引」提示，不静默 |
+| `injectUncertaintyAdaptive` | `false` | 确定性强的话题收缩注入条数（减半、下限 1，#239 第 5 项） | 只做单向收缩，绝不越过 `maxInjectedItems` |
+| `injectGuidanceEnabled` **light** | `true` | 工具描述 + order 150 系统段讲「何时查/何时写」（#249） | `autoInject` 子开关；lightMode 强制关 |
+| `continuityRescueEnabled` **light** | `false` | 压缩边缘双落点：连续性提案落库 + 追加注入（#249 N3） | opt-in（新注入表面）；`autoInject` 子开关；订阅宿主压缩事件，无该时机则降级为持久规则 |
+| `pinnedInjectBudget` | `0` | 约束/偏好 pin 池独立预算（0–5，#249 B1） | 0 = 关；pin 不占 `maxInjectedItems` 名额 |
+| `hotMemoryEnabled` | `true` | 会话近期对话渲染在长期记忆块之前 | — |
+| `hotMemoryRounds` | `5` | 热记忆覆盖最近几轮对话（≤50） | — |
+| `hotMemoryMaxTokens` | `2000` | 热记忆块 token 上限（200–32000） | — |
+| `escapePromptVariables` | `true` | 注入内容连续花括号转义（#162） | 关 = 原样透传（DSH interpolate 可能 throw） |
+
+## 巩固（autoDream）
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `autoDream` **light** | `true` | 阈值触发的后台巩固（LLM 合并/归档/降重） | lightMode 强制关；与 sleepMode 串行、不重叠 |
+| `dreamThresholdCount` / `dreamThresholdChars` | `10` / `5000` | 触发阈值（新增条数 / 字符，双过才跑） | — |
+| `dreamDelayMs` | `2000` | 触发后的延迟（毫秒） | — |
+| `dreamMinIntervalMinutes` | `0` | 两次开跑最小间隔（分钟，≤10080，#89） | 失败/degraded run 也占用；0 = 不限 |
+| `autoDreamFailureBackoff` | `false` | 连续失败指数退避：有效间隔 = 基数 × 2^连败，封顶 30 分钟（#292） | opt-in；基数取 `dreamMinIntervalMinutes`（0 = 无闸可翻倍）；成功一次清零；重启归零 |
+| `dreamPeakHours` | `""` | 巩固错峰，与 `summarizePeakHours` 同一份时段语法（#239） | 命中高峰不做梦、阈值继续累积、留 skip 审计；非法写法按未配置 |
+| `dreamPeakMaxDeferMinutes` | `120` | 巩固顺延上限（分钟） | 0 = 不设上限；到点仍处高峰照跑 |
+| `dreamProvider` / `dreamModel` | 空 | 巩固专用路由（settings「巩固模型」） | 建议非思考模型——思考模型易烧光预算返回空体（#135） |
+| `dreamMaxTokens` | `131072` | 巩固输出预算（256–131072） | 流式计费按实际用量，调大不增加成本 |
+| `dreamReasoningEffort` | 未配置 | 巩固推理档位（同 `summarizeReasoningEffort` 的枚举） | 未配置 = 自动取模型支持的最低档（#135）；显式 `none` = 不发字段 |
+| `dreamSummaryProvider` / `dreamSummaryModel` | 空 | 记忆总览（dream_summarize）专用路由（#258） | 空 = 回落巩固路由；总览输入为全库，建议大 ctx 非思考模型 |
+| `dreamSummaryMaxInputs` | `0` | 总览输入条数硬上限（按 updated_at 倒序取最新 N 条） | 0 = 不设上限（库增长可能撑爆小 ctx 模型） |
+| `dreamMaxSnapshotSize` | `200` | 滑动窗口：每次只巩固最近 N 条（≤1000） | 窗口外旧记忆不进快照 |
+| `dreamCandidateMode` | `window` | 候选集构造：`window` / `hybrid`（并入向量高相似组，#125） | `hybrid` 让该合并的对能碰面；输入成本不随库增长 |
+| `dreamCandidateMax` | `0` | `hybrid` 候选总量上限（≤5000） | 0 = 复用 `dreamMaxSnapshotSize` |
+| `dreamCandidateMinSim` | `0.85` | `hybrid` 判「高相似」的阈值 | 与 sleep normal 档同一个定义 |
+| `dreamMaxArchivePerRun` | `8` | 单轮 archive 决策上限（≤200，#104） | 超限整单拒绝，`dreamSkipInvalid` 不豁免 |
+| `dreamImplicitKeep` | `true` | LLM 未提及的快照记忆自动补 keep | `false` = 恢复严格校验（未覆盖即拒绝整单） |
+| `dreamMinExplicitCoverage` | `0.5` | 显式决策覆盖率下限（0–1） | 防截断输出被隐式 keep 洗白 |
+| `dreamSkipInvalid` | `true` | 跳过单条非法决策、应用合法子集、run 记 degraded（#89） | `false` = 恢复整单拒绝 |
+| `allowCrossTypeMerge` | `false` | 放宽跨类型合并检查 | opt-in；`dreamSkipInvalid` 关时跨类型 merge 直接整单拒绝 |
+| `dreamMergeGuard` | `true` | guarded 类型 merge 护栏（#339/E8）：合并对象命中长保留类型（与 archive 护栏同表：preference/pattern/rejected_solution/constraint/pitfall）的 merge 决策整条跳过——E8 实测巩固损耗里 10/26 条被丢约束已归位 guarded 类型仍被 merge 吃掉 | 默认开（同类压缩管线实测：安全规则被同速压缩后一轮只剩 53%、五轮只剩 10%，全程无报错）；关闭 = guarded 类型的 merge 不再被跳过，「更精炼的摘要」重新成为约束失真的主通道。`dreamSkipInvalid`（默认开）时被跳条目进 `dream_runs.skipped`、run 记 degraded，关闭时整单拒绝 |
+| `dreamNarrativeEnabled` **light** | `false` | dream 期间按共享 tag 聚类合成叙述条（#164 对齐） | opt-in；按需检索、不常驻注入 |
+| `dreamNarrativeMinCluster` | `3` | 成簇门槛（共享同一 tag 的记忆数，2–20） | — |
+| `documentMemoryEnabled` **light** | `false` | document 型记忆：长文档指针行，全文归 agent（#230） | opt-in；注册校验 + C2 去重 + supersede 记账 |
+| `documentInjectBudget` | `2` | document 摘要行的注入预算（1–5） | 只约束注入，不约束检索 |
+| `documentDir` | `""` | managed 落盘目录（#296） | 空 = `<memoryDir>/documents/`；目录之外只登记指针、正文零读零写 |
+| `policyEpoch` | `0` | 裁决规则版本号 | bump 后旧 dream_runs 降为历史证据（receipt 不再驱动现行决策） |
+
+## 睡眠模式（sleep，空闲深维护）
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `sleepModeEnabled` **light** | `false` | 库静默后全库深维护：冲突消解/归档降级/模式发现/关系补全 | opt-in；可被用户活动中止，与 autoDream 串行 |
+| `sleepIdleMinutes` | `5` | 静默多久触发（1–60 分钟） | — |
+| `sleepMinIntervalHours` | `8` | 两次 run 最小间隔（小时，≤168） | — |
+| `sleepConflictStrictness` | `normal` | 冲突裁决档：`gentle`(0.92) / `normal`(0.85) / `aggressive`(0.75) | — |
+| `sleepActionSet` | `conflict` | 动作集：`conflict` / `full`（六分支，#126） | `full` 让互补型/演进型重复有正确出口 |
+| `sleepArchiveDays` / `sleepCompressDays` | `30` / `90` | 归档降级分层（天）：先缩为摘要、再彻底归档 | 实体关系保留 |
+| `sleepPatternMinMemories` | `100` | 模式发现的扫描窗口（条） | — |
+| `sleepPatternLookbackDays` | `30` | 属性变更回看（天） | — |
+| `sleepMaxPatternPerRun` | `3` | 单轮模式条上限（0–10） | 0 = 关闭模式发现 |
+| `sleepProvider` / `sleepModel` | 空 | sleep 专用路由 | 空 = 用巩固路由 / 当前模型 |
+| `sleepReasoningEffort` | 未配置 | 同 `dreamReasoningEffort` | — |
+| `sleepMaxTokens` | `8192` | 冲突/模式阶段输出预算（#257） | 原硬编码 2048 对 `full` 档必然截断 |
+| `sleepHeatThreshold` | `0.05` | 降级联合判定的热度下限（heat < 值且 importance<5 才降） | `heatEnabled` 关时退回纯时间分层 |
+
+## 反思与冲突（dream 配套）
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `reflectionUpdateEnabled` | `true` | 检索后的反思更新既有记忆 | — |
+| `reflectionFailureTracking` | `true` | 失败经验追踪 | — |
+| `reflectionUpdateMaxPerRun` | `2` | 单轮 update 上限（0–5） | — |
+| `reflectionUpdateMinAgeHours` | `24` | 可更新记忆的最短年龄（小时，≤168） | — |
+| `conflictFreezeEnabled` | `false` | 冲突不自动合并、冻结待人工复核 | opt-in |
+| `conflictFreezeMaxPending` | `100` | 冻结队列上限（≤1000） | — |
+
+## 实体
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `entityExtractionEnabled` **light** | `false` | 写入时 LLM 抽取实体/属性/关系 | opt-in；存储三表与 CRUD 恒可用，本键只闸抽取 |
+| `entityExtractionProvider` / `entityExtractionModel` | 空 | 抽取专用路由 | 单边为空时回落调用方默认 |
+| `entityExtractionReasoning` | `none` | 抽取推理档位（#109） | `none` = 不发字段；拒收自动去掉字段重试一次 |
+| `entityExtractionMaxEntities` / `entityExtractionMaxAttrs` | `10` / `20` | 单次抽取的实体数 / 每实体属性数上限 | — |
+| `entitySearchEnabled` | `true` | 实体名前缀/语义搜索（供召回） | — |
+| `entityRecallEnabled` **light** | `false` | 图召回轴：查询命中实体名时并入融合池（#219） | opt-in；依赖实体抽取产出（lightMode 下抽取已关） |
+
+## 检索
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `embedProvider` | `openai` | 嵌入提供方：`openai`（外部 API）/ `local`（ONNX）/ `ollama` | — |
+| `vectorSearchTopK` | `20` | 向量召回条数（≤100） | — |
+| `vectorSearchThreshold` | `0.65` | 固定向量阈值 | `adaptiveThresholdEnabled` 开启时被动态阈值取代 |
+| `adaptiveThresholdEnabled` | `true` | 查询感知动态阈值（实体前缀放宽、短查询收紧等） | 关 = 回到固定 0.65 |
+| `bm25SearchEnabled` **light** | `true` | BM25 第三召回路径（标识符/代码碎片/混排） | — |
+| `hybridSearchVectorWeight` / `hybridSearchKeywordWeight` | `0.6` / `0.4` | 混合检索加权 | — |
+| `recallFusion` | `blend` | 融合配方：`blend`（现状）/ `rrf` / `minmax` | `rrf`/`minmax` 修「raw 余弦 + 关键词分直接相加」的量纲失配 |
+| `signalTransparency` | `false` | 每条结果附带 `{keyword, vector, bm25, final}` 信号 | 只装饰返回行，不改排序 |
+| `hybridInject` **light** | `true` | 注入前语义优先召回、规则序回填 | — |
+| `selectiveInjectEnabled` **light** | `true` | 有查询向量时按相似度重排注入候选 | — |
+| `searchSemanticDedup` **light** | `false` | 检索期语义去重（贪心剔除近重复） | opt-in 激进档：小嵌入模型易把不同条目坍缩 |
+| `searchSemanticDedupThreshold` | `0.95` | 去重阈值 | — |
+| `evalPersistTestResults` | `false` | 检索评测快照落 `recall_evals` | 生产检索恒只进 `recall_runs`，与此键无关 |
+| `recallRecordDefault` | `true` | `recall_runs` 记录默认开 | 显式传 `false` 的调用方不受影响 |
+| `recallRetentionDays` | `90` | `recall_runs` 滚动清理保留天数 | — |
+| `trustEpistemicWeighting` | `false` | 来源可信度（observation/subjective/inferred）参与排序与标注 | opt-in；关时 epistemic_status 只是惰性数据 |
+
+### 重排层
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `rerankEnabled` **light** | `false` | 本地交叉编码器重排 | opt-in：显式 `true` + `local` 才拉起 onnxruntime |
+| `rerankProvider` | `none` | `local` / `none` | — |
+| `rerankModel` | `Xenova/bge-reranker-base` | 重排模型 | — |
+| `rerankBatchSize` | `8` | 批大小（≤64） | — |
+| `rerankMaxCandidates` | `30` | 参与重排的候选上限（5–100） | — |
+| `rerankScoreThreshold` | `0.1` | 重排分数阈值 | — |
+| `rerankDtype` | `q8` | 量化档（#188） | 非法值由 transformers 抛出 → 重排降级告警 |
+
+## 热度
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `heatEnabled` **light** | `false` | 热度曲线（遗忘）：热度字段 / sleep 降级联判（#218） | opt-in；关 = sleep 退回纯时间分层 |
+| `injectHeatEnabled` | `false` | 注入排序乘 heat（#218 / E5 考卷：heat 乘进注入排序在真实年龄混合下饿死老约束，拆独立开关默认关） | 依赖 `heatEnabled`；关 = 注入乘数恒 1（与 heat 关闭逐字节一致）；开 = 恢复层内乘 heat 旧序 |
+| `heatGlobalBeta` | `1.0` | 广义指数形状参数 β（0.5–2） | 专家调优项，不进面板白名单 |
+| `heatTypeDecay` | 内置默认 | per-type 衰减 λ（键为 type 字符串） | λ=0 的类型免疫（热度恒 1、sleep 永不降级） |
+
+## API 与工具面
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `apiToken` | 空 | 宿主内 API 敏感端点的共享 token | 空 = 只读端点保持开放（DSH 绑 127.0.0.1 且无内建鉴权） |
+| `externalApiEnabled` | `false` | 独立 `node:http` 数据面（生态集成用） | opt-in；双宿主共用库时只能一边开（端口冲突） |
+| `externalApiPort` | `8790` | 端口 | — |
+| `externalApiHost` | `127.0.0.1` | 绑定地址 | 改成非回环 = 把整个记忆库暴露给网络，自负其责 |
+| `disableMemorySearch` | `false` | 对模型隐藏 `memory_search` 工具（v0.8.5） | 慢/轻量模型的工具往返节流；隐藏即不可调 |
+| `disableMemoryArchive` | `false` | 对模型隐藏 `memory_archive` 工具 | 同上 |
+
+## 运行时与本地模型
+
+| 键 | 默认 | 作用 | 开启后果 / 冲突 |
+|---|---|---|---|
+| `localEmbedModel` | `Xenova/bge-small-zh-v1.5` | 本地嵌入模型（`embedProvider=local` 时） | — |
+| `localEmbedDimension` | `512` | 向量维度 | — |
+| `localEmbedDevice` | `cpu` | `cpu` / `gpu` | — |
+| `localEmbedBatchSize` | `8` | 批大小（≤64） | — |
+| `localEmbedPooling` | `auto` | 池化：`auto`（BGE→cls，其余→mean）/ `cls` / `mean` | 池化决定向量空间——改动会变 modelHash、触发既有索引重建 |
+| `ollamaBaseUrl` | `http://localhost:11434` | Ollama 地址 | 只接受 http/https（SSRF 防线） |
+| `ollamaModel` | `nomic-embed-text` | Ollama 嵌入模型 | — |
+| `embedModelCacheDir` | `""` | 模型缓存目录 | 空 = `~/.dsh/mneme/models` |
+| `embedModelMirror` | `https://hf-mirror.com` | 模型下载镜像 | — |
+| `resilientModelDownload` | `true` | 模型下载断点续传 + 空闲看门狗（#194） | 关 = 恢复原生 fetch（线上回滚开关） |
+| `runtimeDir` | `""` | 自管运行时目录（transformers + onnxruntime 闭包，#131） | 空 = `~/.dsh/mneme/runtime`；把重依赖挪出宿主 profile 的依赖图 |
+| `runtimeTarballDir` | `""` | 本地 `.tgz` 离线取件目录 | 有货优先于联网（弱网下装 onnxruntime-node 用） |
+| `runtimeMirror` | `""` | registry 镜像前缀（如 `https://npmmirror.com/mirrors/npm/`） | 空 = manifest 里的官方地址 |
+
+## lightMode 强制关闭清单（`LIGHT_MODE_OFF`）
+
+`lightMode: true`（或面板 `panel_mode=light`）时，以下键被预设强制为 `false`——都是
+重型路径；核心循环（autoInject、autoSummarize、hotMemory*、质量过滤、关键词检索）不动：
+
+`entityExtractionEnabled` · `autoDream` · `sleepModeEnabled` · `rerankEnabled` ·
+`autoReindexOnBoot` · `hybridInject` · `injectGuidanceEnabled` · `searchSemanticDedup` ·
+`selectiveInjectEnabled` · `bm25SearchEnabled` · `entityRecallEnabled` ·
+`dreamNarrativeEnabled` · `documentMemoryEnabled` · `heatEnabled` · `continuityRescueEnabled` ·
+`preInjectGate.enabled`（#380）
+
+预设只是默认值而非强制：用户显式写进 feature_flags 的值在装配顺序上后展开、仍然生效
+（「用户开关 > 轻量预设 > bundle 配置」）。

package/docs/CONTINUITY.md

@@ -0,0 +1,124 @@
+# dsh-mneme 压缩边缘抢救（issue #249 N3）
+
+- **日期**：2026-09-24
+- **状态**：✅ 已实现（opt-in，默认关）
+- **范围**：上下文即将被宿主压缩前，抢救「正在做什么」，让它活过这次压缩
+- **相关文档**：[存储与回收](STORAGE.md)（同批的 #275 第一批） · [语义增强](SEMANTIC.md)
+
+## 1. 问题
+
+宿主的压缩摘要器只看对话里的内容：压缩时它按固定字段模板重建对话（Current Work /
+Next Step / Critical Context 等），**系统提示段里的东西不进这次重建**。所以任何"只放在
+提示段里的工作状态"，一过压缩就等于没写过。
+
+## 2. 形态：必须双落点
+
+| 落点 | 去处 | 为什么不能省 |
+|---|---|---|
+| ① 落提案 | `continuity_proposals` 表（`src/store.js`） | 脱离对话独立存活；注入失败/被跳过也不丢工作状态 |
+| ② 追加消息 | 序列末尾一条 `user/message`（`source: {kind: "plugin", plugin: "dsh-mneme"}`） | 这是唯一能进宿主摘要器重建范围的落点 |
+
+落库先于注入。落点顺序由宿主契约保证：压缩插件在自己那一步先压缩、再 `return next()`，
+所以我们在 `agent/pre-step` 拿到 `next()` 结果时压缩事件已落库；而我们返回的
+`decision.messages` 由宿主在本步末尾以 `surfaceOp: "append"` 追加，晚于压缩的
+`surfaceOp: "replace"`——追加物天然在压缩之后、靠近序列末尾。
+
+注入文本是**结构化快照**（统一前缀 + 三行固定字段，整条 ≤900 字符），不是 §6.3 那种
+≤160B 的单行提醒——那条上限约束的是"一句话提醒"，不约束固定字段的快照；字段内部的换行
+仍会被压平成空格，保证它仍是一条消息。**判重按当前表面**（`session.surface.nodes`），
+不按全量日志：被一次压缩折叠出表面的旧快照还在 append-only 日志里，照日志判重会让这次
+该补的注入静默跳过。
+
+## 3. 触发
+
+**不自定阈值**，就是订阅宿主真的压缩：`compaction/start` / `compaction/summary` /
+`compaction/end`（都在宿主的事件白名单里）。理由：「压缩边缘」由宿主定义，我们再校准
+一份阈值参数只会与之漂移，还多一份没人维护的旋钮。
+
+DSH 没有 in-memory 消息改写钩子，所以本机制一律是「注入 + 序号引用寻址」，**不改写
+历史消息本体**。
+
+## 4. 字段与抽取口径
+
+固定三字段（不用自由散文），全程不调模型、纯确定性抽取（`src/continuity.js`）：
+
+| 字段 | 来源 | 截断 |
+|---|---|---|
+| `current_work` | 最近一条**真实** `user/message`（插件注入与子代理上报不算用户指令） | 头部 200 字符 |
+| `next_step` | 最近一条 `assistant/message` | **尾部** 200 字符（下一步活在末尾那句里） |
+| `open_questions` | 恒 `null` | —— |
+
+「哪些问题还没解决」判不出就是判不出，硬猜会给出似是而非的字段；空字段在注入文本里
+如实标 `(none)`。这个字段留给转正通道与人工补。
+
+字段名以 #249 §6.2 为准（`current_work` / `next_step` / `open_questions`）。§4.4 里的
+Current Work / Next Step / Critical Context 是**宿主压缩模板**的字段名，不是这张表的列名
+（规格里两处用词不同，实现取 §6.2）。
+
+## 5. 存储与生命周期
+
+```
+continuity_proposals(id, session_id, kind, current_work, next_step, open_questions,
+                     status, edge_seq, created_at, updated_at)
+UNIQUE (session_id, kind)   -- 「同一会话同一类只留一条」：再次触发是刷新，不是新增
+```
+
+- `kind`：`compaction-edge`（一次会话里这一类只留一条）。
+- `status`：`pending`（本批唯一写入态）→ 未来 `promoted` / `discarded`（转正通道与
+  #254 的二次确认共用一套，阶段二才打开）。
+- **队列满则弃新**（`MAX_CONTINUITY_PENDING = 200`）：达上限丢掉本次触发，而不是淘汰
+  旧行——旧行是别的会话还没转正的工作状态，用「更近的边缘」把它挤掉是反的。满队列
+  不影响已有行的刷新。
+- 丢弃会**留痕**（`agent/pre-step` 监听器 `logger.warn`）：弃新属于"静默失效"，不报出来
+  的话 §8 的触发率口径会把它算成"没触发"。
+- **本批没有回收路径**：`status` 只写 `pending`，`maintenance`/`reclaim` 不碰这张表，
+  所以 200 是上限——满了之后新会话不再落行，直到转正通道打开（阶段二）。判定是进程内的
+  （先查计数再写），两个宿主共用同一 `memoryDir` 时可能各自都看到未满，实际越过 200 条。
+- `edge_seq` 记最近一次触发的压缩事件序号，是「实际触发率」的证据。
+- 落库失败只告警、不抛：可选插件的故障不该把宿主的这一步变成失败，而注入那一半不依赖
+  库，照做。
+
+指标口径（#249 §8 要求触发率/采纳率可统计）：实际触发率 = 提案行数；采纳率 =
+`promoted` / 全部。两者都是就地读表，不需要额外打点。
+
+## 6. 开关
+
+| 层级 | 键 | 默认 |
+|---|---|---|
+| 父 | `autoInject` | 开（既有总闸） |
+| 子 | `continuityRescueEnabled` | **关**（引入新注入表面，按 #249 §10 判据独立成键） |
+
+父关则子不生效（`injectChildEnabled`）；轻量档默认置关（`applyLightModePreset`
+把它算进 `LIGHT_MODE_OFF`），但那只是默认值——装配时按「用户开关 > 轻量预设 >
+bundle 配置」合并，用户在面板里显式勾选仍然赢。面板落点在 `lib/client.js`
+的 `FEATURE_CHILDREN` / `FEATURE_GROUPS`（该文件无 src 对应物），跨文件关系由
+`test/inject-parent-gate.test.js` 逐个断言钉住。
+
+## 7. 降级路径（不要求宿主加接口）
+
+宿主若不提供可挂钩的压缩前时机，双落点里的 ② 就没有触发者。这时**不算失败**：把规则
+写成持久规则交给 agent 自判（`src/guide.js` 的 `CONTINUITY_TOOL_RULE`，挂在
+`memory_save` 的工具描述尾部——常驻文本、零注入成本，只在子开关开启时出现）。
+
+本批**不做宿主能力探测**（没有可靠的探测口，宿主也没有暴露"有没有压缩前时机"这个事实），
+所以子开关打开时这条规则就常驻，与 ② 并存——两者不是互斥的备选，而是同一个开关下的两层：
+② 在宿主真的压缩时自动生效，持久规则在 agent 自己判断"上下文要炸了"时兜底。
+
+## 8. 已知坑
+
+- **判重只能做到「同一份文本不追加第二次」**。没有改写钩子，就不能删掉表面里已经存在
+  的那条旧快照；内容一变就是新的一份（旧的那份随宿主压缩自然消失）。这是形态上限，
+  不是实现偷懒。
+- **注入物不得变成记忆**：追加消息用 `source.kind = "plugin"`，`summarize.js` 的
+  `collectMessages` 会跳过它——否则注入物会被下一轮蒸馏成记忆，形成自我强化。
+- **`open_questions` 恒 null** 是刻意留白，不是没实现。
+
+## 9. 验收锚点
+
+`test/continuity.test.js` 逐条锁形态（不是锁文案）：抽取口径（头/尾方向、插件消息跳过、
+插件消息是最后一条 `user/message` 时仍被跳过）、渲染（统一前缀、单行、`none`、整条上限）、
+唯一键刷新（`created_at` 不动、幂等 UPSERT）、队列满弃新且不影响刷新、丢弃留痕、
+pre-step 双落点与一次性消费、同文本不重复追加（按当前表面）、被折叠出表面的旧注入要补、
+落库失败不打断宿主的一步、`reject` 放行且不消费边缘、缺 session 不抛、dispose 后不再动作、
+默认关 + 父关不生效 + 轻量档压掉 + 降级规则只在开启时进描述、门控不调模型（静态锁）、
+存量库重开即建表。