dsh-layered-memory 0.8.4 → 0.8.6

package/dist/client.js

@@ -244,6 +244,23 @@ window.__ModuleLoader__.load({
       }
     }
 
+    /** 相对时间（悬浮卡摘要行用）：刚刚 / N 分钟前 / N 小时前 / N 天前；无效返回 null。 */
+    function fmtAgo(iso) {
+      if (!iso) return null;
+      try {
+        var t = new Date(iso).getTime();
+        if (!t) return null;
+        var s = Math.floor((Date.now() - t) / 1000);
+        if (s < 0) s = 0;
+        if (s < 45) return "刚刚";
+        if (s < 3600) return Math.floor(s / 60) + " 分钟前";
+        if (s < 86400) return Math.floor(s / 3600) + " 小时前";
+        return Math.floor(s / 86400) + " 天前";
+      } catch (e) {
+        return null;
+      }
+    }
+
     // ── Switch 组件 ──
     function Switch(props) {
       var on = !!props.checked;
@@ -673,6 +690,151 @@ window.__ModuleLoader__.load({
           props.error
             ? react.createElement("div", { style: { fontSize: 11, color: "var(--dsh-mem-danger)", marginTop: 10, whiteSpace: "nowrap" } }, props.error)
             : null,
+          // 会话信息区（分隔线 + 2×2 指标 + 状态行）：session-stats 热路径端点，
+          // 宿主不支持 / 数据缺失时整体不渲染（best-effort 增强，不占位）
+          props.rpc && props.sessionId
+            ? react.createElement(SessionInfoArea, { rpc: props.rpc, sessionId: props.sessionId })
+            : null,
+        ),
+      );
+    }
+
+    // ── 会话信息区：悬浮卡下半部（召回命中 / 攒批进度 / 会话产出 / 会话消息） ──
+    // 数据通道 dsh-memory/session-stats（宿主侧零文件 I/O：内存注册表 + 索引 COUNT，
+    // 见 slider-spec 数据策略节）；自适应轮询：忙时（攒批/挂起/全局待蒸馏）2s，静默 5s，
+    // 浮层卸载即停（ModeSlider 只在 pill 展开期间挂载）。
+    function sinfoCell(val, label, title) {
+      return react.createElement(
+        "div",
+        { title: title || null },
+        react.createElement("div", { className: "dsh-mem-sinfo-val" }, val),
+        react.createElement("div", { className: "dsh-mem-sinfo-label" }, label),
+      );
+    }
+
+    function SessionInfoArea(props) {
+      var rpc = props.rpc;
+      var sessionId = props.sessionId;
+      // undefined=首帧加载中；null=宿主不支持（整体隐藏）；对象=最新快照
+      var stState = react.useState(undefined);
+      var stats = stState[0];
+      var setStats = stState[1];
+      var busyRef = react.useRef(false);
+
+      react.useEffect(function () {
+        if (!rpc || !sessionId) return undefined;
+        var alive = true;
+        var timer = null;
+        var seq = 0;
+        var tick = function () {
+          var token = ++seq;
+          rpc("dsh-memory/session-stats", { sessionId: sessionId })
+            .then(function (r) {
+              if (!alive || token !== seq) return;
+              if (r && r.ok && r.value && r.value.supported === false) {
+                setStats(null); // 宿主无数据源：整体隐藏
+              } else if (r && r.ok && r.value) {
+                setStats(r.value);
+                var d = r.value.distill || {};
+                var g = r.value.global || {};
+                busyRef.current = (d.pendingSlice || 0) > 0 || (d.parkedSlices || 0) > 0 || (g.pendingTotal || 0) > 0;
+              }
+              // RPC 失败：保持旧快照（信息区不因瞬时错误闪没）
+            })
+            .catch(function () {})
+            .then(function () {
+              if (alive) timer = setTimeout(tick, busyRef.current ? 2000 : 5000);
+            });
+        };
+        tick();
+        return function () {
+          alive = false;
+          if (timer) clearTimeout(timer);
+        };
+      }, [rpc, sessionId]);
+
+      // 首帧占位骨架（防内容跳变）；宿主不支持则整体隐藏
+      if (stats === null) return null;
+      if (stats === undefined) {
+        return react.createElement(
+          "div",
+          { className: "dsh-mem-sinfo" },
+          react.createElement(
+            "div",
+            { className: "dsh-mem-sinfo-grid" },
+            sinfoCell("…", "召回命中"),
+            sinfoCell("…", "攒批进度"),
+            sinfoCell("…", "本会话记忆"),
+            sinfoCell("…", "会话消息"),
+          ),
+        );
+      }
+
+      var rc = stats.recall || {};
+      var di = stats.distill || {};
+      var gl = stats.global || {};
+      var isOff = stats.mode === "off";
+
+      // 召回命中：口径是"注入统计"（命中轮次/检索轮次），停用时显示状态而非误导性 0/0
+      var rcVal;
+      var rcLabel;
+      var rcTitle;
+      if (rc.enabled === false) {
+        rcVal = "停用";
+        rcLabel = "召回命中";
+        rcTitle = "召回已停用（开关关闭 / 档位关闭 / 部署未启用）";
+      } else {
+        rcVal = (rc.hitTurns || 0) + "/" + (rc.injectedTurns || 0);
+        rcLabel = "召回命中 · " + (rc.totalHits || 0) + " 条";
+        rcTitle =
+          "最近一轮命中 " + (rc.lastHits || 0) + " 条，耗时 " + (rc.lastDurationMs || 0) + "ms" +
+          ((rc.timeouts || 0) > 0 ? "，超时跳过 " + rc.timeouts + " 次" : "");
+      }
+
+      // 攒批进度（x/生效阈值，含 warmup 爬坡）；off 档显示挂起切片数
+      var dVal;
+      var dLabel;
+      var dTitle;
+      if (isOff) {
+        dVal = String(di.parkedSlices || 0);
+        dLabel = "挂起切片";
+        dTitle = "档位关闭：未蒸馏切片挂起，切回档位后继续";
+      } else {
+        dVal = (di.pendingSlice || 0) + "/" + (di.threshold != null ? di.threshold : "-");
+        dLabel = (di.parkedSlices || 0) > 0 ? "攒批 · 挂起 " + di.parkedSlices : "攒批进度";
+        dTitle = "达到阈值后自动蒸馏（阈值随使用渐进爬坡到稳态）";
+      }
+
+      var pTitle = di.lastDistillAt ? "最近蒸馏 " + fmtTime(di.lastDistillAt) : "本会话尚未蒸馏";
+      var warn = gl.degraded ? "⚠ 存储不可用，记忆功能已停用" : null;
+      var note = null;
+      if (!gl.degraded) {
+        if (stats.retrieval === "keyword" && !isOff) note = "检索降级：纯关键词（向量不可用）";
+        else if (stats.retrieval === "none") note = "检索不可用（FTS 与向量均失效）";
+      }
+      var ago = fmtAgo(gl.lastExtractAt);
+
+      return react.createElement(
+        "div",
+        { className: "dsh-mem-sinfo" },
+        warn
+          ? react.createElement("div", { className: "dsh-mem-sinfo-warn" }, warn)
+          : null,
+        react.createElement(
+          "div",
+          { className: "dsh-mem-sinfo-grid" },
+          sinfoCell(rcVal, rcLabel, rcTitle),
+          sinfoCell(dVal, dLabel, dTitle),
+          sinfoCell(String(di.producedRecords || 0), "本会话记忆", pTitle),
+          sinfoCell(stats.l0Count != null ? String(stats.l0Count) : "…", "会话消息"),
+        ),
+        note
+          ? react.createElement("div", { className: "dsh-mem-sinfo-note" }, note)
+          : null,
+        react.createElement(
+          "div",
+          { className: "dsh-mem-sinfo-sum" },
+          "待蒸馏 " + (gl.pendingTotal || 0) + " · 上次蒸馏 " + (ago || "尚未蒸馏"),
         ),
       );
     }
@@ -930,6 +1092,15 @@ window.__ModuleLoader__.load({
         "  box-shadow: 0 16px 48px rgba(0,0,0,0.24); }",
         "body[data-ds-dark-theme] .dsh-mem-rb-modal { box-shadow: 0 16px 48px rgba(0,0,0,0.6); }",
         ".dsh-mem-rb-muted { font-size: 12px; color: var(--dsh-mem-text-3); }",
+        // ── 会话信息区（悬浮卡下半部）：分隔线 + 2×2 指标 + 状态行；纯静态 DOM，
+        // 不进粒子层 rAF 循环，轮询数据到达才触发本组件小树 re-render ──
+        ".dsh-mem-sinfo { margin-top: 12px; padding-top: 10px; border-top: 1px solid var(--dsh-mem-border); }",
+        ".dsh-mem-sinfo-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 8px 10px; }",
+        ".dsh-mem-sinfo-val { font-size: 13px; font-weight: 600; color: var(--dsh-mem-text-1); line-height: 18px; font-variant-numeric: tabular-nums; }",
+        ".dsh-mem-sinfo-label { font-size: 11px; color: var(--dsh-mem-text-3); line-height: 15px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }",
+        ".dsh-mem-sinfo-warn { font-size: 11px; color: var(--dsh-mem-danger); line-height: 16px; margin-bottom: 6px; }",
+        ".dsh-mem-sinfo-note { font-size: 11px; color: var(--dsh-mem-text-3); line-height: 16px; margin-top: 8px; }",
+        ".dsh-mem-sinfo-sum { font-size: 11px; color: var(--dsh-mem-text-3); line-height: 16px; margin-top: 8px; }",
         // reduced-motion 兜底放样式表末尾：同特异性下后置声明才能压过上面的组件类
         "@media (prefers-reduced-motion: reduce) {",
         "  .dsh-mem-root, .dsh-mem-root *, .dsh-mem-btn, .dsh-mem-input, .dsh-mem-select, .dsh-mem-rb-fill, .dsh-mem-scene-chev, .dsh-mem-sel-chev { transition: none; }",
@@ -1066,6 +1237,8 @@ window.__ModuleLoader__.load({
               mode: mode || "auto",
               onCommit: commit,
               error: error,
+              rpc: rpc,
+              sessionId: sessionId,
             })
           : null,
       );

package/dist/config.d.ts

@@ -66,6 +66,9 @@ export interface MemoryConfig {
         strategy: 'keyword' | 'embedding' | 'hybrid';
         /** 召回路径分数阈值（0~1，低于该分不注入；工具路径不过滤）。 */
         scoreThreshold: number;
+        /** 时效衰减半衰期（天，0=关）：召回排序的 freshness 加权——score × max(0.5, 0.5^(Δ天/半衰期))，
+         *  只影响相关度相近候选间的名次（老记忆最多损失一半排序分，不淘汰）。 */
+        decayHalfLifeDays: number;
     };
     embedding: {
         /** 向量检索总开关；关闭时纯 FTS 运行（官方 provider="none" 同款）。 */
@@ -113,6 +116,9 @@ export interface MemoryConfig {
     };
     /** 是否注册模型可调用的记忆工具。 */
     tools: boolean;
+    /** 注册 bench 控制服务（dsh-memory-bench，进程内 rebuild 触发面）。
+     *  仅供基准/调试部署（bench profile 的 lifecycle 赛道），默认关——生产零表面积。 */
+    benchControl: boolean;
 }
 export declare const memorySchema: Schema<Schemastery.ObjectS<{
     dataDir: Schema<string, string>;
@@ -167,6 +173,7 @@ export declare const memorySchema: Schema<Schemastery.ObjectS<{
         includeSceneNav: Schema<boolean, boolean>;
         strategy: Schema<"keyword" | "embedding" | "hybrid", "keyword" | "embedding" | "hybrid">;
         scoreThreshold: Schema<number, number>;
+        decayHalfLifeDays: Schema<number, number>;
     }>, Schemastery.ObjectT<{
         enabled: Schema<boolean, boolean>;
         maxResults: Schema<number, number>;
@@ -177,6 +184,7 @@ export declare const memorySchema: Schema<Schemastery.ObjectS<{
         includeSceneNav: Schema<boolean, boolean>;
         strategy: Schema<"keyword" | "embedding" | "hybrid", "keyword" | "embedding" | "hybrid">;
         scoreThreshold: Schema<number, number>;
+        decayHalfLifeDays: Schema<number, number>;
     }>>;
     embedding: Schema<Schemastery.ObjectS<{
         enabled: Schema<boolean, boolean>;
@@ -219,6 +227,7 @@ export declare const memorySchema: Schema<Schemastery.ObjectS<{
         timeoutMs: Schema<number, number>;
     }>>;
     tools: Schema<boolean, boolean>;
+    benchControl: Schema<boolean, boolean>;
 }>, Schemastery.ObjectT<{
     dataDir: Schema<string, string>;
     family: Schema<"chat" | "work" | "auto", "chat" | "work" | "auto">;
@@ -272,6 +281,7 @@ export declare const memorySchema: Schema<Schemastery.ObjectS<{
         includeSceneNav: Schema<boolean, boolean>;
         strategy: Schema<"keyword" | "embedding" | "hybrid", "keyword" | "embedding" | "hybrid">;
         scoreThreshold: Schema<number, number>;
+        decayHalfLifeDays: Schema<number, number>;
     }>, Schemastery.ObjectT<{
         enabled: Schema<boolean, boolean>;
         maxResults: Schema<number, number>;
@@ -282,6 +292,7 @@ export declare const memorySchema: Schema<Schemastery.ObjectS<{
         includeSceneNav: Schema<boolean, boolean>;
         strategy: Schema<"keyword" | "embedding" | "hybrid", "keyword" | "embedding" | "hybrid">;
         scoreThreshold: Schema<number, number>;
+        decayHalfLifeDays: Schema<number, number>;
     }>>;
     embedding: Schema<Schemastery.ObjectS<{
         enabled: Schema<boolean, boolean>;
@@ -324,5 +335,6 @@ export declare const memorySchema: Schema<Schemastery.ObjectS<{
         timeoutMs: Schema<number, number>;
     }>>;
     tools: Schema<boolean, boolean>;
+    benchControl: Schema<boolean, boolean>;
 }>>;
 export declare function resolveDataDir(cfg: MemoryConfig): string;

package/dist/config.js

@@ -48,6 +48,9 @@ export const memorySchema = Schema.object({
         includeSceneNav: Schema.boolean().default(true),
         strategy: Schema.union(['keyword', 'embedding', 'hybrid']).default('hybrid'),
         scoreThreshold: Schema.number().min(0).max(1).default(0.3),
+        // 时效衰减（#29）：乘法软加权 + 地板 0.5（老记忆最多损失一半排序分），只轮转
+        // 相关度相近候选的名次；0=关（bench 基线可比性可 pin 0）
+        decayHalfLifeDays: Schema.number().min(0).max(3650).default(30),
     }),
     embedding: Schema.object({
         enabled: Schema.boolean().default(false),
@@ -78,6 +81,7 @@ export const memorySchema = Schema.object({
         timeoutMs: Schema.number().min(1000).max(600_000).default(120_000),
     }),
     tools: Schema.boolean().default(true),
+    benchControl: Schema.boolean().default(false),
 });
 export function resolveDataDir(cfg) {
     if (cfg.dataDir)

package/dist/embedding-worker.cjs

@@ -0,0 +1,176 @@
+/**
+ * 本地嵌入 worker：transformers.js 的模型加载与推理在本线程执行，主线程只
+ * 投递文本、收回向量。onnxruntime-node（v1.24.3）的 run/loadModel 是
+ * setImmediate 回调里的同步调用（Promise 包装不卸载计算），留在主线程会
+ * 冻结宿主事件循环——dsh 页面一切交互无响应数秒的根因。
+ *
+ * 协议（与 src/store/local-embedding.ts 的 RealWorkerChannel 配对；自增 id）：
+ * - 入向：{id,type:'ping'} | {id,type:'warmup'} | {id,type:'embed',texts,priority}
+ * - 出向：{id,ok:true,type:'pong'|'ready'|'embedded',vectors?}（向量经
+ *   transfer 列表零拷贝回传）| {id,ok:false,stage:'load'|'infer',error}
+ *   | {type:'fatal',error}
+ *
+ * 调度：单线程串行。embedBatch 拆成逐条 job、条间 setImmediate 让路——
+ * 单条请求（priority，即召回 query）unshift 插队，最坏只等"正在算的那一条"，
+ * 不会被 reindex 批次（16/32 条 ≈5-10s）堵在队尾。
+ *
+ * 信任边界（沿 AGENTS.md 0.8.2 审查记录）：runtime/ 目录在数据目录信任边界内，
+ * 本线程按其 package.json createRequire 加载 transformers——对数据目录有写
+ * 权限的进程理论上可植入恶意模块；模型文件逐文件 sha256 锁定，运行时代码
+ * 无同级防护，完整修复需安装指纹设计，暂以文档化假设为准。
+ */
+'use strict';
+
+const { parentPort, workerData } = require('node:worker_threads');
+const path = require('node:path');
+const { createRequire } = require('node:module');
+
+/** 错误消息归一化（Error 取 message，其余 String 化）。 */
+function errMsg(err) {
+  return err && err.message ? err.message : String(err);
+}
+
+const cfg = workerData || {};
+const RUNTIME_DIR = typeof cfg.runtimeDir === 'string' ? cfg.runtimeDir : '';
+const MODEL_DIR = typeof cfg.modelDir === 'string' ? cfg.modelDir : '';
+const POOLING = cfg.pooling === 'cls' ? 'cls' : 'mean';
+const DTYPE = typeof cfg.dtype === 'string' ? cfg.dtype : 'q8';
+const MAX_INPUT_CHARS = cfg.maxInputChars > 0 ? cfg.maxInputChars : 5000;
+
+let extractor = null; // pipeline('feature-extraction', …)
+let loadState = 'idle'; // idle | loading | ready | failed
+let loadPromise = null;
+let loadError = null;
+
+// ── 模型懒加载（首请求触发；失败后经 warmup 可重试，embed 请求失败快返回） ──
+function ensureLoaded() {
+  if (loadState === 'ready') return Promise.resolve();
+  if (loadState === 'loading' && loadPromise) return loadPromise;
+  loadState = 'loading';
+  loadError = null;
+  loadPromise = (async () => {
+    try {
+      if (!RUNTIME_DIR || !MODEL_DIR) throw new Error('workerData 缺少 runtimeDir/modelDir');
+      const req = createRequire(path.join(RUNTIME_DIR, 'package.json'));
+      const mod = req('@huggingface/transformers');
+      if (mod.env) {
+        mod.env.allowRemoteModels = false;
+        if (mod.env.allowLocalModels !== undefined) mod.env.allowLocalModels = true;
+      }
+      extractor = await mod.pipeline('feature-extraction', MODEL_DIR, { dtype: DTYPE });
+      loadState = 'ready';
+    } catch (err) {
+      loadState = 'failed';
+      loadError = errMsg(err);
+      loadPromise = null; // 失败后下一次 warmup 重新走加载
+      throw err;
+    }
+  })();
+  return loadPromise;
+}
+
+// ── 推理队列（逐条 job；priority 插队；条间让路） ──
+const queue = []; // [{ request, index, text }]
+let pumping = false;
+
+function postReply(msg, transfer) {
+  parentPort.postMessage(msg, transfer || []);
+}
+
+/** 请求全部条目完成 → 回执（transfer 向量缓冲零拷贝）。 */
+function settle(request) {
+  if (request.failed || request.remaining !== 0) return;
+  postReply(
+    { id: request.id, ok: true, type: 'embedded', vectors: request.vectors },
+    request.vectors.map((v) => v.buffer),
+  );
+}
+
+/** 首个失败即回执错误，并移除该请求尚未开跑的条目（正在跑的至多 1 条，算完即弃）。 */
+function failRequest(request, error, stage) {
+  if (request.failed) return;
+  request.failed = true;
+  for (let i = queue.length - 1; i >= 0; i--) {
+    if (queue[i].request === request) queue.splice(i, 1);
+  }
+  postReply({ id: request.id, ok: false, stage: stage, error: errMsg(error) });
+}
+
+async function pump() {
+  if (pumping) return;
+  pumping = true;
+  try {
+    while (queue.length > 0) {
+      const job = queue.shift();
+      if (job.request.failed) continue;
+      try {
+        const result = await extractor([job.text.slice(0, MAX_INPUT_CHARS)], { pooling: POOLING, normalize: true });
+        const data = result[0] && result[0].data;
+        job.request.vectors[job.index] = data instanceof Float32Array ? data : new Float32Array(data);
+        job.request.remaining -= 1;
+        settle(job.request);
+      } catch (err) {
+        failRequest(job.request, err, 'infer');
+      }
+      // 条间让路：交还本线程事件循环，新消息（含 priority 插队）可在批间被处理
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+  } finally {
+    pumping = false;
+  }
+}
+
+function handleEmbed(msg) {
+  const texts = Array.isArray(msg.texts) ? msg.texts : [];
+  if (texts.length === 0) {
+    postReply({ id: msg.id, ok: true, type: 'embedded', vectors: [] });
+    return;
+  }
+  const request = { id: msg.id, vectors: new Array(texts.length), remaining: texts.length, failed: false };
+  // 单条请求（召回 query）插队到队首；批次追加到队尾（批内条目间仍会被后来的插队）
+  const priority = msg.priority === true && texts.length === 1;
+  for (let i = 0; i < texts.length; i++) {
+    const job = { request: request, index: i, text: String(texts[i] == null ? '' : texts[i]) };
+    if (priority) queue.unshift(job);
+    else queue.push(job);
+  }
+  void pump();
+}
+
+parentPort.on('message', (msg) => {
+  if (!msg || typeof msg.id !== 'number' || typeof msg.type !== 'string') return;
+  if (msg.type === 'ping') {
+    postReply({ id: msg.id, ok: true, type: 'pong' });
+    return;
+  }
+  if (msg.type === 'warmup') {
+    ensureLoaded().then(
+      () => postReply({ id: msg.id, ok: true, type: 'ready' }),
+      () => postReply({ id: msg.id, ok: false, stage: 'load', error: loadError ?? '模型加载失败' }),
+    );
+    return;
+  }
+  if (msg.type === 'embed') {
+    void (async () => {
+      try {
+        await ensureLoaded();
+      } catch {
+        postReply({ id: msg.id, ok: false, stage: 'load', error: loadError ?? '模型加载失败' });
+        return;
+      }
+      handleEmbed(msg);
+    })();
+    return;
+  }
+});
+
+// 未捕获异常：尽力通知主线程后强制退出（主线程的 exit 处理会拒绝全部 pending
+// 并转入 failed 态）。不保持半死状态——半死的 worker 只会让调用方挂到超时。
+process.on('uncaughtException', (err) => {
+  try {
+    postReply({ type: 'fatal', error: errMsg(err) });
+  } catch {
+    /* 端口已坏，exit 处理兜底 */
+  }
+  setTimeout(() => process.exit(1), 50);
+});

package/dist/hooks/recall.d.ts

@@ -30,12 +30,39 @@ import type { MemoryLogger } from '../types.js';
 export declare function buildRecallQuery(messages: Array<{
     content: unknown;
 }>, tailMessages?: number, maxChars?: number): string;
+/** 单会话召回统计（悬浮卡信息区数据源；每轮 O(1) 记账，agent/disposed 清理）。
+ *  口径声明：这是"注入统计"而非 bench 的离线 recall@k——运行时没有 ground truth，
+ *  命中率 = hitTurns / injectedTurns。去重语义（0.8.6）：全量压制轮计入 hitTurns
+ *  （相关记忆已在模型上下文里，本质是命中而非未命中），injectedTurns 仍计全部
+ *  发生过检索的轮次（保住分母语义与悬浮卡口径连续性）。 */
+export interface RecallSessionStats {
+    /** 发生过召回检索的轮次数（含零命中、全量压制与超时）。 */
+    injectedTurns: number;
+    /** 命中（≥1 条实际注入，或有命中但被去重全量压制）轮次数。 */
+    hitTurns: number;
+    /** 累计注入条数（去重过滤后、预算截断前）。 */
+    totalHits: number;
+    /** 总预算超时跳过次数。 */
+    timeouts: number;
+    /** 累计被去重压制的命中条数（同会话已注入过，不重复注入）。 */
+    suppressedRecalls: number;
+    /** 最近一轮实际注入条数（0 = 零命中/超时/全量压制；工具指南门控沿用此信号）。 */
+    lastHits: number;
+    /** 最近一轮检索耗时 ms。 */
+    lastDurationMs: number;
+    /** 最近一次记账时间（LRU 清理依据）。 */
+    updatedAt: number;
+}
+/** 新建零值统计（首次出现的会话）。 */
+export declare function emptyRecallStats(now?: number): RecallSessionStats;
 export interface RecallHooks {
     /** 管线更新后调用：画像/场景缓存立即失效并异步刷新。 */
     invalidateProfile(): void;
+    /** 会话召回统计只读视图（未发生过检索的会话返回 undefined）。 */
+    stats(sessionId: string): RecallSessionStats | undefined;
 }
 export declare function registerRecall(ctx: Context, cfg: MemoryConfig, stores: {
     l1: L1Store;
     scenes: Record<'chat' | 'work', SceneStore>;
     persona: Record<'chat' | 'work', PersonaStore>;
-}, logger: MemoryLogger, live: LiveSettingsHandle, modes: SessionModeStore): RecallHooks;
+}, logger: MemoryLogger, live: LiveSettingsHandle, modes: SessionModeStore, dataDir: string): RecallHooks;

package/dist/hooks/recall.js

@@ -1,4 +1,5 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { RecallDedupeStore } from '../store/recall-dedupe.js';
 import { applyRecallBudget, raceRecallTimeout, RECALL_EMBED_CAP_MS } from '../util/recall-budget.js';
 import { errDetail } from '../util/filelog.js';
 import { blocksToText } from '../util/text.js';
@@ -35,9 +36,32 @@ const MEMORY_TOOLS_GUIDE = `<memory-tools-guide>
 注：若当前环境限制直接调用工具（如仅允许代码执行入口），请经由该环境的工具调用机制
 （如 run_code 程序内）使用以上记忆工具。
 </memory-tools-guide>`;
-export function registerRecall(ctx, cfg, stores, logger, live, modes) {
-    /** 每 agent 最近一次注入的命中条数（工具指南门控的"本轮召回命中"信号）。 */
-    const recallHits = new Map();
+/** 新建零值统计（首次出现的会话）。 */
+export function emptyRecallStats(now = Date.now()) {
+    return {
+        injectedTurns: 0,
+        hitTurns: 0,
+        totalHits: 0,
+        timeouts: 0,
+        suppressedRecalls: 0,
+        lastHits: 0,
+        lastDurationMs: 0,
+        updatedAt: now,
+    };
+}
+export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
+    /** 召回去重存储（同会话已注入的记忆不再重复注入；写穿持久化，重启不丢）。 */
+    const dedupe = new RecallDedupeStore(dataDir, logger);
+    /** 每 agent 召回统计（工具指南门控读 lastHits；悬浮卡信息区读全量计数）。 */
+    const recallStats = new Map();
+    const statFor = (id) => {
+        let s = recallStats.get(id);
+        if (!s) {
+            s = emptyRecallStats();
+            recallStats.set(id, s);
+        }
+        return s;
+    };
     // 画像/场景导航按族缓存（分族隔离：注入时按会话档位选族）
     const profileCache = {
         chat: { persona: '', nav: '' },
@@ -65,9 +89,17 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes) {
     const invalidateProfile = () => {
         void refreshProfile();
     };
-    // agent 销毁时清掉召回信号槽
+    // agent 销毁时清掉召回统计槽（去重记录不随 agent 清——持久化语义：会话恢复后继续压制）
     ctx.on('agent/disposed', (payload) => {
-        recallHits.delete(payload.agent.id);
+        recallStats.delete(payload.agent.id);
+    });
+    // 上下文压缩/清空 → 已注入内容从模型上下文丢失，重置该会话的去重压制
+    // （resume/startup 不重置：历史仍在，已注入的记忆模型还持有）。
+    ctx.on('agent/session-start', (payload) => {
+        if (payload.source === 'compact' || payload.source === 'clear') {
+            dedupe.reset(payload.agent.id);
+            logger.info(`[memory] 召回去重重置（agent=${payload.agent.id}，source=${payload.source}）`);
+        }
     });
     // ── 1. pre-step 消息侧注入：记忆先行于每一条新的用户输入（ADR-0001） ──
     // prepend 注册 + 先 next() 再改写：不劫持其他监听器（dsh-time-context 官方范式）。
@@ -86,25 +118,52 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes) {
                 if (!hasNewUserMessage)
                     return decision;
                 const query = buildRecallQuery(payload.messages);
-                recallHits.set(payload.agent.id, 0);
-                if (!query)
+                // 空查询是退化轮（无用户文本），重置命中信号但不计入统计
+                if (!query) {
+                    const degenerate = statFor(payload.agent.id);
+                    degenerate.lastHits = 0;
                     return decision;
+                }
+                const st = statFor(payload.agent.id);
+                st.injectedTurns++;
+                st.lastHits = 0;
+                st.updatedAt = Date.now();
+                const searchStart = Date.now();
                 const hits = await raceRecallTimeout(stores.l1.search(query, cfg.recall.maxResults, {
                     scoreThreshold: cfg.recall.scoreThreshold,
                     family: mode === 'auto' ? undefined : mode,
-                    // 远程嵌入 fetch 内层钳制：给 FTS 降级留出总预算内的时间（本地推理不钳）
+                    // 嵌入内层钳制：给 FTS 降级留出总预算内的时间（远程限 HTTP fetch；本地经 worker 代理 race 放弃）
                     embeddingTimeoutMs: RECALL_EMBED_CAP_MS,
                 }), cfg.recall.timeoutMs);
+                st.updatedAt = Date.now();
                 if (hits === undefined) {
+                    st.timeouts++;
                     logger.warn('[memory] 召回超时，跳过本轮注入（不阻塞对话）');
                     return decision;
                 }
-                recallHits.set(payload.agent.id, hits.length);
-                if (hits.length === 0)
+                st.lastDurationMs = Date.now() - searchStart;
+                // 召回去重：同会话已注入过的记录不再重复注入（模型上下文已持有，省 token）。
+                // 纯过滤——剩几条注几条，全量压制（0 条新鲜命中）是正确状态而非未命中。
+                const seen = dedupe.seen(payload.agent.id);
+                const fresh = hits.filter((h) => !seen.has(h.id));
+                const suppressed = hits.length - fresh.length;
+                st.suppressedRecalls += suppressed;
+                if (suppressed > 0) {
+                    logger.debug?.(`[memory] 召回去重：压制 ${suppressed} 条已注入记忆（agent=${payload.agent.id}，余 ${fresh.length} 条新鲜命中）`);
+                }
+                if (hits.length > 0) {
+                    // 全量压制轮也计入命中：相关记忆已在模型上下文里，本质是命中
+                    st.hitTurns++;
+                    st.totalHits += fresh.length;
+                }
+                if (fresh.length === 0)
                     return decision;
-                const lines = applyRecallBudget(hits.map((h) => `- [${h.scene_name ? `${h.type}|${h.scene_name}` : h.type}] ${h.content}`), { maxCharsPerMemory: cfg.recall.maxCharsPerMemory, maxTotalRecallChars: cfg.recall.maxTotalRecallChars });
+                const lines = applyRecallBudget(fresh.map((h) => `- [${h.scene_name ? `${h.type}|${h.scene_name}` : h.type}] ${h.content}`), { maxCharsPerMemory: cfg.recall.maxCharsPerMemory, maxTotalRecallChars: cfg.recall.maxTotalRecallChars });
                 if (lines.length === 0)
                     return decision;
+                // 预算截断只丢尾部（前缀保留）：实际注入 = fresh 的前 lines.length 条——只标记模型真实看到的
+                dedupe.mark(payload.agent.id, fresh.slice(0, lines.length).map((h) => h.id));
+                st.lastHits = lines.length;
                 const text = [
                     '<relevant-memories>',
                     '以下是当前对话召回的相关记忆，不代表当前任务进程，仅作为参考：',
@@ -156,7 +215,7 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes) {
                     const body = mode === 'auto'
                         ? formatProfileAuto(profileCache.chat, profileCache.work)
                         : formatProfileSingle(profileCache[mode]);
-                    const hasRecallHit = (recallHits.get(agent.id) ?? 0) > 0;
+                    const hasRecallHit = (recallStats.get(agent.id)?.lastHits ?? 0) > 0;
                     // 指南三条件门控：工具已注册（cfg.tools）&&（稳定内容 ∥ 本轮召回命中）——
                     // 空库用户与关闭工具的用户不付这份固定 token（原版 auto-recall 同款语义）
                     if (!cfg.tools)
@@ -189,7 +248,7 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes) {
             }
         }
     });
-    return { invalidateProfile };
+    return { invalidateProfile, stats: (id) => recallStats.get(id) };
 }
 /** auto 档 <user-persona> 内的域说明：让模型理解分块结构与两域的独立性。 */
 const DOMAIN_HINT = '以下内容按记忆域分块：chat=用户个人画像（User Narrative Profile），work=团队工作准则（Team Operating Doctrine）。' +