dsh-prime-memory 0.14.0-beta.4 → 0.14.0-beta.5

package/dist/client.js

@@ -606,7 +606,7 @@ var __defProp = Object.defineProperty;
 		// client/src/tabs/ConflictsTab.tsx
 		var import_jsx_runtime = require("react/jsx-runtime");
 		var POLL_MS = 1e4;
-		var GONE = "（该记录已不在检索库：被合并或删除掉了）";
+		var GONE = "（该记录正文不可得：已不在主表，或被更早的清理清掉了）";
 		function ConflictsTab(props) {
 		  const rpc = props.rpc;
 		  const [view, setView] = (0, import_react2.useState)(null);
@@ -639,7 +639,7 @@ var __defProp = Object.defineProperty;
 		将要退场的记忆：
 		「${doomed}」
 		
-		它会从检索库移除（事实源保留，可从 L0 重建找回）。本操作不可覆盖。`
+		它会移出检索面（不再被召回），但记录仍保留 —— 可在「记忆」页的「已退场」区恢复。裁决结论本身不可覆盖。`
 		      );
 		      if (!ok) return;
 		    }
@@ -3214,24 +3214,25 @@ var __defProp = Object.defineProperty;
 		    const ids = Array.from(sel);
 		    if (ids.length === 0) return;
 		    if (!hiPriv) {
-		      setError("高权限模式未开启：请在右上「高权限：关」或概览页开关中开启后，再删除记忆。");
+		      setError("高权限模式未开启：请在右上「高权限：关」或概览页开关中开启后，再退场记忆。");
 		      return;
 		    }
 		    if (ids.length > DELETE_LIMIT) {
-		      setError("一次最多删除 " + DELETE_LIMIT + " 条（当前勾选 " + ids.length + " 条），请分批操作。");
+		      setError("一次最多退场 " + DELETE_LIMIT + " 条（当前勾选 " + ids.length + " 条），请分批操作。");
 		      return;
 		    }
-		    if (!window.confirm("删除勾选的 " + ids.length + " 条记忆？本操作不可逆（完整重建可能从 L0 复活，为已知边界）。")) return;
+		    if (!window.confirm("退场勾选的 " + ids.length + " 条记忆？\n\n它们会移出检索面（不再被召回），但记录仍保留 —— 可在下方「已退场」区恢复。")) return;
 		    rpc("dsh-memory/records-delete", { ids }).then((r) => {
 		      if (r && r.ok) {
 		        setSel(/* @__PURE__ */ new Set());
 		        if (expandedId && ids.indexOf(expandedId) >= 0) setExpandedId(null);
 		        fetchPage(last, 0, false);
-		      } else if (r) setError(r.error ? r.error.message : "删除失败");
+		        if (showRetired) loadRetired();
+		      } else if (r) setError(r.error ? r.error.message : "退场失败");
 		    }).catch((e) => setError(String(e && e.message || e)));
 		  };
 		  const deleteRecord = (id) => {
-		    if (!window.confirm("删除该条记忆？本操作不可逆（完整重建可能从 L0 复活，为已知边界）。")) return;
+		    if (!window.confirm("退场该条记忆？\n\n它会移出检索面（不再被召回），但记录仍保留 —— 可在下方「已退场」区恢复。")) return;
 		    rpc("dsh-memory/records-delete", { ids: [id] }).then((r) => {
 		      if (r && r.ok) {
 		        setSel((prev) => {
@@ -3241,9 +3242,42 @@ var __defProp = Object.defineProperty;
 		        });
 		        if (expandedId === id) setExpandedId(null);
 		        fetchPage(last, 0, false);
-		      } else if (r) setError(r.error ? r.error.message : "删除失败");
+		        if (showRetired) loadRetired();
+		      } else if (r) setError(r.error ? r.error.message : "退场失败");
 		    }).catch((e) => setError(String(e && e.message || e)));
 		  };
+		  const [retired, setRetired] = (0, import_react15.useState)([]);
+		  const [retiredTotal, setRetiredTotal] = (0, import_react15.useState)(0);
+		  const [showRetired, setShowRetired] = (0, import_react15.useState)(false);
+		  const [retiredBusy, setRetiredBusy] = (0, import_react15.useState)(false);
+		  const loadRetired = (0, import_react15.useCallback)(() => {
+		    setRetiredBusy(true);
+		    rpc("dsh-memory/records-retired", { limit: 100, offset: 0 }).then((r) => {
+		      if (r && r.ok) {
+		        setRetired(r.value.items);
+		        setRetiredTotal(r.value.total);
+		      } else if (r) setError(r.error ? r.error.message : "已退场列表加载失败");
+		    }).catch((e) => setError(String(e && e.message || e))).finally(() => setRetiredBusy(false));
+		  }, [rpc]);
+		  (0, import_react15.useEffect)(() => {
+		    if (showRetired) loadRetired();
+		  }, [showRetired, loadRetired]);
+		  const restoreRecords = (ids) => {
+		    if (ids.length === 0) return;
+		    setRetiredBusy(true);
+		    rpc("dsh-memory/records-restore", { ids }).then((r) => {
+		      if (r && r.ok) {
+		        loadRetired();
+		        fetchPage(last, 0, false);
+		      } else if (r) setError(r.error ? r.error.message : "恢复失败");
+		    }).catch((e) => setError(String(e && e.message || e))).finally(() => setRetiredBusy(false));
+		  };
+		  const RETIRE_REASON_LABEL = {
+		    conflict: "裁决退场",
+		    superseded: "被取代",
+		    manual: "人工退场",
+		    unknown: "已退场"
+		  };
 		  const countText = total !== null ? "共 " + total + " 条" : items.length + " 条" + (hasMore ? "+" : "");
 		  const selCount = sel.size;
 		  return /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { children: [
@@ -3405,6 +3439,24 @@ var __defProp = Object.defineProperty;
 		        m.id
 		      );
 		    }),
+		    /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { style: { ...S.flexRow, marginTop: 12 }, children: [
+		      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(NButton, { onClick: () => setShowRetired((v) => !v), children: (showRetired ? "收起" : "展开") + "「已退场」（可恢复）" }),
+		      showRetired && retiredBusy ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: "加载中…" }) : null,
+		      showRetired && !retiredBusy && retiredTotal > 0 ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: "共 " + retiredTotal + " 条可恢复" }) : null
+		    ] }),
+		    showRetired ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { style: { marginTop: 8 }, children: retired.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("p", { style: S.hint, children: retiredBusy ? " " : "没有已退场的记忆。" }) : /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { children: [
+		      retired.map((m) => /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { className: "dsh-mem-card", style: S.card, children: [
+		        /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { style: S.cardHead, children: [
+		          /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: RETIRE_REASON_LABEL[m.retiredReason] || m.retiredReason }),
+		          m.verdict ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: "结论 " + m.verdict }) : null,
+		          /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { style: S.grow }),
+		          /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: fmtTime(m.retiredAt) }),
+		          /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(NButton, { disabled: retiredBusy, title: "恢复到检索面", onClick: () => restoreRecords([m.id]), children: "恢复" })
+		        ] }),
+		        /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { style: S.content, children: m.content })
+		      ] }, m.id)),
+		      retiredTotal > retired.length ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("p", { style: S.hint, children: "共 " + retiredTotal + " 条，此处显示 " + retired.length + " 条" }) : null
+		    ] }) }) : null,
 		    hasMore ? /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { style: S.flexRow, children: [
 		      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { style: S.grow }),
 		      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(

package/dist/conflict-service.d.ts

@@ -12,7 +12,7 @@ import type { L1Store } from './store/l1.js';
 import type { ConflictPairView, ConflictsResponse as ConflictsView, ConflictResolveResponse as ConflictResolutionView } from './contract.js';
 export type { ConflictPairView, ConflictsView, ConflictResolutionView };
 export interface ConflictResolveDeps {
-    l1: Pick<L1Store, 'listConflictPending' | 'resolveConflictPending' | 'deleteBatch' | 'syncGraphDisputed'>;
+    l1: Pick<L1Store, 'listConflictPending' | 'resolveConflictPending' | 'retire' | 'syncGraphDisputed'>;
     /** `conflictFreeze.enabled`。未开启时队列恒空,直接给出提示而非静默无操作。 */
     conflictFreezeEnabled: boolean;
 }
@@ -21,9 +21,11 @@ export interface ConflictResolveDeps {
  *
  * 顺序刻意如此:
  * ① **先打 `resolved_at` 再退场 loser**。反过来的话,退场成功但打标失败会留下
- *    "记录已消失、队列里那条仍在待裁决"的状态——人再点一次才发现无据可依。
+ *    "记录已退场、队列里那条仍在待裁决"的状态——人再点一次才发现无据可依。
  *    打标用 `WHERE resolved_at = ''`,天然防重复裁决:第二次调用拿到 0 行即中止。
  * ② 退场后才**重算**图谱 `disputed`(派生字段必须由当前事实重算,见 `syncDisputed`)。
+ * ③ 退场是**软删**(`retire`,可恢复),不是物理删除:主表行留着,`valid_to` 闭合 +
+ *    写取代标记,FTS/向量行撤掉。故"判错了"可以再恢复——裁决不可覆盖,但可以反悔。
  */
 export declare function resolveConflictPair(deps: ConflictResolveDeps, pairId: string, outcome: string): Promise<ConflictResolutionView>;
 /** 裁决结果的人类可读渲染(工具路径用)。schema 产出的是可选字段,故按部分取值渲染。 */

package/dist/conflict-service.js

@@ -7,9 +7,11 @@ function view(partial) {
  *
  * 顺序刻意如此:
  * ① **先打 `resolved_at` 再退场 loser**。反过来的话,退场成功但打标失败会留下
- *    "记录已消失、队列里那条仍在待裁决"的状态——人再点一次才发现无据可依。
+ *    "记录已退场、队列里那条仍在待裁决"的状态——人再点一次才发现无据可依。
  *    打标用 `WHERE resolved_at = ''`,天然防重复裁决:第二次调用拿到 0 行即中止。
  * ② 退场后才**重算**图谱 `disputed`(派生字段必须由当前事实重算,见 `syncDisputed`)。
+ * ③ 退场是**软删**(`retire`,可恢复),不是物理删除:主表行留着,`valid_to` 闭合 +
+ *    写取代标记,FTS/向量行撤掉。故"判错了"可以再恢复——裁决不可覆盖,但可以反悔。
  */
 export async function resolveConflictPair(deps, pairId, outcome) {
     const clean = outcome.trim();
@@ -41,8 +43,17 @@ export async function resolveConflictPair(deps, pairId, outcome) {
         // 并发/重复调用:这一对在本次读取与本次写入之间被裁决了
         return view({ pair_id: pairId, outcome: clean, notice: '该对已被裁决,本次未生效(裁决不可覆盖)。' });
     }
-    if (removedId)
-        await deps.l1.deleteBatch([removedId]);
+    if (removedId) {
+        // **软删**(退场),不是物理删除:主表行保留 + `valid_to` 闭合 + 写取代标记,
+        // FTS/向量行撤掉使其退出检索面。于是"判错了"可以再恢复,而不必去
+        // `records/*.jsonl` 事实源里手工捞——那是本功能上线前唯一的后悔药。
+        deps.l1.retire([removedId], {
+            at: resolvedAt,
+            reason: 'conflict',
+            verdict: clean,
+            pairId,
+        });
+    }
     // 图谱 disputed 重算:此刻仍未裁决的对才是争议集,已了结的节点自动复原 active
     const ids = new Set();
     for (const p of deps.l1.listConflictPending()) {
@@ -59,7 +70,7 @@ export function renderConflictResolution(v) {
     const outcome = v.outcome ?? '';
     const label = outcome === 'winner' ? '判定 LLM 建议的胜方为真' : outcome === 'loser' ? '判定败方为真' : '两者都保留(判为各自独立的事实)';
     const removed = v.removed_record_id
-        ? `\n退场记录:${v.removed_record_id}(已从检索中移除,事实源保留)`
+        ? `\n退场记录:${v.removed_record_id}(已移出检索面,**可恢复**——记忆列表里能找回)`
         : '\n未移除任何记录。';
     return `已裁决待裁决对 ${v.pair_id ?? ''}\n结论:${outcome}(${label})\n裁决时刻:${v.resolved_at ?? ''}${removed}`;
 }

package/dist/contract.d.ts

@@ -610,14 +610,76 @@ export interface ListRecordsResponse {
     /** 场景筛选下拉选项(仅 offset===0 时附带)。 */
     scenes?: string[];
 }
-/** dsh-memory/records-delete(面板高权限删除指定记忆;须 memoryMutate 开启)。 */
+/** dsh-memory/records-delete(面板高权限退场指定记忆;须 memoryMutate 开启)。 */
 export interface RecordsDeleteRequest {
-    /** 要删除的 L1 record id 列表(≤200)。 */
+    /** 要**退场(软删)**的 L1 record id 列表(≤200)。不是物理删除,可恢复。 */
     ids: string[];
 }
 export interface RecordsDeleteResponse {
     deleted: number;
 }
+/**
+ * 已退场记录的一条(在浏览卡片之上补退场信息)。
+ *
+ * `retiredReason` 用宽松 `string` 而非字面量联合:契约要能在**客户端**那一档
+ * (`types: []`)独立编译,不该反向依赖宿主 store 的类型;严格联合留在 store 侧,
+ * 面板只做展示。新增原因时面板不认识也能照常显示,不会编译失败。
+ */
+export interface RetiredRecordView extends UiRecord {
+    /** 退场时刻(ISO 8601)。 */
+    retiredAt: string;
+    /** 退场原因:`conflict`(裁决) / `superseded`(去重取代) / `manual`(人工)。 */
+    retiredReason: string;
+    /** 裁决结论(仅 reason=conflict)。 */
+    verdict?: string;
+    /** 取代它的新记录 id(仅 reason=superseded)。 */
+    supersededBy?: string;
+}
+/** dsh-memory/records-retired(已退场列表;面板据此展示"可恢复"区)。 */
+export interface RecordsRetiredRequest {
+    limit?: number;
+    offset?: number;
+}
+export interface RecordsRetiredResponse {
+    items: RetiredRecordView[];
+    total: number;
+}
+/** dsh-memory/records-restore(把已退场记录送回检索面)。 */
+export interface RecordsRestoreRequest {
+    /** 要恢复的 record id 列表(≤200)。 */
+    ids: string[];
+}
+export interface RecordsRestoreResponse {
+    restored: number;
+    /** 成功补回向量的条数(嵌入不可用时可能小于 `restored`)。 */
+    vectorsWritten: number;
+}
+/**
+ * dsh-memory/cleanup-retired(物理清理已退场记录)。
+ *
+ * **默认干跑**:`dryRun` 省略即视为 `true`,只报"将要清理多少条"。
+ * 真要物理删除必须显式 `dryRun:false` —— 这是本插件唯一不可逆的动作。
+ * 即便显式执行,也要先落快照并校验通过,否则中止(`aborted:true`)。
+ */
+export interface CleanupRetiredRequest {
+    /** 限定要清理的 id;省略 = 全部已退场记录。 */
+    ids?: string[];
+    /** 默认 true(干跑)。显式 false 才真正删除。 */
+    dryRun?: boolean;
+}
+export interface CleanupRetiredResponse {
+    dryRun: boolean;
+    /** 本次涉及(干跑)或实际处理(真跑)的条数。 */
+    targets: number;
+    /** 真正物理删除的条数(干跑恒为 0;中止恒为 0)。 */
+    purged: number;
+    /** 门禁未通过而中止。 */
+    aborted: boolean;
+    /** 快照目录(真跑时非空)。 */
+    dir: string;
+    /** 中止原因(仅 aborted 时非空)。 */
+    diffs: string[];
+}
 /** dsh-memory/graph-search(图谱节点检索;紧凑节点卡)。 */
 export interface GraphSearchRequest {
     /** 自然语言查询(≤4096 字符;空查询返回空)。 */
@@ -903,6 +965,9 @@ export interface DshMemoryRequestMap {
     'dsh-memory/embedding-runtime-cancel': Record<string, never>;
     'dsh-memory/embedding-reindex': Record<string, never>;
     'dsh-memory/embedding-reindex-cancel': Record<string, never>;
+    'dsh-memory/records-retired': RecordsRetiredRequest;
+    'dsh-memory/records-restore': RecordsRestoreRequest;
+    'dsh-memory/cleanup-retired': CleanupRetiredRequest;
 }
 export interface DshMemoryResponseMap {
     'dsh-memory/stats': StatsResponse;
@@ -938,6 +1003,9 @@ export interface DshMemoryResponseMap {
     'dsh-memory/embedding-runtime-cancel': EmbeddingCancelResponse;
     'dsh-memory/embedding-reindex': EmbeddingReindexStartResponse;
     'dsh-memory/embedding-reindex-cancel': EmbeddingCancelResponse;
+    'dsh-memory/records-retired': RecordsRetiredResponse;
+    'dsh-memory/records-restore': RecordsRestoreResponse;
+    'dsh-memory/cleanup-retired': CleanupRetiredResponse;
 }
 /** 全部端点名(client 调用与 host case 表的共用字面量来源)。 */
 export type DshMemoryEndpoint = keyof DshMemoryResponseMap;

package/dist/pipeline/l1.js

@@ -272,7 +272,11 @@ anchorMap) {
             relatedIds.add(c.id);
     }
     const byId = new Map(store.getByIds([...relatedIds]).map((r) => [r.id, r]));
-    const deletedIds = new Set();
+    /**
+     * update/merge 取代掉的旧记录 → **取代它的**新记录 id。
+     * 用 Map 而非 Set:退场标记要带 `by`,否则"被谁取代"只能靠时间猜。
+     */
+    const supersededBy = new Map();
     const added = [];
     /** §C 本轮新冻结的冲突对(应用完新增记录后统一落盘)。 */
     const frozen = [];
@@ -323,11 +327,14 @@ anchorMap) {
             }
             continue;
         }
-        // update / merge:目标记录从检索库删除,合并结果作为新记录追加(版本 +1)
+        // update / merge:目标记录**退场(软删)**,合并结果作为新记录追加(版本 +1)
         // 候选召回按族隔离,合并产物保持新记忆的族标签
         const targets = (decision.target_ids ?? []).filter((id) => byId.has(id));
+        // 同一目标被多条新记录取代时保留**首个**取代者:与 retire 的幂等语义一致
+        // (已退场记录不重复写标记),故先到先得而不是被后者覆盖
         for (const id of targets)
-            deletedIds.add(id);
+            if (!supersededBy.has(id))
+                supersededBy.set(id, m.record_id);
         const targetVersion = targets.reduce((max, id) => Math.max(max, byId.get(id)?.version ?? 0), 0);
         const mergedTs = (decision.merged_timestamps ?? [])
             .map((t) => Date.parse(t))
@@ -356,13 +363,27 @@ anchorMap) {
         });
     }
     await store.appendNew(added);
-    if (deletedIds.size > 0)
-        await store.deleteBatch([...deletedIds]);
-    // §C 自动裁决的执行面:LLM 的 loser 从检索库退场(winner 存活)。
+    if (supersededBy.size > 0) {
+        // **软删**(取代):不是物理删除——主表行保留 + `valid_to` 闭合 + 取代标记,
+        // FTS/向量撤出检索面。于是"合并错了"也能恢复,而不必去 `records/*.jsonl` 手工捞。
+        // 按取代者分组落盘(一次事务一组),避免逐条开事务。
+        const retiredAt = new Date(now).toISOString();
+        const byNewRecord = new Map();
+        for (const [targetId, newId] of supersededBy) {
+            const arr = byNewRecord.get(newId) ?? [];
+            arr.push(targetId);
+            byNewRecord.set(newId, arr);
+        }
+        for (const [newId, ids] of byNewRecord) {
+            store.retire(ids, { at: retiredAt, reason: 'superseded', by: newId });
+        }
+    }
+    // §C 自动裁决的执行面:LLM 的 loser 从检索面退场(winner 存活),同为**软删**。
     // 排在 appendNew 之后——若 loser 恰是**本轮新记忆**(LLM 判定新记忆更差),
-    // 也必须先让它进库再退场,以保证"本轮新增"与"本轮删除"的账面一致。
-    if (autoLosers.size > 0)
-        await store.deleteBatch([...autoLosers]);
+    // 也必须先让它进库再退场,以保证"本轮新增"与"本轮退场"的账面一致。
+    if (autoLosers.size > 0) {
+        store.retire([...autoLosers], { at: new Date(now).toISOString(), reason: 'conflict', verdict: 'auto' });
+    }
     // ── §C 冻结对落盘(排在 appendNew 之后) ──
     // 顺序有讲究:先让新记忆真正进 L1,再登记"它和谁构成待裁决对"。反过来的话,
     // 落盘失败会留下一条指向**不存在记录**的裁决请求,人工打开队列只会看到悬空 id。
@@ -404,7 +425,7 @@ anchorMap) {
         states[f].memoriesSinceL3 += addedByFamily[f];
     }
     markExtracted(states, mode, lastScene);
-    logger.info(`[memory] L1 抽取完成(mode=${mode}):消息 ${pending.length} 条,抽取 ${extracted.length} 条,去重后新增 ${added.length} 条(替换 ${deletedIds.size} 条,chat=${addedByFamily.chat}/work=${addedByFamily.work}),累计 chat=${states.chat.totalExtracted}/work=${states.work.totalExtracted}`);
+    logger.info(`[memory] L1 抽取完成(mode=${mode}):消息 ${pending.length} 条,抽取 ${extracted.length} 条,去重后新增 ${added.length} 条(取代退场 ${supersededBy.size} 条,chat=${addedByFamily.chat}/work=${addedByFamily.work}),累计 chat=${states.chat.totalExtracted}/work=${states.work.totalExtracted}`);
     return { stored: added.length, skipped: false, sceneName: lastScene, newRecords: added };
 }
 /** auto 档取最近活跃的族 checkpoint(情境链/计数锚点)。 */

package/dist/stats.d.ts

@@ -22,7 +22,7 @@ export interface MemoryStatusSource {
     pending(): number;
 }
 /**
- * 端点全集运行时清单(33 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
+ * 端点全集运行时清单(36 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
  * contract.ts 类型映射表三方对齐,漂移由键集 diff 测试暴露)。
  * 注意:本清单同时是 HTTP 前缀路由 `/dsh-memory/rpc/<短名>` 的**放行白名单**
  * (见下方 SHORT_ENDPOINTS),漏一条 = 该端点在面板里静默消失(404 被客户端

package/dist/stats.js

@@ -22,12 +22,13 @@ import { projectDistillChain, validateDistillChain } from './settings.js';
 import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from './store/receipts.js';
 import { resolveConflictPair, listConflictPairs } from './conflict-service.js';
 import { sourceAnchorLabels } from './pipeline/anchors.js';
+import { readSupersedeMarker } from './store/supersede.js';
 import { errDetail } from './util/filelog.js';
 import { snapshotTokenCost } from './token-cost.js';
 const require = createRequire(import.meta.url);
 export const PLUGIN_VERSION = require('../package.json').version;
 /**
- * 端点全集运行时清单(33 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
+ * 端点全集运行时清单(36 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
  * contract.ts 类型映射表三方对齐,漂移由键集 diff 测试暴露)。
  * 注意:本清单同时是 HTTP 前缀路由 `/dsh-memory/rpc/<短名>` 的**放行白名单**
  * (见下方 SHORT_ENDPOINTS),漏一条 = 该端点在面板里静默消失(404 被客户端
@@ -71,6 +72,9 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/embedding-runtime-cancel',
     'dsh-memory/embedding-reindex',
     'dsh-memory/embedding-reindex-cancel',
+    'dsh-memory/records-retired',
+    'dsh-memory/records-restore',
+    'dsh-memory/cleanup-retired',
 ];
 /** HTTP 路由前缀(客户端 fetch `/dsh-memory/rpc/<短方法名>`)。 */
 const RPC_ROUTE_PREFIX = '/dsh-memory/rpc';
@@ -751,7 +755,12 @@ export async function handleEndpoint(endpoint, payload, deps) {
             return await resolveConflictPair({ l1: stores.l1, conflictFreezeEnabled: effectiveCfg(cfg, live).conflictFreeze?.enabled === true }, pairId, outcome);
         }
         case 'dsh-memory/records-delete': {
-            // 面板高权限删除指定记忆;写入删权限门(memoryMutate)防御
+            // 面板高权限删除指定记忆;写入删权限门(memoryMutate)防御。
+            //
+            // **软删**(退场),不是物理删除:与裁决 / 取代共用同一原语。面板上的"删除"
+            // 因此可撤销;真要抹掉数据只能走 `cleanup-retired`(先落快照 + 校验通过才删)。
+            // 这样 `deleteL1Batch` 在整个代码里**只有一个调用方**(exportThenPurge),
+            // "物理删除必须先有可信导出物"就成了结构性事实,而不是一句约定。
             if (!live?.get().memoryMutate) {
                 throw new Error('记忆写删未开放:请在记忆库面板开启高权限模式');
             }
@@ -759,9 +768,101 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const ids = (Array.isArray(p.ids) ? p.ids : []).filter((x) => typeof x === 'string').slice(0, 200);
             if (ids.length === 0)
                 throw new Error('ids 缺失');
-            await stores.l1.deleteBatch(ids);
-            deps.logger.info(`[memory] 高权限删除记忆 ${ids.length} 条(${ids.join('，')})`);
-            return { deleted: ids.length };
+            const n = stores.l1.retire(ids, { at: new Date().toISOString(), reason: 'manual' });
+            deps.logger.info(`[memory] 高权限退场(软删)记忆 ${n} 条(${ids.join('，')})`);
+            return { deleted: n };
+        }
+        // ── 记忆退场(软删)与清理:已退场列表 / 恢复 / 物理清理 ──
+        // 读方向**不开**权限门(与 conflicts 一致:看得见才知道要不要恢复);
+        // 恢复与物理清理由 memoryMutate 门控。
+        case 'dsh-memory/records-retired': {
+            const p = (payload ?? {});
+            const limit = Math.min(Math.max(Math.floor(Number(p.limit)) || 50, 1), 200);
+            const offset = Math.min(Math.max(Math.floor(Number(p.offset)) || 0, 0), 1_000_000);
+            const { items, total } = stores.l1.listRetired({ limit, offset });
+            const resp = {
+                items: items.map((r) => {
+                    const mark = readSupersedeMarker(r.metadata);
+                    const view = hitToUiRecord(r);
+                    return {
+                        ...view,
+                        // 标记缺失时退回 `valid_to`(软删的两条判据任一成立即算已退场)
+                        retiredAt: mark?.at ?? (r.validTo !== undefined ? new Date(r.validTo).toISOString() : ''),
+                        retiredReason: mark?.reason ?? 'unknown',
+                        ...(mark?.verdict ? { verdict: mark.verdict } : {}),
+                        ...(mark?.by ? { supersededBy: mark.by } : {}),
+                    };
+                }),
+                total,
+            };
+            return resp;
+        }
+        case 'dsh-memory/records-restore': {
+            if (!live?.get().memoryMutate) {
+                throw new Error('记忆写删未开放:请在记忆库面板开启高权限模式');
+            }
+            const p = (payload ?? {});
+            const ids = (Array.isArray(p.ids) ? p.ids : [])
+                .filter((x) => typeof x === 'string' && x !== '')
+                .slice(0, 200);
+            if (ids.length === 0)
+                throw new Error('ids 缺失');
+            const r = await stores.l1.restore(ids);
+            deps.logger.info(`[memory] 恢复已退场记忆 ${r.restored} 条(补向量 ${r.vectorsWritten} 条)`);
+            const resp = r;
+            return resp;
+        }
+        case 'dsh-memory/cleanup-retired': {
+            if (!live?.get().memoryMutate) {
+                throw new Error('记忆写删未开放:请在记忆库面板开启高权限模式');
+            }
+            const p = (payload ?? {});
+            // **默认干跑**:省略 `dryRun` 即视为 true。物理删除是本插件唯一不可逆的动作,
+            // 必须由调用方显式要求才做(与"所有破坏性动作必须默认可回滚"同一条纪律)。
+            const dryRun = p.dryRun !== false;
+            const explicit = (Array.isArray(p.ids) ? p.ids : [])
+                .filter((x) => typeof x === 'string' && x !== '')
+                .slice(0, 500);
+            let targets;
+            if (explicit.length > 0) {
+                // 显式 id 也要**复核**是否真的处于已退场态:防止调用方用一个 id 列表
+                // 把活动记忆绕过软删直接物理抹掉(那等于给了一条硬删后门)。
+                targets = explicit.filter((id) => stores.l1.getByIds([id]).some((r) => r.validTo !== undefined));
+            }
+            else {
+                targets = [];
+                for (let offset = 0;; offset += 200) {
+                    const page = stores.l1.listRetired({ limit: 200, offset });
+                    targets.push(...page.items.map((r) => r.id));
+                    if (page.items.length < 200)
+                        break;
+                }
+            }
+            if (dryRun) {
+                const resp = {
+                    dryRun: true,
+                    targets: targets.length,
+                    purged: 0,
+                    aborted: false,
+                    dir: '',
+                    diffs: [],
+                };
+                return resp;
+            }
+            if (targets.length === 0) {
+                const resp = { dryRun: false, targets: 0, purged: 0, aborted: false, dir: '', diffs: [] };
+                return resp;
+            }
+            const r = await stores.l1.purgeRetired(targets, 'cleanup-retired');
+            const resp = {
+                dryRun: false,
+                targets: targets.length,
+                purged: r.purged,
+                aborted: r.aborted,
+                dir: r.dir,
+                diffs: r.diffs,
+            };
+            return resp;
         }
         // ── 知识图谱(面板图谱视图;graph 未装配时返空不报错) ──
         case 'dsh-memory/graph-search': {

package/dist/store/l1-snapshot.d.ts

@@ -97,3 +97,35 @@ export declare function restoreL1Snapshot(db: SnapshotDbLike, dir: string, logge
  * @returns 快照目录与清单;调用方拿到后才可以继续清空。
  */
 export declare function snapshotBeforeClear(db: SnapshotDbLike, dataDir: string, reason: string, now?: Date): Promise<CreateSnapshotResult>;
+/** 物理清理面(比快照面多一个删除能力)。 */
+export interface PurgeDbLike extends SnapshotDbLike {
+    deleteL1Batch: (ids: string[]) => number;
+}
+export interface ExportThenPurgeResult {
+    /** 清理是否真的执行了。 */
+    ok: boolean;
+    /** 门禁未通过而**中止**(`purged` 必为 0)。 */
+    aborted: boolean;
+    /** 快照目录(中止时也给,便于人工查看失败现场)。 */
+    dir: string;
+    purged: number;
+    /** 校验差异(仅 aborted 时非空)。 */
+    diffs: string[];
+}
+/**
+ * **先导出,后清理**——把这句话变成调用方绕不过去的一步。
+ *
+ * 顺序与理由:
+ * ① 建快照(写正文 + 清单);**写盘失败即中止**,绝不"先删了再说";
+ * ② `verifySnapshot` 按**内容哈希**比对快照与当前库。不一致说明两者之间有别的写入
+ *    发生(并发蒸馏、另一次清理),此时快照**不代表**将要被删的那批数据 → 中止;
+ * ③ 只有 ①② 都通过,才 `deleteL1Batch` 做物理删除。
+ *
+ * 为什么值得这么严:物理删除是本插件唯一**不可逆**的动作。软删(退场)可以恢复,
+ * 而清理一旦没有可信的导出物,就只剩 `records/*.jsonl` 事实源这一条后路,
+ * 且那条路只覆盖 L1 记录、不覆盖 receipts/conflicts 的当时快照。
+ */
+export declare function exportThenPurge(db: PurgeDbLike, dataDir: string, ids: readonly string[], reason: string, logger?: {
+    info: (m: string) => void;
+    warn: (m: string) => void;
+}, now?: Date): Promise<ExportThenPurgeResult>;

package/dist/store/l1-snapshot.js

@@ -187,3 +187,38 @@ export async function snapshotBeforeClear(db, dataDir, reason, now = new Date())
     const dir = snapshotPathFor(dataDir, now, reason);
     return createL1Snapshot(db, dir, reason, now);
 }
+/**
+ * **先导出,后清理**——把这句话变成调用方绕不过去的一步。
+ *
+ * 顺序与理由:
+ * ① 建快照(写正文 + 清单);**写盘失败即中止**,绝不"先删了再说";
+ * ② `verifySnapshot` 按**内容哈希**比对快照与当前库。不一致说明两者之间有别的写入
+ *    发生(并发蒸馏、另一次清理),此时快照**不代表**将要被删的那批数据 → 中止;
+ * ③ 只有 ①② 都通过,才 `deleteL1Batch` 做物理删除。
+ *
+ * 为什么值得这么严:物理删除是本插件唯一**不可逆**的动作。软删(退场)可以恢复,
+ * 而清理一旦没有可信的导出物,就只剩 `records/*.jsonl` 事实源这一条后路,
+ * 且那条路只覆盖 L1 记录、不覆盖 receipts/conflicts 的当时快照。
+ */
+export async function exportThenPurge(db, dataDir, ids, reason, logger, now = new Date()) {
+    if (ids.length === 0)
+        return { ok: true, aborted: false, dir: '', purged: 0, diffs: [] };
+    let dir = '';
+    try {
+        const snap = await snapshotBeforeClear(db, dataDir, reason, now);
+        dir = snap.dir;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger?.warn(`[memory] 清理中止:快照写入失败(${msg})——未删除任何记录`);
+        return { ok: false, aborted: true, dir, purged: 0, diffs: [`快照写入失败:${msg}`] };
+    }
+    const verdict = await verifySnapshot(db, dir);
+    if (!verdict.ok) {
+        logger?.warn(`[memory] 清理中止:快照校验未通过(${verdict.diffs.join(';')})——未删除任何记录`);
+        return { ok: false, aborted: true, dir, purged: 0, diffs: verdict.diffs };
+    }
+    const purged = db.deleteL1Batch([...ids]);
+    logger?.info(`[memory] 已物理清理 ${purged} 条已退场记录(快照:${dir})`);
+    return { ok: true, aborted: false, dir, purged, diffs: [] };
+}

package/dist/store/l1.d.ts

@@ -2,6 +2,8 @@ import type { L1Hit, MemoryFamily, MemoryLogger, MemoryRecord } from '../types.j
 import type { GraphNodeSearchResult } from '../graph/types.js';
 import type { L1Receipt, ReceiptQuery } from './receipts.js';
 import type { ConflictPair, ConflictResolution } from './conflicts.js';
+import type { SupersedeInfo } from './supersede.js';
+import { type ExportThenPurgeResult } from './l1-snapshot.js';
 import { type EmbeddingService } from './embedding.js';
 import { type MemoryDb } from './sqlite.js';
 export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
@@ -102,7 +104,39 @@ export declare class L1Store {
      *  (见本文件 `reindex` 首行),调用方必须自己问这里——否则"根本没跑"
      *  会长得和"跑完了、零条待补"一模一样。 */
     vectorsReady(): boolean;
-    deleteBatch(ids: string[]): Promise<void>;
+    /**
+     * **软删**(记忆退场):保留主表行 + 撤出检索面,可被 `restore` 找回。
+     *
+     * 三条退场路径 —— 裁决判负 / 去重取代(`update`/`merge`) / 人工删除 ——
+     * **共用这一个入口**。分成三份实现迟早会出现"某条路径还在硬删"的不一致语义,
+     * 而那种不一致只有在误删发生时才暴露。
+     */
+    retire(ids: string[], info: SupersedeInfo): number;
+    /** 已退场(可恢复)记录列表(面板用)。 */
+    listRetired(opts: {
+        limit: number;
+        offset: number;
+    }): {
+        items: MemoryRecord[];
+        total: number;
+    };
+    /**
+     * 恢复:清退场标记 → 重新 upsert 以重建 FTS(与向量)。
+     *
+     * 嵌入不可用/超时时**不抛**:向量补不上只是"暂时只能关键词召回",而"恢复失败"
+     * 会让人以为记录丢了 —— 后者严重得多。记录先回到检索面,向量留给后续 `reindex`。
+     */
+    restore(ids: string[]): Promise<{
+        restored: number;
+        vectorsWritten: number;
+    }>;
+    /**
+     * 已退场记录的**物理清理**(不可逆):先落快照 + 校验,门禁不过即中止。
+     *
+     * 门禁本体在 `l1-snapshot.exportThenPurge`(与"重建前必快照"同一套设施);
+     * 这里只把 L1Store 已知的 dataDir 与 logger 接上去,避免端点层自己去推路径。
+     */
+    purgeRetired(ids: string[], reason: string): Promise<ExportThenPurgeResult>;
     /**
      * 三策略检索(自动召回与 memory_search 工具共用接缝)。
      * embedding 不可用时自动降级 keyword;type 后置过滤;

package/dist/store/l1.js

@@ -10,6 +10,7 @@ import { existsSync, promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { familyForType, isScopeVisible } from '../types.js';
 import { graphHitRecordIds } from '../graph/search.js';
+import { exportThenPurge } from './l1-snapshot.js';
 import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
 import { appendJsonl, dayKey, ensureDir, readJsonl } from '../util/io.js';
 import { applyDecayWeight, normalizeRrf, rrfMerge } from './search-utils.js';
@@ -185,8 +186,63 @@ export class L1Store {
     vectorsReady() {
         return this.helper.vectorReady();
     }
-    async deleteBatch(ids) {
-        this.db.deleteL1Batch(ids);
+    // 这里**刻意没有** `deleteBatch`:物理删除(L1 三表同清)是不可逆的,
+    // 故它只能经由 `purgeRetired` → `exportThenPurge`(先落快照 + 校验通过)抵达。
+    // 曾经的 `deleteBatch(ids)` 是个无门禁的硬删入口,裁决 / 取代 / 面板删除都直接
+    // 调它 —— 那正是"删错了只能去 records/*.jsonl 手工捞"的根源。
+    // 若将来确需新增强删路径,请复用它下面的门禁,而不是重新暴露一个裸入口。
+    /**
+     * **软删**(记忆退场):保留主表行 + 撤出检索面,可被 `restore` 找回。
+     *
+     * 三条退场路径 —— 裁决判负 / 去重取代(`update`/`merge`) / 人工删除 ——
+     * **共用这一个入口**。分成三份实现迟早会出现"某条路径还在硬删"的不一致语义,
+     * 而那种不一致只有在误删发生时才暴露。
+     */
+    retire(ids, info) {
+        return this.db.retireL1Batch(ids, info);
+    }
+    /** 已退场(可恢复)记录列表(面板用)。 */
+    listRetired(opts) {
+        return this.db.listRetiredL1(opts);
+    }
+    /**
+     * 恢复:清退场标记 → 重新 upsert 以重建 FTS(与向量)。
+     *
+     * 嵌入不可用/超时时**不抛**:向量补不上只是"暂时只能关键词召回",而"恢复失败"
+     * 会让人以为记录丢了 —— 后者严重得多。记录先回到检索面,向量留给后续 `reindex`。
+     */
+    async restore(ids) {
+        const records = this.db.clearRetireMarker(ids);
+        let vectorsWritten = 0;
+        for (const rec of records) {
+            if (!rec.family)
+                rec.family = familyForType(rec.type);
+            let vec;
+            try {
+                vec = (await this.helper.batch([rec.content]))[0];
+            }
+            catch (err) {
+                this.logger?.warn(`[memory] 恢复时向量计算失败,先回关键词检索面(日后重建可补齐): ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (vec && !isZeroVector(vec))
+                vectorsWritten++;
+            this.db.upsertL1(rec, vec);
+        }
+        return { restored: records.length, vectorsWritten };
+    }
+    /**
+     * 已退场记录的**物理清理**(不可逆):先落快照 + 校验,门禁不过即中止。
+     *
+     * 门禁本体在 `l1-snapshot.exportThenPurge`(与"重建前必快照"同一套设施);
+     * 这里只把 L1Store 已知的 dataDir 与 logger 接上去,避免端点层自己去推路径。
+     */
+    async purgeRetired(ids, reason) {
+        // **只清理确实处于退场态的记录**。这道复核必须在删除发生的地方(而不是调用方):
+        // 否则任何调用方传一个 id 列表就能绕过软删、把活动记忆直接物理抹掉——
+        // 那等于给"先导出后清理"留了一条硬删后门。
+        const known = new Map(this.db.getL1ByIds(ids).map((r) => [r.id, r]));
+        const retiredIds = ids.filter((id) => known.get(id)?.validTo !== undefined);
+        return exportThenPurge(this.db, path.dirname(this.recordsDir), retiredIds, reason, this.logger);
     }
     /**
      * 三策略检索(自动召回与 memory_search 工具共用接缝)。

package/dist/store/sqlite.d.ts

@@ -17,6 +17,7 @@ import type { CostByModel } from '../contract.js';
 import { GraphStore } from './graph-store.js';
 import type { L1Receipt, ReceiptQuery, ReceiptRetentionOptions } from './receipts.js';
 import type { ConflictPair, ConflictResolution } from './conflicts.js';
+import { type SupersedeInfo } from './supersede.js';
 /** L1 检索命中(含 BM25/余弦归一分数)。 */
 export interface L1SearchHit {
     id: string;
@@ -145,6 +146,48 @@ export declare class MemoryDb {
     /** 批量删除 L1(元数据 + 向量 + FTS),返回删除条数。IN 按 ≤900 分块(避变量数上限)。
      *  删除成功后触发图谱删除传播(来源全失效的节点/边惰性标 archived;失败不影响删除结果)。 */
     deleteL1Batch(ids: string[]): number;
+    /**
+     * **软删**(记忆退场):保留主表行,撤出检索面。
+     *
+     * 与 `deleteL1Batch` 的差别**只有一处**:不动 `l1_records` 行本身。
+     * `valid_to` 闭合 + `metadata_json` 写取代标记 → 记录仍能被 `listL1` 列出、
+     * 能被 `clearRetireMarker` + upsert 恢复;而 FTS 与向量行照旧删除,于是检索面
+     * (含去重候选召回)自然看不到它 —— **检索 SQL 一行都不用改**,活动记录零漂移
+     * 因此是构造性的,不是比对出来的。
+     *
+     * 顺序刻意如此:先打标记(可逆的那一半),再撤检索面,且整体在一个事务里。
+     * 反过来先撤索引而打标记失败,记录会落在"检索不到、也没被标记"的状态 ——
+     * 既查不出来也恢复不了,是最坏的一种中间态。
+     *
+     * **幂等**:已退场(`valid_to` 非空或已有标记)的 id 不再重复写标记,
+     * 保留首次退场的原因与时刻(「谁先取代了它」不该被后一次调用改写)。
+     *
+     * **不调** `graphStore.markSourcesDeleted`:那是"来源已物理消失"的传播,
+     * 而软删的记录仍活在主表里 —— 图谱侧的退役语义另计(见计划 findings R-a)。
+     */
+    retireL1Batch(ids: string[], info: SupersedeInfo): number;
+    /**
+     * 撤出检索面(删 FTS + 向量行,**主表保留**)。
+     * 与 `deleteL1Batch` 的删除面同源,只是不动 `l1_records`。
+     */
+    private detachL1FromRetrieval;
+    /**
+     * 清掉退场标记(恢复的**前半**)。返回清完标记的记录,供调用方 re-upsert 以重建
+     * FTS/向量 —— 那条路径(`upsertL1InTx`)已存在,不在这里重复实现。
+     *
+     * 只清 `valid_to` 与标记键,**不碰内容**:恢复不该修改记忆本身。
+     * 返回的 `validTo` 显式置 `undefined`(而非留着旧 epoch),否则 upsert 会
+     * 用 `toIso(旧值)` 把 `valid_to` 又写回去,恢复静默失败。
+     */
+    clearRetireMarker(ids: string[]): MemoryRecord[];
+    /** 已退场记录列表(面板用):`valid_to` 非空即已退场。失败返回空。 */
+    listRetiredL1(opts: {
+        limit: number;
+        offset: number;
+    }): {
+        items: MemoryRecord[];
+        total: number;
+    };
     private inStatement;
     /**
      * 清空 L1 检索库全部数据(重建用)。records/FTS 直接 DELETE;

package/dist/store/sqlite.js

@@ -33,6 +33,7 @@ import { CostLedger } from './cost-ledger.js';
 // 图谱存储(graph_* 表族)同为独立职责类;init 失败仅图谱 no-op,不传染主库降级
 import { GraphStore } from './graph-store.js';
 import { RECEIPTS_MAX_RUNS, RECEIPTS_QUERY_LIMIT_MAX } from './receipts.js';
+import { isRetired, readSupersedeMarker, stripSupersedeMarker, withSupersedeMarker } from './supersede.js';
 /** vec0 KNN 对遗留零向量的补偿缓冲。 */
 const ZERO_VEC_BUFFER = 10;
 /** IN 查询/删除的分块大小(保守避开 SQLite 变量数上限:现代构建 32766,老版 999)。 */
@@ -826,20 +827,28 @@ export class MemoryDb {
         // 全扫(批量写整体 O(N²))。只有主表已有该行(覆盖/合并)才可能有旧 FTS 行需要删。
         // 同批重复 id 也能正确处理:首条插入后,第二条的点查在同一事务内已见新行。
         const ftsExisted = this.ftsAvailable ? this.stmtL1Exists.get(record.id) !== undefined : false;
+        // **退场不变量必须在写入漏斗上强制**:已退场的记录(valid_to 闭合或带取代标记)
+        // 永不出现在检索面。只靠 `retireL1Batch` 保证是不够的——快照恢复 / 重建 /
+        // 旧版导入都会经这里写回记录,若照常重建 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);
-        // vec0 不支持 ON CONFLICT → 先删后插;零向量跳过(cosine 未定义)
+        // vec0 不支持 ON CONFLICT → 先删后插;零向量跳过(cosine 未定义)。
+        // 已退场则**只删不插**(见上方 retiredNow 的说明)。
         if (this.stmtDeleteL1Vec && this.stmtInsertL1Vec) {
             this.stmtDeleteL1Vec.run(record.id);
-            if (embedding && !isZeroVector(embedding)) {
+            if (!retiredNow && embedding && !isZeroVector(embedding)) {
                 this.stmtInsertL1Vec.run(record.id, vecToBuffer(embedding), toIso(record.updatedAt));
             }
         }
         // FTS 删除/插入与元数据同事务:失败必须整体回滚——若只吞 FTS 错误照常 COMMIT,
         // 已执行的 DELETE 会让该 id 的索引行被删未补,记录从此全文检索不可见(静默丢数据)。
         if (this.ftsAvailable) {
-            if (ftsExisted)
+            if (ftsExisted || retiredNow)
                 this.stmtL1FtsDelete.run(record.id);
-            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, scope, workspaceId);
+            if (!retiredNow) {
+                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, scope, workspaceId);
+            }
         }
     }
     /** 批量删除 L1(元数据 + 向量 + FTS),返回删除条数。IN 按 ≤900 分块(避变量数上限)。
@@ -868,6 +877,114 @@ export class MemoryDb {
             return 0;
         }
     }
+    /**
+     * **软删**(记忆退场):保留主表行,撤出检索面。
+     *
+     * 与 `deleteL1Batch` 的差别**只有一处**:不动 `l1_records` 行本身。
+     * `valid_to` 闭合 + `metadata_json` 写取代标记 → 记录仍能被 `listL1` 列出、
+     * 能被 `clearRetireMarker` + upsert 恢复;而 FTS 与向量行照旧删除,于是检索面
+     * (含去重候选召回)自然看不到它 —— **检索 SQL 一行都不用改**,活动记录零漂移
+     * 因此是构造性的,不是比对出来的。
+     *
+     * 顺序刻意如此:先打标记(可逆的那一半),再撤检索面,且整体在一个事务里。
+     * 反过来先撤索引而打标记失败,记录会落在"检索不到、也没被标记"的状态 ——
+     * 既查不出来也恢复不了,是最坏的一种中间态。
+     *
+     * **幂等**:已退场(`valid_to` 非空或已有标记)的 id 不再重复写标记,
+     * 保留首次退场的原因与时刻(「谁先取代了它」不该被后一次调用改写)。
+     *
+     * **不调** `graphStore.markSourcesDeleted`:那是"来源已物理消失"的传播,
+     * 而软删的记录仍活在主表里 —— 图谱侧的退役语义另计(见计划 findings R-a)。
+     */
+    retireL1Batch(ids, info) {
+        if (this.degraded || ids.length === 0)
+            return 0;
+        try {
+            const existing = new Map(this.getL1ByIds(ids).map((r) => [r.id, r]));
+            const update = this.db.prepare('UPDATE l1_records SET valid_to = ?, metadata_json = ? WHERE record_id = ?');
+            const retired = [];
+            this.withTransaction(() => {
+                for (const id of ids) {
+                    const rec = existing.get(id);
+                    // 不存在的 id 静默跳过;已退场的跳过以保幂等
+                    if (!rec || isRetired(rec))
+                        continue;
+                    update.run(info.at, JSON.stringify(withSupersedeMarker(rec.metadata, info)), id);
+                    retired.push(id);
+                }
+                if (retired.length > 0)
+                    this.detachL1FromRetrieval(retired);
+            });
+            return retired.length;
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L1 软删(退场)失败: ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+    }
+    /**
+     * 撤出检索面(删 FTS + 向量行,**主表保留**)。
+     * 与 `deleteL1Batch` 的删除面同源,只是不动 `l1_records`。
+     */
+    detachL1FromRetrieval(ids) {
+        if (this.stmtDeleteL1Vec) {
+            for (const chunk of chunkIds(ids))
+                this.inStatement('l1_vec', 'delete', chunk.length).run(...chunk);
+        }
+        if (this.ftsAvailable) {
+            for (const chunk of chunkIds(ids))
+                this.inStatement('l1_fts', 'delete', chunk.length).run(...chunk);
+        }
+    }
+    /**
+     * 清掉退场标记(恢复的**前半**)。返回清完标记的记录,供调用方 re-upsert 以重建
+     * FTS/向量 —— 那条路径(`upsertL1InTx`)已存在,不在这里重复实现。
+     *
+     * 只清 `valid_to` 与标记键,**不碰内容**:恢复不该修改记忆本身。
+     * 返回的 `validTo` 显式置 `undefined`(而非留着旧 epoch),否则 upsert 会
+     * 用 `toIso(旧值)` 把 `valid_to` 又写回去,恢复静默失败。
+     */
+    clearRetireMarker(ids) {
+        if (this.degraded || ids.length === 0)
+            return [];
+        try {
+            const existing = this.getL1ByIds(ids);
+            const update = this.db.prepare('UPDATE l1_records SET valid_to = ?, metadata_json = ? WHERE record_id = ?');
+            const restored = [];
+            this.withTransaction(() => {
+                for (const rec of existing) {
+                    const metadata = stripSupersedeMarker(rec.metadata);
+                    if (isRetired(rec))
+                        update.run('', JSON.stringify(metadata), rec.id);
+                    restored.push({ ...rec, metadata, validTo: undefined });
+                }
+            });
+            return restored;
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L1 恢复(清退场标记)失败: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
+    /** 已退场记录列表(面板用):`valid_to` 非空即已退场。失败返回空。 */
+    listRetiredL1(opts) {
+        if (this.degraded)
+            return { items: [], total: 0 };
+        try {
+            const totalRow = this.db
+                .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
+           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) };
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 已退场列表查询失败(返回空): ${err instanceof Error ? err.message : String(err)}`);
+            return { items: [], total: 0 };
+        }
+    }
     inStatement(table, action, size) {
         const key = `${table}:${action}:${size}`;
         let stmt = this.inStmts.get(key);

package/dist/store/supersede.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 记忆退场的**取代标记**(软删可恢复)——纯函数层。
+ *
+ * ## 为什么需要它
+ *
+ * 退场(裁决判负 / 去重取代 / 人工删除)此前一律 `deleteL1Batch` **物理删除**:
+ * 主表、FTS、向量三处同清,记录直接消失。于是"删错了"只能靠 `records/*.jsonl`
+ * 事实源捞回来——**检索库自身不可恢复**。
+ *
+ * 本模块承载"可恢复"里最纯的那一半:**标记的形状**。把它抽成独立纯函数层,
+ * 与 `anchors.ts` 同一理由——读写都是"输入 → 输出",可以是单测直接验的,
+ * 而不必起库、起宿主。
+ *
+ * ## 两条铁律
+ *
+ * 1. **不可变**:`with*` / `strip*` 一律返回**新对象**,绝不改入参。调用方的
+ *    `record.metadata` 可能正被别处引用(检索命中、面板视图),就地改写会
+ *    造成"读一次数据被改一次"的隐性副作用。
+ * 2. **零漂移**:`strip` 在无标记时返回**原引用**;`with` 只在确有标记时才写键。
+ *    既有记录的 `metadata_json` 不该因为本功能上线而多出任何字节。
+ */
+import type { MemoryRecord } from '../types.js';
+/**
+ * `l1_records.metadata_json` 里承载取代标记的**保留键**。
+ *
+ * 加 `dsh_` 前缀的理由与 `ANCHOR_METADATA_KEY` 完全相同:写库时本插件的保留键
+ * 会与 LLM 产出的 metadata(`hall` / `artifact_type` 等)合并进同一个 JSON 对象,
+ * 必须靠命名空间隔开,否则一次 LLM 幻觉输出 `superseded` 就能伪装成人工裁决。
+ */
+export declare const SUPERSEDE_METADATA_KEY = "dsh_superseded";
+/**
+ * 退场原因。**穷举**而非自由字符串:面板要按原因给不同文案与图标,
+ * 自由字符串会让"未识别的原因"静默退化成无徽标。
+ */
+export type RetireReason = 'conflict' | 'superseded' | 'manual';
+/** 取代标记(写进 metadata 的负载)。 */
+export interface SupersedeInfo {
+    /** 退场时刻(ISO 8601)。 */
+    at: string;
+    reason: RetireReason;
+    /** 裁决结论 `winner` / `loser` / `both` / `auto`(仅 `reason='conflict'`)。 */
+    verdict?: string;
+    /** 产生该退场的待裁决对 id(仅 `reason='conflict'`,供交叉审计)。 */
+    pairId?: string;
+    /** **取代它的**新记录 id(仅 `reason='superseded'`)。 */
+    by?: string;
+}
+/**
+ * 写入取代标记(返回**新对象**)。
+ *
+ * 与 `withSourceAnchors` 的差别:锚点"无锚点时不写键",而退场标记**永远写**——
+ * 调用它的前提就是"这条记录正在退场",没有"空标记"这种合法输入。
+ */
+export declare function withSupersedeMarker(metadata: Record<string, unknown> | undefined, info: SupersedeInfo): Record<string, unknown>;
+/**
+ * 读回取代标记(读侧唯一入口)。
+ *
+ * 形状校验从严:缺 `at` 或 `reason` 非法 → 返回 `undefined`(当作**未退场**)。
+ * 宁可把一条坏标记的记录当活动记录,也不把它当"已退场"而藏起来——
+ * 后者会让记忆**悄悄消失**,正是本功能要根治的病。
+ */
+export declare function readSupersedeMarker(metadata: unknown): SupersedeInfo | undefined;
+/**
+ * 去标记(恢复时用)。返回**新对象**。
+ *
+ * 无标记时返回**原引用**——恢复一条从未退场的记录不该产生任何新对象,
+ * 这条判据让"恢复"对活动记录是彻底的 no-op。
+ */
+export declare function stripSupersedeMarker(metadata: Record<string, unknown> | undefined): Record<string, unknown>;
+/** 该记录是否处于**已退场**状态(读主表 `valid_to` 的语义封装)。 */
+export declare function isRetired(record: Pick<MemoryRecord, 'validTo' | 'metadata'>): boolean;

package/dist/store/supersede.js

@@ -0,0 +1,74 @@
+/**
+ * `l1_records.metadata_json` 里承载取代标记的**保留键**。
+ *
+ * 加 `dsh_` 前缀的理由与 `ANCHOR_METADATA_KEY` 完全相同:写库时本插件的保留键
+ * 会与 LLM 产出的 metadata(`hall` / `artifact_type` 等)合并进同一个 JSON 对象,
+ * 必须靠命名空间隔开,否则一次 LLM 幻觉输出 `superseded` 就能伪装成人工裁决。
+ */
+export const SUPERSEDE_METADATA_KEY = 'dsh_superseded';
+const REASONS = ['conflict', 'superseded', 'manual'];
+/**
+ * 写入取代标记(返回**新对象**)。
+ *
+ * 与 `withSourceAnchors` 的差别:锚点"无锚点时不写键",而退场标记**永远写**——
+ * 调用它的前提就是"这条记录正在退场",没有"空标记"这种合法输入。
+ */
+export function withSupersedeMarker(metadata, info) {
+    const base = metadata ?? {};
+    const marker = { at: info.at, reason: info.reason };
+    // 可选字段缺省即不写键:空串会让"没有 pairId"与"pairId 是空串"无法区分
+    if (info.verdict)
+        marker.verdict = info.verdict;
+    if (info.pairId)
+        marker.pairId = info.pairId;
+    if (info.by)
+        marker.by = info.by;
+    return { ...base, [SUPERSEDE_METADATA_KEY]: marker };
+}
+/**
+ * 读回取代标记(读侧唯一入口)。
+ *
+ * 形状校验从严:缺 `at` 或 `reason` 非法 → 返回 `undefined`(当作**未退场**)。
+ * 宁可把一条坏标记的记录当活动记录,也不把它当"已退场"而藏起来——
+ * 后者会让记忆**悄悄消失**,正是本功能要根治的病。
+ */
+export function readSupersedeMarker(metadata) {
+    if (metadata === null || typeof metadata !== 'object')
+        return undefined;
+    const raw = metadata[SUPERSEDE_METADATA_KEY];
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const o = raw;
+    const at = o.at;
+    const reason = o.reason;
+    if (typeof at !== 'string' || !at)
+        return undefined;
+    if (typeof reason !== 'string' || !REASONS.includes(reason))
+        return undefined;
+    const info = { at, reason: reason };
+    if (typeof o.verdict === 'string' && o.verdict)
+        info.verdict = o.verdict;
+    if (typeof o.pairId === 'string' && o.pairId)
+        info.pairId = o.pairId;
+    if (typeof o.by === 'string' && o.by)
+        info.by = o.by;
+    return info;
+}
+/**
+ * 去标记(恢复时用)。返回**新对象**。
+ *
+ * 无标记时返回**原引用**——恢复一条从未退场的记录不该产生任何新对象,
+ * 这条判据让"恢复"对活动记录是彻底的 no-op。
+ */
+export function stripSupersedeMarker(metadata) {
+    const base = metadata ?? {};
+    if (!(SUPERSEDE_METADATA_KEY in base))
+        return base;
+    const next = { ...base };
+    delete next[SUPERSEDE_METADATA_KEY];
+    return next;
+}
+/** 该记录是否处于**已退场**状态(读主表 `valid_to` 的语义封装)。 */
+export function isRetired(record) {
+    return record.validTo !== undefined || readSupersedeMarker(record.metadata) !== undefined;
+}

package/dist/tools/index.js

@@ -463,10 +463,18 @@ ruminate) {
     // memory_delete:显式"忘了 X"——按语义检索命中后删除(高权限门控)。
     ctx.tools.register(defineTool({
         name: 'memory_delete',
-        description: '删除与查询相关的记忆(L1)。仅当用户显式要求"忘记/删除某条记忆"时用;需高权限模式开启。按语义检索命中后删除(最多若干条),无法精确匹配时返回 zero。',
+        description: '退场(软删)与查询相关的记忆(L1)。仅当用户显式要求"忘记/删除某条记忆"时用;需高权限模式开启。' +
+            '默认只退场**最贴近的 1 条**;可用 limit 放大(上限 10)。' +
+            '退场是**软删**:记录移出检索面但保留在主表,可在记忆列表恢复,不是物理删除。' +
+            '已知确切 record_id 时应走 ids 参数(精确退场,不做语义匹配)。',
         parameters: {
-            query: { type: 'string', required: true, description: '要删除的记忆描述(自然语言,匹配最贴近的现存记忆)' },
-            limit: { type: 'number', description: '最多删除条数(默认 3,上限 10)' },
+            query: { type: 'string', description: '要退场的记忆描述(自然语言,匹配最贴近的现存记忆);给出 ids 时可省略' },
+            ids: {
+                type: 'array',
+                items: { type: 'string' },
+                description: '确切的 record_id 列表(给了它就不做语义匹配,只退场这些 id;上限同 limit)',
+            },
+            limit: { type: 'number', description: '最多退场条数(默认 1,上限 10)' },
         },
         output: {
             schema: {
@@ -479,27 +487,48 @@ ruminate) {
                 additionalProperties: false,
             },
             render: (_args, value) => [
-                { type: 'text', text: value.notice ?? `已删除 ${value.deleted ?? 0} 条记忆` },
+                {
+                    type: 'text',
+                    text: value.notice ??
+                        `已退场(软删)${value.deleted ?? 0} 条记忆` +
+                            (value.ids && value.ids.length ? `:${value.ids.join('，')}` : '') +
+                            '——它们仍在主表,可在记忆列表恢复',
+                },
             ],
         },
         execute: async (args, exec) => {
             if (!live.get().memoryMutate)
                 return { deleted: 0, ids: [], notice: MUTATE_OFF_NOTICE };
-            const query = String(args.query ?? '').trim();
-            if (!query)
-                return { deleted: 0, ids: [], notice: 'query 为空,未删除' };
             const family = familyOfCaller(exec);
-            const limit = Math.min(Math.max(args.limit ?? 3, 1), 10);
-            const hits = await stores.l1.search(query, limit, {
-                family: family && family !== null ? family : undefined,
-                workspaceId: scopeFilterOf(cfg.scope, exec),
-            });
-            const ids = hits.map((h) => h.id);
+            // 默认 1(原为 3):"忘记某条记忆"是一对一的意图,而 limit=3 会顺带退场
+            // 两条语义邻近但无关的记忆 —— 实测已发生过一次真实误删。
+            const limit = Math.min(Math.max(args.limit ?? 1, 1), 10);
+            // 精确路径优先:给了 ids 就**不做语义匹配**。语义匹配的"顺带多删几条"
+            // 正是误删的来源,而调用方一旦能给出 id,就没有理由再走模糊匹配。
+            const explicit = Array.isArray(args.ids)
+                ? args.ids.filter((x) => typeof x === 'string' && x.trim() !== '').slice(0, limit)
+                : [];
+            let ids;
+            if (explicit.length > 0) {
+                ids = explicit;
+            }
+            else {
+                const query = String(args.query ?? '').trim();
+                if (!query)
+                    return { deleted: 0, ids: [], notice: 'query 与 ids 均为空,未删除' };
+                const hits = await stores.l1.search(query, limit, {
+                    family: family && family !== null ? family : undefined,
+                    workspaceId: scopeFilterOf(cfg.scope, exec),
+                });
+                ids = hits.map((h) => h.id);
+            }
             if (ids.length === 0)
                 return { deleted: 0, ids: [], notice: '未找到匹配的记忆,未删除' };
-            await stores.l1.deleteBatch(ids);
-            logger.info(`[memory] 高权限删除记忆 ${ids.length} 条(${ids.join('，')})`);
-            return { deleted: ids.length, ids };
+            // **软删**(退场),不是物理删除:与裁决 / 取代共用同一原语,故"删错了"
+            // 可以在记忆列表里恢复,而不必去 records/*.jsonl 事实源手工捞。
+            const n = stores.l1.retire(ids, { at: new Date().toISOString(), reason: 'manual' });
+            logger.info(`[memory] 高权限退场(软删)记忆 ${n} 条(${ids.join('，')})`);
+            return { deleted: n, ids };
         },
     }));
     // ── 图谱工具(读;受与 memory_search 同款的档位/注入拒读门 + 族过滤) ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-prime-memory",
-  "version": "0.14.0-beta.4",
+  "version": "0.14.0-beta.5",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public",