sage-mem 0.9.19 → 0.9.21

package/README.md

@@ -163,7 +163,7 @@ SAGE_MEM_DIR=/path/to/your/memory
 - **摘要没写到的，正文能找回来**。摘要是精准的一句话，代价是正文细节天生检索不到；摘要一条都没命中时改由正文检索兜底——此前这种情况直接等于「没有记忆可用」。正文检索只在问题**至少 4 个字符**时才跑：`继续` 这种两个字的问题拿去做正文匹配，命中的全是「继续」这个词本身
 - **换个说法也能命中**：打分是**词面重合**，不是语义的——问「我有什么待办」而文件里写的是「代办清单」，差一个字就完全不命中。给这类记忆加一行 `aliases: [待办, todo]` 就能补上
 - **注入的是命中段落，不是文件开头**。命中段落标成 `### 项目_部署.md:40-52`，agent 据此能直接跳到那几行核对来源；段落前补一句该记忆的 `description`，补回「这段是从哪条记忆切出来的」。`baseline` 与没命中正文的文件仍注入开头。单条正文超 1500 字符截断并标 `…（截断）`
-- **同一个问题不会重复注入**（按会话记签名），问第二遍不会又追加一遍
+- **相邻的重复问题不会重复注入**（按会话只留一个签名），连着问两遍不会又追加一遍。注意这**不是**「整个会话同题只给一次」：问 A → 问 B → 再问 A，第三次会重新注入 —— 再次要求回忆时重新给证据未必是坏事
 - **单场会话预算 60 KB，拆成两本账**（`MAX_SESSION_BYTES`）：**正文池** = 总上限 − **状态卡预留**（5%，夹在 1–4 KB）。总上限的数字没变，变的是到顶之后的行为 —— 旧行为是「正文装不下就一个字都不注，连为什么都没有」；现在是「正文照旧不注，但缺口状态卡发得出来，告诉你漏了什么、下一步怎么查」。**压缩或清空之后两本账与卡的去重签名一起归零**，又能注进来
 - **缺口状态卡只在真有缺口时说话**：有候选没读、或有候选被预算省略时才出现，说清范围、条数、最佳线索和**一个可做的动作**；一条都没命中时**只在你问自己的历史时**才说（否则提示会被当噪音忽略）。单张卡上限 512 字节，且按内容签名去重 —— 同一张卡不会每一步都追加一遍
 
@@ -208,8 +208,24 @@ SAGE_MEM_DIR=/path/to/your/memory
 
 **这张台账目前只用于诊断与自动归档阈值，不参与检索排序。** 观测有已知盲区：`pwsh` 里
 `cat 某记忆` 认不出来，那就不认 —— 我们不会把「看不到」说成「没读过」。
+
+### 两个写入者撞上时，不会互相覆盖
+
+记忆是**文件**，所以「你正在编辑」和「agent 正在改」完全可能同时发生。默认行为是**后写的赢、
+先写的悄悄消失** —— 那是最糟的一种，因为你不会发现。
+
+sage-mem 给记忆目录的写入加了**版本守卫**：写入前记下当前版本，写入时要求版本没变过。
+变了就**明确拒绝**，而不是盖掉。模型用内置 `write` / `edit` 改记忆时会自动带上这层守卫。
+
+**被拒的那次会落成一条待处理的记录**（`<状态根>/conflicts/<id>.json`），里面留着
+**盘上那一版**和**想要写的那一版** —— 因为只有一边等于没得判。
+
+- **冲突不会自动合并**，保留哪边由你决定。静默重试和静默放弃都是在替你决定。
+- 同一条冲突重复上报时 id 相同，队列里不会长出重复项。
+- 已知边界：**在 shell 里改记忆不走这条路**（`pwsh` 里 `cat > 某个记忆` 我们认不出来）。
+  写门守的是「经过工具的记忆写入」，不是「所有对文件的修改」。
 - **每条记忆的标题带新鲜度**：`（保存于 N 天前）`，**优先读 frontmatter 的 `updated:`，缺失才回落文件 mtime** —— 手写的时间戳是权威，文件系统时间会被复制 / 备份还原 / checkout 整批改掉。理由是陈旧记忆被当事实引用时，「引用」这个动作本身会让它显得更权威而不是更可疑，所以注入文本开头还带一节**引用纪律**（提到路径先确认存在、提到函数先 grep、要动手先核实）。它**独立成节**而不是一条 bullet：Claude Code 实测同一句话埋成 bullet 命中 0/3、独立成节 3/3
-- **`baseline: true` 的记忆每场会话第一步无条件注入**，最多 8 条——给「你是谁」「待办清单」这类每次开场都该在场的记忆用。多条 baseline 之间的先后由 `baselinePriority` 决定（数字越大越前，缺省 0），**不按文件名排**
+- **`baseline: true` 的记忆每场会话第一步无条件注入**，最多 8 条——给「你是谁」「待办清单」这类每次开场都该在场的记忆用。⚠️ **「不吃段落替换」不等于整份**：它同样受单文件长度上限（默认 1500 字符）截断，**关键内容若落在尾部会看不到** —— baseline 适合放短摘要，完整正文留给工具去读。多条 baseline 之间的先后由 `baselinePriority` 决定（数字越大越前，缺省 0），**不按文件名排**
 - 记忆目录读不到、权限错、frontmatter 格式坏，这些都**降级为不注入并写日志**，不会静默失效
 
 单文件上限 512 KB，**读写两侧都校验**（读的时候先看体积，超了就不读进来）；标签最多 20 个、每个 40 字符（再多就不是标签，是一句话被塞进 `tags` 了）。

package/lib/autodream-tools.js

@@ -32,6 +32,8 @@ import { archiveMemory } from './memory/archive.js'
 import { MAX_FILE_BYTES, STATE_ROOT } from './memory/config.js'
 import { writeFileAtomic, warnLog } from './memory/util.js'
 import { buildConflict, writeConflict } from './memory/conflicts.js'
+import { memoryPathOf } from './memory/paths.js'
+import { decideWriteIntent } from './memory/write-gate.js'
 import { inspectMemoryEntry, reservedIdentitySet } from './memory/scan.js'
 
 /** 单次 read_memory 返回的正文上限（字符）。超过就截断并明确告诉模型。 */
@@ -460,6 +462,71 @@ export function createToolRunner(opts) {
    * @param {'create'|'update'|'archive'} op
    * @param {'model'|'auto'} reasonSource — model = 模型自述；auto = 宿主追溯（模型没给）
    */
+  /**
+   * 「这份文件我们读到时是什么版本」——**按规范化路径**记，写的时候拿它当守卫。
+   *
+   * 为什么必须有这张表（外部复审 R01，P1 数据丢失）：守卫如果取**写的那一刻**的版本，
+   * 它只保护 `stat → writeText` 这一小段，而真实的危险窗口是 **`读 → 生成 → 写`** 整个周期。
+   * 复现：读 A → 人工改成 B → 自动整理基于 A 生成 C → 写时 stat 拿到 B → 守卫通过 → **B 被覆盖**。
+   * 单进程里顺序交错就能发生，不需要多进程竞争。
+   *
+   * 存的是**读到内容那一刻的版本**：C 是基于 A 生成的，就该拿 A 去比。
+   * 磁盘已经是 B 时，守卫会以 `FS_STALE_VERSION` 拒绝，内容不丢。
+   */
+  const readVersions = new Map()
+
+  /**
+   * 记下一次读取对应的版本。取不到可信版本就**什么都不记**（宁可让写入走「拒绝」，
+   * 也不要拿一个来路不明的版本假装有守卫）。
+   *
+   * 一致性：宿主 fs 可用时用 `stat → 读 → stat`，**两次版本相同**才认这份内容是那个版本的快照。
+   * 中间被人改过就不记 —— 分开读拿不到原子快照，那就诚实地说「不知道」。
+   */
+  async function rememberReadVersion(fullPath, content, truncated) {
+    try {
+      const fs = hostFs()
+      if (!fs || typeof fs.stat !== 'function') return
+      const target = await fs.resolve(fullPath)
+      const before = await fs.stat(target)
+      if (!before?.version) return
+      const after = await fs.stat(target)
+      if (!after?.version || after.version !== before.version) return
+      const where = memoryPathOf(fullPath, memoryDir)
+      if (where.ok) readVersions.set(where.canon, { version: before.version, truncated: truncated === true })
+    } catch { /* 记不下就不记：调用方会按「未知版本」处理 */ }
+  }
+
+  /**
+   * 取「这次写入该用哪个守卫」。
+   *
+   * 三种情形，**每一种都是有意的**：
+   *   - 文件不存在 → `createIfAbsent`（新建不可能覆盖谁）
+   *   - 文件存在 + 我们记过它被读到时是哪个版本 → `replaceIfVersion(那个版本)`
+   *   - 文件存在 + **没记过**（没读过 / 版本取不到 / 读的是截断内容）→ **不给守卫，由调用方拒绝**
+   *
+   * 第三种是 R01 的要害：以前这里退化成「用当前版本」，等于**替调用方担保了一份它没读过的内容**。
+   * 现在返回 `{refuse, why}`，让调用方把这次写入转成一条待人工处理的冲突，而不是盲写。
+   */
+  async function guardForWrite(fullPath) {
+    const fs = hostFs()
+    if (!fs || typeof fs.stat !== 'function') return { expected: undefined, known: false }
+    const target = await fs.resolve(fullPath)
+    let info
+    try {
+      info = await fs.stat(target)
+    } catch (err) {
+      // stat 抛错 = **不知道盘上是什么**。不知道就不写，而不是「不传守卫让宿主随便写」。
+      return { expected: undefined, known: false, refuse: true, why: `取不到当前版本（${err?.code ?? err?.message ?? err}），不能替你覆盖` }
+    }
+    // 「明确不存在」这一支仍走写门的判定表（`write-gate.js`）—— 能共用的就别写第二份。
+    if (!info) return { expected: decideWriteIntent({ memoryPath: memoryPathOf(fullPath, memoryDir), exists: false, version: null, caller: undefined }).intent, known: true }
+    const where = memoryPathOf(fullPath, memoryDir)
+    const seen = where.ok ? readVersions.get(where.canon) : undefined
+    if (!seen?.version) return { expected: undefined, known: false, refuse: true, why: '这份记忆我们没有读过（或版本取不到），不能替你覆盖它' }
+    if (seen.truncated) return { expected: undefined, known: false, refuse: true, why: '上次读到的是截断内容，不能拿它作为整份覆盖的依据' }
+    return { expected: { kind: 'replaceIfVersion', version: seen.version }, known: true }
+  }
+
   /**
    * 取宿主的 `fs` 服务，拿不到就返回 null。
    *
@@ -486,7 +553,7 @@ export function createToolRunner(opts) {
    * ⚠️ 这里**吞掉一切异常**：它发生在「写入已经失败」的路径上，再抛一次只会把真正的原因
    * （`FS_STALE_VERSION`）盖掉。留不下记录就只留日志，绝不改变向外抛的那个错误。
    */
-  async function recordStaleConflict(fullPath, incoming, err) {
+  async function recordStaleConflict(fullPath, incoming, err, kind = 'stale_version') {
     try {
       const fs = hostFs()
       let onDisk = null
@@ -495,7 +562,7 @@ export function createToolRunner(opts) {
         if (fs && typeof fs.readText === 'function') onDisk = await fs.readText(await fs.resolve(fullPath))
       } catch { /* 读不到就只留我们这一版：宁缺一半，也不要为它把冲突记录整条丢掉 */ }
       const record = buildConflict({
-        kind: 'stale_version',
+        kind,
         file: basename(fullPath),
         expectedVersion: 'unknown',   // 守卫是我们自己按 stat 到的版本构造的，这里拿不到那个字符串
         actualVersion: String(err?.code ?? ''),
@@ -534,8 +601,22 @@ export function createToolRunner(opts) {
       return null
     }
     const target = await fs.resolve(fullPath)
+    // ⚠️ **守卫必须由我们自己传。** `fs/write-intent` 只为「工具发起」的写入派发，
+    // 插件自己调 `writeText` 时一次都不发（实测）—— 不自己传，这次写入就是**无守卫**的。
+    //
+    // ⚠️⚠️ **而且必须是「读到内容那一刻」的版本，不是「现在」的版本。** 拿现在这个版本当守卫
+    // 只保护 `stat → writeText` 这一小段；真正的危险窗口是 `读 → 生成 → 写`。
+    // 外部复审 R01 就是这样复现出数据丢失的（读 A → 人工改 B → 基于 A 生成 C → 写时拿到 B 的版本
+    // → 守卫通过 → B 没了）。守卫的版本来自 `readVersions`，见 guardForWrite。
+    const guard = await guardForWrite(fullPath)
+    if (guard.refuse) {
+      // **不知道就不写。** 以前这条路会退化成「用当前版本当守卫」，等于替调用方担保一份它没读过的
+      // 内容 —— 那比「什么都不做」危险得多。转成一条待人工处理的冲突，让人来判。
+      await recordStaleConflict(fullPath, content, { code: 'UNVERIFIED_OVERWRITE', message: guard.why }, 'external_change')
+      throw Object.assign(new Error(guard.why), { code: 'SAGE_MEM_UNVERIFIED_OVERWRITE' })
+    }
     try {
-      return await fs.writeText(target, content)
+      return await fs.writeText(target, content, guard.expected)
     } catch (err) {
       // 版本过期不是「写失败」，是**一次待判定的冲突**：有人在我们读入之后改过这份记忆。
       // 落一条记录（保留哪边由人决定），然后**照旧把错误抛出去** ——
@@ -621,8 +702,12 @@ export function createToolRunner(opts) {
               throw err
             })
             if (content === null) return `错误：没有这个文件：${basename(full)}`
-            if (content.length > READ_LIMIT) {
-              return `${content.slice(0, READ_LIMIT)}\n\n…（已截断，全文 ${content.length} 字符）`
+            // 记下「这份内容对应磁盘上的哪个版本」——写回时用它当守卫（外部复审 R01）。
+            // 截断的读也要标出来：截断内容不足以作为整份覆盖的依据。
+            const truncated = content.length > READ_LIMIT
+            await rememberReadVersion(full, content, truncated)
+            if (truncated) {
+              return `${content.slice(0, READ_LIMIT)}\n\n…（已截断，全文 ${content.length} 字符。注意：截断的读不能作为整份覆盖的依据）`
             }
             return content
           }

package/lib/index.js

@@ -75,6 +75,59 @@ function dedupeByFile(hits) {
   return out
 }
 
+/**
+ * 会话级注入状态：**一处持有、一处提交**。
+ *
+ * 为什么必须集中：原先这是三个散落的容器（检索签名 `recallCache`、baseline 标记
+ * `baselineInjected`、注入账本 `injectLedger`），而代次变化本该让它们**同时**归零 ——
+ * 旧代码把重置写在去重**之后**，于是同一问题在压缩后仍被上一代的检索签名挡住，
+ * 记忆再也回不来（外部复审 R03）。集中之后，顺序是能被读出来的：
+ *
+ *     begin() 处理代次变化 → 调用方算正文与控制提示 → commit() 一次写回
+ *
+ * 为什么提交放最后：中途抛错时状态不该前进 —— 没注进去的东西不能记成「已注过」，
+ * 否则一次失败会把这条记忆永久挡在门外。唯一的例外是代次变化：那是**已经发生的事实**
+ * （上下文真的被压缩了），必须在算任何东西之前生效，否则这一步会拿着上一代的账做判断。
+ *
+ * ⚠️ 诚实边界：压缩信号是「消息条数下降」这条启发式，它**覆盖不了条数不降的压缩**
+ * （宿主原地改写历史，或截断后又在同一步补足条数）。那种情况下这里看不出代次变化，
+ * 记忆仍会被去重挡住。要真正解决得等宿主给出可比的上下文代次标识（目前没有）。
+ */
+function createSessionInjectState(maxSessions = 64) {
+  const sessions = new Map()
+  const fresh = () => ({
+    signature: null,      // 已注入过的检索签名（问题 + 命中文件集）
+    contentBytes: 0,      // 本代正文累计字节
+    cardBytes: 0,         // 本代状态卡累计字节（与正文分账，见 config.js）
+    cardSig: '',          // 本代已发过的那张卡（含检查点句柄的合成文本）
+    gapCard: '',          // 本代渲染过的缺口卡正文（签名没变时沿用，避免换个数字重发）
+    messageCount: -1,     // 上一次见效时的消息条数（压缩判据）
+    baselineDone: false,  // 本代是否已经给过 baseline
+  })
+  return {
+    /**
+     * 处理代次变化，取回本会话这一代的起点。**必须在算正文与控制提示之前调用。**
+     * 返回值是一份快照 —— 调用方只读，写回统一走 `commit()`。
+     */
+    begin(key, messageCount) {
+      const prev = sessions.get(key)
+      const generationChanged = !!prev && messageCount < prev.messageCount
+      // 条数下降 → 四样东西一起归零。少清任何一样都会留下一个「上一代的真相」：
+      // 字节账残留 → 新内容注不进来；baseline 残留 → 它再也不出现；
+      // 卡签名残留 → 恢复入口永久失效。
+      if (generationChanged) sessions.set(key, { ...fresh(), messageCount })
+      const cur = sessions.get(key) ?? fresh()
+      return { ...cur, generationChanged }
+    },
+    /** 一次写回。只防长驻进程无限增长：被挤掉的老会话下次醒来至多把同一批记忆再注一次。 */
+    commit(key, next) {
+      sessions.set(key, { ...next })
+      // FIFO 而不是 LRU：Map 重写已存在的键不会挪动位置，与旧行为一致。
+      if (sessions.size > maxSessions) sessions.delete(sessions.keys().next().value)
+    },
+  }
+}
+
 /**
  * 面板可改的 5 项注入上限 —— 与 `memory/config.js` 里的 `SAGE_MEM_*` 一一对应。
  * 边界值照抄那边的 envInt 调用（lo/hi 不许在这里另立一套）。
@@ -354,31 +407,17 @@ export class MemoryGateway extends TypertRemoteService {
       }
     } catch { /* 老宿主没有这两个事件：写入按宿主默认语义走 */ }
 
-    // 同一轮对话里问题不变、注入内容也不变，但 DSH 每一步都会往 session 追加
-    // 一条 context 消息——不去重的话同一份记忆会被反复追加，撑爆上下文。
-    const recallCache = new Map()
-
-    // 「本会话是否已注入过 baseline」——会话级状态，按 session id 记。
-    //
-    // 为什么不是消息条数：见下面 baseline 那段注释（恢复会话的历史消息早就在
-    // session 里，条数永不为 0）。会话 id 在整场会话里稳定，与 assemble 时
-    // 当前用户消息有没有落盘完全无关，所以新会话、恢复会话两种时序都成立。
-    // 容量 64 与 recallCache 同理，只防长驻进程无限增长：要挤掉一个 id 得先有
-    // 63 场别的会话开起来，那场老会话再被唤醒时最多是把同样的 baseline 再注入一次。
-    const BASELINE_CACHE_MAX = 64
-    const baselineInjected = new Set()
-
-    // 「本会话已经注入掉多少字节」—— 会话级账本，按 session id 记。
+    // 会话级注入状态（检索签名 / baseline 标记 / 两本账 / 卡签名）——
+    // 一处持有、一处提交，理由与顺序见 `createSessionInjectState` 的注释。
     //
-    // 为什么不扫会话记录去算：同一轮 assemble 出来的内容会被宿主合进**同一条**
-    // user/message（运行时上下文、工作区指令、插件注入共用一条），按消息字节统计
-    // 会把别人的内容算进本插件的账；按文本找标记又太脆。自己记账是确定性最高的。
+    // 为什么不扫会话记录去算「已经注掉多少字节」：同一轮 assemble 出来的内容会被宿主
+    // 合进**同一条** user/message（运行时上下文、工作区指令、插件注入共用一条），
+    // 按消息字节统计会把别人的内容算进本插件的账；按文本找标记又太脆。自己记账确定性最高。
     //
-    // 为什么要连 messageCount 一起记：压缩 / 清空之后上下文里的记忆已经没了，而
-    // session id 不变 —— 只按 id 记账会让「预算用满」变成永久状态，压缩之后再也
-    // 注不进来。消息条数变小是压缩发生过的最直接信号，用它把账本归零。
-    const INJECT_LEDGER_MAX = 64
-    const injectLedger = new Map()
+    // baseline 为什么按会话记而不是按消息条数：恢复会话的历史消息早就在 session 里，
+    // 条数永不为 0。会话 id 在整场会话里稳定，与 assemble 时当前用户消息有没有落盘无关，
+    // 所以新会话、恢复会话两种时序都成立。
+    const injectState = createSessionInjectState()
 
     // 按问题检索注入：system-prompt/assemble 是异步 waterfall，监听器可 await。
     // 从 agent.session 拿当前 user message，扫 memory 目录按摘要匹配选相关
@@ -410,6 +449,14 @@ export class MemoryGateway extends TypertRemoteService {
         const text = extractText(userMessages[userMessages.length - 1]?.content)
 
         const files = await scanMemoryFiles(ctx, sessionId)
+
+        // ── 代次：**先处理状态转换，再算正文与控制提示** ──
+        // 压缩 / 清空（消息条数下降）在这一行里就让签名、两本账、卡签名、baseline 标记
+        // 一起归零。放到后面（比如去重之后再算）就等于「拿上一代的账本判这一代」——
+        // 复审 R03 的「同题压缩后仍被挡住」正是这么来的。
+        const ledgerKey = session.id || 'no-session-id'
+        const st = injectState.begin(ledgerKey, messages.length)
+
         const picked = []
         const seen = new Set()
         const take = (f) => {
@@ -431,22 +478,17 @@ export class MemoryGateway extends TypertRemoteService {
         // 命中 → 永不注入。而「继续吧」这类短问题在 description 里找不到匹配、检索
         // 返回 0 条，baseline 恰恰是那时唯一的兜底。这是本会话级状态要修的东西。
         let baselineTaken = 0
-        const baselineKey = session.id ? session.id : session
-        if (!baselineInjected.has(baselineKey)) {
+        if (!st.baselineDone) {
           selectBaseline(files)
             .forEach(f => {
               const before = picked.length
               take(f)
               if (picked.length > before) baselineTaken++
             })
-          // 只有真取到才落标记：首步若正好撞上目录读不到（scanMemoryFiles 降级返回 []），
+          // 只有真取到才算「给过」：首步若正好撞上目录读不到（scanMemoryFiles 降级返回 []），
           // 整场会话就再也没机会补 baseline 了。宁可下一步重算一次。
-          if (baselineTaken > 0) {
-            baselineInjected.add(baselineKey)
-            if (baselineInjected.size > BASELINE_CACHE_MAX) {
-              baselineInjected.delete(baselineInjected.values().next().value)
-            }
-          }
+          // 标记本身随这一步一起在 commit() 落 —— 与「提交放最后」同一条理由：
+          // 没真注进去的东西不能记成「已经给过」。
         }
 
         // 检索签名只覆盖「检索出来的那批」，baseline 不再掺进这个签名。
@@ -505,16 +547,15 @@ export class MemoryGateway extends TypertRemoteService {
         }
 
         const signature = text + '\u0000' + selected.map(f => f.file).join(',')
-        if (recallCache.get(session.id) !== signature) {
-          recallCache.set(session.id, signature)
-          if (recallCache.size > 8) recallCache.delete(recallCache.keys().next().value)
-          selected.forEach(take)
-        }
+        // 检索签名没变 = 这一代里这条问题已经处理过 → 不再重复追加同一份记忆。
+        // ⚠️ 这个判断必须排在代次处理**之后**：压缩后的同题恢复，靠的就是上面 `begin()`
+        // 把签名一起清掉（复审 R03）。
+        const deduped = st.signature === signature
+        if (!deduped) selected.forEach(take)
 
-        if (picked.length === 0) {
-          if (DEBUG_RECALL) debugRecall({ scanned: files.length, hits: relevant.length, scores: [], picked: [], injected: [], chars: 0, skippedByBudget: 0 })
-          return assembled
-        }
+        // ⚠️ 这里**不能**再写「picked 为空就返回」：检查点句柄与未命中提示都不依赖候选，
+        // 提前返回会让它们在「目录为空」或「零命中」时永远不可达（复审 R02）。
+        // 统一的出口在下面 —— 只有**正文与控制提示都为空**才返回。
 
         // ── 单会话累计预算：**拆成两本账** ──
         //   正文池 = CONTENT_BUDGET（总上限 − 状态卡预留）／卡池 = STATUS_RESERVE
@@ -522,15 +563,10 @@ export class MemoryGateway extends TypertRemoteService {
         // 都没有；而那个上限是**本插件自己定的**，完全可以给状态卡留一份固定额度。
         // 账记在 session id 上；picked 里 baseline 永远排在检索结果之前，所以预算不够时
         // 先被挤掉的是「更晚才想起来的」那些 —— baseline 有优先权。
-        const ledgerKey = session.id || 'no-session-id'
-        const prevLedger = injectLedger.get(ledgerKey)
-        // 压缩 / 清空 → **两本账与卡签名一起归零**。卡签名必须一起清：不然「本会话已经发过
-        // 这张卡」仍然成立，而那张卡早已随旧上下文消失 —— 恢复入口就此永久失效。
-        // （「本会话注入过」不等于「压缩后还看得见」，这条是计划里点名要处理的。）
-        const carried = prevLedger && messages.length >= prevLedger.messageCount ? prevLedger : null
-        let contentBytes = carried?.contentBytes ?? 0
-        let cardBytes = carried?.cardBytes ?? 0
-        let cardSig = carried?.cardSig ?? ''
+        // 起点来自 `begin()`：它可能刚因压缩把两本账连同卡签名一起归零过。
+        let contentBytes = st.contentBytes
+        let cardBytes = st.cardBytes
+        let cardSig = st.cardSig
         const nowMs = Date.now()
 
         // ── 渲染候选，然后交给展示层决定「给正文 / 给指针 / 不给」──
@@ -634,19 +670,27 @@ export class MemoryGateway extends TypertRemoteService {
         } catch { /* 读不到检查点就当没有：它是可选的接力棒，不是必需件 */ }
 
         const wantCard = gapExists || intentInfo.historyDependent || !!checkpointLine
-        const cardBody = wantCard
-          ? renderStatusCard({
-              scope: bodySearched ? 'all' : 'summary',
-              scanned: files.length,
-              injected: parts.length,
-              omitted: skippedForBudget,
-              unread,
-              best: beacon ? { file: beacon.file, title: beacon.chunk?.title || beacon.chunk?.headingPath || '' } : null,
-              needle: text ? text.slice(0, 40) : null,
-              toolsAvailable: toolsReady,
-              memoryDir: MEMORY_DIR,
-            })
-          : ''
+        // 签名没变时沿用上一步渲染好的那份缺口卡，而不是重渲染一张。
+        // 两条理由：其一，那一步与这一步的检索面**逐字相同**，缺口也相同，重渲染只会把
+        // 同一件事换个数字再说一遍 —— 而局部变量算出来的数字还是错的（上一步注了 N 条，
+        // 这一步按本轮 parts 算是 0 条）；其二，文本一变 `cardSig` 去重就失效，同一张语义
+        // 的卡会被反复追加进会话。
+        // 检查点句柄不在此列：它是可能刚刚才出现的接力棒，所以始终参与合成。
+        const cardBody = !wantCard
+          ? ''
+          : deduped
+            ? st.gapCard
+            : renderStatusCard({
+                scope: bodySearched ? 'all' : 'summary',
+                scanned: files.length,
+                injected: parts.length,
+                omitted: skippedForBudget,
+                unread,
+                best: beacon ? { file: beacon.file, title: beacon.chunk?.title || beacon.chunk?.headingPath || '' } : null,
+                needle: text ? text.slice(0, 40) : null,
+                toolsAvailable: toolsReady,
+                memoryDir: MEMORY_DIR,
+              })
         // 句柄与卡**共用卡池**：它是同一个通道里的另一句提示，不该另开一份额度。
         const cardText = [cardBody, checkpointLine].filter(Boolean).join('\n')
         let cardPart = ''
@@ -674,10 +718,18 @@ export class MemoryGateway extends TypertRemoteService {
           return assembled
         }
 
-        injectLedger.set(ledgerKey, { contentBytes, cardBytes, cardSig, messageCount: messages.length })
-        if (injectLedger.size > INJECT_LEDGER_MAX) {
-          injectLedger.delete(injectLedger.keys().next().value)
-        }
+        // 状态一次写回：签名、两本账、卡签名、缺口卡、条数、baseline 标记。
+        // 放在这里（而不是更早）是刻意的 —— 上面每一步都可能没真注进去东西，
+        // 那就不该让状态前进；一次失败把一条记忆永久挡在门外是最难查的一种。
+        injectState.commit(ledgerKey, {
+          signature,
+          contentBytes,
+          cardBytes,
+          cardSig,
+          gapCard: cardBody,
+          messageCount: messages.length,
+          baselineDone: st.baselineDone || baselineTaken > 0,
+        })
 
         if (DEBUG_RECALL) {
           debugRecall({

package/lib/memory/scan.js

@@ -14,6 +14,7 @@ import { MAX_FILE_BYTES, MEMORY_DIR } from './config.js'
 import { parseBaseline, parseFrontmatter } from './frontmatter.js'
 import { isMemoryEntry, isReserved } from './naming.js'
 import { warnLog } from './util.js'
+import { createDirWatcher } from './watch.js'
 import { lstat, readFile, readdir } from 'node:fs/promises'
 import { join } from 'node:path'
 
@@ -235,12 +236,135 @@ export async function inspectDir(dir) {
   return { ok: true }
 }
 
-/** 扫 memory 目录，读回全部记忆文件（跳过索引与子目录），并解析 frontmatter 摘要。 */
+/**
+ * 进程内扫描缓存，**按目录分账**。
+ *
+ * 为什么按目录分：`scanMemoryFiles` 用的是模块级 `MEMORY_DIR`，但「扫一个目录」这件事本身
+ * 与目录无关（`scanMemoryDir` 允许显式给一个）。两个目录的失效信号、文件名集合、文件内容
+ * 都不该互相污染 —— 与 D18「台账跟着它依据的目录走」同一条道理。串了账的缓存比没有缓存
+ * 更危险：它会拿 A 目录的内容去回答关于 B 目录的问题。
+ *
+ * 每条：`{generation, watcher, entry}`
+ *   - `generation` —— watcher 送来的失效信号计数，只增不减。
+ *   - `watcher`    —— `createDirWatcher` 的句柄；**`ok === false` 时一律不缓存**。
+ *   - `entry`      —— `{generation, namesKey, files}`，命中要同时满足代次相同与文件名集合相同。
+ */
+const scanStates = new Map()
+
+/** 目录名集合的指纹：排序后拼接。新增 / 删除 / 重命名都会换指纹。 */
+function namesKeyOf(names) {
+  return [...names].sort().join('\n')
+}
+
+/** 取（必要时建）某个目录的缓存账与它的失效信号源。 */
+function scanStateOf(dir) {
+  let st = scanStates.get(dir)
+  if (!st) {
+    st = { generation: 0, watcher: null, entry: null }
+    scanStates.set(dir, st)
+  }
+  /**
+   * watcher 起不来时**每轮再试一次**，而不是永久禁用：记忆目录可能在插件加载时还不存在
+   * （首扫落空）、之后才被建出来，永久禁用会让这一整个进程都拿不到加速。失败一次的代价
+   * 只是一次系统调用级的失败（相对全量扫描可忽略）。
+   */
+  if (!st.watcher || !st.watcher.ok) {
+    if (st.watcher) st.watcher.dispose()
+    /**
+     * 换失效信号源时把缓存一起丢掉。旧 watcher 死掉（报错 / 洪流哨兵）这件事本身说明
+     * 「它最后一次送信号之后的这段时间里目录可能变过」，留着旧条目就是拿一段无据可依的
+     * 历史继续供内容。代价只是多一次全扫，而换 watcher 是罕见事件。
+     */
+    st.entry = null
+    // 失效信号只做一件事：代次 +1。去抖在 watcher 内部完成（首个事件立刻、窗口末尾再一次）。
+    st.watcher = createDirWatcher(dir, () => {
+      st.generation++
+    })
+  }
+  return st
+}
+
+/**
+ * 扫 memory 目录，读回全部记忆文件（跳过索引与子目录），并解析 frontmatter 摘要。
+ *
+ * A2 之后本函数**可能命中进程内缓存**：目录真的没变时，直接把上一次的结果还给你，
+ * 一份文件都不打开。失效判据与残余风险见 `scanMemoryDir`。
+ */
 export async function scanMemoryFiles(ctx, sessionId) {
+  return scanMemoryDir(ctx, sessionId, MEMORY_DIR)
+}
+
+/**
+ * 同 `scanMemoryFiles`，但目录可显式给（缓存按目录分账；测试用它证明两个目录不互相污染）。
+ *
+ * 失效判据**两层**，缺一不可：
+ *   1. **主判据 —— watcher 代次**：目录里发生过事件就重扫。它也是「只改内容、不改名」这类
+ *      变更**唯一**的失效来源 —— 文件名集合看不出内容变没变。
+ *   2. **兜底判据 —— 文件名集合**：每次仍做一次 `readdir`（1000 份实测 0.7 ms）比集合。
+ *      它防的是 watcher 最可能漏的那一类：**新增 / 删除 / 重命名**（漏事件时它仍然准确）。
+ *
+ * ⚠️ **残余风险（有意的取舍，不是疏忽）**：watcher 漏掉「只改内容、不改文件名」的事件时，
+ * 本进程会继续供旧内容，直到下一次任何失效。为什么接受：想独立复核内容变没变，只能逐份
+ * `lstat` 比 mtime，而那是这次要省掉的主要成本（1000 份实测 83 ms）—— 要复核就等于放弃加速。
+ * 后果是**一次注入拿到旧内容**，不是永久错误：文件一旦被增 / 删 / 改名，兜底判据立刻恢复正确，
+ * 下一次侥幸收到的事件也会。漏事件概率主要落在「外部程序原地覆写文件」这类姿势上：
+ * 插件自己的写入路径（设置页 / 工具）走的是原子写（临时名 + rename），必然触发事件。
+ *
+ * watcher 不可用（起不来 / 报错）时**一律全扫**，与加缓存之前逐字一致 —— 拿不到失效信号
+ * 就不许缓存，这是这条优化的安全底线。
+ */
+export async function scanMemoryDir(ctx, sessionId, dir = MEMORY_DIR) {
+  const st = scanStateOf(dir)
+  // ── 命中检查：代次 + 文件名集合，两道都对上才算「目录真的没变」──
+  if (st.watcher.ok && st.entry) {
+    const g0 = st.generation
+    if (st.entry.generation === g0) {
+      const names = await readdir(dir).catch(() => null)
+      /**
+       * 校验期间若又来了事件（代次变了）就当没命中。与落缓存时同一条理由：我无法证明
+       * 「刚读到的这份指纹」与「刚比过的那份缓存」描述的是同一瞬间的那个目录。
+       */
+      if (names && namesKeyOf(names) === st.entry.namesKey && st.generation === g0) {
+        // 还一个新数组：缓存是共享的，调用方就地排序 / splice 不该改到别人的那一份。
+        return st.entry.files.slice()
+      }
+    }
+  }
+  // ── 未命中：全扫（与加缓存之前逐字一致），只在「扫描期间没有任何变更」时才落缓存 ──
+  const gStart = st.generation
+  const scanned = await fullScanMemoryDir(ctx, sessionId, dir)
+  const gEnd = st.generation
+  st.entry = null
+  /**
+   * 连目录都列不出来（不存在 / 无权限）→ 这个失效信号源已经不可信，就地关掉。
+   * 为什么必须这么干：句柄在目录消失后会变成**空转的**（每秒十几万个 'change'，
+   * 且不发 'error'，见 watch.js 的洪流哨兵）—— 主动关掉比等哨兵兜底更早、也更直白。
+   * 关掉之后下一轮扫描会重新起表：目录回来了就继续用，回不来就是 fs.watch 抛错 → 全扫。
+   */
+  if (scanned.namesKey === null && st.watcher) {
+    st.watcher.dispose()
+    st.watcher = null
+  }
+  if (st.watcher && st.watcher.ok && scanned.namesKey !== null && gStart === gEnd) {
+    st.entry = { generation: gEnd, namesKey: scanned.namesKey, files: scanned.files }
+  }
+  // 也还新数组：上面刚把同一份引用存进了缓存，交出去就等于把缓存的所有权给了调用方。
+  return scanned.files.slice()
+}
+
+/**
+ * 真的走一遍磁盘。返回 `{files, namesKey}`。
+ *
+ * `namesKey === null` 表示目录根本没列出来（不存在 / 无权限）→ 这一轮**不落缓存**：
+ * 把一次失败当成「目录是空的」存下来，会让之后每一次读取都命中这份假结果。
+ */
+async function fullScanMemoryDir(ctx, sessionId, dir) {
   try {
-    const entries = await readdir(MEMORY_DIR, { withFileTypes: true })
+    const entries = await readdir(dir, { withFileTypes: true })
+    // 目录名集合的指纹：作为缓存的**兜底判据**（watcher 漏掉增 / 删 / 改名时的第二道闸）。
+    const namesKey = namesKeyOf(entries.map(e => e.name))
     /** 保留名的文件身份：8.3 短名与硬链接都得靠它才认得出（名字文本上它们毫无关系）。 */
-    const reservedIds = await reservedIdentitySet()
+    const reservedIds = await reservedIdentitySet(dir)
     /**
      * 链接条目在 `isFile()` 这一步就被滤掉了（`readdir` 的 Dirent 报的是链接本身），
      * 也就是说**闸门根本没机会看到它们** —— 不在这里出声，用户只会看到「这条记忆不见了」。
@@ -254,7 +378,7 @@ export async function scanMemoryFiles(ctx, sessionId) {
       .filter(e => e.isFile() && isMemoryEntry(e.name))
       .map(e => e.name)
     const loaded = await Promise.all(names.map(async (name) => {
-      const full = join(MEMORY_DIR, name)
+      const full = join(dir, name)
       // 先过闸门（lstat + 体积），再读：链接与超大文件都在**全量读之前**被挡下，
       // 而不是读进来之后才发现不该读。mtime 由闸门一并给出，比原来少一跳 stat。
       const gate = await inspectMemoryEntry(full)
@@ -295,10 +419,10 @@ export async function scanMemoryFiles(ctx, sessionId) {
         return null
       }
     }))
-    return loaded.filter(Boolean)
+    return { files: loaded.filter(Boolean), namesKey }
   } catch (err) {
-    if (err?.code !== 'ENOENT') warnLog(ctx, `cannot scan ${MEMORY_DIR}: ${err?.message ?? err}`, sessionId)
-    return []
+    if (err?.code !== 'ENOENT') warnLog(ctx, `cannot scan ${dir}: ${err?.message ?? err}`, sessionId)
+    return { files: [], namesKey: null }
   }
 }
 

package/lib/memory/watch.js

@@ -0,0 +1,171 @@
+/**
+ * sage-mem 记忆层 —— 目录监视（**只为缓存失效服务**，不承载任何业务语义）。
+ *
+ * 为什么需要它：记忆注入每走一步都要 `scanMemoryFiles` 全量列目录 + 逐份开文件读
+ * frontmatter，而成本几乎全在 `open` 这个系统调用上（1000 份合成记忆实测：只 `lstat`
+ * 不开文件 83 ms，`open`+`close` 只开不读 614 ms，`readFile` 全文 719 ms）。
+ * 也就是说「读的文件少一点」省不下来 —— 只有**不去打开没变过的文件**才省得下来。
+ *
+ * 那怎么知道「没变过」？本模块给出的信号是：**目录里发生过事件**。调用方（`scan.js`）
+ * 拿它当缓存的主判据，并且**只在 watcher 真的可用时才敢缓存** —— 拿不到信号就一律全扫，
+ * 与没有缓存时逐字一致。这是一条安全降级：性能优化不许以「看到的内容可能是旧的」为代价。
+ *
+ * ⚠️ 本模块的取舍（调用方必须知道的那条残余风险）：
+ * `fs.watch` 是**通知**机制，不是**保证**机制。平台、网络盘、编辑器写文件的姿势（先写临时
+ * 文件再 rename / 直接覆写 / 只在内存里改）都可能让事件丢掉。丢掉一个「只改内容、不改文件名」
+ * 的事件时，缓存会在本进程内继续供旧内容，直到下一次**任何**失效（新增 / 删除 / 重命名，
+ * 或下一次侥幸收到的事件）—— 那时会退回全扫，正确性恢复。有意选这个取舍，而不是每次扫都
+ * 逐份 `lstat` 复核 mtime：后者在 1000 份上要 83 ms，正是这次要省掉的东西。
+ * 真丢事件的后果是**一次注入拿到旧内容**，不是永久错误 —— 调用方 `scan.js` 的兜底判据
+ * （每次仍做一次 `readdir` 比文件名集合）覆盖了「新增 / 删除 / 重命名」这一大类，
+ * 而「只改内容」这一类是**明知的、写在这里的**残余风险。
+ */
+
+import { watch } from 'node:fs'
+
+/**
+ * 事件去抖窗口（毫秒）。
+ *
+ * 一次保存常常触发多个事件（临时文件 + rename + 内容写），去抖把一串合并成「两次通知」：
+ * 第一次**立刻**，最后一次在窗口结束时。为什么保留第一次而不只留末尾那次 —— 见 onEvent。
+ */
+export const WATCH_DEBOUNCE_MS = 50
+
+/**
+ * 事件洪流哨兵：窗口内超过这么多个事件，就认定这个句柄已经坏了，主动掐掉。
+ *
+ * ⚠️ 这不是防御性编程，是**实测踩到的坑**：Windows 上被监视的目录一旦被删（或删除后
+ * 用同名目录重建），底层句柄失效，`fs.watch` 会以**每秒十几万个** `'change'` 事件空转，
+ * 而且**不会**发 `'error'` —— 实测 2.9 秒收到 388,196 个事件。后果有两层：
+ *   1. 进程 100% CPU 空转、**永远不退出**（`persistent: false` 拦不住一个忙等的句柄）；
+ *      仓库里 `scripts/perf-chain.mjs` 每档结束都会 `rmSync` 掉沙箱，于是子进程卡死、
+ *      父进程 `spawnSync` 无限等待 —— 整个脚本挂住（这次就是这么发现的）。
+ *   2. 每个事件都重置去抖定时器 → 定时器分配风暴，进一步烧 CPU。
+ * 真实变更不可能到这个量级（一次批量写 1000 个文件也就 1000 个事件），所以阈值取哨兵值即可；
+ * 万一误判，代价也只是「这个目录退回全扫」（正确性不受影响），下一轮扫描会重新起表。
+ */
+export const WATCH_FLOOD_WINDOW_MS = 1000
+
+/** 见 WATCH_FLOOD_WINDOW_MS。 */
+export const WATCH_FLOOD_MAX_EVENTS = 2000
+
+/**
+ * 起一个只在**失效信号**意义上使用的目录监视器。
+ *
+ * @param {string} dir — 要监视的目录（不存在也算「起不来」，不抛）
+ * @param {() => void} [onChange] — 目录有变更时的通知（去抖后 + 首次立即各一次）
+ * @returns {{ok:boolean, reason:string, dispose:() => void}}
+ *   `ok` / `reason` 是**活的取值器**：起表成功之后如果 watcher 报错，`ok` 会变成 false、
+ *   `reason` 会变成失败原因 —— 调用方每次用之前重新读一遍，就不会拿着一个已经死掉的
+ *   watcher 继续相信缓存。**任何失败都不抛**，一律用 `ok: false` 表达。
+ */
+export function createDirWatcher(dir, onChange) {
+  const notify = typeof onChange === 'function' ? onChange : () => {}
+  /** 起表失败的原因；空串 = 还活着。 */
+  let failed = ''
+
+  let watcher
+  try {
+    // persistent: false —— 监视器不许拖住进程退出（测试里也会造一堆临时目录的 watcher）。
+    watcher = watch(dir, { persistent: false })
+  } catch (err) {
+    // 目录不存在 / 没有权限 / 平台不支持：都是「起不来」，调用方据此退回全扫。
+    return { ok: false, reason: `fs.watch 打不开（${err?.code ?? err?.message ?? err}）`, dispose() {} }
+  }
+
+  let disposed = false
+  let timer = null
+  /** 本轮突发里「第一次通知」是否已经发过 —— 决定后面的还发不发。 */
+  let burstOpen = false
+  /** 洪流哨兵的固定窗口计数（见 WATCH_FLOOD_WINDOW_MS）。 */
+  let floodWindowStart = 0
+  let floodCount = 0
+
+  const fire = () => {
+    if (disposed || failed) return
+    try {
+      notify()
+    } catch {
+      // 通知是调用方的代码，它出错不该把 watcher 弄死；失效信号本身已经送到了。
+    }
+  }
+
+  /**
+   * 第一条事件**立刻**透传，之后同一突发里的事件只在去抖窗口结束时再通知一次。
+   *
+   * 为什么不干脆等去抖结束：去抖的目的是**合并通知**，不是**延迟失效**。等 50 ms 才失效，
+   * 意味着这 50 ms 里来一次扫描就会喂旧内容 —— 而「每走一步扫一次」正是本插件的用法，
+   * 两步之间远小于 50 ms。所以：首个事件立刻失效（把窗口压到事件送达那一刻），
+   * 窗口结束时再补一次（合并掉这一串的其余事件）。
+   */
+  const onEvent = () => {
+    const now = Date.now()
+    if (now - floodWindowStart > WATCH_FLOOD_WINDOW_MS) {
+      floodWindowStart = now
+      floodCount = 0
+    }
+    floodCount++
+    if (floodCount > WATCH_FLOOD_MAX_EVENTS) {
+      // 句柄已坏（多半是目录被删 / 被同名重建）：报错这条路会顺手 close 掉，空转立刻停。
+      onError({ code: 'FLOOD', message: `${WATCH_FLOOD_WINDOW_MS}ms 内 ${floodCount} 个变更事件，句柄已不可信` })
+      return
+    }
+    if (!burstOpen) {
+      burstOpen = true
+      fire()
+    }
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => {
+      timer = null
+      burstOpen = false
+      fire()
+    }, WATCH_DEBOUNCE_MS)
+    // 定时器也不许拖住进程退出（与 persistent: false 同一目的；老 Node 上没有 unref 就跳过）。
+    if (typeof timer.unref === 'function') timer.unref()
+  }
+
+  /**
+   * 失败一律转成「这台 watcher 死了」，而不是抛出去。
+   * 调用方（scan.js）看到 `ok` 变 false 会丢掉缓存并退回全扫 —— 所以这里**必须**
+   * 把失败暴露出来，静默吞掉等于让它继续相信一份再也收不到失效信号的缓存。
+   */
+  const onError = (err) => {
+    failed = `fs.watch 出错（${err?.code ?? err?.message ?? err}）`
+    cleanup()
+  }
+
+  const cleanup = () => {
+    if (timer) {
+      clearTimeout(timer)
+      timer = null
+    }
+    burstOpen = false
+    try {
+      watcher.close()
+    } catch {
+      // 已经关掉了 / 底层句柄没了 —— dispose 必须幂等，不许在这里抛。
+    }
+  }
+
+  const dispose = () => {
+    if (disposed) return
+    disposed = true
+    cleanup()
+  }
+
+  watcher.on('change', onEvent)
+  // 'error' 是失败的另一条路（句柄彻底失效时 Node 才报）。⚠️ **目录被删不走这条** ——
+  // 实测 Windows 上是「静默洪流」（见洪流哨兵），所以两条都得接；不接 'error' 会变成
+  // uncaughtException，不接洪流就是 100% CPU 空转。
+  watcher.on('error', onError)
+
+  return {
+    get ok() {
+      return !disposed && failed === ''
+    },
+    get reason() {
+      return failed
+    },
+    dispose,
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "File-based memory plugin for DeepSeek Harness (DSH) — cross-session memory in plain markdown files, with a memory star-map view, type/tag filtering, retrieval aliases, and an optional autodream pass that consolidates memories on demand or on a schedule — with per-run rollback points, a per-file change declaration (what changed and why), and a separately selectable model for the consolidation pass",
-  "version": "0.9.19",
+  "version": "0.9.21",
   "type": "module",
   "main": "lib/index.js",
   "exports": {