dsh-prime-memory 0.22.2 → 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)。 */
@@ -326,6 +340,16 @@ export class MemoryDb {
             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(`
@@ -442,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, ext_key
-      ) 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,
@@ -464,13 +488,14 @@ export class MemoryDb {
         repo_key_name=excluded.repo_key_name,
         repo_key_owner=excluded.repo_key_owner,
         applicability=excluded.applicability,
-        ext_key=excluded.ext_key
+        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 = ?');
@@ -611,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 (?, ?, ?, ?, ?, ?, ?)
@@ -744,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'), 
@@ -760,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() {
@@ -916,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), record.extKey ?? '');
+        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) {
@@ -1059,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) };
@@ -1085,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})`)
@@ -1228,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)}`;
@@ -1298,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);
     }
@@ -1643,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 };
         }
@@ -2190,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;
         }
@@ -2212,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) {
@@ -2424,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

@@ -17,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

@@ -13,6 +13,7 @@
  */
 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';
@@ -181,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: {
@@ -481,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);
     // ── 工具刷写的公共装配(时间轴 + 溯源 + 冲突标记) ──
     //
@@ -514,8 +520,19 @@ roomRegistry) {
     };
     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);
@@ -564,7 +581,7 @@ roomRegistry) {
     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',
@@ -1273,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, decayHalfLifeDays: cfg.recall?.decayHalfLifeDays }, { 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 丢弃留痕的读出口 ──

package/dist/types.d.ts

@@ -1,9 +1,3 @@
-/**
- * 领域类型与词汇表(净室重写)。
- *
- * 覆盖:记忆族/档位、Hall 目录、L0/L1 记录形状、抽取产出与族判定三级兜底、
- * L2 场景摘要与 L1 检索命中。字段名与取值是磁盘/管线两侧的既定契约,不可更名。
- */
 /** 蒸馏 Prompt 家族:chat = 个人记忆(persona/episodic/instruction + 用户画像),work = 工作记忆(work_fact/work_task/work_method/work_artifact + Team Operating Doctrine)。 */
 export type MemoryFamily = 'chat' | 'work';
 /** 会话记忆档位:auto = 双族自动判定 | chat/work = 单族 | off = 本会话对记忆系统隐身。 */
@@ -46,7 +40,14 @@ export interface RoomCount {
     /** 人类可读名(注册表条目才有;面板 chip 可用 label 展示)。 */
     label?: string;
 }
-/** 记录族标签推断:work_* 前缀 → work,其余(含 auto 档兜底)→ chat。 */
+/**
+ * 记录族标签推断（pm-name-distill task_1.2）：查 `TYPE_FAMILY_MAP`（词表单一真源）。
+ *
+ * 旧实现是 `type.startsWith('work')` 前缀猜族——新词表里 `project_*`/`development_*`/
+ * `*_experience` 都是 work 族却不带 work 前缀，前缀判定会把它们静默归进 chat，
+ * 而 family 决定召回/浏览/去重的共享面。未知值仍回落旧前缀规则并 warn 一次（可观测，
+ * 不静默）。
+ */
 export declare function familyForType(type: string): MemoryFamily;
 /**
  * 记忆的持续性(时间轴第三维,与 createdAt/updatedAt 正交):
@@ -118,6 +119,13 @@ export interface ExtractedMemory {
     metadata: Record<string, unknown>;
     /** 所属情境名(L1 抽取的情境切分结果)。 */
     scene_name: string;
+    /**
+     * 名称蒸馏（Phase 3）：模型**当场**给的短标题（名词短语，回答“这条讲的是什么”），
+     * 与 `content`（完整叙述正文）分离。只在 `cfg.naming.enabled` 时被要求产出；
+     * 缺省或过不了 `validateTitle` 形状闸就**不写成名字**，仍由 `L1Store.assignMissingNames`
+     * 兜底——名字的唯一真源不因多一个来源就分两套判据。
+     */
+    title?: string;
     /** auto 档抽取输出的显式族判定(chat|work;纯档 Prompt 无此字段)。
      *  语境归族、形状不归族——避免"个人计划性事实被 work_* 形状吸走"的族错标。 */
     family?: string;
@@ -232,6 +240,15 @@ export interface MemoryRecord {
      * 与 `scene_name`/`metadata.origin` 不同:这是**存储层强制去重键**,不是展示用的溯源标签。
      */
     extKey?: string;
+    /**
+     * 文件身份键（md 投射相，N1）：人可读、可编辑、全库唯一，直接当
+     * `<root>/<type>/<name>.memory.md` 的文件名。与 `extKey` 的分工：extKey 是
+     * **导入幂等键**（机器算的、来源内唯一），name 是**文件身份**（人写的、全库唯一）。
+     * 不用 id 当身份：id 每轮新铸、从不复用；不用 scene_name：它的基数大于记录数。
+     * undefined = 还没名字（存量记录），投射器则回落 `mem-<id8>`。
+     * 非空值受 `l1_records` 上的部分唯一索引约束；该列**不进**快照哈希投影。
+     */
+    name?: string;
 }
 /** L2 场景块摘要(META 解析结果)。 */
 export interface SceneSummary {

package/dist/types.js

@@ -4,6 +4,7 @@
  * 覆盖:记忆族/档位、Hall 目录、L0/L1 记录形状、抽取产出与族判定三级兜底、
  * L2 场景摘要与 L1 检索命中。字段名与取值是磁盘/管线两侧的既定契约,不可更名。
  */
+import { familyOf } from './memory-types.js';
 export const WING_CATALOG = [
     { id: 'work', label: '工作' },
     { id: 'relationships', label: '人际' },
@@ -27,9 +28,16 @@ export function wingLabel(id) {
     const h = WING_CATALOG.find((x) => x.id === id);
     return h ? h.label : id;
 }
-/** 记录族标签推断:work_* 前缀 → work,其余(含 auto 档兜底)→ chat。 */
+/**
+ * 记录族标签推断（pm-name-distill task_1.2）：查 `TYPE_FAMILY_MAP`（词表单一真源）。
+ *
+ * 旧实现是 `type.startsWith('work')` 前缀猜族——新词表里 `project_*`/`development_*`/
+ * `*_experience` 都是 work 族却不带 work 前缀，前缀判定会把它们静默归进 chat，
+ * 而 family 决定召回/浏览/去重的共享面。未知值仍回落旧前缀规则并 warn 一次（可观测，
+ * 不静默）。
+ */
 export function familyForType(type) {
-    return type.startsWith('work') ? 'work' : 'chat';
+    return familyOf(type);
 }
 export const PERSISTENCE_VALUES = ['p', 's', 'o', 't'];
 /** 持续性取值归一:只认 p/s/o/t,其余(缺省/非法)返回 undefined。 */

package/dist/util/maturity.d.ts

@@ -1,13 +1,19 @@
 /**
  * 成熟度（maturity）合成——G3，单一事实源的纯函数。
  *
- * 把三个**已存在**的信号合成一个可解释的置信档，供面板显示（后续可作召回排序/矛盾旁注）：
+ * 把四个**已存在**的信号合成一个可解释的置信档，供面板显示与召回排序：
  * - `priority`（L1 真实列，0-100）：写入时的重要性先验；
  * - `usage.used`（recall-usage，进 topN 被注入才计）：被反复用到 = 越"确立"；
- * - `agingWeight`（读路径衰减系数 0.5~1，null=关）：新鲜度。
+ * - `agingWeight`（读路径衰减系数 0.5~1，null=关）：新鲜度；
+ * - `mark`（人在召回卡上打的 -1..5，**只看最近一笔**）：显式的人工裁决。
+ *
+ * 人工标记是**加性**项（±W_MARK），不是权重再分配：未打分时贡献恒为 0，
+ * 与三输入时代的分值**逐字相等**（旧回归断言不会因新增一项而漂）。
+ * 档位设计（用户口径：0/1/2 拉低、4/5 抬高）：0/1/2 为负、3 中性、4/5 为正；
+ * `-1`（声明过时）**不在此计分**——它走退场，若再计一次罚就是同一件事罚两遍。
  *
  * 刻意**读时派生、不落库**（Agent B/C 结论）：落库会在每轮 recordAttempt 触发双写 + 值随时间陈旧，
- * 且顶层列不进快照哈希=隐形改写。三输入即时可得，纯函数零 IO。
+ * 且顶层列不进快照哈希=隐形改写。各输入即时可得，纯函数零 IO。
  *
  * 权重/阈值集中为常量，便于回归与调参；缺 usage（未装配）按 0 强化处理（不虚构成熟度）。
  */
@@ -20,7 +26,18 @@ export interface MaturityInput {
     usage?: MaturityUsage | null;
     /** 读路径老化权重（0.5~1）；null = 衰减关闭 → 视为 1（不惩罚）。 */
     agingWeight?: number | null;
+    /**
+     * 人给的最近一笔打分（-1..5）；未打分 = undefined/null → 贡献 0（逐字旧行为）。
+     * `-1` 也按 0 处理：那条记录已经退场，不该在成熟度上再罚一次。
+     */
+    mark?: number | null;
 }
+/**
+ * 打分 → 归一化人工信号（-1..1）。3 分与未打分同为中性。
+ * 正侧只分两档（4 半、5 满）；负侧分三档渐次加重（2 轻罚 -0.4、1 中罚 -0.7、0 重罚 -1）——
+ * “不相关”是个需要区分程度的否定，而“相关”不必分那么细。
+ */
+export declare function markSignal(mark: number | null | undefined): number;
 /** 合成分值（0~1），导出供测试与未来排序复用。 */
 export declare function maturityScore(i: MaturityInput): number;
 /** 三档成熟度：high ≥0.66、mid ≥0.40、否则 low。 */

package/dist/util/maturity.js

@@ -1,10 +1,27 @@
 const W_PRIORITY = 0.45;
 const W_USAGE = 0.3;
 const W_AGING = 0.25;
+/** 人工标记的加性幅度（±0.3）：够让一档在强先验上被推翻，又不足以一票定生死。 */
+const W_MARK = 0.3;
 /** used 达到该数即满强化（再高不加分）。 */
 const USAGE_SATURATE = 5;
 const HIGH_THRESHOLD = 0.66;
 const MID_THRESHOLD = 0.4;
+/**
+ * 打分 → 归一化人工信号（-1..1）。3 分与未打分同为中性。
+ * 正侧只分两档（4 半、5 满）；负侧分三档渐次加重（2 轻罚 -0.4、1 中罚 -0.7、0 重罚 -1）——
+ * “不相关”是个需要区分程度的否定，而“相关”不必分那么细。
+ */
+export function markSignal(mark) {
+    switch (mark) {
+        case 5: return 1;
+        case 4: return 0.5;
+        case 2: return -0.4;
+        case 1: return -0.7;
+        case 0: return -1;
+        default: return 0; // 3 / -1 / 未打分 / 越界值
+    }
+}
 function clamp01(x) {
     return Math.max(0, Math.min(1, x));
 }
@@ -13,7 +30,7 @@ export function maturityScore(i) {
     const p = clamp01(i.priority / 100);
     const u = i.usage ? clamp01(i.usage.used / USAGE_SATURATE) : 0;
     const a = i.agingWeight == null ? 1 : clamp01(i.agingWeight);
-    return W_PRIORITY * p + W_USAGE * u + W_AGING * a;
+    return clamp01(W_PRIORITY * p + W_USAGE * u + W_AGING * a + W_MARK * markSignal(i.mark));
 }
 /** 三档成熟度：high ≥0.66、mid ≥0.40、否则 low。 */
 export function computeMaturity(i) {