dsh-prime-memory 0.22.1 → 0.24.0

package/dist/store/sqlite.js

@@ -28,6 +28,20 @@ import { bm25RankToScore, buildFtsQuery, tokenizeForFts } from './search-utils.j
 import { describeTokenizer, ensureTokenizer, tokenizerStamp } from '../util/tokenizer.js';
 const require = createRequire(import.meta.url);
 const TAG = '[memory][sqlite]';
+/**
+ * 退场判据的 **SQL 侧同口径表达**（与 `isRetired` / `upsertL1InTx` 里的 `retiredNow` 一一对应）：
+ * `valid_to` 非空 **或** `metadata_json` 带退场标记。
+ *
+ * 为什么仓内只能有一份：退场记录有**三条检索面写路径绕过 upsert 漏斗**——
+ * FTS 重建回灌、增量重嵌入取数、补齐判据计数。任一处漏了就是：
+ * ① 退场行被放回检索面（前两处；重嵌入是 30 分钟一轮，比 FTS 重建更易命中）；
+ * ② 补齐判据永不收敛（第三处：缺向量的退场行永远算“还差”，却永远不该被补）。
+ * 判据分头写，三处迟早各自漂移 —— 故集中成这一个函数。
+ */
+function retiredL1Sql(alias) {
+    const p = alias ? `${alias}.` : '';
+    return `COALESCE(${p}valid_to, '') <> '' OR ${p}metadata_json LIKE '%"${SUPERSEDE_METADATA_KEY}"%'`;
+}
 // 成本账本(token_cost 表族)独立职责,此处 re-export 不断裂既有引用;
 // MemoryDb 的四个公开方法为一行委托。
 import { CostLedger } from './cost-ledger.js';
@@ -35,7 +49,7 @@ import { CostLedger } from './cost-ledger.js';
 import { GraphStore } from './graph-store.js';
 import { RECEIPTS_MAX_RUNS, RECEIPTS_QUERY_LIMIT_MAX } from './receipts.js';
 import { DEFER_MAX, groupConflictPairsByClaim, normalizeClaimKey, normalizeConflictType } from './conflicts.js';
-import { isRetired, readSupersedeMarker, stripSupersedeMarker, withSupersedeMarker } from './supersede.js';
+import { isRetired, readSupersedeMarker, stripSupersedeMarker, withSupersedeMarker, SUPERSEDE_METADATA_KEY } from './supersede.js';
 /** vec0 KNN 对遗留零向量的补偿缓冲。 */
 const ZERO_VEC_BUFFER = 10;
 /** IN 查询/删除的分块大小(保守避开 SQLite 变量数上限:现代构建 32766,老版 999)。 */
@@ -318,6 +332,24 @@ export class MemoryDb {
             this.db.exec("ALTER TABLE l1_records ADD COLUMN applicability TEXT NOT NULL DEFAULT ''");
             this.logger?.info(`${TAG} l1_records 补 repo 归属列(DEFAULT 即标注,存量零回填)`);
         }
+        // ── 外部导入幂等键(轨3-P0):ext_key='' 即内部记录(不参与去重),DEFAULT '' 存量零搬运。
+        // 部分唯一索引只约束非空值——多条内部记录 ext_key 同为 '' 互不冲突;仅当外部导入的
+        // 同一 (来源, 稳定身份) 重复导入才被结构性拒绝(写侧 pre-check + 索引双保险)。
+        if (!this.hasColumn('l1_records', 'ext_key')) {
+            this.db.exec("ALTER TABLE l1_records ADD COLUMN ext_key TEXT NOT NULL DEFAULT ''");
+            this.logger?.info(`${TAG} l1_records 补 ext_key 列(外部导入幂等键)`);
+        }
+        this.db.exec("CREATE UNIQUE INDEX IF NOT EXISTS l1_records_ext_key_uidx ON l1_records(ext_key) WHERE ext_key <> ''");
+        // ── 文件身份键(md 投射相, N1/N8/N9):`name` 是人可读且可编辑的稳定键，用来当
+        // `<root>/<type>/<name>.memory.md` 的文件名。为何不用 id：id 每轮新铸、从不复用；
+        // 为何不用 scene_name：实测基数大于记录数，当不了唯一名。
+        // 存量 name 恒为 '' ⇒ 部分索引不约束空串 ⇒ 旧库首次建索引必成（不会因重复值而
+        // 整库 degraded）。该列**不进** canonicalRecords 哈希字段表 ⇒ 快照零影响。
+        if (!this.hasColumn('l1_records', 'name')) {
+            this.db.exec("ALTER TABLE l1_records ADD COLUMN name TEXT NOT NULL DEFAULT ''");
+            this.logger?.info(`${TAG} l1_records 补 name 列(文件身份键，存量全空)`);
+        }
+        this.db.exec("CREATE UNIQUE INDEX IF NOT EXISTS l1_records_name_uidx ON l1_records(name) WHERE name <> ''");
         // L2 场景重聚类作业队列(治理 W3 T3.10;ruminate 空闲档消费,每轮至多 1 作业)。
         // source 区分触发来源('demote'|'repo-change'),便于诊断与重入队语义区分。
         this.db.exec(`
@@ -434,8 +466,8 @@ export class MemoryDb {
         record_id, content, type, priority, scene_name, session_id, version,
         timestamp_str, timestamp_start, timestamp_end, created_time, updated_time, metadata_json, family,
         valid_from, valid_to, persistence, scope, workspace_id,
-        repo_key_name, repo_key_owner, applicability
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        repo_key_name, repo_key_owner, applicability, ext_key, name
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(record_id) DO UPDATE SET
         content=excluded.content,
         type=excluded.type,
@@ -455,13 +487,15 @@ export class MemoryDb {
         workspace_id=excluded.workspace_id,
         repo_key_name=excluded.repo_key_name,
         repo_key_owner=excluded.repo_key_owner,
-        applicability=excluded.applicability
+        applicability=excluded.applicability,
+        ext_key=excluded.ext_key,
+        name=excluded.name
     `);
         this.stmtGetL1 = this.db.prepare(`
       SELECT record_id, content, type, priority, scene_name, version, timestamp_str,
              timestamp_start, timestamp_end, created_time, updated_time, metadata_json, family,
              valid_from, valid_to, persistence, scope, workspace_id,
-             repo_key_name, repo_key_owner, applicability
+             repo_key_name, repo_key_owner, applicability, name
       FROM l1_records WHERE record_id = ?
     `);
         this.stmtL1Exists = this.db.prepare('SELECT 1 FROM l1_records WHERE record_id = ?');
@@ -602,6 +636,10 @@ export class MemoryDb {
       `);
             if (ftsRebuilt)
                 this.backfillL1Fts();
+            // 退场残留清理(幂等):历史上退场不变量只在写入漏斗上强制,FTS 重建回灌与
+            // 增量重嵌入两条旁路会把已退场记录留在检索面里(实测本机 725 行)。
+            // 上面的口径修复只挡新增，已有的要在这里收掉——否则那 725 条永远脏着。
+            this.purgeRetiredRetrievalRows();
             this.stmtL0FtsInsert = this.db.prepare(`
         INSERT INTO l0_fts (message_text, message_text_original, record_id, session_id, role, recorded_at, timestamp)
         VALUES (?, ?, ?, ?, ?, ?, ?)
@@ -735,10 +773,14 @@ export class MemoryDb {
      */
     backfillL1Fts() {
         let count = 0;
+        // 退场行不回灌(理由见 `retiredL1Sql`)。跳过数单独数一次:重建是低频动作,
+        // 多一条 COUNT 换“运维看得见跳过了多少”比静默少灌划算。
+        const retiredSkipped = this.countL1Retired();
         const stmt = this.db
             .prepare(`SELECT record_id, content, type, priority, scene_name, session_id, version,
                 timestamp_str, timestamp_start, timestamp_end, metadata_json, family,
-                scope, workspace_id FROM l1_records`);
+                scope, workspace_id FROM l1_records
+         WHERE NOT (${retiredL1Sql()})`);
         for (const r of stmt.iterate()) {
             try {
                 this.stmtL1FtsInsert.run(tokenizeForFts(String(r.content ?? '')), String(r.content ?? ''), String(r.record_id ?? ''), String(r.type ?? ''), Number(r.priority ?? 50), String(r.scene_name ?? ''), String(r.session_id ?? 'default'), Number(r.version ?? 0), String(r.timestamp_str ?? ''), String(r.timestamp_start ?? ''), String(r.timestamp_end ?? ''), String(r.metadata_json ?? '{}'), String(r.family ?? 'chat'), 
@@ -751,8 +793,52 @@ export class MemoryDb {
                 /* 单行失败跳过(吞+计数:count 与总量比对可发现大面积失败) */
             }
         }
-        if (count > 0)
-            this.logger?.info(`${TAG} l1_fts 回灌 ${count} 行`);
+        if (count > 0 || retiredSkipped !== 0) {
+            this.logger?.info(`${TAG} l1_fts 回灌 ${count} 行(跳过已退场 ${retiredSkipped < 0 ? '计数失败' : retiredSkipped} 行)`);
+        }
+    }
+    /**
+     * 已退场 L1 行数。原本只给回灌留痕用，现在展示面也要它：
+     * `vectorCounts` 算“待补”时得分掉退场行（它们合法地无向量），否则那个数永远归不了零。
+     * 失败返回 -1——宁可日志写“未知”也不假装 0 条。
+     */
+    countL1Retired() {
+        try {
+            const row = this.db.prepare(`SELECT COUNT(*) AS n FROM l1_records WHERE ${retiredL1Sql()}`).all()[0];
+            return row?.n ?? 0;
+        }
+        catch {
+            return -1;
+        }
+    }
+    /**
+     * 清除“已退场但仍待在检索面”的残留行（FTS + 向量）。幂等：第二次跑命中 0 行。
+     *
+     * 为什么必须存在于启动路径：口径修复只挡住**新增**的脏行，而存量脏行仍在给
+     * BM25/向量检索供货——对用户而言就是“标了失效却还能被召回”。
+     * 失败只 warn：这是个修复动作，无权把库拖进 degraded，更不能抛进启动
+     * 的 await 链（那里报错 = storageOk=false = 记忆功能整体停用）。
+     */
+    purgeRetiredRetrievalRows() {
+        const sub = `SELECT record_id FROM l1_records WHERE ${retiredL1Sql()}`;
+        // 能力不在就别发 DELETE——每次启动一条无谓告警会把真问题埋掉。
+        const targets = [
+            { table: 'l1_fts', ready: this.stmtL1FtsInsert !== undefined },
+            { table: 'l1_vec', ready: this.stmtDeleteL1Vec !== undefined && this.tableExists('l1_vec') },
+        ];
+        let purged = 0;
+        for (const t of targets) {
+            if (!t.ready)
+                continue;
+            try {
+                purged += Number(this.db.prepare(`DELETE FROM ${t.table} WHERE record_id IN (${sub})`).run().changes);
+            }
+            catch (err) {
+                this.logger?.warn(`${TAG} 退场残留清理失败(${t.table}，本轮跳过): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (purged > 0)
+            this.logger?.info(`${TAG} 清理退场残留检索行 ${purged} 条(FTS + 向量)`);
     }
     /** 重建后的 l0_fts 从 l0_conversations 全量回灌(仅 drop 重建时调用;iterate 流式)。 */
     backfillL0Fts() {
@@ -907,7 +993,10 @@ export class MemoryDb {
         // 旧版导入都会经这里写回记录,若照常重建 FTS/向量行,一条带退场标记的记录
         // 会**悄悄回到检索结果里**(而检索侧刻意不看 valid_to,正是为了零漂移)。
         const retiredNow = record.validTo !== undefined || readSupersedeMarker(record.metadata) !== undefined;
-        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, toIso(record.validFrom), toIso(record.validTo), normPersistence(record.persistence) ?? '', scope, workspaceId, record.repoKeyName ?? '', record.repoKeyOwner ?? '', normApplicability(record.applicability));
+        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, toIso(record.validFrom), toIso(record.validTo), normPersistence(record.persistence) ?? '', scope, workspaceId, record.repoKeyName ?? '', record.repoKeyOwner ?? '', normApplicability(record.applicability), record.extKey ?? '', 
+        // 文件身份键。存什么由调用方定（`deriveName` 已按 `sanitizeFilename` 纪律截断/洗字符），
+        // 这里只做 undefined → '' 的绑定兜底，与同一行其他可选列同口径。
+        record.name ?? '');
         // vec0 不支持 ON CONFLICT → 先删后插;零向量跳过(cosine 未定义)。
         // 已退场则**只删不插**(见上方 retiredNow 的说明)。
         if (this.stmtDeleteL1Vec && this.stmtInsertL1Vec) {
@@ -1050,7 +1139,7 @@ export class MemoryDb {
                 .prepare("SELECT COUNT(*) AS n FROM l1_records WHERE COALESCE(valid_to, '') <> ''")
                 .get();
             const rows = this.db
-                .prepare(`SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence, scope, workspace_id, repo_key_name, repo_key_owner, applicability
+                .prepare(`SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence, scope, workspace_id, repo_key_name, repo_key_owner, applicability, name
            FROM l1_records WHERE COALESCE(valid_to, '') <> '' ORDER BY updated_time DESC LIMIT ? OFFSET ?`)
                 .all(opts.limit, opts.offset);
             return { items: rows.map(rowToRecord), total: Number(totalRow?.n ?? 0) };
@@ -1076,10 +1165,14 @@ export class MemoryDb {
             const repoCols = table === 'l1_records' && this.hasColumn('l1_records', 'repo_key_name')
                 ? ', repo_key_name, repo_key_owner, applicability'
                 : '';
+            // 文件身份键(md 投射相):同款形状探测。没这一列的旧库读侧归一 undefined，
+            // 不报错——投射器把空 name 回落到 `mem-<id8>`，而不是把整条取记录路径弄挂。
+            const nameCol = table === 'l1_records' && this.hasColumn('l1_records', 'name') ? ', name' : '';
             const metaCols = 'record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family' +
                 temporal +
                 scopeCols +
-                repoCols;
+                repoCols +
+                nameCol;
             stmt =
                 action === 'delete'
                     ? this.db.prepare(`DELETE FROM ${table} WHERE record_id IN (${ph})`)
@@ -1134,6 +1227,23 @@ export class MemoryDb {
             return 0;
         }
     }
+    /**
+     * 按外部导入幂等键查已存在记录 id(轨3-P0 幂等 pre-check)。
+     * 空键/降级一律返回 undefined;未迁移旧库(无 ext_key 列)由 catch 兜底 undefined(fail-open)。
+     */
+    findRecordIdByExtKey(extKey) {
+        if (this.degraded || !extKey)
+            return undefined;
+        try {
+            const row = this.db
+                .prepare("SELECT record_id FROM l1_records WHERE ext_key = ? AND ext_key <> '' LIMIT 1")
+                .get(extKey);
+            return row?.record_id;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * 游标分批取 L1 元信息(**仅三列**):后台巡检专用。
      *
@@ -1202,7 +1312,138 @@ export class MemoryDb {
             return 0;
         }
     }
+    /**
+     * 批量写 `workspace_id`（内容路由 / 存量 re-link 用）。单事务，**刻意不碰 `updated_time`**。
+     *
+     * 为什么不碰 `updated_time`（三条都是硬约束）：
+     * ① 它在 `canonicalRecords` 的哈希字段表里——动了就是“静默改写”，会让改动前建的快照
+     *    永久 verify 不通过（`workspace_id` 本身不在表里，所以**只**写它才是快照安全的）；
+     * ② 它是时效衰减（agingWeight）与列表排序的输入，改一下归属顺手把记忆“刷陈旧”是意外副作用；
+     * ③ re-link 按固定序分页扫，不写它才不会边扫边漂。
+     *
+     * 为什么连 `l1_fts` 一起改：FTS 行**自带** `workspace_id`（UNINDEXED 随行），
+     * 而检索过滤 `(? = '' OR scope='global' OR workspace_id = ?)` 读的就是 FTS 行那一列。
+     * 只改主表 = 一旦启用围栏，关键词路按旧归属过滤、向量路按新归属过滤，两路结果不一致。
+     * 退场行不在 FTS 里，那条 UPDATE 自然命中 0 行，不是错误。
+     */
+    setL1WorkspaceIds(items) {
+        if (this.degraded || items.length === 0)
+            return 0;
+        try {
+            // 现值已等于目标值时不写：幂等（第二次跑零写入，不白刷 WAL）。
+            const upd = this.db.prepare("UPDATE l1_records SET workspace_id = ? WHERE record_id = ? AND COALESCE(workspace_id, '') <> ?");
+            const ftsReady = this.stmtL1FtsInsert !== undefined;
+            const ftsUpd = ftsReady ? this.db.prepare('UPDATE l1_fts SET workspace_id = ? WHERE record_id = ?') : null;
+            return this.withTransaction(() => {
+                let changed = 0;
+                for (const it of items) {
+                    if (!it.id || !it.workspaceId)
+                        continue;
+                    if (Number(upd.run(it.workspaceId, it.id, it.workspaceId).changes) === 0)
+                        continue;
+                    changed++;
+                    ftsUpd?.run(it.workspaceId, it.id);
+                }
+                return changed;
+            });
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 批量写 workspace_id 失败(${items.length} 条，本轮全量回退): ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+    }
     // ── L2 场景重聚类作业队列(治理 W3,T3.10)──────────────────────────────
+    /**
+     * 改一条记录的文件身份名（N1）。三态返回，**不碰 `updated_time`**：它在快照哈希
+     * 字段表里、又是衰减与排序的输入——改名不是“内容变了”，不该顺带把这条记成刚更新过
+     * （与 `setL1WorkspaceIds` 同一个理由）。`name=''` 是合法值（= 没名字，部分索引不约束空串）。
+     *
+     * 唯一性由 `l1_records_name_uidx` 挡：撞名 ⇒ `'dup'`，由调用方决定报错还是让用户先改
+     * 另一条——**不自动加后缀**，那会静默造出语义重叠的第二条记忆。
+     * （另一个口径：机器给**本来没名字**的记录起名时必须消歧，见 `renameL1Batch` 的注释。）
+     */
+    renameL1(id, name) {
+        if (this.degraded)
+            return 'failed';
+        try {
+            if (this.stmtGetL1.get(id) === undefined)
+                return 'missing';
+            this.db.prepare('UPDATE l1_records SET name = ? WHERE record_id = ?').run(name, id);
+            return 'ok';
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('UNIQUE constraint failed: l1_records.name'))
+                return 'dup';
+            this.logger?.warn(`${TAG} 改名失败(${id}): ${msg}`);
+            return 'failed';
+        }
+    }
+    /**
+     * 批量写 `name`（单事务）。给“机器起名”用：存量记录没名字时一次补齐。
+     *
+     * 与 `renameL1` 的分工不是性能而是**语义**：那里是**人给的**名字，撞了就报错让用户
+     * 先改另一条，绝不静默加后缀；这里是机器给**本来没名字**的记录派生名字，同正文的
+     * 多条必然撞名（真机实测 42 条挤进 17 个路径），**不消歧就是每轮导出重刷 + 反向同步
+     * 把一份内容回灌给多条**。所以消歧必须在本层之上先把名字算唯一，本层只负责落库。
+     *
+     * 与 `renameL1` 同样**不碰 `updated_time`**（起名不是“内容变了”），也不动 FTS——
+     * `name` 不在检索面里（`l1_fts` 没这一列）。
+     *
+     * @param items - `{ id, name }`，name 已由调用方保证全库唯一。
+     * @returns 实际写入的 id 集（现值已等于目标值的跳过——幂等）与失败集。
+     */
+    renameL1Batch(items) {
+        const done = [];
+        const failed = [];
+        if (this.degraded || items.length === 0)
+            return { done, failed: items.map((it) => it.id) };
+        const upd = this.db.prepare("UPDATE l1_records SET name = ? WHERE record_id = ? AND COALESCE(name, '') <> ?");
+        try {
+            this.withTransaction(() => {
+                for (const it of items) {
+                    if (!it.id || it.name.length === 0) {
+                        failed.push(it.id);
+                        continue;
+                    }
+                    try {
+                        const ch = Number(upd.run(it.name, it.id, it.name).changes);
+                        // changes=0 两种可能：没这行，或现值已相等。前者要报出去，后者算幂等成功。
+                        if (ch === 0 && this.stmtGetL1.get(it.id) === undefined) {
+                            failed.push(it.id);
+                            continue;
+                        }
+                        done.push(it.id);
+                    }
+                    catch (err) {
+                        // 单条撞唯一索引不影响事务里的其它行（ABORT 只回退当前语句）。
+                        this.logger?.warn(`${TAG} 批量起名单条失败(${it.id}): ${err instanceof Error ? err.message : String(err)}`);
+                        failed.push(it.id);
+                    }
+                }
+            });
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 批量起名事务失败(${items.length} 条): ${err instanceof Error ? err.message : String(err)}`);
+            for (const it of items)
+                if (!done.includes(it.id))
+                    failed.push(it.id);
+        }
+        return { done, failed };
+    }
+    /** 按文件身份名反查 record_id（重名预检与 md 回灌用）；没这条名 ⇒ undefined。*/
+    findRecordIdByName(name) {
+        if (this.degraded || name.length === 0)
+            return undefined;
+        try {
+            const row = this.db.prepare("SELECT record_id FROM l1_records WHERE name = ? AND name <> '' LIMIT 1").get(name);
+            return row?.record_id;
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 按名反查失败: ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    }
     /** 入队一个重聚类作业(demote-to-wiki / repo 归属变化触发;source 区分来源)。 */
     enqueueSceneRecluster(family, sceneNames, batchId, source = 'demote') {
         const jobId = `recl_${Date.now()}_${Math.random().toString(16).slice(2, 8)}`;
@@ -1272,7 +1513,7 @@ export class MemoryDb {
         if (this.degraded)
             return [];
         const rows = this.db
-            .prepare('SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence, scope, workspace_id, repo_key_name, repo_key_owner, applicability FROM l1_records')
+            .prepare('SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence, scope, workspace_id, repo_key_name, repo_key_owner, applicability, name FROM l1_records')
             .all();
         return rows.map(rowToRecord);
     }
@@ -1617,7 +1858,7 @@ export class MemoryDb {
             const whereSql = where.length > 0 ? ` WHERE ${where.join(' AND ')}` : '';
             const totalRow = this.db.prepare(`SELECT COUNT(*) AS n FROM l1_records${whereSql}`).get(...params);
             const rows = this.db
-                .prepare(`SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence, scope, workspace_id, repo_key_name, repo_key_owner, applicability FROM l1_records${whereSql} ORDER BY updated_time DESC LIMIT ? OFFSET ?`)
+                .prepare(`SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence, scope, workspace_id, repo_key_name, repo_key_owner, applicability, name FROM l1_records${whereSql} ORDER BY updated_time DESC LIMIT ? OFFSET ?`)
                 .all(...params, opts.limit, opts.offset);
             return { items: rows.map(rowToRecord), total: totalRow?.n ?? 0 };
         }
@@ -2164,7 +2405,7 @@ export class MemoryDb {
             const row = this.db
                 .prepare(`SELECT COUNT(*) AS n FROM ${srcTable} r
            LEFT JOIN ${vecTable} v ON v.record_id = r.record_id
-           WHERE v.record_id IS NULL${notInClause('r.record_id', exclude)}`)
+           WHERE v.record_id IS NULL${kind === 'l1' ? ` AND NOT (${retiredL1Sql('r')})` : ''}${notInClause('r.record_id', exclude)}`)
                 .all(...notInParams(exclude))[0];
             return row?.n ?? 0;
         }
@@ -2186,7 +2427,7 @@ export class MemoryDb {
             return this.db
                 .prepare(`SELECT r.record_id AS id, r.content FROM l1_records r
            LEFT JOIN l1_vec v ON v.record_id = r.record_id
-           WHERE v.record_id IS NULL${notInClause('r.record_id', exclude)}`)
+           WHERE v.record_id IS NULL AND NOT (${retiredL1Sql('r')})${notInClause('r.record_id', exclude)}`)
                 .all(...notInParams(exclude));
         }
         catch (err) {
@@ -2398,6 +2639,9 @@ function rowToRecord(row) {
         repoKeyName: row.repo_key_name ?? '',
         repoKeyOwner: row.repo_key_owner ?? '',
         applicability: normApplicability(row.applicability),
+        // 文件身份键回读：空串归一 undefined（“还没名字”与“名字是空串”不是一种意思），
+        // 缺列的旧库也是 undefined。读侧同样 fail-open。
+        name: row.name || undefined,
     };
 }
 /**

package/dist/store/supersede.d.ts

@@ -32,7 +32,7 @@ export declare const SUPERSEDE_METADATA_KEY = "dsh_superseded";
  * 退场原因。**穷举**而非自由字符串:面板要按原因给不同文案与图标,
  * 自由字符串会让"未识别的原因"静默退化成无徽标。
  */
-export type RetireReason = 'conflict' | 'superseded' | 'manual';
+export type RetireReason = 'conflict' | 'superseded' | 'manual' | 'obsolete';
 /** 取代标记(写进 metadata 的负载)。 */
 export interface SupersedeInfo {
     /** 退场时刻(ISO 8601)。 */

package/dist/store/supersede.js

@@ -6,7 +6,7 @@
  * 必须靠命名空间隔开,否则一次 LLM 幻觉输出 `superseded` 就能伪装成人工裁决。
  */
 export const SUPERSEDE_METADATA_KEY = 'dsh_superseded';
-const REASONS = ['conflict', 'superseded', 'manual'];
+const REASONS = ['conflict', 'superseded', 'manual', 'obsolete'];
 /**
  * 写入取代标记(返回**新对象**)。
  *

package/dist/tools/index.d.ts

@@ -1,16 +1,3 @@
-/**
- * 模型可调用工具:memory_search(L1)、conversation_search(L0)、memory_read_scene(L2/L3)、
- * 高权限 memory_add / memory_delete。
- *
- * 会话档位联动:execute 的 exec.agent 即发起调用的 agent(agent.id === sessionId),
- * memory_search 按会话档位过滤族(auto 不过滤,纯档只查本族);off 档下读类工具统一
- * 返回提示(本会话已对记忆系统隐身)。conversation_search 检索范围保持全库。
- * 只写会话(注入覆盖=关)同款拒读,notice 区分文案——写入走捕获钩子不经工具,
- * 拒读不影响"只写"语义。
- *
- * 写删工具受 live.memoryMutate 高权限门控(默认 false):显式记忆指令语义——
- * 用户说"记得 X" → memory_add;说"忘了/删除该记忆" → memory_delete。
- */
 import type { Context } from '@deepseek-ai/cordis';
 import type { MemoryConfig } from '../config.js';
 import type { LiveSettingsHandle } from '../settings.js';
@@ -30,6 +17,10 @@ export declare function registerMemoryTools(ctx: Context, cfg: MemoryConfig, sto
     persona: Record<MemoryFamily, PersonaStore>;
     /** 图谱存储(可选:未装配时图谱工具返回未启用提示)。 */
     graph?: GraphStore;
+    /** 人工打分面(可选)：冲突视图的成熟度旁注与面板同一口径。 */
+    feedback?: {
+        lastOf(id: string): number | undefined;
+    };
 }, logger: MemoryLogger, modes: SessionModeStore, live: LiveSettingsHandle, 
 /** 反刍控制器(可选:未装配时 ruminate 工具返回未启用提示)。 */
 ruminate?: RuminateController, 

package/dist/tools/index.js

@@ -1,4 +1,19 @@
+/**
+ * 模型可调用工具:memory_search(L1)、conversation_search(L0)、memory_read_scene(L2/L3)、
+ * 高权限 memory_add / memory_delete。
+ *
+ * 会话档位联动:execute 的 exec.agent 即发起调用的 agent(agent.id === sessionId),
+ * memory_search 按会话档位过滤族(auto 不过滤,纯档只查本族);off 档下读类工具统一
+ * 返回提示(本会话已对记忆系统隐身)。conversation_search 检索范围保持全库。
+ * 只写会话(注入覆盖=关)同款拒读,notice 区分文案——写入走捕获钩子不经工具,
+ * 拒读不影响"只写"语义。
+ *
+ * 写删工具受 live.memoryMutate 高权限门控(默认 false):显式记忆指令语义——
+ * 用户说"记得 X" → memory_add;说"忘了/删除该记忆" → memory_delete。
+ */
+import { createHash } from 'node:crypto';
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { DOWNGRADE_TARGET, familyOf, isKnownType, typeEnumSep } from '../memory-types.js';
 import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from '../store/receipts.js';
 import { listConflictPairs, renderConflictResolution, renderConflicts, resolveConflictPair } from '../conflict-service.js';
 import { WING_CATALOG, WING_FALLBACK, normPersistence, normScope, resolveRecordScope } from '../types.js';
@@ -167,7 +182,7 @@ roomRegistry) {
         parameters: {
             query: { type: 'string', required: true, description: '搜索查询文本(自然语言)' },
             limit: { type: 'number', description: '最大返回条数(默认 5)' },
-            type: { type: 'string', description: '按记忆类型过滤(如 persona/episodic/instruction/work_fact/work_task/work_method/work_artifact)' },
+            type: { type: 'string', description: `按记忆类型过滤(词表 ${typeEnumSep('/')})` },
         },
         output: {
             schema: {
@@ -467,7 +482,12 @@ roomRegistry) {
     }));
     // ── 写删工具(高权限门控):memory_add / memory_delete ──
     const MUTATE_OFF_NOTICE = '记忆写删未开放:请在记忆库面板开启「高权限模式」后,模型才能写入/删除记忆。';
-    const ADD_TYPES = ['persona', 'episodic', 'instruction', 'work_fact', 'work_task', 'work_method', 'work_artifact'];
+    /**
+     * 非词表 type 的降级台账（pm-name-distill task_1.4）。旧实现把外部分类**静默改写**成
+     * `episodic`，而 memport 文案却承诺“按原样透传”——两套口径对同一件事相反。
+     * 现在降级仍发生（写入面需要一个合法值），但**可观测**：每个不同值 warn 一次并计数。
+     */
+    const addTypeDowngrades = new Set();
     const newMemId = () => 'mem-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);
     // ── 工具刷写的公共装配(时间轴 + 溯源 + 冲突标记) ──
     //
@@ -491,10 +511,28 @@ roomRegistry) {
      * 时间轴同时写顶层字段(时间增强列)与 metadata(列迁移前的兼容层,
      * 也是面板与图谱时间锚的读取点);`cf`/`rw` 落在 metadata.conflict/rewritten。
      */
-    function buildRecord(item, sceneName, now, workspaceId) {
+    /** 外部导入幂等键:sha1(source_id \0 稳定身份)。身份取 dedupe_key,缺省用内容规范化。 */
+    const computeExtKey = (sourceId, item, content) => {
+        const identity = typeof item.dedupe_key === 'string' && item.dedupe_key.trim()
+            ? item.dedupe_key.trim()
+            : content.replace(/\s+/g, ' ').toLowerCase();
+        return createHash('sha1').update(`${sourceId}\u0000${identity}`, 'utf8').digest('hex');
+    };
+    function buildRecord(item, sceneName, now, workspaceId, sourceId) {
         const content = String(item.content ?? '').trim();
-        const type = ADD_TYPES.includes(String(item.type ?? '')) ? String(item.type) : 'episodic';
-        const family = type.startsWith('work') ? 'work' : 'chat';
+        const rawType = String(item.type ?? '').trim();
+        // 白名单判据来自词表单一真源；非词表值降级为 DOWNGRADE_TARGET 并留痕（不静默）。
+        let type = rawType;
+        if (!isKnownType(rawType)) {
+            type = DOWNGRADE_TARGET;
+            if (rawType.length > 0 && !addTypeDowngrades.has(rawType)) {
+                addTypeDowngrades.add(rawType);
+                logger.warn(`[memory] memory_add/import type '${rawType}' 不在词表,已降级为 '${DOWNGRADE_TARGET}'(同值不再重复提醒)`);
+            }
+        }
+        // 族判定不再 `startsWith('work')` 内联猜——`project_*`/`development_*`/`*_experience`
+        // 都是 work 族却不带 work 前缀，猜错的族会静默改这批记录的共享面。
+        const family = familyOf(type);
         const validFrom = parseTime(item.valid_from);
         const validTo = parseTime(item.valid_to);
         const persistence = normPersistence(item.persistence);
@@ -536,13 +574,14 @@ roomRegistry) {
             ...(validFrom !== undefined ? { validFrom } : {}),
             ...(validTo !== undefined ? { validTo } : {}),
             ...(persistence !== undefined ? { persistence } : {}),
+            ...(sourceId && sourceId.trim() ? { extKey: computeExtKey(sourceId.trim(), item, content) } : {}),
         };
     }
     /** 时间轴/溯源字段的可选入参(两个写工具共用同一形状)。 */
     const writeFields = {
         type: {
             type: 'string',
-            description: '记忆类型(persona/episodic/instruction/work_fact/work_task/work_method/work_artifact;缺省 episodic)',
+            description: `记忆类型(${typeEnumSep('/')};缺省 ${DOWNGRADE_TARGET})`,
         },
         hall: {
             type: 'string',
@@ -618,6 +657,10 @@ roomRegistry) {
                         },
                         ...writeFields,
                         priority: { type: 'number', description: '优先级 0-100(缺省 80)' },
+                        dedupe_key: {
+                            type: 'string',
+                            description: '可选稳定身份(外部包内该条的稳定 id);与顶层 source_id 组合算幂等键,缺省用内容规范化哈希',
+                        },
                     },
                 },
             },
@@ -625,12 +668,17 @@ roomRegistry) {
                 type: 'string',
                 description: `归属场景名(缺省 ${DEFAULT_IMPORT_SCENE};建议用"${DEFAULT_IMPORT_SCENE}/<来源>")`,
             },
+            source_id: {
+                type: 'string',
+                description: '来源标识(如 "workbuddy"/"claude-code"/外部包名);非空时启用幂等——同一来源重复导入相同 dedupe_key/内容会被跳过并计入 deduped',
+            },
         },
         output: {
             schema: {
                 type: 'object',
                 properties: {
                     written: { type: 'number' },
+                    deduped: { type: 'number' },
                     ids: { type: 'array', items: { type: 'string' } },
                     skipped: {
                         type: 'array',
@@ -653,15 +701,16 @@ roomRegistry) {
         },
         execute: async (args, exec) => {
             if (!live.get().memoryMutate) {
-                return { written: 0, ids: [], skipped: [], notice: MUTATE_OFF_NOTICE };
+                return { written: 0, deduped: 0, ids: [], skipped: [], notice: MUTATE_OFF_NOTICE };
             }
             const raw = Array.isArray(args.records) ? args.records : [];
             if (raw.length === 0) {
-                return { written: 0, ids: [], skipped: [], notice: 'records 为空,未写入' };
+                return { written: 0, deduped: 0, ids: [], skipped: [], notice: 'records 为空,未写入' };
             }
             if (raw.length > MAX_IMPORT) {
                 return {
                     written: 0,
+                    deduped: 0,
                     ids: [],
                     skipped: [],
                     notice: `单次上限 ${MAX_IMPORT} 条(收到 ${raw.length} 条),请拆批导入`,
@@ -670,10 +719,13 @@ roomRegistry) {
             const scene = typeof args.scene === 'string' && args.scene.trim()
                 ? args.scene.trim().slice(0, 120)
                 : DEFAULT_IMPORT_SCENE;
+            const sourceId = typeof args.source_id === 'string' ? args.source_id.trim() : '';
             const now = Date.now();
             const seen = new Set();
+            const seenExt = new Set();
             const records = [];
             const skipped = [];
+            let deduped = 0;
             raw.forEach((item, index) => {
                 const content = String(item?.content ?? '').trim();
                 if (!content) {
@@ -686,14 +738,30 @@ roomRegistry) {
                     return;
                 }
                 seen.add(key);
-                const record = buildRecord(item, scene, now, workspaceIdOf(exec));
+                // 幂等(轨3-P0):带 source_id 时按 ext_key 拦截重复——先查库内、再查本批，
+                // 命中即计入 deduped 并跳过(不写 JSONL、不写检索库)。无 source_id 保持既有逐字行为。
+                if (sourceId) {
+                    const extKey = computeExtKey(sourceId, item, content);
+                    if (seenExt.has(extKey)) {
+                        deduped++;
+                        skipped.push({ index, reason: '与本批前面的记录外部键重复(幂等跳过)' });
+                        return;
+                    }
+                    if (stores.l1.findIdByExtKey(extKey)) {
+                        deduped++;
+                        skipped.push({ index, reason: '库内已存在同外部键记录(幂等跳过)' });
+                        return;
+                    }
+                    seenExt.add(extKey);
+                }
+                const record = buildRecord(item, scene, now, workspaceIdOf(exec), sourceId);
                 applyManualRedaction(record, cfg, logger);
                 records.push(record);
             });
             if (records.length > 0)
                 await stores.l1.appendNew(records);
-            logger.info(`[memory] 批量导入 ${records.length} 条(跳过 ${skipped.length} 条,场景 ${scene})`);
-            return { written: records.length, ids: records.map((r) => r.id), skipped };
+            logger.info(`[memory] 批量导入 ${records.length} 条(幂等跳过 ${deduped} 条,场景 ${scene}${sourceId ? `,来源 ${sourceId}` : ''})`);
+            return { written: records.length, deduped, ids: records.map((r) => r.id), skipped };
         },
     })));
     // memory_delete:显式"忘了 X"——按语义检索命中后删除(高权限门控)。
@@ -1222,7 +1290,7 @@ roomRegistry) {
             if (family === null) {
                 return { enabled: false, total: 0, items: [], notice: blockNoticeOf(exec) };
             }
-            return listConflictPairs({ l1: stores.l1, conflictFreezeEnabled: live.get().conflictFreeze === true }, { limit: typeof args.limit === 'number' ? args.limit : undefined });
+            return listConflictPairs({ l1: stores.l1, conflictFreezeEnabled: live.get().conflictFreeze === true, decayHalfLifeDays: cfg.recall?.decayHalfLifeDays, feedback: stores.feedback }, { limit: typeof args.limit === 'number' ? args.limit : undefined });
         },
     })));
     // ── memory_conflicts_rejected: §C 丢弃留痕的读出口 ──