dsh-prime-memory 0.14.0-beta.6 → 0.14.0-beta.7

package/CHANGELOG.en.md

@@ -18,8 +18,19 @@ This file covers the **0.12.0** release notes and the current **unreleased** cha
   - New host API `MemoryDb.l0ByAnchor(sessionId, turn, step?)` fetches L0 messages **by coordinate** instead of by recency; this is the single read entry point for the upcoming evidence reader.
 - **The records panel now shows the source anchor** where it previously always showed a dash.
 
+- **Memory retirement (soft delete) and a real cleanup round-trip: deleting no longer means losing data.** "Delete" used to be a **physical** delete — a mistake could only be undone by hand from the `records/*.jsonl` fact source. Deletion now has two tiers, and **the reversible one is the default**.
+  - **Retirement (soft delete)**: the main-table row is kept, `valid_to` is closed, and a supersede marker is written (reserved `metadata` key `dsh_superseded`, carrying time / reason / verdict / conflict-pair id). Only the `l1_fts` and `l1_vec` rows are dropped. **The retrieval SQL is untouched** — zero query drift. All three retirement paths (conflict verdict / dedup supersede via `update`·`merge` / manual delete) **share one primitive**, so "delete" means the same thing everywhere.
+  - **Endpoints 33 → 38**: `records-retired` / `records-restore` / `cleanup-retired` / `snapshots-list` / `snapshot-restore`. Three lists (the `contract.ts` map, the `MEMORY_ENDPOINTS` allow-list in `stats.ts`, and the dispatcher `case` table) plus the endpoint-count assertion were updated together — missing any one makes an endpoint permanently 404 while the client `rpc` catch swallows the error silently and the whole panel block disappears.
+  - **`memory_delete` now retires 1 record by default** (was 3) and gained an exact `ids` path that skips semantic matching. The old semantic top-N batch delete **actually removed two unrelated real memories** during testing: precision has to come from exact ids, not from similarity.
+  - **Physical cleanup defaults to dry-run**: omitting `dryRun` means `true`. Even when explicitly executed it first writes a **full-library snapshot**, verifies it **by content hash**, and aborts with zero deletions on any mismatch. To make that impossible to bypass, `deleteL1Batch` was reduced to a **single caller** (`exportThenPurge`), pinned by a source-level guard test — "there is no physical-delete path that skips the export" is now a structural fact rather than a convention.
+  - **The return ticket was missing.** `restoreL1Snapshot` had **no production caller at all**, so "export before cleanup" was only half true: the export existed, the way back did not. `snapshots-list` / `snapshot-restore` now wire it up — snapshot **directory names only** (paths and `..` are rejected), dry-run by default, and `stillRetired` reported honestly. That field is not optional: cleanup only ever removes **already-retired** records and the snapshot is taken **before** deletion, so every record it can bring back carries a retirement marker. **Back in the main table ≠ back in recall**, and staying silent about it makes people believe recovery finished. Pass `unretire: true` for a genuine one-call rollback (it reuses the existing `restore`, no new write path).
+  - **Panel**: the records tab gained a collapsed "retired (recoverable)" section that only fetches when expanded, and delete confirmations now state that the action is reversible. **Physical cleanup deliberately has no panel entry** — irreversible actions stay on the RPC/model surface.
+- **§C conflict freeze: same-batch contradictions can now be frozen (fixing "the only thing the model ever says is exactly what gets rejected").** Investigation showed that `validateConflictPair`'s third condition required the other side to be a known record from the candidate pool — and **ids of memories created in the same batch are not in it** (they were just generated and are not stored yet). So the most typical "the machine cannot decide" case, two fresh contradictory memories in one batch, was **necessarily rejected and fell back to `store`** even when the model correctly emitted `conflict`. Evidence: the model emits it 7/7 at the model level, yet that hop never reached the database (`conflict_pending` has had 0 rows since the DB was created, and `conflict` receipts are 0 across `store 381 / merge 204 / update 172 / skip 7`). Fix: `validateConflictPair` takes an optional `batchIds` (omitted = previous behaviour) while still requiring exactly one side to be the current record, which keeps pairing unique; plus a queue-full guard so that **a loser belonging to the current batch is never auto-resolved** (otherwise freshly extracted output would be retired immediately with nobody informed) — it is simply not parked and stored as usual.
+
 ### Fixed
 
+- **The panel reported "conflict freeze is off" while the switch was clearly on.** The `conflicts` / `conflict-resolve` endpoints read the **static deployment config** `cfg.conflictFreeze.enabled`, whereas the panel writes the **live runtime setting**. The deployment default is always `false`, so with the switch on and `true` persisted to `settings.yaml` the page still said it was off. It now resolves through `effectiveCfg(cfg, live)`, the same resolution the dedup pipeline uses: there is exactly **one** source of truth, and the read and write sides must see the same state — otherwise you get "the list says it is on while the verdict says it is off".
+- **`dsh-memory/embedding-reindex` was declared but permanently 404.** The endpoint existed in the contract yet was missing from both the `MEMORY_ENDPOINTS` allow-list and the dispatcher `case` table, and `startReindex()` was **dead code** — which is why the settings "vector index" block only ever offered Cancel and never Start. Allow-list, `case`, and tests added.
 - **`UiRecord.sourceMessageIds` was a dead field.** It read a column `l1_records` never had, so it always resolved to `[]` and the panel's source row **never rendered**. Replaced by `sourceAnchors`, which reads real data.
 
 ## [0.12.0] — 2026-09-17

package/CHANGELOG.ja.md

@@ -20,8 +20,19 @@
   - ホスト側の新 API `MemoryDb.l0ByAnchor(sessionId, turn, step?)`：**座標で** L0 メッセージを取得します（時間順ではない）。今後の「証拠リーダー」の唯一の入口です。
 - **記録パネルがソースアンカーを表示**（従来は常に「-」でした）。
 
+- **記憶の退場（ソフト削除）とクリーンアップの往復：削除はデータ喪失ではなくなりました。** 従来の「削除」は**物理削除**で、誤削除は `records/*.jsonl` の事実源から手作業で拾い直すしかありませんでした。現在は二段階で、**可逆な側が既定**です。
+  - **退場（ソフト削除）**：主テーブルの行は残し、`valid_to` を閉じ、取代マーカー（`metadata` の予約キー `dsh_superseded`：時刻 / 理由 / 裁定結果 / 衝突ペア id）を書き込み、`l1_fts` と `l1_vec` の行だけを落とします。**検索側 SQL は一字も変えていません**（クエリのドリフトゼロ）。三つの退場経路（裁定敗北 / 重複排除による取代 `update`·`merge` / 手動削除）は**同一プリミティブを共有**します。
+  - **エンドポイント 33 → 38**：`records-retired` / `records-restore` / `cleanup-retired` / `snapshots-list` / `snapshot-restore`。三つの一覧（`contract.ts` のマップ / `stats.ts` の `MEMORY_ENDPOINTS` 許可リスト / ディスパッチャの `case`）と端点総数のアサーションを同時に更新——どれか一つでも漏れると端点は恒久的に 404 になり、クライアント `rpc` の catch が黙って握り潰しパネルが丸ごと消えます。
+  - **`memory_delete` の既定は 1 件のみ退場**（従来 3 件）。意味的マッチを行わない `ids` **厳密経路**を追加。旧実装の意味的 top-N 一括削除は、実測で**無関係な実記憶を 2 件誤削除**しました——「正確に消す」は類似度ではなく厳密 ID で担保すべきものです。
+  - **物理クリーンアップは既定でドライラン**（`dryRun` 省略 = `true`）。明示実行でも**全庫スナップショット**を先に書き、**内容ハッシュで検証**し、不一致なら中止して 1 件も削除しません。これを回避不能にするため `deleteL1Batch` を**単一の呼び出し元**（`exportThenPurge`）に収束させ、ソースレベルのガードテストで固定しました。
+  - **復路が欠けていました。** `restoreL1Snapshot` は**プロダクションからの呼び出しが皆無**で、「クリーンアップ前にエクスポート」は半分しか成立していませんでした（エクスポートは在るが戻り道が無い）。`snapshots-list` / `snapshot-restore` で接続：受け付けるのはスナップショットの**ディレクトリ名のみ**（パスと `..` は拒否）、既定はドライラン、`stillRetired` を正直に報告します。この項目は必須です——クリーンアップは**既に退場した**記録しか消さず、スナップショットは削除**前**に撮るため、戻せる記録はすべて退場マーカー付きです。**主テーブルに戻った ≠ 検索に戻った**。黙っていると「復元完了」と誤解されます。完全な一発ロールバックは `unretire: true`（既存の `restore` を再利用、新しい書き込み経路は作りません）。
+  - **パネル**：記録タブに「退場済み（復元可能）」区画を追加（既定は折り畳み、展開時のみ取得）。削除確認の文言は「復元可能」に変更。**物理クリーンアップは意図的にパネル入口を作りません**——不可逆操作は RPC / モデル側の出口だけに残します。
+- **§C 矛盾凍結：同一バッチ内の矛盾も凍結できるようになりました（「モデルが唯一言うことだけが必ず拒否される」の修正）。** 調査の結果、`validateConflictPair` の第③条件は「相手が候補プール内の既知レコードであること」を要求していましたが、**同一バッチで生成された新記憶の id はそこに含まれません**（まだ保存されていないため）。つまり最も典型的な「機械には判定できない」ケース（同一バッチの矛盾した二つの新記憶）は、モデルが正しく `conflict` を出しても**必ず不成対と判定され `store` にフォールバック**していました。証拠：モデル層では 7/7 で出力されるのに、その一歩は一度も DB に到達していません（`conflict_pending` は DB 作成以来 0 行、`l1_receipts` の `conflict` は `store 381 / merge 204 / update 172 / skip 7` の中で 0 件）。修正：`validateConflictPair` に任意の `batchIds` を追加（省略 = 従来動作）。ただし「必ず一方が本条の記録」は維持し、ペアが一意になるようにします。さらにキュー満杯ガードを追加し、**敗方が当バッチの新記憶である場合は自動了結しない**（抽出直後の産出が誰にも知られず即退場するのを避ける）ようにし、単に停放置せず通常どおり格納します。
+
 ### 修正
 
+- **スイッチは明らかに ON なのに、パネルは「矛盾凍結は未開啟」と表示していました。** `conflicts` / `conflict-resolve` 端点は**デプロイ時の静的設定** `cfg.conflictFreeze.enabled` を読んでいたのに対し、パネルは**実行時設定**（live）に書き込んでいました。デプロイ既定値は常に `false` のため、スイッチが ON で `settings.yaml` に `true` が保存されていても未開啟と表示されます。`effectiveCfg(cfg, live)` 経由に変更し、重複排除パイプラインと同じ解決に統一しました——真実の源は**一つ**であり、読み手と書き手が同じ状態を見る必要があります。
+- **`dsh-memory/embedding-reindex` は宣言されているのに恒久的に 404。** 契約には存在するものの `MEMORY_ENDPOINTS` 許可リストにもディスパッチャの `case` にも無く、`startReindex()` は**死んだコード**でした（設定の「ベクトル索引」ブロックに「開始」が無く「キャンセル」だけだった理由）。許可リスト + `case` + テストを追加。
 - **`UiRecord.sourceMessageIds` は死んだフィールドでした。** `l1_records` に**存在しない列**を読んでいたため常に `[]` になり、パネルの来源行は**一度も描画されていません**でした。実データを読む `sourceAnchors` に置き換えました。
 
 ## [0.12.0] — 2026-09-17

package/CHANGELOG.ko.md

@@ -20,8 +20,19 @@
   - 호스트 신규 API `MemoryDb.l0ByAnchor(sessionId, turn, step?)`: **좌표로**(시간순이 아니라) L0 메시지를 가져옵니다. 향후 "증거 리더"의 유일한 진입점입니다.
 - **기록 패널이 출처 앵커를 표시**합니다(이전에는 항상 "-"였습니다).
 
+- **기억 퇴장(소프트 삭제)과 정리 왕복: 삭제가 더 이상 데이터 손실이 아닙니다.** 기존의 "삭제"는 **물리 삭제**였고, 실수는 `records/*.jsonl` 사실 원본에서 손으로 건져내는 수밖에 없었습니다. 이제 두 단계이며 **되돌릴 수 있는 쪽이 기본**입니다.
+  - **퇴장(소프트 삭제)**: 메인 테이블 행은 유지하고 `valid_to`를 닫은 뒤 대체 마커(`metadata` 예약 키 `dsh_superseded`: 시각 / 사유 / 판정 결과 / 충돌 페어 id)를 기록하고, `l1_fts`와 `l1_vec` 행만 제거합니다. **검색 측 SQL은 한 글자도 바꾸지 않았습니다**(쿼리 드리프트 0). 세 가지 퇴장 경로(판정 패배 / 중복 제거 대체 `update`·`merge` / 수동 삭제)는 **동일한 프리미티브를 공유**합니다.
+  - **엔드포인트 33 → 38**: `records-retired` / `records-restore` / `cleanup-retired` / `snapshots-list` / `snapshot-restore`. 세 목록(`contract.ts` 맵 / `stats.ts`의 `MEMORY_ENDPOINTS` 허용 목록 / 디스패처 `case`)과 엔드포인트 총수 단언을 함께 갱신했습니다 — 하나라도 빠지면 해당 엔드포인트는 영구히 404가 되고, 클라이언트 `rpc`의 catch가 조용히 삼켜 패널 블록 전체가 사라집니다.
+  - **`memory_delete`의 기본은 1건만 퇴장**(기존 3건)이며, 의미 매칭을 건너뛰는 `ids` **정확 경로**를 추가했습니다. 기존 의미 기반 top-N 일괄 삭제는 실측에서 **무관한 실제 기억 2건을 잘못 삭제**했습니다 — "정확히 지우기"는 유사도가 아니라 정확한 ID로 보장해야 합니다.
+  - **물리 정리는 기본이 드라이런**(`dryRun` 생략 = `true`). 명시적으로 실행해도 먼저 **전체 라이브러리 스냅샷**을 쓰고 **내용 해시로 검증**하며, 불일치면 중단하고 한 건도 삭제하지 않습니다. 이를 우회 불가능하게 만들기 위해 `deleteL1Batch`를 **단일 호출자**(`exportThenPurge`)로 수렴시키고 소스 수준 가드 테스트로 고정했습니다.
+  - **복귀 경로가 없었습니다.** `restoreL1Snapshot`은 **프로덕션 호출자가 전혀 없어서** "정리 전에 내보내기"가 절반만 성립했습니다(내보내기는 있는데 돌아오는 길이 없음). `snapshots-list` / `snapshot-restore`로 연결했습니다: 스냅샷 **디렉터리 이름만** 받고(경로와 `..`는 거부), 기본은 드라이런이며 `stillRetired`를 정직하게 보고합니다. 이 필드는 필수입니다 — 정리는 **이미 퇴장한** 기록만 지우고 스냅샷은 삭제 **전**에 찍히므로, 되찾을 수 있는 모든 기록에 퇴장 마커가 붙어 있습니다. **메인 테이블로 돌아온 것 ≠ 검색으로 돌아온 것**이며, 이를 말하지 않으면 "복구 완료"로 오해합니다. 완전한 한 번의 롤백은 `unretire: true`(기존 `restore`를 재사용, 새 쓰기 경로 없음)입니다.
+  - **패널**: 기록 탭에 "퇴장됨(복구 가능)" 구획을 추가했습니다(기본 접힘, 펼칠 때만 조회). 삭제 확인 문구는 "복구 가능"으로 변경했습니다. **물리 정리는 의도적으로 패널 진입점을 만들지 않습니다** — 되돌릴 수 없는 동작은 RPC / 모델 표면에만 남깁니다.
+- **§C 모순 동결: 동일 배치 내 모순도 이제 동결할 수 있습니다("모델이 유일하게 하는 말이 정확히 거부되는" 문제 수정).** 조사 결과 `validateConflictPair`의 세 번째 조건은 "상대방이 후보 풀의 기존 기록일 것"을 요구했지만, **동일 배치에서 생성된 새 기억의 id는 거기에 없습니다**(아직 저장되지 않았기 때문). 즉 가장 전형적인 "기계가 판단할 수 없는" 상황(한 배치의 모순된 두 새 기억)은 모델이 `conflict`를 올바르게 내도 **반드시 페어가 아니라고 판정되어 `store`로 폴백**했습니다. 증거: 모델 층에서는 7/7로 출력되지만 그 단계는 DB에 한 번도 도달하지 않았습니다(`conflict_pending`은 DB 생성 이래 0행, `l1_receipts`의 `conflict`는 `store 381 / merge 204 / update 172 / skip 7` 중 0건). 수정: `validateConflictPair`에 선택적 `batchIds` 추가(생략 = 기존 동작). 단 "정확히 한쪽이 본 기록"은 유지해 페어가 유일하도록 합니다. 또한 큐 만원 가드를 추가해 **패배자가 이번 배치의 새 기억이면 자동 종결하지 않습니다**(방금 추출된 산출물이 아무에게도 알려지지 않고 즉시 퇴장하는 것을 방지) — 단순히 대기시키지 않고 정상 저장합니다.
+
 ### 수정
 
+- **스위치는 분명히 켜져 있는데 패널은 "모순 동결 미개방"이라고 표시했습니다.** `conflicts` / `conflict-resolve` 엔드포인트는 **배포 시점의 정적 설정** `cfg.conflictFreeze.enabled`를 읽었지만, 패널은 **런타임 설정**(live)에 기록했습니다. 배포 기본값은 항상 `false`이므로, 스위치가 켜지고 `settings.yaml`에 `true`가 저장되어도 미개방으로 표시됩니다. `effectiveCfg(cfg, live)` 경로로 변경해 중복 제거 파이프라인과 동일한 해석으로 통일했습니다 — 진실의 원천은 **하나**이며, 읽는 쪽과 쓰는 쪽이 같은 상태를 봐야 합니다.
+- **`dsh-memory/embedding-reindex`는 선언되었지만 영구히 404였습니다.** 계약에는 있으나 `MEMORY_ENDPOINTS` 허용 목록과 디스패처 `case` 양쪽에 없었고, `startReindex()`는 **죽은 코드**였습니다(설정의 "벡터 인덱스" 블록에 "시작"이 없고 "취소"만 있던 이유). 허용 목록 + `case` + 테스트를 추가했습니다.
 - **`UiRecord.sourceMessageIds`는 죽은 필드였습니다.** `l1_records`에 **존재하지 않는 컬럼**을 읽어 항상 `[]`가 되었고, 패널의 출처 행은 **한 번도 렌더링되지 않았습니다**. 실제 데이터를 읽는 `sourceAnchors`로 교체했습니다.
 
 ## [0.12.0] — 2026-09-17

package/CHANGELOG.md

@@ -22,8 +22,19 @@
   - **忠实投影**：不 `stripCodeBlocks`、不按长度截断、不做「值不值得记」筛选——**捕获可以为省 token 丢东西，取证不行**。唯一保留的过滤是「插件注入的上下文不算用户发言」。
   - **失败可分类**（这是本节的重点）：`no-service` / `no-anchor` / `session-unreadable` / `anchor-not-found` / `timeout` / `error`。前四类的区分是必需的——把「读不到」当成「没谈过」会让已归档会话的记忆被系统性误判。
 
+- **记忆退场（软删）与清理闭环：删除不再等于丢数据。** 此前"删除"是**物理删除**——一次误删只能去 `records/*.jsonl` 事实源里手工捞。现在删除分两档，**可逆的那档是默认**，不可逆的那档需要显式要求且自带导出物。
+  - **退场（软删）**：保留主表行 + 闭合 `valid_to` + 写取代标记（`metadata` 保留键 `dsh_superseded`，含时刻 / 原因 / 裁决结论 / 冲突对 id），只撤掉 `l1_fts` 与 `l1_vec` 行。**检索侧 SQL 一字未改**——不引入任何查询漂移。三条退场路径（裁决判负 / 去重取代 `update`·`merge` / 人工删除）**共用同一个原语**，否则迟早出现"某条路径还在硬删"的不一致语义，而那种不一致只在误删发生时才暴露。
+  - **端点 33 → 38**：`records-retired`（已退场列表）/ `records-restore`（找回）/ `cleanup-retired`（物理清理）/ `snapshots-list`（快照清单）/ `snapshot-restore`（从快照回灌）。三处清单（`contract.ts` 映射表 / `stats.ts` 的 `MEMORY_ENDPOINTS` 白名单 / 分发 `case`）与端点总数断言同步更新——少改任一处都会让端点恒返 404，而客户端 `rpc` 的 catch 会静默吞掉异常、面板整块消失。
+  - **`memory_delete` 默认只退场 1 条**（原为 3），并新增 `ids` **精确路径**（跳过语义匹配）。原实现用语义 top-N 批量删，实测**误删过两条无关的真实记忆**——"删得准"必须由精确 ID 保证，而不是靠相似度。
+  - **物理清理默认干跑**：省略 `dryRun` 即视为 `true`。即便显式执行，也先落**全库快照**并**按内容哈希**校验，不一致即中止且一条不删。为此把 `deleteL1Batch` 收敛到**唯一调用方**（`exportThenPurge`），并由源码守卫测试钉住——"没有绕过导出的物理删除路径"由此成为结构事实，而不是一句约定。
+  - **补上回程票**：`restoreL1Snapshot` 此前**只有测试在调用**，于是"先有导出物再清理"只成立了一半——导出物在、回灌出口不在，真出事只能人工解析 `l1-records.json`。现接上 `snapshots-list` / `snapshot-restore`：只收快照**目录名**（拒绝路径与 `..`）、默认干跑、并如实报出 `stillRetired`。这一条是必需的：清理只清理**已退场**记录，而快照拍在删除**之前**，所以找回的每一条都带退场标记——**写回主表 ≠ 回到召回**，不说明就会让人以为"恢复完了"。要一步完成真正的回滚用 `unretire: true`（复用既有 `restore`，不新开写路径）。
+  - **面板**：记录页新增「已退场（可恢复）」区（默认折叠、展开时才拉取，不让它拖慢正常浏览）；删除确认文案改为明确"可恢复"。**物理清理刻意不做面板入口**——不可逆动作只留 RPC / 模型出口。
+- **§C 矛盾冻结：同批次矛盾现在也能冻结（修掉"模型唯一会说的话恰好被拒收"）。** 取证发现 `validateConflictPair` 的第③条硬性要求"另一方必须是候选池里的已知记录"，而**同批次新记忆的 id 不在其中**（它们是本轮刚生成的、尚未入库）。于是"本轮两条新记忆互相矛盾"这种最典型的"机器判不了"情形，模型即便正确 emit 了 `conflict`，也**必然被判不成对而回落 `store`**。证据：模型层 7/7 会 emit，但那一跳从未落库（`conflict_pending` 建库以来 0 行、`l1_receipts` 里 `conflict` 凭证 0 条，而 `store 381 / merge 204 / update 172 / skip 7`）。修法：`validateConflictPair` 新增可选 `batchIds`（缺省 = 旧行为），仍要求"恰有一方是本条记忆"以保证配对唯一；并补队列满护栏——**败方属本轮新记忆时不做自动了结**，否则刚抽取的产出会立刻退场且没有任何人被告知，改为不停放、照常入库。
+
 ### 修复
 
+- **面板说"矛盾冻结未开启"，而开关明明是开的。** `conflicts` / `conflict-resolve` 端点读的是**部署静态配置** `cfg.conflictFreeze.enabled`，而面板写入的是**运行时设置**（live）。部署默认恒 `false`，于是开关已开、`settings.yaml` 已落 `true`，本页仍报未开启。改走 `effectiveCfg(cfg, live)`，与去重管线同一套解析——开关只有**一个**事实源，读端与写端必须看同一份状态，否则会出现"列表说开着、裁决说没开"的自相矛盾。
+- **`dsh-memory/embedding-reindex` 声明了却恒返 404。** 端点写在契约里，但既缺席 `MEMORY_ENDPOINTS` 白名单、也没有分发 `case`；同时 `startReindex()` 是**死代码**，设置页「向量索引」区块因此只有"取消"没有"开始"。补白名单 + `case` + 用例。
 - **`UiRecord.sourceMessageIds` 是死字段。** 它读的是 `l1_records` **从不存在的列**，永远回退 `[]`，于是记录面板的来源行**从未渲染过**。已替换为读真实数据的 `sourceAnchors`。
 
 ## [0.12.0] — 2026-09-17

package/README.en.md

@@ -473,6 +473,31 @@ dual-write storage architecture) are modeled after **MemoryCore** from
 [TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory).
 Thanks to the original project for open-sourcing its design and implementation.
 
+## Memory Retirement, Recovery, and Cleanup
+
+Deletion has **two tiers**, and the tier is chosen by cost: **the reversible one is the default**, while the irreversible one must be requested explicitly and always carries an export.
+
+| Action | Endpoint / tool | Reversible | Notes |
+| --- | --- | --- | --- |
+| Retire (soft delete) | `memory_delete` · `dsh-memory/records-delete` | ✅ | Keeps the main-table row, closes `valid_to`, writes a supersede marker, and drops only the FTS/vector rows. **Retires 1 record by default**; for batches pass exact `ids` rather than relying on semantic matching |
+| Recover | `dsh-memory/records-restore` | — | Clears the retirement marker and rebuilds indexes, returning the record to recall |
+| Physical cleanup | `dsh-memory/cleanup-retired` | ❌ | The plugin's **only irreversible** action. **Dry-run by default** (omitting `dryRun` deletes nothing); even when executed explicitly it first writes a full-library snapshot and verifies it **by content hash**, aborting with zero deletions on any mismatch |
+| List snapshots | `dsh-memory/snapshots-list` | — | Lists the snapshots under `snapshots/` that have a valid manifest, with reason and record counts |
+| Restore from snapshot | `dsh-memory/snapshot-restore` | — | Writes cleaned-up records back. **Dry-run by default**; accepts snapshot directory names only, never paths |
+
+All three retirement paths — conflict verdict, dedup supersede (`update`/`merge`), manual delete — **share one primitive**, so "delete" means the same thing in all of them: recoverable.
+
+### How the cleanup safety net is built
+
+Physical deletion must be preceded by a snapshot that passes verification (see the table above). The way back is:
+
+1. `dsh-memory/snapshots-list` — get the snapshot directory name (shaped like `l1-<timestamp>-<reason>`);
+2. `dsh-memory/snapshot-restore` — dry-run first to read `missing` (how many records would genuinely come back, not the snapshot's total), then write with an explicit `dryRun:false`.
+
+The restore entry point accepts **directory names only, never paths**: otherwise this RPC would incidentally gain the ability to read any directory and write its contents into the retrieval database. Restore itself is an idempotent upsert and can be re-run safely.
+
+> **One semantic you need to know**: `cleanup-retired` only removes **already-retired** records, and the snapshot is taken **before** deletion — so every record a cleanup snapshot can bring back carries a retirement marker. By default `snapshot-restore` only writes the row back to the main table (and reports it honestly in `stillRetired`); **"back in the main table" ≠ "back in recall"**. For a genuine one-call rollback add `unretire: true`, or call `records-restore` on that batch of ids afterwards.
+
 ## Roadmap
 
 Features under planning — feedback and priorities welcome in the

package/README.ja.md

@@ -294,6 +294,31 @@ dsh ホストはプラグインのログをコンソールへ出力します。
 - 想起注入点は `agent/pre-step`（メッセージ側合成メッセージ）＋ エージェント作用域 `systemPrompt.context`（ペルソナ/ナビ安定域）；
 - ストレージ/検索は公式 sqlite バックエンドの単機削ぎ版（マルチテナント分離列・TCVDB クラウドバックエンド・監査表を削除；トークン化は公式同様 jieba を使用）。
 
+## 記憶の退場・復元・クリーンアップ
+
+削除は**二段階**で、段階はコストで決まります：**可逆な側が既定**、不可逆な側は明示的に要求する必要があり、常にエクスポートを伴います。
+
+| 操作 | 端点 / ツール | 可逆 | 説明 |
+| --- | --- | --- | --- |
+| 退場（ソフト削除） | `memory_delete` · `dsh-memory/records-delete` | ✅ | 主テーブルの行を残し `valid_to` を閉じ、取代マーカーを書き、FTS/ベクトル行だけを落とします。**既定は 1 件のみ退場**。一括は意味的マッチではなく厳密な `ids` を渡してください |
+| 復元 | `dsh-memory/records-restore` | — | 退場マーカーを消しインデックスを再構築して、想起対象に戻します |
+| 物理クリーンアップ | `dsh-memory/cleanup-retired` | ❌ | 本プラグインで**唯一不可逆**な操作。**既定はドライラン**（`dryRun` 省略なら何も削除しません）。明示実行でも先に全庫スナップショットを書き、**内容ハッシュで検証**し、不一致なら中止して 1 件も削除しません |
+| スナップショット一覧 | `dsh-memory/snapshots-list` | — | `snapshots/` 下で有効なマニフェストを持つスナップショットを、理由と件数つきで列挙 |
+| スナップショットから復元 | `dsh-memory/snapshot-restore` | — | クリーンアップ済みの記録を書き戻します。**既定はドライラン**。受け付けるのはディレクトリ名のみでパスは不可 |
+
+三つの退場経路——裁定敗北、重複排除による取代（`update`/`merge`）、手動削除——は**同一プリミティブを共有**するため、「削除」はどの経路でも同じ意味になります：復元可能です。
+
+### クリーンアップの「後悔薬」の構成
+
+物理削除の前には必ず検証を通過したスナップショットが必要です（上の表を参照）。戻る道は次のとおりです：
+
+1. `dsh-memory/snapshots-list` —— スナップショットのディレクトリ名（`l1-<タイムスタンプ>-<理由>` 形式）を取得；
+2. `dsh-memory/snapshot-restore` —— まずドライランで `missing`（スナップショット総数ではなく、実際に戻る件数）を確認し、明示的に `dryRun:false` で書き戻します。
+
+復元の入口は**ディレクトリ名のみを受け付け、パスは受け付けません**。そうでなければこの RPC が「任意のディレクトリを読んで内容を検索 DB に書き込む」能力を副次的に得てしまいます。復元自体は冪等な upsert で、安全に再実行できます。
+
+> **知っておくべき一つの意味論**：`cleanup-retired` は**既に退場した**記録しか消さず、スナップショットは削除**前**に撮られるため、クリーンアップのスナップショットで戻せる記録はすべて退場マーカー付きです。既定では `snapshot-restore` は行を主テーブルに書き戻すだけ（`stillRetired` で正直に報告）で、**「主テーブルに戻った」≠「想起に戻った」**。真の一発ロールバックには `unretire: true` を付けるか、後でその id 群に対して `records-restore` を呼んでください。
+
 ## ロードマップ
 
 [Issues](https://github.com/drscrewdriver/dsh-prime-memory/issues) で要望と優先度を募集中：

package/README.ko.md

@@ -294,6 +294,31 @@ dsh 호스트는 플러그인 로그를 콘솔로 출력합니다. 플러그인
 - 회상 주입점은 `agent/pre-step`（메시지 측 합성 메시지）＋ 에이전트 범위 `systemPrompt.context`（페르소나/내비 안정 영역）；
 - 저장/검색은 공식 sqlite 백엔드의 단기 슬림판（멀티테넌트 분리열·TCVDB 클라우드 백엔드·감사표 삭제；토큰화는 공식과 동일 jieba 사용）.
 
+## 기억 퇴장·복구·정리
+
+삭제는 **두 단계**이며 단계는 비용으로 정해집니다: **되돌릴 수 있는 쪽이 기본**이고, 되돌릴 수 없는 쪽은 명시적으로 요청해야 하며 항상 내보내기를 동반합니다.
+
+| 동작 | 엔드포인트 / 도구 | 되돌리기 | 설명 |
+| --- | --- | --- | --- |
+| 퇴장(소프트 삭제) | `memory_delete` · `dsh-memory/records-delete` | ✅ | 메인 테이블 행을 유지하고 `valid_to`를 닫으며 대체 마커를 쓰고 FTS/벡터 행만 제거합니다. **기본은 1건만 퇴장**. 일괄은 의미 매칭이 아니라 정확한 `ids`를 전달하세요 |
+| 복구 | `dsh-memory/records-restore` | — | 퇴장 마커를 지우고 인덱스를 재구축해 회상 대상으로 되돌립니다 |
+| 물리 정리 | `dsh-memory/cleanup-retired` | ❌ | 이 플러그인의 **유일한 비가역** 동작. **기본은 드라이런**(`dryRun` 생략 시 아무것도 삭제하지 않음). 명시 실행이라도 먼저 전체 라이브러리 스냅샷을 쓰고 **내용 해시로 검증**하며, 불일치면 중단하고 한 건도 삭제하지 않습니다 |
+| 스냅샷 목록 | `dsh-memory/snapshots-list` | — | `snapshots/` 아래에서 유효한 매니페스트를 가진 스냅샷을 사유와 건수와 함께 나열 |
+| 스냅샷에서 복원 | `dsh-memory/snapshot-restore` | — | 정리된 기록을 다시 씁니다. **기본은 드라이런**. 디렉터리 이름만 받고 경로는 받지 않습니다 |
+
+세 가지 퇴장 경로 — 판정 패배, 중복 제거 대체(`update`/`merge`), 수동 삭제 — 는 **동일한 프리미티브를 공유**하므로 "삭제"는 어느 경로에서나 같은 의미입니다: 복구 가능합니다.
+
+### 정리의 "되돌리기 수단" 구성
+
+물리 삭제 전에는 반드시 검증을 통과한 스냅샷이 있어야 합니다(위 표 참조). 돌아가는 길은 다음과 같습니다:
+
+1. `dsh-memory/snapshots-list` —— 스냅샷 디렉터리 이름(`l1-<타임스탬프>-<사유>` 형식)을 얻습니다;
+2. `dsh-memory/snapshot-restore` —— 먼저 드라이런으로 `missing`(스냅샷 총수가 아니라 실제로 되돌아오는 건수)을 확인하고, 명시적으로 `dryRun:false`로 기록합니다.
+
+복원 진입점은 **디렉터리 이름만 받고 경로는 받지 않습니다**. 그렇지 않으면 이 RPC가 "임의 디렉터리를 읽어 내용을 검색 DB에 쓰는" 능력을 부수적으로 얻게 됩니다. 복원 자체는 멱등 upsert이므로 안전하게 재실행할 수 있습니다.
+
+> **반드시 알아야 할 의미론 하나**: `cleanup-retired`는 **이미 퇴장한** 기록만 지우고 스냅샷은 삭제 **전**에 찍히므로, 정리 스냅샷으로 되찾을 수 있는 모든 기록에는 퇴장 마커가 붙어 있습니다. 기본적으로 `snapshot-restore`는 행을 메인 테이블로 되돌릴 뿐이며(`stillRetired`로 정직하게 보고), **"메인 테이블로 돌아옴" ≠ "회상으로 돌아옴"** 입니다. 진정한 한 번의 롤백에는 `unretire: true`를 붙이거나, 이후 해당 id들에 `records-restore`를 호출하세요.
+
 ## 로드맵
 
 [Issues](https://github.com/drscrewdriver/dsh-prime-memory/issues)에서 요구와 우선순위 환영：

package/README.md

@@ -410,6 +410,31 @@ fsync），断电等极端崩溃最多丢最后一小段尾部，检索库可用
   词元供 BM25 精确整词命中、二元组保子词召回；加载失败自动回退纯二元组，
   FTS 索引按分词器版本戳自动重建）。
 
+## 记忆退场、恢复与清理
+
+删除分**两档**，档位由代价决定：**可逆的那档是默认**，不可逆的那档需要显式要求，并且自带导出物。
+
+| 动作 | 端点 / 工具 | 可逆 | 说明 |
+| --- | --- | --- | --- |
+| 退场（软删） | `memory_delete` · `dsh-memory/records-delete` | ✅ | 保留主表行 + 闭合 `valid_to` + 写取代标记，只撤掉 FTS/向量行。**默认只退场 1 条**；批量请传精确 `ids`，不要依赖语义匹配 |
+| 找回 | `dsh-memory/records-restore` | — | 清退场标记 + 重建索引，记录重新进入召回 |
+| 物理清理 | `dsh-memory/cleanup-retired` | ❌ | 本插件**唯一不可逆**的动作。**默认干跑**（省略 `dryRun` 即不删）；即便显式执行，也先落全库快照并**按内容哈希**校验，不一致即中止且一条不删 |
+| 快照清单 | `dsh-memory/snapshots-list` | — | 列出 `snapshots/` 下带合法清单的快照（含原因与条数） |
+| 从快照回灌 | `dsh-memory/snapshot-restore` | — | 把已清理的记录写回。**默认干跑**；只收快照目录名，不接受路径 |
+
+三条退场路径——裁决判负、去重取代（`update`/`merge`）、人工删除——**共用同一个原语**，所以"删除"在三处语义一致：都可恢复。
+
+### 清理的"后悔药"是怎么构成的
+
+物理删除前必须先落快照并校验通过（见上表）。走回去的那条路是：
+
+1. `dsh-memory/snapshots-list` —— 拿到快照目录名（形如 `l1-<时间戳>-<原因>`）；
+2. `dsh-memory/snapshot-restore` —— 先干跑看 `missing`（真正被找回的条数，而不是快照总条数），再显式 `dryRun:false` 写回。
+
+恢复入口**只收目录名、不收路径**：否则这条 RPC 就等于顺带获得了"读任意目录并把内容写进检索库"的能力。恢复本身是幂等的 upsert，可安全重跑。
+
+> **一处必须知道的语义**：`cleanup-retired` 只清理**已退场**记录，而快照拍在删除**之前**——所以清理快照能找回的每一条都带着退场标记。默认情况下 `snapshot-restore` 只把行写回主表（并在 `stillRetired` 里如实报出），**"回到主表" ≠ "回到召回"**；要一步完成真正的回滚，加 `unretire: true`，或随后对该批 id 调 `records-restore`。
+
 ## 路线图
 
 以下为规划中的功能，欢迎在 [Issues](https://github.com/drscrewdriver/dsh-prime-memory/issues) 反馈需求与优先级：

package/dist/contract.d.ts

@@ -677,9 +677,90 @@ export interface CleanupRetiredResponse {
     aborted: boolean;
     /** 快照目录(真跑时非空)。 */
     dir: string;
+    /**
+     * 快照**目录名**(真跑时非空)。
+     *
+     * `dir` 是给人看的绝对路径;`name` 是给 `snapshot-restore` 用的**唯一寻址口径**
+     * ——恢复入口只收名字、不收路径(见 `isSnapshotName`)。没有它,调用方就得自己
+     * 从 `dir` 里切最后一段,还要同时兼容 `/` 与 `\` 两种分隔符。
+     */
+    name: string;
     /** 中止原因(仅 aborted 时非空)。 */
     diffs: string[];
 }
+/** dsh-memory/snapshots-list(可用快照清单;恢复前先看有哪些)。 */
+export interface SnapshotsListRequest {
+    /** 最多返回几份(1~200,默认 50)。 */
+    limit?: number;
+}
+/** 一份快照的摘要(与 `l1-snapshot.SnapshotSummary` 同形)。 */
+export interface SnapshotSummaryView {
+    /** 目录名——恢复时传它。 */
+    name: string;
+    /** 绝对路径(给人看/给运维定位)。 */
+    dir: string;
+    createdAt: string;
+    /** 建它的原因(如 `cleanup-retired` / `pre-rebuild`)。 */
+    reason: string;
+    /** `l1_records` 条数。 */
+    records: number;
+    receipts: number;
+    conflicts: number;
+    /** `l1_vec` 行数(派生投影,不落快照,只记数)。 */
+    vecCount: number;
+}
+export interface SnapshotsListResponse {
+    /** 按时间**倒序**(最新的在前)。 */
+    items: SnapshotSummaryView[];
+    total: number;
+}
+/**
+ * dsh-memory/snapshot-restore(从快照把已物理删除的记录灌回检索库)。
+ *
+ * **默认干跑**:`dryRun` 省略即视为 `true`。恢复本身是幂等的 upsert(不删任何东西),
+ * 但它是"把历史状态写回当前库",仍须调用方显式要求才做——与 `cleanup-retired` 同一条纪律。
+ */
+export interface SnapshotRestoreRequest {
+    /** 快照**目录名**(见 snapshots-list)。**不接受路径**。 */
+    name: string;
+    /** 只恢复这些 id(≤2000);省略 = 快照内全部。 */
+    ids?: string[];
+    /** 默认 true(干跑)。显式 false 才真正写库。 */
+    dryRun?: boolean;
+    /**
+     * 顺手把带回的记录**放回检索面**(清退场标记 + 重建索引)。默认 `false`。
+     *
+     * 为什么默认关:`cleanup-retired` 只清理**已退场**记录,快照又拍在删除**之前**
+     * ——所以清理快照找回的每一条都带退场标记,只回主表、不回召回。默认关 = 恢复
+     * 的是"当时的状态";要一步到位(真正的回滚)再显式打开。两种情形都会在
+     * `stillRetired` / `unretired` 里如实报出,不存在"悄悄复活"。
+     */
+    unretire?: boolean;
+}
+export interface SnapshotRestoreResponse {
+    name: string;
+    dir: string;
+    dryRun: boolean;
+    /** 快照里的记录总数(过滤前)。 */
+    inSnapshot: number;
+    /** 本次涉及(过滤后)的条数。 */
+    targets: number;
+    /** 其中当前**不在库**的条数——真正被找回的条数。 */
+    missing: number;
+    /** 实际写回条数(干跑恒为 0)。 */
+    restored: number;
+    failed: number;
+    /** 成功补回向量的条数(干跑恒为 0;嵌入不可用时可能为 0)。 */
+    vectorsWritten: number;
+    /** 本次顺手放回检索面的条数(仅 `unretire:true` 时可能非零)。 */
+    unretired: number;
+    /** 回到主表但**仍不在检索面**的 id(再调 `records-restore` 可放回)。 */
+    stillRetired: string[];
+    /** 请求了但该快照里没有的 id。 */
+    notFound: string[];
+    /** 提示(如名字非法/快照不存在,或"还有记录没回到检索面")。 */
+    notice?: string;
+}
 /** dsh-memory/graph-search(图谱节点检索;紧凑节点卡)。 */
 export interface GraphSearchRequest {
     /** 自然语言查询(≤4096 字符;空查询返回空)。 */
@@ -968,6 +1049,8 @@ export interface DshMemoryRequestMap {
     'dsh-memory/records-retired': RecordsRetiredRequest;
     'dsh-memory/records-restore': RecordsRestoreRequest;
     'dsh-memory/cleanup-retired': CleanupRetiredRequest;
+    'dsh-memory/snapshots-list': SnapshotsListRequest;
+    'dsh-memory/snapshot-restore': SnapshotRestoreRequest;
 }
 export interface DshMemoryResponseMap {
     'dsh-memory/stats': StatsResponse;
@@ -1006,6 +1089,8 @@ export interface DshMemoryResponseMap {
     'dsh-memory/records-retired': RecordsRetiredResponse;
     'dsh-memory/records-restore': RecordsRestoreResponse;
     'dsh-memory/cleanup-retired': CleanupRetiredResponse;
+    'dsh-memory/snapshots-list': SnapshotsListResponse;
+    'dsh-memory/snapshot-restore': SnapshotRestoreResponse;
 }
 /** 全部端点名(client 调用与 host case 表的共用字面量来源)。 */
 export type DshMemoryEndpoint = keyof DshMemoryResponseMap;

package/dist/stats.js

@@ -23,6 +23,7 @@ import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from './store/re
 import { resolveConflictPair, listConflictPairs } from './conflict-service.js';
 import { sourceAnchorLabels } from './pipeline/anchors.js';
 import { readSupersedeMarker } from './store/supersede.js';
+import { isSnapshotName } from './store/l1-snapshot.js';
 import { errDetail } from './util/filelog.js';
 import { snapshotTokenCost } from './token-cost.js';
 const require = createRequire(import.meta.url);
@@ -75,6 +76,8 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/records-retired',
     'dsh-memory/records-restore',
     'dsh-memory/cleanup-retired',
+    'dsh-memory/snapshots-list',
+    'dsh-memory/snapshot-restore',
 ];
 /** HTTP 路由前缀(客户端 fetch `/dsh-memory/rpc/<短方法名>`)。 */
 const RPC_ROUTE_PREFIX = '/dsh-memory/rpc';
@@ -845,12 +848,13 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     purged: 0,
                     aborted: false,
                     dir: '',
+                    name: '',
                     diffs: [],
                 };
                 return resp;
             }
             if (targets.length === 0) {
-                const resp = { dryRun: false, targets: 0, purged: 0, aborted: false, dir: '', diffs: [] };
+                const resp = { dryRun: false, targets: 0, purged: 0, aborted: false, dir: '', name: '', diffs: [] };
                 return resp;
             }
             const r = await stores.l1.purgeRetired(targets, 'cleanup-retired');
@@ -860,10 +864,106 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 purged: r.purged,
                 aborted: r.aborted,
                 dir: r.dir,
+                name: r.name,
                 diffs: r.diffs,
             };
             return resp;
         }
+        // ── 快照(清单 / 回灌):`cleanup-retired` 与「重建」的**回程票** ──
+        // 在此之前 `restoreL1Snapshot` 只有测试调用:导出物会落盘,却没有任何出口能
+        // 装回去 —— "清理是本插件唯一不可逆的动作"这句话因此只成立了一半。
+        // 读方向(列表)不开权限门(看得见才知道要不要恢复);回灌由 memoryMutate 门控。
+        case 'dsh-memory/snapshots-list': {
+            const p = (payload ?? {});
+            const raw = Math.floor(Number(p.limit));
+            const limit = Number.isFinite(raw) && raw > 0 ? Math.min(raw, 200) : 50;
+            const { items, total } = await stores.l1.listSnapshots({ limit });
+            const resp = { items, total };
+            return resp;
+        }
+        case 'dsh-memory/snapshot-restore': {
+            if (!live?.get().memoryMutate) {
+                throw new Error('记忆写删未开放:请在记忆库面板开启高权限模式');
+            }
+            const p = (payload ?? {});
+            const name = typeof p.name === 'string' ? p.name.trim() : '';
+            if (!name)
+                throw new Error('需要 name(快照目录名,见 dsh-memory/snapshots-list)');
+            // 只收名字、不收路径:恢复入口若接受任意路径,就等于顺带给这条 RPC 开放了
+            // "读任意目录并把内容写进检索库"的能力。非法名一律拒绝而不是静默返零。
+            if (!isSnapshotName(name)) {
+                throw new Error('name 非法:只接受快照目录名(形如 l1-<时间戳>-<原因>),不接受路径');
+            }
+            // **默认干跑**:省略 `dryRun` 即视为 true(与 cleanup-retired 同一条纪律)。
+            const dryRun = p.dryRun !== false;
+            const unretire = p.unretire === true;
+            const ids = (Array.isArray(p.ids) ? p.ids : [])
+                .filter((x) => typeof x === 'string' && x !== '')
+                .slice(0, 2000);
+            if (dryRun) {
+                const plan = await stores.l1.planSnapshotRestore(name, ids);
+                const resp = {
+                    name,
+                    dir: plan.dir,
+                    dryRun: true,
+                    inSnapshot: plan.inSnapshot,
+                    targets: plan.targets,
+                    missing: plan.missing,
+                    restored: 0,
+                    failed: 0,
+                    vectorsWritten: 0,
+                    unretired: 0,
+                    stillRetired: unretire ? [] : plan.stillRetired,
+                    notFound: plan.notFound,
+                    ...(plan.found ? {} : { notice: `找不到快照 ${name}:snapshots/ 下没有同名目录,或它的 manifest.json 缺失/版本不符` }),
+                };
+                return resp;
+            }
+            const r = await stores.l1.restoreFromSnapshot(name, { ids, unretire });
+            if (!r.found) {
+                const resp = {
+                    name,
+                    dir: '',
+                    dryRun: false,
+                    inSnapshot: 0,
+                    targets: 0,
+                    missing: 0,
+                    restored: 0,
+                    failed: 0,
+                    vectorsWritten: 0,
+                    unretired: 0,
+                    stillRetired: [],
+                    notFound: [],
+                    notice: `找不到快照 ${name}:snapshots/ 下没有同名目录,或它的 manifest.json 缺失/版本不符`,
+                };
+                return resp;
+            }
+            deps.logger.info(`[memory] 快照恢复 ${name}:写回 ${r.restored} 条(补向量 ${r.vectorsWritten} 条,失败 ${r.failed} 条,放回检索面 ${r.unretired} 条)`);
+            const resp = {
+                name,
+                dir: r.dir,
+                dryRun: false,
+                inSnapshot: r.inSnapshot,
+                targets: r.targets,
+                missing: r.missing,
+                restored: r.restored,
+                failed: r.failed,
+                vectorsWritten: r.vectorsWritten,
+                unretired: r.unretired,
+                stillRetired: r.stillRetired,
+                notFound: r.notFound,
+                // 写回主表 ≠ 回到检索面:清理快照里的记录都带退场标记,不明说会让人以为
+                // "恢复完了"而记忆其实仍不可见。这是本次接线最容易漏掉的一跳。
+                ...(r.stillRetired.length > 0
+                    ? {
+                        notice: `已写回主表,但其中 ${r.stillRetired.length} 条仍处于退场态、不会出现在召回里` +
+                            `(清理只清理已退场记录,快照拍在删除之前)。要放回检索面:` +
+                            `再调 dsh-memory/records-restore(或本次改用 unretire:true)。`,
+                    }
+                    : {}),
+            };
+            return resp;
+        }
         // ── 知识图谱(面板图谱视图;graph 未装配时返空不报错) ──
         case 'dsh-memory/graph-search': {
             const p = (payload ?? {});

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

@@ -23,6 +23,49 @@ export interface L1SnapshotManifest {
 export declare function snapshotDirName(createdAt: Date, reason: string): string;
 /** 快照目录的绝对路径(与既有 `pendingPathFor` / `reconcileStatePathFor` 同风格)。 */
 export declare function snapshotPathFor(dataDir: string, createdAt: Date, reason: string): string;
+/** 快照的**存放根**(所有 `snapshotPathFor` 产物都在它下面)。 */
+export declare function snapshotsRootFor(dataDir: string): string;
+/** 目录路径 → 目录名(与 `snapshotDirFor` 互为逆运算;兼容 `/` 与 `\`)。 */
+export declare function snapshotNameOf(dir: string): string;
+/**
+ * 目录名是否是可寻址的快照名。
+ *
+ * **只接受"名字",不接受路径**——这是恢复入口的第一道门。若允许调用方传路径,
+ * 恢复就变成了"把任意目录里的 JSON 灌进记忆库",而这条 RPC 的信任级别只到
+ * "本机同用户",不该顺带获得读任意目录并把内容写进检索库的能力。
+ * 故:长度受限、必须带 `l1-` 前缀(与 `snapshotDirName` 的产物一致)、
+ * 且不含路径分隔符与 `..`。
+ */
+export declare function isSnapshotName(name: string): boolean;
+/** 名字 → 绝对路径(仅当名字合法;否则返回 `undefined`,由调用方拒绝)。 */
+export declare function snapshotDirFor(dataDir: string, name: string): string | undefined;
+/** 一份可用快照的摘要(面板 / 工具选哪份来恢复)。 */
+export interface SnapshotSummary {
+    /** 目录名(恢复时传它,不传路径)。 */
+    name: string;
+    dir: string;
+    createdAt: string;
+    /** 建这份快照的原因(如 `cleanup-retired` / `pre-rebuild`)。 */
+    reason: string;
+    records: number;
+    receipts: number;
+    conflicts: number;
+    /** `l1_vec` 行数(派生投影,只记数)。 */
+    vecCount: number;
+}
+/**
+ * 列出可用快照(按时间**倒序**:最新的在前)。
+ *
+ * 只认**带合法清单**的目录:清单缺失或版本不符的目录不算快照(半截写入的产物
+ * 不能出现在"选一份来恢复"的列表里,否则人会选中一份根本恢复不了的东西)。
+ * 目录不存在**不抛**,返回空列表——"还没建过快照"是部署状态,不是调用错误。
+ */
+export declare function listSnapshots(dataDir: string, opts?: {
+    limit?: number;
+}): Promise<{
+    items: SnapshotSummary[];
+    total: number;
+}>;
 /** 稳定内容哈希(与 `canonicalRecords` 配套:同内容恒同哈希)。 */
 export declare function hashRecords(records: readonly MemoryRecord[]): string;
 /** 任意对象的内容哈希(用于 receipts / conflicts 这类外来形状)。 */
@@ -45,12 +88,14 @@ export interface SnapshotDbLike {
         limit?: number;
     }) => readonly unknown[];
     countL1Vec: () => number;
-    upsertL1: (record: MemoryRecord) => boolean;
+    upsertL1: (record: MemoryRecord, embedding?: Float32Array) => boolean;
 }
 /** 分页取全量 L1(一次 500,避免大库一次性拉爆内存)。 */
 export declare function listAllL1(db: SnapshotDbLike, hardLimit?: number): MemoryRecord[];
 export interface CreateSnapshotResult {
     dir: string;
+    /** 目录名——`snapshot-restore` 的寻址口径(调用方不必自己切路径)。 */
+    name: string;
     manifest: L1SnapshotManifest;
     records: readonly MemoryRecord[];
 }
@@ -75,20 +120,74 @@ export interface SnapshotVerification {
 /** 比对快照与当前库(**按内容哈希**,不是按行数)。 */
 export declare function verifySnapshot(db: SnapshotDbLike, dir: string): Promise<SnapshotVerification>;
 export interface RestoreResult {
+    /** 快照里的记录总数(按 `ids` 过滤**之前**)。 */
+    inSnapshot: number;
+    /** 本次实际要恢复的条数(过滤**之后**)。 */
+    targets: number;
     restored: number;
     failed: number;
+    /** 成功补上向量的条数(未提供 `vectorize` 时恒为 0)。 */
+    vectorsWritten: number;
+    /** 请求了但快照里没有的 id(仅传 `ids` 时可能非空)。 */
+    notFound: string[];
 }
+export interface RestoreOptions {
+    /** 日志出口(缺省静默)。 */
+    logger?: {
+        info: (m: string) => void;
+        warn: (m: string) => void;
+    };
+    /** 只恢复这些 id;省略 = 快照内全部。 */
+    ids?: readonly string[];
+    /**
+     * 可选向量补算钩子。
+     *
+     * 为何是**注入的函数**而不是直接 import 嵌入模块:快照模块刻意不依赖嵌入栈
+     * (见模块头——`l1_vec` 是派生投影,不落快照)。把向量能力做成参数,单向依赖
+     * 就保住了:快照模块提供"从 JSON 回到检索库"的事实,调用方提供"怎么算向量"。
+     * 实现方在嵌入不可用时应返回 `undefined` 而**不是抛**——见 `restore` 的同款理由。
+     */
+    vectorize?: (records: readonly MemoryRecord[]) => Promise<readonly (Float32Array | undefined)[]>;
+}
+/** 干跑结论:这份快照恢复下去**会发生什么**(不写库)。 */
+export interface SnapshotRestorePlan {
+    name: string;
+    /** 解析出的绝对路径;名字非法或清单缺失时为空串。 */
+    dir: string;
+    /** 这个名字是否指向一份**真实存在且清单合法**的快照。 */
+    found: boolean;
+    inSnapshot: number;
+    /** 本次实际要恢复的条数(按 `ids` 过滤后)。 */
+    targets: number;
+    /** 其中当前**不在库**的条数——这才是真正被找回的条数。 */
+    missing: number;
+    /**
+     * 目标里**仍处于退场态**的 id。
+     *
+     * 为什么这个字段是必需的:`cleanup-retired` 只清理**已退场**记录,而快照拍在删除
+     * **之前** ——所以清理快照能找回的每一条都带着退场标记。于是"回到主表"≠"回到
+     * 检索面":记录行在,但仍不出现在召回里,还要 `records-restore` 才放得回去。
+     * 不报这个,调用方会以为恢复完了、而记忆其实还是不可见的。
+     */
+    stillRetired: string[];
+    notFound: string[];
+}
+/** 按 id 过滤快照记录,并报出请求了却没找到的 id(人工恢复要能看到"没找到哪条")。 */
+export declare function selectSnapshotTargets(records: readonly MemoryRecord[], ids?: readonly string[]): {
+    targets: MemoryRecord[];
+    notFound: string[];
+};
 /**
  * 从快照恢复 L1。
  *
  * **幂等**:走 `upsertL1`(按 id upsert),恢复两遍与一遍等价,中断后重跑安全。
  * 只恢复 `l1_records`——receipts / conflicts 今天不被 `clearL1()` 销毁(见模块头),
  * 且它们的写入口不归本模块所有(单一所有者)。
+ *
+ * **向量一次算完再逐条写**:`vectorize` 收的是整批记录,而不是每条回调一次——
+ * 否则恢复 787 条就是 787 次嵌入往返。
  */
-export declare function restoreL1Snapshot(db: SnapshotDbLike, dir: string, logger?: {
-    info: (m: string) => void;
-    warn: (m: string) => void;
-}): Promise<RestoreResult>;
+export declare function restoreL1Snapshot(db: SnapshotDbLike, dir: string, opts?: RestoreOptions): Promise<RestoreResult>;
 /**
  * 清空前必须调用的守门函数:先建快照,再允许清空。
  *
@@ -108,6 +207,8 @@ export interface ExportThenPurgeResult {
     aborted: boolean;
     /** 快照目录(中止时也给,便于人工查看失败现场)。 */
     dir: string;
+    /** 快照**目录名**(供 `snapshot-restore` 直接寻址;中止且未建快照时为空串)。 */
+    name: string;
     purged: number;
     /** 校验差异(仅 aborted 时非空)。 */
     diffs: string[];

package/dist/store/l1-snapshot.js

@@ -33,6 +33,7 @@
  * 等于把证据链悄悄拆了。这条有专门用例。
  */
 import { createHash } from 'node:crypto';
+import { readdir } from 'node:fs/promises';
 import { atomicWriteJson, readJsonIfExists } from '../util/io.js';
 export const SNAPSHOT_VERSION = 1;
 /** 快照目录名:`l1-<时间戳>-<原因>`。**时间戳在前**,目录自然按时间排序。 */
@@ -45,6 +46,80 @@ export function snapshotDirName(createdAt, reason) {
 export function snapshotPathFor(dataDir, createdAt, reason) {
     return `${dataDir.replace(/[\\/]+$/, '')}/snapshots/${snapshotDirName(createdAt, reason)}`;
 }
+/** 快照的**存放根**(所有 `snapshotPathFor` 产物都在它下面)。 */
+export function snapshotsRootFor(dataDir) {
+    return `${dataDir.replace(/[\\/]+$/, '')}/snapshots`;
+}
+/** 目录路径 → 目录名(与 `snapshotDirFor` 互为逆运算;兼容 `/` 与 `\`)。 */
+export function snapshotNameOf(dir) {
+    return dir.replace(/[\\/]+$/, '').split(/[\\/]/).pop() ?? '';
+}
+/**
+ * 目录名是否是可寻址的快照名。
+ *
+ * **只接受"名字",不接受路径**——这是恢复入口的第一道门。若允许调用方传路径,
+ * 恢复就变成了"把任意目录里的 JSON 灌进记忆库",而这条 RPC 的信任级别只到
+ * "本机同用户",不该顺带获得读任意目录并把内容写进检索库的能力。
+ * 故:长度受限、必须带 `l1-` 前缀(与 `snapshotDirName` 的产物一致)、
+ * 且不含路径分隔符与 `..`。
+ */
+export function isSnapshotName(name) {
+    if (typeof name !== 'string')
+        return false;
+    const n = name.trim();
+    if (n.length === 0 || n.length > 200)
+        return false;
+    if (!n.startsWith('l1-'))
+        return false;
+    if (n.includes('/') || n.includes('\\') || n.includes('..'))
+        return false;
+    return true;
+}
+/** 名字 → 绝对路径(仅当名字合法;否则返回 `undefined`,由调用方拒绝)。 */
+export function snapshotDirFor(dataDir, name) {
+    return isSnapshotName(name) ? `${snapshotsRootFor(dataDir)}/${name.trim()}` : undefined;
+}
+/**
+ * 列出可用快照(按时间**倒序**:最新的在前)。
+ *
+ * 只认**带合法清单**的目录:清单缺失或版本不符的目录不算快照(半截写入的产物
+ * 不能出现在"选一份来恢复"的列表里,否则人会选中一份根本恢复不了的东西)。
+ * 目录不存在**不抛**,返回空列表——"还没建过快照"是部署状态,不是调用错误。
+ */
+export async function listSnapshots(dataDir, opts = {}) {
+    const root = snapshotsRootFor(dataDir);
+    let names;
+    try {
+        names = await readdir(root);
+    }
+    catch {
+        return { items: [], total: 0 };
+    }
+    // 目录名里时间戳在前(`l1-<时间戳>-<原因>`),故字典序倒序即时间倒序。
+    names.sort((a, b) => b.localeCompare(a));
+    const items = [];
+    for (const name of names) {
+        if (!isSnapshotName(name))
+            continue;
+        const dir = `${root}/${name}`;
+        const manifest = await readSnapshotManifest(dir);
+        if (manifest === undefined)
+            continue;
+        items.push({
+            name,
+            dir,
+            createdAt: manifest.createdAt,
+            reason: manifest.reason,
+            records: manifest.sections.records.count,
+            receipts: manifest.sections.receipts.count,
+            conflicts: manifest.sections.conflicts.count,
+            vecCount: manifest.vecCount,
+        });
+    }
+    const raw = Math.floor(Number(opts.limit));
+    const limit = Number.isFinite(raw) && raw > 0 ? raw : items.length;
+    return { items: items.slice(0, limit), total: items.length };
+}
 /** 记录数组的规范序列化:键序固定 + 按 id 排序,保证**同一内容恒得同一哈希**。 */
 function canonicalRecords(records) {
     return JSON.stringify(records
@@ -116,7 +191,7 @@ export async function createL1Snapshot(db, dir, reason, now = new Date()) {
     await atomicWriteJson(`${dir}/l1-receipts.json`, receipts);
     await atomicWriteJson(`${dir}/l1-conflicts.json`, conflicts);
     await atomicWriteJson(`${dir}/manifest.json`, manifest);
-    return { dir, manifest, records };
+    return { dir, name: snapshotNameOf(dir), manifest, records };
 }
 /** 读快照清单;不存在或版本不符返回 undefined。 */
 export async function readSnapshotManifest(dir) {
@@ -149,23 +224,54 @@ export async function verifySnapshot(db, dir) {
         diffs.push('conflict_pending 内容与快照不一致');
     return { ok: diffs.length === 0, diffs };
 }
+/** 按 id 过滤快照记录,并报出请求了却没找到的 id(人工恢复要能看到"没找到哪条")。 */
+export function selectSnapshotTargets(records, ids) {
+    if (!ids || ids.length === 0)
+        return { targets: [...records], notFound: [] };
+    const wanted = new Set(ids);
+    const targets = records.filter((r) => typeof r?.id === 'string' && wanted.has(r.id));
+    const found = new Set(targets.map((r) => r.id));
+    return { targets, notFound: [...wanted].filter((id) => !found.has(id)) };
+}
 /**
  * 从快照恢复 L1。
  *
  * **幂等**:走 `upsertL1`(按 id upsert),恢复两遍与一遍等价,中断后重跑安全。
  * 只恢复 `l1_records`——receipts / conflicts 今天不被 `clearL1()` 销毁(见模块头),
  * 且它们的写入口不归本模块所有(单一所有者)。
+ *
+ * **向量一次算完再逐条写**:`vectorize` 收的是整批记录,而不是每条回调一次——
+ * 否则恢复 787 条就是 787 次嵌入往返。
  */
-export async function restoreL1Snapshot(db, dir, logger) {
-    const records = await readSnapshotRecords(dir);
+export async function restoreL1Snapshot(db, dir, opts = {}) {
+    const { logger, ids, vectorize } = opts;
+    const all = await readSnapshotRecords(dir);
+    const { targets, notFound } = selectSnapshotTargets(all, ids);
+    let vectors = [];
+    if (vectorize && targets.length > 0) {
+        try {
+            vectors = await vectorize(targets);
+        }
+        catch (err) {
+            // 向量补算失败**不中止恢复**:记录先回到检索面(关键词仍可召回)比"一条都没恢复"
+            // 严重程度低得多。缺失的向量留给后续 `embedding-reindex`。
+            logger?.warn(`[memory] 快照恢复:向量补算失败,先回关键词检索面(日后重建可补齐): ${err instanceof Error ? err.message : String(err)}`);
+            vectors = [];
+        }
+    }
     let restored = 0;
     let failed = 0;
-    for (const record of records) {
+    let vectorsWritten = 0;
+    for (let i = 0; i < targets.length; i++) {
+        const record = targets[i];
         if (typeof record?.id !== 'string' || typeof record.content !== 'string') {
             failed += 1;
             continue;
         }
-        if (db.upsertL1(record))
+        const vec = vectors[i];
+        if (vec !== undefined)
+            vectorsWritten += 1;
+        if (db.upsertL1(record, vec))
             restored += 1;
         else
             failed += 1;
@@ -174,7 +280,7 @@ export async function restoreL1Snapshot(db, dir, logger) {
         logger?.warn(`[memory] 快照恢复:${restored} 条成功,${failed} 条失败`);
     else
         logger?.info(`[memory] 快照恢复:${restored} 条`);
-    return { restored, failed };
+    return { inSnapshot: all.length, targets: targets.length, restored, failed, vectorsWritten, notFound };
 }
 /**
  * 清空前必须调用的守门函数:先建快照,再允许清空。
@@ -202,23 +308,25 @@ export async function snapshotBeforeClear(db, dataDir, reason, now = new Date())
  */
 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: [] };
+        return { ok: true, aborted: false, dir: '', name: '', purged: 0, diffs: [] };
     let dir = '';
+    let name = '';
     try {
         const snap = await snapshotBeforeClear(db, dataDir, reason, now);
         dir = snap.dir;
+        name = snap.name;
     }
     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}`] };
+        return { ok: false, aborted: true, dir, name, 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 };
+        return { ok: false, aborted: true, dir, name, purged: 0, diffs: verdict.diffs };
     }
     const purged = db.deleteL1Batch([...ids]);
     logger?.info(`[memory] 已物理清理 ${purged} 条已退场记录(快照:${dir})`);
-    return { ok: true, aborted: false, dir, purged, diffs: [] };
+    return { ok: true, aborted: false, dir, name, purged, diffs: [] };
 }

package/dist/store/l1.d.ts

@@ -2,8 +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 SupersedeInfo } from './supersede.js';
+import { type ExportThenPurgeResult, type RestoreResult, type SnapshotRestorePlan, type SnapshotSummary } from './l1-snapshot.js';
 import { type EmbeddingService } from './embedding.js';
 import { type MemoryDb } from './sqlite.js';
 export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
@@ -30,9 +30,28 @@ export interface L1SearchOptions {
     /** 嵌入查询内层钳制(ms,只缩短不放大;召回路径传入给 FTS 降级留时间)。 */
     embeddingTimeoutMs?: number;
 }
+/** 快照回灌的结果(在 `RestoreResult` 之上补"从哪来"与"找回了多少")。 */
+export interface SnapshotRestoreOutcome extends RestoreResult {
+    /** 解析出的快照目录;名字非法或快照不存在时为空串。 */
+    dir: string;
+    /** 这个名字是否指向一份真实存在且清单合法的快照。 */
+    found: boolean;
+    /** 其中当前**不在库**、本次被找回的条数(写库前算出)。 */
+    missing: number;
+    /** 本次顺手放回检索面的条数(仅 `unretire: true` 时可能非零)。 */
+    unretired: number;
+    notFound: string[];
+    /**
+     * 回到主表但**仍未回到检索面**的 id(见 `SnapshotRestorePlan.stillRetired`)。
+     * `unretire: true` 且放回成功时为空数组。
+     */
+    stillRetired: string[];
+}
 export declare class L1Store {
     private readonly db;
     private readonly strategy;
+    /** 记忆库根目录(`records/` 与 `snapshots/` 都在它下面)。 */
+    private readonly dataDir;
     private readonly recordsDir;
     private readonly legacyFile;
     private readonly helper;
@@ -137,6 +156,44 @@ export declare class L1Store {
      * 这里只把 L1Store 已知的 dataDir 与 logger 接上去,避免端点层自己去推路径。
      */
     purgeRetired(ids: string[], reason: string): Promise<ExportThenPurgeResult>;
+    /** 可用快照列表(按时间倒序;面板/工具据此选一份来恢复)。 */
+    listSnapshots(opts?: {
+        limit?: number;
+    }): Promise<{
+        items: SnapshotSummary[];
+        total: number;
+    }>;
+    /**
+     * 名字 → 真实快照。
+     *
+     * 两道判定合一:名字合法(`snapshotDirFor`)且**清单存在且版本相符**
+     * (`readSnapshotManifest`)。只有前者会被"目录里有个同名空目录"骗过——
+     * 而那正是半截写入的产物,选中它恢复会得到 0 条却报成功。
+     */
+    private resolveSnapshot;
+    /**
+     * 干跑:算出"这份快照恢复下去会发生什么",**不写库**。
+     *
+     * `missing` 才是真正被找回的条数——快照里绝大多数记录今天仍在库里(快照是
+     * **全库**拷贝,而被清掉的只是其中几条)。只报 `targets` 会让人以为"要恢复 787 条",
+     * 从而不敢按下去。
+     */
+    planSnapshotRestore(name: string, ids?: readonly string[]): Promise<SnapshotRestorePlan>;
+    /**
+     * 从快照恢复(不可逆动作的**回程票**;本身幂等,可安全重跑)。
+     *
+     * 向量按整批补算(`helper.batch`),失败即降级成"暂时只走关键词召回"而不中止——
+     * 与 `restore` 同一条纪律:补不上向量是小事,让人以为记录丢了是大事。
+     *
+     * @param opts.unretire - 顺手把带退场标记的记录放回检索面(走既有 `restore`,
+     *   不新开写路径)。默认 `false`:只回主表,与"恢复的是当时的状态"一致。
+     */
+    restoreFromSnapshot(name: string, opts?: {
+        ids?: readonly string[];
+        unretire?: boolean;
+    }): Promise<SnapshotRestoreOutcome>;
+    /** 这批 id 里当前**在库**的集合(分块查,避免一次 IN 太多参数)。 */
+    private existingIds;
     /**
      * 三策略检索(自动召回与 memory_search 工具共用接缝)。
      * embedding 不可用时自动降级 keyword;type 后置过滤;

package/dist/store/l1.js

@@ -10,7 +10,8 @@ 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 { isRetired } from './supersede.js';
+import { exportThenPurge, readSnapshotManifest, readSnapshotRecords, restoreL1Snapshot, selectSnapshotTargets, snapshotDirFor, listSnapshots as listSnapshotsIn } 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';
@@ -20,6 +21,8 @@ const CANDIDATE_MULTIPLIER = 3;
 export class L1Store {
     db;
     strategy;
+    /** 记忆库根目录(`records/` 与 `snapshots/` 都在它下面)。 */
+    dataDir;
     recordsDir;
     legacyFile;
     helper;
@@ -36,6 +39,7 @@ export class L1Store {
     graphLane) {
         this.db = db;
         this.strategy = strategy;
+        this.dataDir = dataDir;
         this.recordsDir = path.join(dataDir, 'records');
         this.legacyFile = path.join(dataDir, 'l1', 'records.jsonl');
         this.embedSvc = embed;
@@ -242,7 +246,109 @@ export class L1Store {
         // 那等于给"先导出后清理"留了一条硬删后门。
         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);
+        return exportThenPurge(this.db, this.dataDir, retiredIds, reason, this.logger);
+    }
+    // ───────────────────────────────────────────────────────────────────────────
+    // 快照的**读与回灌**(task_27):`purgeRetired` 会先落快照,但只落不接等于
+    // 后悔药只做了一半——"清理不可逆"这句话必须配一条能走回去的路,否则
+    // `exportThenPurge` 的导出物就只是给人手工解析的 JSON。
+    //
+    // 恢复走 `restoreL1Snapshot`(本文件的 `restore` 管的是**软删**退场,
+    // 两者不是一件事:软删的行一直在主表里,快照恢复要管的是**已被物理删除**的行)。
+    // ───────────────────────────────────────────────────────────────────────────
+    /** 可用快照列表(按时间倒序;面板/工具据此选一份来恢复)。 */
+    listSnapshots(opts = {}) {
+        return listSnapshotsIn(this.dataDir, opts);
+    }
+    /**
+     * 名字 → 真实快照。
+     *
+     * 两道判定合一:名字合法(`snapshotDirFor`)且**清单存在且版本相符**
+     * (`readSnapshotManifest`)。只有前者会被"目录里有个同名空目录"骗过——
+     * 而那正是半截写入的产物,选中它恢复会得到 0 条却报成功。
+     */
+    async resolveSnapshot(name) {
+        const dir = snapshotDirFor(this.dataDir, name);
+        if (dir === undefined)
+            return undefined;
+        if ((await readSnapshotManifest(dir)) === undefined)
+            return undefined;
+        return { dir, records: await readSnapshotRecords(dir) };
+    }
+    /**
+     * 干跑:算出"这份快照恢复下去会发生什么",**不写库**。
+     *
+     * `missing` 才是真正被找回的条数——快照里绝大多数记录今天仍在库里(快照是
+     * **全库**拷贝,而被清掉的只是其中几条)。只报 `targets` 会让人以为"要恢复 787 条",
+     * 从而不敢按下去。
+     */
+    async planSnapshotRestore(name, ids) {
+        const resolved = await this.resolveSnapshot(name);
+        if (resolved === undefined) {
+            return { name, dir: '', found: false, inSnapshot: 0, targets: 0, missing: 0, stillRetired: [], notFound: [] };
+        }
+        const { targets, notFound } = selectSnapshotTargets(resolved.records, ids);
+        const targetIds = targets.filter((r) => typeof r?.id === 'string').map((r) => r.id);
+        const current = this.existingIds(targetIds);
+        return {
+            name,
+            dir: resolved.dir,
+            found: true,
+            inSnapshot: resolved.records.length,
+            targets: targets.length,
+            missing: targetIds.filter((id) => !current.has(id)).length,
+            // 目标里带退场标记的那些:它们即便回到主表也仍不在检索面(见字段说明)。
+            stillRetired: targets.filter((r) => isRetired(r)).map((r) => r.id),
+            notFound,
+        };
+    }
+    /**
+     * 从快照恢复(不可逆动作的**回程票**;本身幂等,可安全重跑)。
+     *
+     * 向量按整批补算(`helper.batch`),失败即降级成"暂时只走关键词召回"而不中止——
+     * 与 `restore` 同一条纪律:补不上向量是小事,让人以为记录丢了是大事。
+     *
+     * @param opts.unretire - 顺手把带退场标记的记录放回检索面(走既有 `restore`,
+     *   不新开写路径)。默认 `false`:只回主表,与"恢复的是当时的状态"一致。
+     */
+    async restoreFromSnapshot(name, opts = {}) {
+        const resolved = await this.resolveSnapshot(name);
+        if (resolved === undefined) {
+            return { dir: '', found: false, inSnapshot: 0, targets: 0, missing: 0, unretired: 0, stillRetired: [], restored: 0, failed: 0, vectorsWritten: 0, notFound: [] };
+        }
+        // `missing` 必须在写库**之前**算:写完再算恒为 0,那这个字段就废了。
+        const { targets } = selectSnapshotTargets(resolved.records, opts.ids);
+        const targetIds = targets.filter((r) => typeof r?.id === 'string').map((r) => r.id);
+        const current = this.existingIds(targetIds);
+        const missing = targetIds.filter((id) => !current.has(id)).length;
+        const retired = targets.filter((r) => isRetired(r)).map((r) => r.id);
+        const r = await restoreL1Snapshot(this.db, resolved.dir, {
+            logger: this.logger,
+            ids: opts.ids,
+            vectorize: async (records) => {
+                const vecs = await this.helper.batch(records.map((x) => x.content));
+                // 零向量 = "嵌入其实没算出来",按未补上计(与 `restore` 的判据一致)。
+                return vecs.map((v) => (v && !isZeroVector(v) ? v : undefined));
+            },
+        });
+        let unretired = 0;
+        let stillRetired = retired;
+        if (opts.unretire && retired.length > 0) {
+            // 复用已验收的 `restore`(清标记 + 重算向量 + 重建 FTS),不另开一条写路径。
+            const back = await this.restore(retired);
+            unretired = back.restored;
+            stillRetired = [];
+        }
+        return { ...r, dir: resolved.dir, found: true, missing, unretired, stillRetired };
+    }
+    /** 这批 id 里当前**在库**的集合(分块查,避免一次 IN 太多参数)。 */
+    existingIds(ids) {
+        const out = new Set();
+        for (let i = 0; i < ids.length; i += 400) {
+            for (const r of this.db.getL1ByIds(ids.slice(i, i + 400)))
+                out.add(r.id);
+        }
+        return out;
     }
     /**
      * 三策略检索(自动召回与 memory_search 工具共用接缝)。

package/package.json

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