dsh-layered-memory 0.8.4 → 0.8.6

package/dist/store/local-embedding.js

@@ -1,20 +1,118 @@
+/**
+ * 本地嵌入服务（D1/D6 决策，worker 线程化版）：transformers.js 的模型加载与
+ * ONNX 推理全部在 worker_threads 子线程执行（resources/embedding-worker.cjs），
+ * 本类只是主线程侧的协议代理——onnxruntime-node 的 run/loadModel 是主线程
+ * 同步调用，留在宿主事件循环会冻结整个 dsh 页面（0.8.6 修复的真实事故）。
+ *
+ * - 懒加载（D6）：首次嵌入/warmup 才让 worker 加载模型，close()=terminate
+ *   释放线程与模型（嵌入源切走/关闭时调用），terminated 后不可复用；
+ * - 模型从数据目录 models/<id>/ 本地加载（worker 侧 env.allowRemoteModels=false）；
+ * - channel 可注入（测试缝）：smoke 用假通道验证协议与状态机，不触真模型；
+ * - callOpts.timeoutMs 经 Promise.race 钳制（迟到回复按 id 丢弃——推理在
+ *   worker 线程无法真正取消，但主线程可以停止等待并降级 FTS）；
+ * - 池化方式来自模型目录（BGE 系 CLS / Gemma 系 MEAN），normalize 交给
+ *   pipeline 内建 L2 归一（与远程路径的 sanitizeAndNormalize 语义一致）。
+ */
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+/** 默认 worker 资产路径：dist/store/ → dist/embedding-worker.cjs（构建期拷入）。 */
+function defaultWorkerPath() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'embedding-worker.cjs');
+}
+/** 真实通道：spawn worker_threads + 自增 id 配对 + 崩溃兜底拒绝。 */
+class RealWorkerChannel {
+    worker;
+    pending = new Map();
+    nextId = 1;
+    terminated = false;
+    crashed;
+    crashCb;
+    constructor(workerPath, workerData) {
+        this.worker = new Worker(workerPath, { workerData });
+        this.worker.on('message', (msg) => {
+            if (msg && msg.type === 'fatal') {
+                this.failAll(`本地嵌入 worker 致命错误: ${msg.error ?? '未知'}`);
+                return;
+            }
+            const id = msg.id;
+            if (typeof id !== 'number')
+                return;
+            const entry = this.pending.get(id);
+            if (!entry)
+                return; // 迟到回复（调用方已超时放弃）
+            this.pending.delete(id);
+            entry.resolve(msg);
+        });
+        // error（未捕获异常且 worker 未自处理）与 exit（含 fatal 后的退出）都兜底拒绝
+        this.worker.on('error', (err) => this.failAll(`本地嵌入 worker 线程错误: ${err.message}`));
+        this.worker.on('exit', (code) => {
+            if (!this.terminated)
+                this.failAll(`本地嵌入 worker 线程退出（code=${code}）`);
+        });
+    }
+    request(call) {
+        // 已释放/已崩溃的通道快速拒绝——postMessage 到死线程是静默无回应，调用方会挂到超时
+        if (this.terminated)
+            return Promise.reject(new Error('嵌入 worker 已释放'));
+        if (this.crashed)
+            return Promise.reject(new Error(this.crashed));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.worker.postMessage({ ...call, id });
+        });
+    }
+    terminate() {
+        if (this.terminated)
+            return;
+        this.terminated = true;
+        this.failAll('嵌入 worker 已释放');
+        void this.worker.terminate();
+    }
+    setOnCrash(cb) {
+        this.crashCb = cb;
+        // 构造与回调注册之间发生的崩溃（spawn 即失败等）不丢通知
+        if (this.crashed)
+            cb(this.crashed);
+    }
+    failAll(error) {
+        for (const [, entry] of this.pending)
+            entry.reject(new Error(error));
+        this.pending.clear();
+        if (!this.terminated && !this.crashed) {
+            this.crashed = error;
+            this.crashCb?.(error);
+        }
+    }
+}
 export class LocalEmbeddingService {
     state = 'idle';
-    extractor = null;
-    loadPromise = null;
     loadError = null;
-    modelDir;
+    channel;
     entry;
-    loader;
     logger;
-    /** 输入截断（与远程路径同源的 embedding.maxInputChars 配置，缺省 5000）。 */
-    maxInputChars;
-    constructor(entry, modelDir, loader, logger, maxInputChars) {
+    constructor(entry, modelDir, opts) {
         this.entry = entry;
-        this.modelDir = modelDir;
-        this.loader = loader;
-        this.logger = logger;
-        this.maxInputChars = maxInputChars && maxInputChars > 0 ? maxInputChars : 5000;
+        this.logger = opts.logger;
+        const maxInputChars = opts.maxInputChars && opts.maxInputChars > 0 ? opts.maxInputChars : 5000;
+        this.channel =
+            opts.channel ??
+                new RealWorkerChannel(opts.workerPath ?? defaultWorkerPath(), {
+                    runtimeDir: opts.runtimeDir,
+                    modelDir,
+                    pooling: entry.pooling,
+                    dtype: 'q8',
+                    maxInputChars,
+                });
+        // 崩溃不自愈（换源/重启恢复）：拒绝语义沿 EmbedHelper 降级链走 FTS
+        this.channel.setOnCrash((error) => {
+            if (this.state === 'terminated')
+                return;
+            this.state = 'failed';
+            this.loadError = error;
+            this.logger?.warn(`[memory] ${error}（本地嵌入转入 failed 态，换源或重启可恢复）`);
+        });
     }
     getDimensions() {
         return this.entry.dims;
@@ -24,7 +122,7 @@ export class LocalEmbeddingService {
         return { provider: 'local', model: this.entry.id, dimensions: this.entry.dims };
     }
     isReady() {
-        return this.state === 'ready' && this.extractor !== null;
+        return this.state === 'ready';
     }
     /** 状态（进度展示用）。 */
     getState() {
@@ -33,91 +131,97 @@ export class LocalEmbeddingService {
     getLoadError() {
         return this.loadError;
     }
-    /** 后台预热：下载完成后验证可加载性（幂等；失败态可重试）。 */
+    /** 后台预热：启动后让 worker 立即加载模型（幂等；失败态可重试）。 */
     startWarmup() {
-        void this.ensureLoaded();
+        void this.waitForReady().catch(() => { });
     }
-    /** 等待预热完成（测试用）。 */
+    /** 等待模型就绪（warmup 协议；applyChain 的 warming 阶段与测试用）。 */
     async waitForReady() {
-        await this.ensureLoaded();
+        if (this.state === 'ready')
+            return;
+        if (this.state === 'terminated') {
+            throw new Error('本地嵌入服务已释放（嵌入源已切换）；本实例不可复用');
+        }
+        if (this.state !== 'failed')
+            this.state = 'loading';
+        const reply = await this.channel.request({ type: 'warmup' });
+        if (!reply.ok) {
+            this.applyLoadFailure(reply.error);
+            throw new Error(reply.error);
+        }
+        this.markReady();
     }
-    async embed(text) {
-        const [vec] = await this.embedBatch([text]);
+    async embed(text, callOpts) {
+        const [vec] = await this.embedBatch([text], callOpts);
         return vec;
     }
-    async embedBatch(texts) {
+    async embedBatch(texts, callOpts) {
         if (texts.length === 0)
             return [];
         if (this.state === 'terminated') {
             throw new Error('本地嵌入服务已释放（嵌入源已切换）；本实例不可复用');
         }
-        // 首次调用触发懒加载（D6：加载期间调用方等待而非失败——召回只慢这一次）；
-        // 只有明确失败过的服务才抛错（EmbedHelper 捕获后降级 FTS）
-        if (this.state !== 'ready') {
-            if (this.state === 'failed') {
-                throw new Error(`本地嵌入模型加载失败: ${this.loadError ?? '未知原因'}（重启插件或重新下载模型可重试）`);
-            }
-            await this.ensureLoaded();
+        if (this.state === 'failed') {
+            // 只有明确失败过的服务才抛错（EmbedHelper 捕获后降级 FTS）；warmup 可重试
+            throw new Error(`本地嵌入模型加载失败: ${this.loadError ?? '未知原因'}（重启插件或重新下载模型可重试）`);
+        }
+        if (this.state !== 'ready')
+            this.state = 'loading';
+        // 单条请求（召回 query）带优先标记：worker 侧插队，不被 reindex 批次堵队尾
+        const reply = await this.requestWithTimeout({ type: 'embed', texts, priority: texts.length === 1 }, callOpts?.timeoutMs);
+        if (!reply.ok) {
+            if (reply.stage === 'load')
+                this.applyLoadFailure(reply.error);
+            else
+                this.markReady(); // 推理失败说明模型已加载成功（loading → ready），失败只属于这一次调用
+            throw new Error(reply.error);
         }
-        const out = [];
-        // CPU 推理逐条最稳（ORT session 内部并行），量级为本插件写入/重嵌批（≤16）没问题
-        for (const text of texts) {
-            const result = await this.extractor([text.slice(0, this.maxInputChars)], { pooling: this.entry.pooling, normalize: true });
-            out.push(new Float32Array(result[0].data));
+        if (reply.type !== 'embedded')
+            throw new Error(`嵌入 worker 返回异常消息类型: ${reply.type}`);
+        this.markReady();
+        for (const v of reply.vectors) {
+            if (v.length !== this.entry.dims) {
+                throw new Error(`本地嵌入维度不匹配：期望 ${this.entry.dims}，得到 ${v.length}`);
+            }
         }
-        return out;
+        return reply.vectors;
     }
-    /** 释放模型（嵌入源切走/关闭时调用；幂等）。terminated 后不可再复用——
-     * 防止插件卸载/切走后残留的重嵌循环把模型重新加载常驻（内存泄漏）。 */
+    /** 释放 worker 线程与模型（嵌入源切走/关闭时调用；幂等）。terminated 后不可
+     *  再复用——防止插件卸载/切走后残留的重嵌循环把模型重新加载常驻（内存泄漏）。 */
     close() {
-        const ext = this.extractor;
-        this.extractor = null;
-        this.loadPromise = null;
         this.state = 'terminated';
         this.loadError = null;
+        this.channel.terminate();
+    }
+    /** 内层钳制（仅缩短）：超时放弃等待（迟到回复由通道按 id 丢弃），调用方降级。 */
+    async requestWithTimeout(call, timeoutMs) {
+        if (!(timeoutMs && timeoutMs > 0))
+            return this.channel.request(call);
+        let timer;
         try {
-            const dispose = ext?.dispose;
-            if (dispose)
-                void Promise.resolve(dispose.call(ext));
+            return await Promise.race([
+                this.channel.request(call),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`本地嵌入调用超时（${timeoutMs}ms），已放弃等待`)), timeoutMs);
+                }),
+            ]);
         }
-        catch {
-            /* 释放失败不影响状态复位 */
+        finally {
+            // 先到者胜出后清掉另一个定时器（不清理会挂住引用至自然到期，raceRecallTimeout 同款）
+            if (timer)
+                clearTimeout(timer);
         }
     }
-    async ensureLoaded() {
+    /** loading → ready 一次性日志（memory.log 时序可读性：启动到模型就绪的间隔）。 */
+    markReady() {
         if (this.state === 'ready')
             return;
-        if (this.state === 'loading' && this.loadPromise)
-            return this.loadPromise;
-        this.state = 'loading';
-        this.loadError = null;
-        this.loadPromise = (async () => {
-            try {
-                const mod = await this.loader();
-                if (mod.env) {
-                    mod.env.allowRemoteModels = false;
-                    if (mod.env.allowLocalModels !== undefined)
-                        mod.env.allowLocalModels = true;
-                }
-                const extractor = await mod.pipeline('feature-extraction', this.modelDir, { dtype: 'q8' });
-                // loading 中被 close()（terminated）：不得覆写状态复活（review C）——直接释放丢弃
-                if (this.state === 'terminated') {
-                    const dispose = extractor.dispose;
-                    if (dispose)
-                        void Promise.resolve(dispose.call(extractor)).catch(() => { });
-                    throw new Error('加载期间服务已释放');
-                }
-                this.extractor = extractor;
-                this.state = 'ready';
-                this.logger?.info(`[memory] 本地嵌入模型就绪: ${this.entry.id}（dims=${this.entry.dims}，pooling=${this.entry.pooling}）`);
-            }
-            catch (err) {
-                this.state = 'failed';
-                this.loadError = err instanceof Error ? err.message : String(err);
-                this.logger?.warn(`[memory] 本地嵌入模型加载失败（${this.entry.id}）: ${this.loadError}`);
-                throw err;
-            }
-        })();
-        return this.loadPromise;
+        this.state = 'ready';
+        this.logger?.info(`[memory] 本地嵌入模型就绪: ${this.entry.id}（dims=${this.entry.dims}，pooling=${this.entry.pooling}）`);
+    }
+    applyLoadFailure(error) {
+        this.state = 'failed';
+        this.loadError = error;
+        this.logger?.warn(`[memory] 本地嵌入模型加载失败（${this.entry.id}）: ${error}`);
     }
 }

package/dist/store/recall-dedupe.d.ts

@@ -0,0 +1,26 @@
+import type { MemoryLogger } from '../types.js';
+/** 会话条目上限（按 updatedAt 淘汰最旧；防文件无限增长）。 */
+export declare const RECALL_DEDUPE_SESSION_CAP = 200;
+/** 单会话记录 id 上限（按插入序淘汰最旧；Set 迭代序即插入序）。 */
+export declare const RECALL_DEDUPE_IDS_CAP = 512;
+export declare class RecallDedupeStore {
+    private readonly logger?;
+    private readonly file;
+    private readonly entries;
+    private persistFailed;
+    /** 串行化持久化写（避免并发原子写撞临时文件名）；init 链最前（先载入再落盘，防丢更新）。 */
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    /** 载入持久化映射（合并进内存——构造与载入之间发生的 mark 不丢）；失败降级内存态。 */
+    private init;
+    /** 该会话的已注入集合（热路径同步读；未出现过的会话返回空集合，惰性建条）。 */
+    seen(sessionId: string): Set<string>;
+    /** 标记本轮实际注入的记录 id（写穿；调用方保证只传模型真实看到的条目）。 */
+    mark(sessionId: string, recordIds: string[]): void;
+    /** 清空该会话的记录（compact/clear 后上下文已丢失，记忆需可重新注入）。 */
+    reset(sessionId: string): void;
+    /** 等待在途持久化写完成（测试/停机用）。 */
+    flush(): Promise<void>;
+    private persist;
+    private serialize;
+}

package/dist/store/recall-dedupe.js

@@ -0,0 +1,138 @@
+/**
+ * 召回去重存储：sessionId → 已注入 L1 记录 id 集合的持久化映射。
+ *
+ * 语义（2026-08-24 设计共识）：
+ * - 同会话内已注入过的记忆不再重复注入（模型上下文已持有，重复注入浪费 token）；
+ * - 压制粒度 = 记录 id——去重合并更新会换新 id，新内容天然解除压制重新注入；
+ * - compact/clear 事件重置（上下文被压缩/清空，注入内容已丢失）；resume 不重置；
+ * - 热路径（召回 pre-step）同步内存读取，mark/reset 写穿持久化（session-modes 同款：
+ *   串行化原子写 + 失败降级内存态），任何 I/O 失败绝不抛进召回路径。
+ */
+import * as path from 'node:path';
+import { errDetail } from '../util/filelog.js';
+import { atomicWriteJson, ensureDir, readJsonIfExists } from './io.js';
+/** 会话条目上限（按 updatedAt 淘汰最旧；防文件无限增长）。 */
+export const RECALL_DEDUPE_SESSION_CAP = 200;
+/** 单会话记录 id 上限（按插入序淘汰最旧；Set 迭代序即插入序）。 */
+export const RECALL_DEDUPE_IDS_CAP = 512;
+/** 条目过期清理（90 天未更新即丢弃，与 session-modes 同款量级）。 */
+const PRUNE_MS = 90 * 24 * 3600_000;
+export class RecallDedupeStore {
+    logger;
+    file;
+    entries = new Map();
+    persistFailed = false;
+    /** 串行化持久化写（避免并发原子写撞临时文件名）；init 链最前（先载入再落盘，防丢更新）。 */
+    writeChain;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'recall-dedupe.json');
+        this.writeChain = this.init();
+    }
+    /** 载入持久化映射（合并进内存——构造与载入之间发生的 mark 不丢）；失败降级内存态。 */
+    async init() {
+        const data = await readJsonIfExists(this.file);
+        if (!data?.sessions || typeof data.sessions !== 'object')
+            return;
+        const now = Date.now();
+        let count = 0;
+        for (const [sid, entry] of Object.entries(data.sessions)) {
+            if (!Array.isArray(entry?.recordIds))
+                continue;
+            if (now - (entry.updatedAt ?? 0) > PRUNE_MS)
+                continue;
+            const existing = this.entries.get(sid);
+            if (existing) {
+                // 合并：构造后、载入完成前已发生的 mark（保留较大 updatedAt）
+                for (const id of entry.recordIds)
+                    existing.ids.add(id);
+                existing.updatedAt = Math.max(existing.updatedAt, entry.updatedAt ?? 0);
+            }
+            else {
+                this.entries.set(sid, { ids: new Set(entry.recordIds), updatedAt: entry.updatedAt ?? now });
+            }
+            count++;
+        }
+        if (count > 0)
+            this.logger?.info(`[memory] 召回去重记录载入 ${count} 个会话`);
+    }
+    /** 该会话的已注入集合（热路径同步读；未出现过的会话返回空集合，惰性建条）。 */
+    seen(sessionId) {
+        let entry = this.entries.get(sessionId);
+        if (!entry) {
+            entry = { ids: new Set(), updatedAt: 0 };
+            this.entries.set(sessionId, entry);
+        }
+        return entry.ids;
+    }
+    /** 标记本轮实际注入的记录 id（写穿；调用方保证只传模型真实看到的条目）。 */
+    mark(sessionId, recordIds) {
+        if (recordIds.length === 0)
+            return;
+        const ids = this.seen(sessionId);
+        for (const id of recordIds)
+            ids.add(id);
+        // 插入序淘汰最旧（Set 迭代序 = 插入序）
+        while (ids.size > RECALL_DEDUPE_IDS_CAP) {
+            const oldest = ids.values().next().value;
+            if (oldest === undefined)
+                break;
+            ids.delete(oldest);
+        }
+        const entry = this.entries.get(sessionId);
+        entry.updatedAt = Date.now();
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    /** 清空该会话的记录（compact/clear 后上下文已丢失，记忆需可重新注入）。 */
+    reset(sessionId) {
+        if (!this.entries.has(sessionId))
+            return;
+        this.entries.delete(sessionId);
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    /** 等待在途持久化写完成（测试/停机用）。 */
+    flush() {
+        return this.writeChain;
+    }
+    async persist() {
+        try {
+            await ensureDir(path.dirname(this.file));
+            await atomicWriteJson(this.file, this.serialize());
+            this.persistFailed = false;
+        }
+        catch (err) {
+            if (!this.persistFailed) {
+                this.persistFailed = true;
+                this.logger?.warn(`[memory] 召回去重持久化失败（降级内存态）: ${errDetail(err)}`);
+            }
+        }
+    }
+    serialize() {
+        const now = Date.now();
+        // 超期清理 + 条数上限（按 updatedAt 淘汰最旧）
+        for (const [sid, e] of this.entries) {
+            if (now - e.updatedAt > PRUNE_MS && e.updatedAt > 0)
+                this.entries.delete(sid);
+        }
+        while (this.entries.size > RECALL_DEDUPE_SESSION_CAP) {
+            let oldest;
+            let oldestAt = Infinity;
+            for (const [sid, e] of this.entries) {
+                if (e.updatedAt > 0 && e.updatedAt < oldestAt) {
+                    oldest = sid;
+                    oldestAt = e.updatedAt;
+                }
+            }
+            if (oldest === undefined)
+                break; // 只剩惰性空条目（updatedAt=0），不占文件体积可留待过期清理
+            this.entries.delete(oldest);
+        }
+        const sessions = {};
+        for (const [sid, e] of this.entries) {
+            if (e.ids.size === 0)
+                continue; // 空集合不落盘
+            sessions[sid] = { recordIds: [...e.ids], updatedAt: e.updatedAt };
+        }
+        return { version: 1, sessions };
+    }
+}

package/dist/store/runtime-installer.d.ts

@@ -60,8 +60,6 @@ export declare class RuntimeInstaller {
      * runNpm 起跑前复查即不再起新进程（否则回退的 npm 会跑到自然结束且无法再取消）。
      */
     cancel(): boolean;
-    /** 从 runtime 目录解析已安装的 transformers 模块（LocalEmbeddingService 用）。 */
-    resolveModule(): unknown;
     private pushLine;
     /** 跑一次 npm 子进程（采集尾行 + 超时 kill），返回退出码（null = 被杀死/启动失败）。 */
     private runNpm;

package/dist/store/runtime-installer.js

@@ -14,7 +14,6 @@
  * - 幂等：已装版本 == 目标版本直接就绪；版本漂移（插件升级换了钉死版本）重装覆盖。
  */
 import { spawn } from 'node:child_process';
-import { createRequire } from 'node:module';
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -139,11 +138,6 @@ export class RuntimeInstaller {
         this.child?.kill();
         return true;
     }
-    /** 从 runtime 目录解析已安装的 transformers 模块（LocalEmbeddingService 用）。 */
-    resolveModule() {
-        const req = createRequire(path.join(this.runtimeDir, 'package.json'));
-        return req(RuntimeInstaller.packageName);
-    }
     pushLine(line) {
         const lines = this.progress.lastLines;
         lines.push(line.length > 300 ? line.slice(0, 300) + '…' : line);

package/dist/store/search-utils.d.ts

@@ -1,5 +1,22 @@
 /** 标准 RRF 常数（原论文值）；k 越大越偏向低排名项（分布更平滑）。 */
 export declare const RRF_K = 60;
+/** 衰减地板（#29 时效加权的安全边界）：老记忆最多损失一半排序分，永不沉底。
+ *  内部常量不进配置——它是安全机制不是调参旋钮。 */
+export declare const DECAY_FLOOR = 0.5;
+/**
+ * 时效衰减加权（#29，读路径专用）：score × max(FLOOR, 0.5^(Δ天/半衰期)) 后重排序。
+ *
+ * - Δ 按 updated_at（内容版本时间）起算，缺失/非法按最老 → 地板接管（零特判分支）；
+ * - 乘法保相关性主导：只在相关度相近的候选之间轮转名次（名额新鲜度），不淘汰不
+ *   硬过滤——score≈0 的新记忆乘什么都是 ≈0；hit 的原 score 字段不被改写（排序用
+ *   加权分，展示仍反映检索相关度）；
+ * - halfLifeDays ≤ 0 直接原样返回（开关关闭）；
+ * - 仅用于召回/工具检索；searchCandidates（去重候选）不得应用——写路径找同语义
+ *   旧记录要无视新旧，衰减会让去重漏检（同事实双记录）。
+ */
+export declare function applyDecayWeight<T extends {
+    score: number;
+}>(hits: T[], halfLifeDays: number, updatedAtOf: (hit: T) => number | undefined, now?: number): T[];
 /**
  * RRF 融合多个已排序列表：每项得分 = 各列表 1/(k + rank + 1) 之和。
  * 出现在多个列表的项得分累加，按得分降序返回（附 rrfScore）。

package/dist/store/search-utils.js

@@ -10,6 +10,35 @@
 import { tokenize } from '../util/text.js';
 /** 标准 RRF 常数（原论文值）；k 越大越偏向低排名项（分布更平滑）。 */
 export const RRF_K = 60;
+/** 衰减地板（#29 时效加权的安全边界）：老记忆最多损失一半排序分，永不沉底。
+ *  内部常量不进配置——它是安全机制不是调参旋钮。 */
+export const DECAY_FLOOR = 0.5;
+/**
+ * 时效衰减加权（#29，读路径专用）：score × max(FLOOR, 0.5^(Δ天/半衰期)) 后重排序。
+ *
+ * - Δ 按 updated_at（内容版本时间）起算，缺失/非法按最老 → 地板接管（零特判分支）；
+ * - 乘法保相关性主导：只在相关度相近的候选之间轮转名次（名额新鲜度），不淘汰不
+ *   硬过滤——score≈0 的新记忆乘什么都是 ≈0；hit 的原 score 字段不被改写（排序用
+ *   加权分，展示仍反映检索相关度）；
+ * - halfLifeDays ≤ 0 直接原样返回（开关关闭）；
+ * - 仅用于召回/工具检索；searchCandidates（去重候选）不得应用——写路径找同语义
+ *   旧记录要无视新旧，衰减会让去重漏检（同事实双记录）。
+ */
+export function applyDecayWeight(hits, halfLifeDays, updatedAtOf, now = Date.now()) {
+    if (!(halfLifeDays > 0) || hits.length === 0)
+        return hits;
+    const weight = (h) => {
+        const t = updatedAtOf(h);
+        if (t == null || !Number.isFinite(t))
+            return DECAY_FLOOR;
+        const days = Math.max(0, (now - t) / 86_400_000);
+        return Math.max(DECAY_FLOOR, 0.5 ** (days / halfLifeDays));
+    };
+    return hits
+        .map((h) => ({ h, weighted: h.score * weight(h) }))
+        .sort((a, b) => b.weighted - a.weighted)
+        .map((x) => x.h);
+}
 /**
  * RRF 融合多个已排序列表：每项得分 = 各列表 1/(k + rank + 1) 之和。
  * 出现在多个列表的项得分累加，按得分降序返回（附 rrfScore）。

package/dist/store/sqlite.d.ts

@@ -148,6 +148,8 @@ export declare class MemoryDb {
     countL0(): number;
     /** 统计 recorded_at >= iso 的消息数（状态面板"今日捕获"用）。 */
     countL0Since(iso: string): number;
+    /** 统计某会话已捕获消息数（session-stats 数据源；idx_l0_session_id 索引点查）。 */
+    countL0BySession(sessionId: string): number;
     /** 按会话取最近消息（时间升序返回；走 idx_l0_session_id 索引）。
      *  蒸馏背景参考专用——按会话现查替代全局内存数组（ADR-0003）。 */
     recentL0BySession(sessionId: string, limit: number): L0MessageRecord[];

package/dist/store/sqlite.js

@@ -670,12 +670,19 @@ export class MemoryDb {
     /** 事务内的单条写入体（upsertL1 / upsertL1Batch 共用；调用方负责 BEGIN/COMMIT）。 */
     upsertL1InTx(record, embedding) {
         const ts = timestampsToDb(record.timestamps);
+        // 绑定层字段兜底（取 schema 列默认）：旧版 JSONL 等外部数据缺字段时 undefined
+        // 无法绑定（node:sqlite 拒绝绑定），曾致旧版导入逐条全挂、每次启动无限重试（#28）。
+        // 主表与 FTS 两条语句共用同源归一化值；type 归一化后 familyForType 也不再收到 undefined。
+        const type = record.type ?? '';
+        const priority = record.priority ?? 50;
+        const sceneName = record.scene_name ?? '';
+        const family = record.family ?? familyForType(type);
         // 防御性 FTS 删除的前置点查（主键索引，微秒级）：record_id 在 FTS 表是 UNINDEXED，
         // 按 id DELETE 是 O(N) 全表扫描——导入/重建/重嵌等"全新增"路径曾为每条记录白付一次
         // 全扫（批量写整体 O(N²)）。只有主表已有该行（覆盖/合并）才可能有旧 FTS 行需要删。
         // 同批重复 id 也能正确处理：首条插入后，第二条的点查在同一事务内已见新行。
         const ftsExisted = this.ftsAvailable ? this.stmtL1Exists.get(record.id) !== undefined : false;
-        this.stmtUpsertL1.run(record.id, record.content, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
+        this.stmtUpsertL1.run(record.id, record.content, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), family);
         // vec0 不支持 ON CONFLICT → 先删后插；零向量跳过（cosine 未定义）
         if (this.stmtDeleteL1Vec && this.stmtInsertL1Vec) {
             this.stmtDeleteL1Vec.run(record.id);
@@ -688,7 +695,7 @@ export class MemoryDb {
         if (this.ftsAvailable) {
             if (ftsExisted)
                 this.stmtL1FtsDelete.run(record.id);
-            this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
+            this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), family);
         }
     }
     /** 批量删除 L1（元数据 + 向量 + FTS），返回删除条数。IN 按 ≤900 分块（避变量数上限）。 */
@@ -932,22 +939,29 @@ export class MemoryDb {
         try {
             this.db.exec('BEGIN');
             for (let i = 0; i < records.length; i++) {
-                const r = records[i];
+                const rec = records[i];
+                // 绑定层字段兜底（取 schema 列默认）：同 upsertL1InTx——外部数据缺字段时
+                // undefined 无法绑定（#28）；主表/向量/FTS 共用同源归一化值
+                const sessionId = rec.sessionId ?? 'default';
+                const role = rec.role ?? '';
+                const content = rec.content ?? '';
+                const recordedAt = rec.recordedAt ?? '';
+                const timestamp = rec.timestamp ?? 0;
                 // 同 upsertL1 的点查预判：全新增路径跳过 UNINDEXED 列的 FTS 全扫删除
-                const ftsExisted = this.ftsAvailable ? this.stmtL0Exists.get(r.id) !== undefined : false;
-                this.stmtUpsertL0.run(r.id, r.sessionId, r.role, r.content, r.recordedAt, r.timestamp);
+                const ftsExisted = this.ftsAvailable ? this.stmtL0Exists.get(rec.id) !== undefined : false;
+                this.stmtUpsertL0.run(rec.id, sessionId, role, content, recordedAt, timestamp);
                 if (this.stmtDeleteL0Vec && this.stmtInsertL0Vec) {
-                    this.stmtDeleteL0Vec.run(r.id);
+                    this.stmtDeleteL0Vec.run(rec.id);
                     const vec = embeddings?.[i];
                     if (vec && !isZeroVector(vec)) {
-                        this.stmtInsertL0Vec.run(r.id, vecToBuffer(vec), r.recordedAt);
+                        this.stmtInsertL0Vec.run(rec.id, vecToBuffer(vec), recordedAt);
                     }
                 }
                 if (this.ftsAvailable) {
                     // 同 upsertL1：FTS 失败冒泡触发整批回滚，禁止"删了没补"的索引空洞。
                     if (ftsExisted)
-                        this.stmtL0FtsDelete.run(r.id);
-                    this.stmtL0FtsInsert.run(tokenizeForFts(r.content), r.content, r.id, r.sessionId, r.role, r.recordedAt, r.timestamp);
+                        this.stmtL0FtsDelete.run(rec.id);
+                    this.stmtL0FtsInsert.run(tokenizeForFts(content), content, rec.id, sessionId, role, recordedAt, timestamp);
                 }
             }
             this.db.exec('COMMIT');
@@ -989,6 +1003,20 @@ export class MemoryDb {
             return 0;
         }
     }
+    /** 统计某会话已捕获消息数（session-stats 数据源；idx_l0_session_id 索引点查）。 */
+    countL0BySession(sessionId) {
+        if (this.degraded)
+            return 0;
+        try {
+            const row = this.db
+                .prepare('SELECT COUNT(*) AS n FROM l0_conversations WHERE session_id = ?')
+                .get(sessionId);
+            return row?.n ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    }
     /** 按会话取最近消息（时间升序返回；走 idx_l0_session_id 索引）。
      *  蒸馏背景参考专用——按会话现查替代全局内存数组（ADR-0003）。 */
     recentL0BySession(sessionId, limit) {