sage-mem 2.4.1 → 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.1`** — 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.

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.1`** —— 顶部 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 是最直接的反馈。

package/lib/client.js

@@ -3164,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) {

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.1",
+  "version": "2.4.3",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",