sage-mem 2.4.0 → 2.4.3

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.4.0`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `2.4.3`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.
@@ -79,7 +79,7 @@ Most memory schemes take the "SQLite + a long-running worker" route: once memori
 | **Migration from Claude Code** | The persona (`CLAUDE.md` → `AGENTS.md`) is copied as-is; memories just need organizing into `.md` files under four types (see [the next section](#migrating-from-claude-code)) |
 | **Ships its own usage guide** | The package carries a skill (`skills/sage-mem/`): what a memory looks like, the four types, what not to store, the frontmatter pitfalls, how retrieval actually works, how to audit and fix a broken index. Installing the plugin is enough — the agent gets the instructions, no manual setup |
 
-The UI also carries four more capabilities (all of them optional): the memory management page, type and tag filtering, the memory star map, and audit & archiving.
+The UI also carries four more capabilities (all of them optional): the memory management page, type and tag filtering, the timeline (an entries list by default, with an optional star-map view), and audit & archiving.
 
 **Since 1.8.0, memory management is also reachable from the sidebar**: a 「记忆管理」(memory management) icon appears in the sidebar and switches the central panel to this page (with a "back to conversation" control at the top).
 It can be turned off in the settings page under 「记忆管理 → 自动做梦 → 设置」(on by default; applies immediately, no restart);
@@ -165,7 +165,7 @@ The state directory (configuration, ledger, rollback points, conflict queue) def
 
 Every image below is **rendered from the UI code in this repository** (the same CSS, the same component tree; the data is demo data for illustration, not a real memory directory).
 
-Since 1.9.0 the memory-management surface follows the harness language (**Settings → General → Language**); memory content itself stays in whatever language it was written in, 2.1.0 extends it to the **Autodream** (run / settings / records) and **Auto-archive** screens; the star map is the only panel still Chinese until the next i18n batch.
+Since 1.9.0 the memory-management surface follows the harness language (**Settings → General → Language**); memory content itself stays in whatever language it was written in, 2.1.0 extends it to the **Autodream** (run / settings / records) and **Auto-archive** screens; the timeline / star-map screen is the only panel still Chinese until the next i18n batch.
 
 ![File list: one Markdown file per memory, greyed rows are archived](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/files-list.png)
 
@@ -191,9 +191,13 @@ Since 1.9.0 the memory-management surface follows the harness language (**Settin
 
 *Archive candidates — each states "why archiving is suggested" (idle days vs the threshold for that type); files are touched only after you confirm one by one or select all. Archiving moves a file into `archive/`, it **does not delete**; to actually delete an archived entry, click 「彻底删除」(delete permanently) in the archive view and confirm once more.*
 
-![Memory star map: dark stars are archived memories](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/starmap-archive.png)
+![Timeline (default view): entries sorted newest-first](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/starmap-list.png)
 
-*Memory star map — colour maps to type, size to volume, brightness to freshness; dark stars are archived memories, and opening one shows the archive time and reason.*
+*Timeline — **this is what the tab opens on**: a list of entries sorted newest-first, most recently changed at the top. Want the picture? Switch to 「星空」(star map) in the top-right corner.*
+
+![Timeline · star-map view: dark stars are archived memories](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/starmap-archive.png)
+
+*After switching to the star-map view — colour maps to type, size to volume, brightness to freshness; dark stars are archived memories, and opening one shows the archive time and reason.*
 
 ![Autodream · settings](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/autodream-settings.png)
 
@@ -203,9 +207,9 @@ Since 1.9.0 the memory-management surface follows the harness language (**Settin
 
 *Auto-archive — it is not the same thing as autodream: archiving is a **deterministic rule** (computed from idle days in the access ledger, no model call), which is why it gets a page of its own. Thresholds take effect on save, no restart needed.*
 
-![Memory star map](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/starmap.png)
+![Timeline · star-map view](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/starmap.png)
 
-*Memory star map in full — the canvas draws only relations and distribution; the file name of a single memory appears only when you hover over or open that star. Rendering is redrawn on demand; no drawing is initiated while the view is static.*
+*The star-map view in full — the canvas draws only relations and distribution; the file name of a single memory appears only when you hover over or open that star. Rendering is redrawn on demand; no drawing is initiated while the view is static.*
 
 ## Memory File Format
 

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`2.4.0`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.4.3`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。
@@ -81,7 +81,7 @@ sage-mem 补上这一层，做法是：**把该记住的事写成一张张卡片
 | **从 Claude Code 迁移** | 人格（`CLAUDE.md` → `AGENTS.md`）照搬；记忆按四类整理成 `.md` 即可（见[下一节](#从-claude-code-迁移)） |
 | **自带使用指南** | 包内携带一份技能（`skills/sage-mem/`）：记忆长什么样、四类怎么分、什么不该存、frontmatter 的坑、检索怎么工作、索引坏了怎么修。装上插件就够了 —— Agent 拿到说明书，不需要手工配置 |
 
-界面上还有四块能力（都可以不用）：记忆管理页、类型与标签筛选、记忆星图、体检与归档。
+界面上还有四块能力（都可以不用）：记忆管理页、类型与标签筛选、时间线（默认是条目列表，可切星空视角）、体检与归档。
 
 **1.8.0 起，记忆管理还能从侧栏直接进**：侧栏多一个「记忆管理」图标，点它把中央主区切到本页（页顶有「返回会话」）。
 设置页「记忆管理 → 自动做梦 → 设置」里可以关掉这个入口（默认开，立即生效、不用重启）；
@@ -165,7 +165,7 @@ SAGE_MEM_DIR=/path/to/your/memory
 
 下面每张图都是**从仓库里的界面代码渲染出来的**（同一份 CSS、同一棵组件树；数据是演示用的假数据，不是真实记忆目录）。
 
-1.9.0 起，记忆管理这一块跟随宿主语言（**设置 → 通用 → 语言**）；记忆内容本身保持它被写下时的语言，2.1.0 起扩展到**自动做梦**（运行 / 设置 / 记录）与**自动归档**两屏；只剩记忆星图仍是中文，等下一批 i18n。
+1.9.0 起，记忆管理这一块跟随宿主语言（**设置 → 通用 → 语言**）；记忆内容本身保持它被写下时的语言，2.1.0 起扩展到**自动做梦**（运行 / 设置 / 记录）与**自动归档**两屏；只剩时间线/星图那一屏仍是中文，等下一批 i18n。
 
 ![文件列表：每条记忆一个 Markdown 文件，灰底的是已归档](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/files-list.png)
 
@@ -191,9 +191,13 @@ SAGE_MEM_DIR=/path/to/your/memory
 
 *归档候选 —— 每条写清「为什么建议归档」（闲置天数 vs 该类型阈值），逐条或全选后确认才动文件。归档是把文件移进 `archive/`，**不删除**；真要删掉一条归档件，得在档案馆里单独点「彻底删除」并再确认一次。*
 
-![记忆星图：暗星是已归档的记忆](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/starmap-archive.png)
+![时间线（默认视角）：按更新时间倒序的条目列表](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/starmap-list.png)
 
-*记忆星图 —— 颜色对应类型、大小对应体积、亮度对应新鲜度；暗星是已归档的记忆，点开可看归档时间与理由。*
+*时间线 —— **打开这个标签先看见的就是这一屏**：按更新时间倒序的条目列表，最近改过的在最上面。想看图，右上角「星空」自己切。*
+
+![时间线 · 星空视角：暗星是已归档的记忆](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/starmap-archive.png)
+
+*切到「星空」之后 —— 颜色对应类型、大小对应体积、亮度对应新鲜度，暗星是已归档的记忆，点开可看归档时间与理由。*
 
 ![自动做梦 · 设置](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/images/autodream-settings.png)
 
@@ -203,9 +207,9 @@ SAGE_MEM_DIR=/path/to/your/memory
 
 *自动归档 —— 它和自动做梦不是一件事：归档是**确定性规则**（按访问台账的闲置天数算，不调模型），所以单独一页。阈值保存即生效，不用重启。*
 
-![记忆星图](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/starmap.png)
+![时间线 · 星空视角](https://raw.githubusercontent.com/gezi-wen/sage-mem/main/docs/starmap.png)
 
-*记忆星图全貌 —— 画布上只画关系与分布；悬停或点开某颗星时才显示那一条的文件名。渲染是按需重绘，画面静止时不发起任何绘制。*
+*「星空」视角全貌 —— 画布上只画关系与分布；悬停或点开某颗星时才显示那一条的文件名。渲染是按需重绘，画面静止时不发起任何绘制。*
 
 ## 记忆文件格式
 

package/lib/client.js

@@ -1128,10 +1128,12 @@ const StarmapRuntime = (function (require, _react) {
 			const busyS = react.useState(false);
 			const busy = busyS[0];
 			const setBusy = busyS[1];
-			// 2.3.1：默认仍是「星空」—— 它是这个功能的招牌视觉（README 封面图），
-			// 而且改成 timeline 会让 8 条「画布真的画出来了 / 点得中暗星」的渲染断言失去
-			// 前提（那些只在空间视角成立）。变的是**按钮顺序**：时间线在前。
-			const viewS = react.useState("sky");
+			// 2.4.1：默认视角是**时间线**。产品要求「点开这个标签先看见按时间排的条目」——
+			// 星空是这个功能的可选视角，不是入口。原先默认星空，理由是它更适合当招牌视觉；
+			// 但一个叫「时间线」的标签第一屏却是一张星图，等于让人先猜这里是什么。
+			// 代价：8 条「画布真的画出来了 / 点得中暗星」的渲染断言失去前提，
+			// 所以 client-render-test 里补了一条切视角的入口（先点「星空」再断言）。
+			const viewS = react.useState("timeline");
 			const viewMode = viewS[0];
 			const setViewMode = viewS[1];
 			const emptySkyS = react.useState(false);
@@ -1623,15 +1625,16 @@ const StarmapRuntime = (function (require, _react) {
 			}
 
 			return h("div", { className: "smap-card" },
-				// 卡片里不再重复「记忆星图 / sage-mem memory」这一行 —— 标题已经在面板顶部
+				// 卡片里不再重复标题那一行 —— 标签本身叫「时间线」，标题已经在面板顶部
 				// 那条共用头部带里（「我在哪」），这里只留控件，少一行噪音。
 				h("div", { className: "smap-head" },
 					h("span", { className: "smap-spacer" }),
-					// 2.3.1：时间线在前（默认视角），星空在后 —— 与默认值一致，别让人点开
-					// 一个高亮的按钮发现它不在第一位。
+					// 2.4.1：内部视角按钮叫「列表 | 星空」—— 标签已经叫「时间线」，
+					// 里面再放一个「时间线」按钮就成了「时间线 ▸ 时间线 | 星空」，读起来像 bug。
+					// 「列表」也更准：它就是按更新时间倒序的条目列表。
 					h("span", { className: "smap-viewtoggle" },
-						h("button", { className: "smap-vt-btn" + (viewMode === "timeline" ? " on" : ""), onClick: () => setViewMode("timeline"), title: "时间视角：最近更新在前" }, "时间线"),
-						h("button", { className: "smap-vt-btn" + (viewMode === "sky" ? " on" : ""), onClick: () => setViewMode("sky"), title: "空间视角：星座分布" }, "星空")),
+						h("button", { className: "smap-vt-btn" + (viewMode === "timeline" ? " on" : ""), onClick: () => setViewMode("timeline"), title: "列表视角：最近更新在前" }, "列表"),
+						h("button", { className: "smap-vt-btn" + (viewMode === "sky" ? " on" : ""), onClick: () => setViewMode("sky"), title: "星空视角：星座分布" }, "星空")),
 					// 档案馆开关：默认开。关掉只是本地不再画暗星，不重新取数。
 					// 只留文字，不挂数字（计数归脚注的「档案馆 N 颗暗星」）；开/关靠 on 态
 					// 与 aria-pressed 的样式差，别让人猜现在是开还是关。
@@ -3161,6 +3164,9 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				if (!r) return "";
 				if (r.outcome === "injected") return "本步注入 " + (Array.isArray(r.injected) ? r.injected.length : 0) + " 条正文";
 				if (r.outcome === "card-only") return "正文没进，只发了状态卡";
+				// 2.4.3：短路闸门命中 —— 这一步**压根没算**。它的 outcome 也是 empty，
+				// 不单独说一句就会跟「算过了但没有可注入的内容」混成同一种读数。
+				if (r.gated) return "本步跳过：同题、同目录，未重算";
 				return r.deduped ? "同题已注入过，本步去重" : "本步没有可注入的内容";
 			}
 			function outcomeClass(r) {
@@ -3834,7 +3840,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			"sidebar.label": "记忆管理",
 
 			"tab.files": "文件列表",
-			"tab.star": "记忆星图",
+			"tab.star": "时间线",
 			"tab.autodream": "自动做梦",
 			"tab.archive": "自动归档",
 			"tab.audit": "体检",
@@ -4317,7 +4323,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			"sidebar.label": "Memory management",
 
 			"tab.files": "Files",
-			"tab.star": "Star map",
+			"tab.star": "Timeline",
 			"tab.autodream": "Autodream",
 			"tab.archive": "Auto-archive",
 			"tab.audit": "Audit",

package/lib/memory/conflicts.js

@@ -19,7 +19,7 @@
  */
 
 import { createHash } from 'node:crypto'
-import { mkdir, readdir, readFile, unlink } from 'node:fs/promises'
+import { mkdir, readdir, readFile, stat, unlink } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { STATE_ROOT } from './config.js'
 import { writeFileAtomic } from './util.js'
@@ -460,6 +460,41 @@ const INDEX_CACHE = new Map()
 /** 注入侧缓存有效期。改这里要同时想清楚「用户点完面板多久该见效」。 */
 export const CONFLICT_INDEX_TTL_MS = 1000
 
+/**
+ * 冲突队列的**廉价指纹**（目录里的文件名 + mtime 秒）。
+ *
+ * 注入链的短路闸门要判断「这一步的输入与上一步是否同一份」。记忆目录有 `namesKey`，
+ * 而冲突队列**不在记忆目录里** —— 用户在面板上裁决一条冲突，会改变「哪些记忆该被抑制」，
+ * 记忆目录却一个字节都没动。不把这一份算进指纹，裁决结果就要等下一轮提问才生效。
+ *
+ * 它与 `listConflictIndex` 的分工：那个要**读内容**（几十毫秒），这个只 `stat`
+ * （通常 0–2 个文件，微秒级）。闸门每一步都要判，只能用后者。
+ *
+ * @returns 读不到就返回 `null` —— 调用方据此**放弃短路**。把「看不见」当成「没变」，
+ *   会让一次读失败变成「这一步的记忆全部作废」。`ENOENT` 是「还没有任何冲突」，
+ *   是确定的事实，返回空串照常参与比较。
+ */
+export async function conflictsFingerprint(opts) {
+  const dir = conflictsDir(opts && typeof opts === 'object' ? opts.stateRoot : undefined)
+  let names
+  try {
+    names = await readdir(dir)
+  } catch (err) {
+    return err?.code === 'ENOENT' ? '' : null
+  }
+  const rows = []
+  for (const name of names.sort()) {
+    try {
+      const info = await stat(join(dir, name))
+      rows.push(`${name}@${Math.round(info.mtimeMs)}`)
+    } catch {
+      // 读得到名字、读不到属性（这期间被删或被换）：指纹里留一个「不知道」，下一步必然不等。
+      rows.push(`${name}@?`)
+    }
+  }
+  return rows.join(',')
+}
+
 /** 这组文件的**摘要索引**：不带两份正文，给注入链用。 */
 export async function listConflictIndex(opts) {
   const dir = conflictsDir(opts && typeof opts === 'object' ? opts.stateRoot : undefined)

package/lib/recall/injector.js

@@ -15,10 +15,10 @@
  *   2. 代次处理（`state.begin`）必须在算正文与控制提示**之前**，否则压缩后会拿上一代的账去判重（复审 R03）。
  */
 import { MAX_CHARS_PER_FILE, MAX_FILE_BYTES, MAX_RESULTS, MAX_SESSION_BYTES, MEMORY_DIR, RECALL_DISCIPLINE, STATE_ROOT, validityEnabled } from '../memory/config.js'
-import { listConflictIndex } from '../memory/conflicts.js'
+import { conflictsFingerprint, listConflictIndex } from '../memory/conflicts.js'
 import { buildContradictionFileSet, buildExpirySet } from '../memory/validity.js'
 import { extractText } from '../memory/retrieval.js'
-import { scanMemoryFiles } from '../memory/scan.js'
+import { scanMemoryFilesDetailed } from '../memory/scan.js'
 import { readCheckpoint } from '../memory/checkpoint.js'
 import { warnLog } from '../memory/util.js'
 import { selectRecall, dedupeByFile } from './select.js'
@@ -63,6 +63,43 @@ function validitySuppressedItems(items, conflictIds) {
   return out
 }
 
+/** 短路指纹：问题文本 + 目录名集合 + baseline 是否已发 + 冲突队列。四样都在判定前就拿得到。 */
+function gateFingerprint({ text, namesKey, baselineDone, conflicts }) {
+  return `${text}\u0000${namesKey ?? ''}\u0000${baselineDone ? 'b' : ''}\u0000${conflicts}`
+}
+
+/**
+ * 闸门命中时的调试账。
+ *
+ * 字段集与 `makeDebug()` 逐项一致（面板读的是同一份形状），数值全部来自
+ * 「这一步没有任何东西被重算」这个事实：没有候选、没有正文、没有卡。
+ * `gated: true` 把它与「算过了但没有东西可给」分开 —— 两者的 `outcome` 都是 `empty`，
+ * 不标出来，面板上就分不清「检索没命中」和「压根没检索」。
+ */
+function gatedDebugPayload({ nowMs, sessionId, text, scanned, st }) {
+  return {
+    at: nowMs,
+    sessionId,
+    query: typeof text === 'string' ? text.slice(0, 160) : '',
+    outcome: 'empty',
+    deduped: true,
+    gated: true,
+    baseline: 0,
+    scanned: Array.isArray(scanned?.files) ? scanned.files.length : 0,
+    hits: 0,
+    scores: [],
+    body: [],
+    picked: [],
+    injected: [],
+    chars: 0,
+    sessionChars: st.contentBytes,
+    cardChars: 0,
+    skippedByBudget: 0,
+    validitySuppressed: [],
+    card: st.cardSig ? 'deduped-or-over-budget' : 'none',
+  }
+}
+
 /**
  * @param {object} deps
  * @param {object} deps.ctx — 宿主 ctx（`scanMemoryFiles` / `warnLog` 用）
@@ -107,8 +144,6 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
       const userMessages = messages.filter(m => m?.role === 'user' && m?.source?.kind === 'user')
       const text = extractText(userMessages[userMessages.length - 1]?.content)
 
-      const files = await scanMemoryFiles(ctx, sessionId)
-
       // ── 代次：**先处理状态转换，再算正文与控制提示** ──
       // `begin()` 会把「这一次观测到的消息条数」立刻落进状态（Q08）——去重 / 零命中 /
       // 预算拒绝的轮次不会走到 commit，若不在这里落账，下一次 begin 就还拿旧基数比，
@@ -116,6 +151,38 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
       const ledgerKey = session.id || 'no-session-id'
       const st = state.begin(ledgerKey, messages.length)
 
+      // 扫描本身很便宜（命中缓存时只做一次 readdir 比文件名集合，1000 份实测 0.7 ms），
+      // 贵的是它后面的打分：逐份切段 + BM25。闸门因此放在扫描之后、检索之前。
+      const scanned = await scanMemoryFilesDetailed(ctx, sessionId)
+      const files = scanned.files
+
+      // ── 短路闸门（2.4.3）──
+      // 「问题没变、目录没变、baseline 该发的发了、冲突队列没动」同时成立时，这一步算出来的
+      // 候选必然与上一步逐条相同，`selectRecall` 的签名比对也必然判去重 —— 判据已经齐了，
+      // 就先判，把打分整段跳过。一个带 10 次工具调用的回合里，有 9 步走这条路。
+      //
+      // 三条不许短路的硬条件，缺一不可：
+      //   1. `scanned.cached === true` —— 这次是**缓存命中**，说明目录名集合没变、watcher 代次也没动
+      //      （代次是「只改内容、不改名」的唯一失效信号），正文与上一步逐字相同，指纹才可信。
+      //      `cached !== true` 说明这次是真扫了盘 —— 内容刚被改过，而指纹里只有文件名，判不出来；
+      //   2. `!st.generationChanged` —— 刚判出上下文被压缩，账本刚归零，必须重算；
+      //   3. `gate !== null` —— 冲突队列读不到（`conflictsFingerprint` 返回 null）时放弃，
+      //      宁可多算一遍，也不要把「看不见」当成「没变」。
+      const conflicts = await conflictsFingerprint({ stateRoot: STATE_ROOT })
+      const gate = conflicts === null
+        ? null
+        : gateFingerprint({ text, namesKey: scanned.namesKey, baselineDone: st.baselineDone, conflicts })
+      if (gate !== null && scanned.cached === true && !st.generationChanged && st.gate === gate) {
+        // 账照记：面板上「这一步为什么什么都没给」与「这一步根本不算」是两件事，
+        // 靠 `gated: true` 分开（两者的 outcome 都是 empty）。
+        if (debugEnabled()) {
+          const payload = gatedDebugPayload({ nowMs: Date.now(), sessionId, text, scanned, st })
+          debugRecall(payload)
+          recordInjection(payload)
+        }
+        return assembled
+      }
+
       const { picked, baselineTaken, relevant, intentInfo, bodyRanked, bestChunk, selected, signature, deduped } =
         selectRecall({ text, files, st })
 
@@ -261,6 +328,9 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
         gapCard: cardBody,
         messageCount: messages.length,
         baselineDone: st.baselineDone || baselineTaken > 0,
+        // 闸门与签名同一条纪律：**没投递出去就不前进**。上面任何一步空手而归都会提前
+        // return，走不到这里 —— 于是一次目录抖动不会把这一步的记忆关在门外。
+        gate,
       })
 
       emitDebug(makeDebug(parts.length > 0 ? 'injected' : 'card-only'))
@@ -280,12 +350,20 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
         },
       })
 
+      // ⚠️ `interpolate: false` 不是可选项，是**安全边界**（2026-11-07 真实事故）。
+      // 记忆正文是用户写的 Markdown，不是提示词模板。宿主默认会对每个 context 做
+      // `{{变量}}` 解析：正文里只要出现过一双大括号（`{{ }}`、`{{foo_bar}}`、`{{#if x}}`
+      // 都算），解析就在**模型还没开跑**时抛错，整轮对话直接失败，报错还是
+      // `malformed prompt variable reference … in context "sage-mem:recall"` ——
+      // 用户既不知道自己写了什么触发它，也改不动插件。关掉解析是这个问题的唯一解，
+      // 而正文本来就该逐字呈现（段落命中、行号、引用纪律全靠字面文本）。
       return {
         ...assembled,
         contexts: [...(assembled.contexts ?? []), {
           name: 'sage-mem:recall',
           order: 1000,
           text: recallText,
+          interpolate: false,
         }],
       }
     } catch (err) {

package/lib/recall/state.js

@@ -32,6 +32,11 @@ export function createSessionInjectState(maxSessions = 64) {
     lastObservedMessageCount: -1, // 上一次 assemble **观测到**的消息条数（压缩判据的唯一基点）
     messageCount: -1,     // 上一次**成功投递**时的消息条数（delivered 账，只有 commit 推进）
     baselineDone: false,  // 本代是否已经给过 baseline
+    // 2.4.3：上一次投递时的**短路指纹**（问题 + 目录名集合 + baseline 标记 + 冲突队列）。
+    // 与 `signature` 的区别是它**不依赖检索结果** —— 签名要先算完命中集才知道，而这个
+    // 只读现成的四样东西，所以能在打分之前判「这一步必然和上一步一样」。
+    // 同样只在 commit 前进：没投递出去的轮次不许把这个闸门关上。
+    gate: null,
   })
   return {
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "2.4.0",
+  "version": "2.4.3",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",