sage-mem 1.0.2 → 1.2.0

package/lib/memory/archive.js

@@ -15,7 +15,7 @@
  * 就是临时目录），拿模块级常量会写错地方 —— 那是会碰到真实记忆的危险错误。
  */
 
-import { ARCHIVE_DIR_NAME, addArchiveMeta, inspectDir, inspectMemoryEntry, localStamp, stripArchiveMeta } from './scan.js'
+import { ARCHIVE_DIR_NAME, addArchiveMeta, inspectDir, inspectMemoryEntry, localStamp, readArchivedMeta, stripArchiveMeta } from './scan.js'
 import { isReserved, nameKey, safeName } from './naming.js'
 import { writeFileAtomic, writeFileExclusive } from './util.js'
 import { isLocked } from './lock.js'
@@ -290,3 +290,104 @@ export async function restoreMemory(memoryDir, name) {
     ...(indexError ? { indexError } : {}),
   }
 }
+
+/**
+ * 从归档区**彻底删除**一条记忆（不可恢复）。
+ *
+ * 为什么不复用 `deleteFile`：归档的承诺是「只移不删」，活记忆的 `deleteFile` 承诺的
+ * 是「删掉活的这份」。两者混在一个名字下，用户就永远分不清自己按的是哪一个；
+ * 而这个操作**没有回收站**。
+ *
+ * 三道判据，缺一不可：
+ *   1. **归档区的目录闸门**：它若被换成指向外部的联接，删掉的是别人的文件；
+ *   2. **条目闸门**：链接 / 硬链接指向的可能是记忆目录之外的内容，删它等于替别人删文件；
+ *   3. **代次（`archivedAt`）**：名字不是身份。用户从列表看到确认框、到请求到达之间，
+ *      这条完全可能被恢复回顶层、又被另一版同名记忆归档进来 —— 按名删掉的就不再是他
+ *      确认过的那一份。所以调用方必须交回它当时看见的 `archived_at`，对不上就拒绝。
+ *      老数据没有留痕时两边都是空串，仍然一致（那是「同一份、只是没有时间戳」）。
+ *
+ * ⚠️ 删除本身用 **`rename` 到私有名 + `rm` 私有名**：`inspect` 与 `unlink` 之间隔着
+ * 读文件，直接 `unlink(full)` 认的是**名字**而不是我们核对过的那份实物。`rename` 是原子的，
+ * 之后删的一定是刚移走的那一个 inode。删失败时把名字 `link()` 还回去 —— 绝不让它
+ * 以 `.deleting-` 的私有名留在盘上（扫描不认那个名字，等于文件凭空消失）。
+ *
+ * @param {string} memoryDir — 记忆根目录（调用方给，不许拿模块常量）
+ * @param {string} name — 归档区里的文件名
+ * @param {string} expectedArchivedAt — 调用方看见的 `archived_at`（没有留痕时传空串）
+ * @returns {Promise<{ok:true,file:string}|{ok:false,code:string,error:string}>}
+ */
+export async function deleteArchivedMemory(memoryDir, name, expectedArchivedAt = '') {
+  const gate = checkName(name, 'delete')
+  if (!gate.ok) return gate
+  const safe = gate.safe
+  const dirGate = await inspectDir(archiveDirOf(memoryDir))
+  if (!dirGate.ok) {
+    return {
+      ok: false,
+      code: dirGate.code === 'missing' ? 'not-archived' : dirGate.code,
+      error: `sage-mem: not archived: ${safe}（${dirGate.error}）`,
+    }
+  }
+  const full = join(archiveDirOf(memoryDir), safe)
+  const srcGate = await inspectMemoryEntry(full, { limitBytes: null })
+  if (!srcGate.ok) {
+    return {
+      ok: false,
+      code: srcGate.code === 'missing' ? 'not-archived' : srcGate.code,
+      error: `sage-mem: not archived: ${safe}（${srcGate.error}）`,
+    }
+  }
+  // 读全文只为取留痕：代次判据必须来自**盘上的那份**，不能信调用方一路传下来的展示值。
+  const onDisk = readArchivedMeta(await readFile(full, 'utf8'))
+  const expected = String(expectedArchivedAt ?? '')
+  if (expected !== onDisk.archivedAt) {
+    return {
+      ok: false,
+      code: 'changed',
+      error:
+        `sage-mem: ${safe} 在确认之后被换成了另一版（界面上是「${expected || '时间未知'}」，` +
+        `盘上是「${onDisk.archivedAt || '时间未知'}」），本次一个字节都没删 —— 请刷新列表再看一眼。`,
+    }
+  }
+  const taken = join(archiveDirOf(memoryDir), `.${safe}.deleting-${randomUUID().replace(/-/g, '')}`)
+  const moveErr = await rename(full, taken).then(
+    () => null,
+    (err) => err,
+  )
+  if (moveErr) {
+    if (moveErr?.code === 'ENOENT') {
+      return { ok: false, code: 'not-archived', error: `sage-mem: not archived: ${safe}（删除途中它从归档区消失了）` }
+    }
+    return {
+      ok: false,
+      code: 'move-failed',
+      error: `sage-mem: 删除 ${safe} 时移不动它（${moveErr?.code ?? moveErr}：${moveErr?.message ?? moveErr}）。文件仍在 archive/ 里、一个字节没动 —— 可稍后重试（若是被其它程序占用，关掉它再来）。`,
+    }
+  }
+  const delErr = await rm(taken, { force: true }).then(
+    () => null,
+    (err) => err,
+  )
+  if (delErr) {
+    const restored = await link(taken, full).then(
+      () => true,
+      () => false,
+    )
+    if (!restored) {
+      return {
+        ok: false,
+        code: 'delete-failed',
+        error:
+          `sage-mem: 删除 ${safe} 失败（${delErr?.code ?? delErr}），且归还原名时被占用 —— ` +
+          `**内容仍保留在 archive/${basename(taken)}**，请手工改回 ${safe} 再试。`,
+      }
+    }
+    await rm(taken, { force: true }).catch(() => {})
+    return {
+      ok: false,
+      code: 'delete-failed',
+      error: `sage-mem: 删除 ${safe} 失败（${delErr?.code ?? delErr}：${delErr?.message ?? delErr}），文件已还回 archive/${safe}，没有丢。`,
+    }
+  }
+  return { ok: true, file: safe }
+}

package/lib/memory/write-gate.js

@@ -26,7 +26,7 @@
  *   临时文件；监听器不需要声明 `inject` 也能收到，与 sage-mem 主插件的处境一致）。
  * - **插件自己调 `ctx.fs.writeText` / `editText` 时一次都不派发**（实测 0）。所以 autodream
  *   那类**插件内部写入不经过这里**，本模块也不假装能兜底它 —— 那条路由调用方自己传
- *   `expected`（`lib/autodream-tools.js` 就是这么做的）。
+ *   `expected`（`lib/autodream/tools.js` 就是这么做的）。
  *
  * 由此两条硬结论：
  *

package/lib/recall/compose.js

@@ -0,0 +1,160 @@
+/**
+ * 注入链的**渲染与预算**阶段（1.2.0 从 `lib/index.js` 原样搬出）。
+ *
+ * 三段，每段都能单独测（`test/recall-unit-test.mjs`）：
+ *   - `buildCandidates`：只负责「每条候选长什么样」；
+ *   - `composeDelivery`：只负责「在正文预算内该给哪几条」（`decideDelivery` 是纯函数）；
+ *   - `composeStatus`：只负责「缺口卡 / 检查点句柄该不该说、还能不能说」。
+ *
+ * 两件事分开是 v0.9.17 的教训：预算、渲染、去重挤在一个循环里时，谁也说不清
+ * 某条为什么没进去。
+ */
+import { CONTENT_BUDGET, MAX_CHARS_PER_FILE, STALE_DAYS, STATUS_RESERVE } from '../memory/config.js'
+import { ageDays } from '../memory/retrieval.js'
+import { decideDelivery } from '../memory/deliver.js'
+import { renderStatusCard } from '../memory/status.js'
+import { recordAccess } from '../memory/access.js'
+import { dedupeByFile } from './select.js'
+
+/** 把候选文件渲染成「要不要端上去」的条目（不含预算决策）。 */
+export function buildCandidates({ picked, bestChunk, nowMs = Date.now() }) {
+  const candidates = []
+  for (const f of picked) {
+    // **baseline 不吃段落替换**：它的语义是「这条记忆每场会话都该完整在场」
+    // （你是谁、待办清单）。一旦用户的问句碰巧命中它，替换成单个段落就等于
+    // 把「完整在场」偷偷降级成「命中在场」—— 那正是 baseline 要防的事。
+    const chunk = f.baseline ? null : bestChunk.get(f.file)
+    // 命中段落优先；没有命中（baseline、或 query 太短没做正文检索）才回到「文件开头」。
+    // 旧写法对**任何**问题都端同一段开头，等于把「命中在哪」这个信息扔掉了。
+    const raw = chunk ? chunk.text : f.content
+    const body = raw.length > MAX_CHARS_PER_FILE
+      ? raw.slice(0, MAX_CHARS_PER_FILE) + '\n…（截断）'
+      : raw
+    const days = ageDays(f, nowMs)
+    const stamp = days !== null && days >= STALE_DAYS ? `（保存于 ${days} 天前）` : ''
+    // 段落命中时补两样东西：
+    //   - 行号：模型据此能直接用文件工具跳过去核对来源，「引用可核对」靠它成立；
+    //   - 摘要：段落本身不含 frontmatter，补回「这一段是从哪条记忆里切出来的」。
+    const loc = chunk ? `:${chunk.startLine}-${chunk.endLine}` : ''
+    const brief = chunk && f.description ? ` · ${f.description.slice(0, 80)}` : ''
+    candidates.push({
+      file: f.file,
+      id: chunk?.id ?? `${f.file}#head`,
+      revision: chunk?.revision ?? '',
+      score: f.score ?? 0,
+      baseline: f.baseline === true,
+      lines: chunk ? [chunk.startLine, chunk.endLine] : null,
+      title: f.description || '',
+      text: `### ${f.file}${loc}${stamp}${brief}\n${body}`,
+    })
+  }
+  return candidates
+}
+
+/**
+ * 展示层决策 + 记账。
+ *
+ * 按**实际进正文的字节**记账，而不是 `delivery.totals` —— 后者含指针的额度，
+ * 而指针没有真的进上下文。两本账要对得上，就不能把没花出去的钱记进去。
+ */
+export function composeDelivery({ candidates, text, intent, contentBytes, nowMs = Date.now() }) {
+  const delivery = decideDelivery(candidates, {
+    intent,
+    // ⚠️ 这里**故意传空集**：按 revision 抑制重复对「同一份文件的不同段落」太粗 ——
+    // 换一个问题往往会命中同一份文件的**另一段**，按文件级 revision 抑制会把新相关
+    // 的那段一起挡掉。要启用它得先用「段落身份」而不是「文件 revision」做键，
+    // 并且单独评测一次。这条记在 docs/decisions.md 的 D15，不是遗漏。
+    visibleRevisions: new Set(),
+    scopeDenied: new Set(),
+    conflicts: new Set(),
+    expired: new Set(),
+    needle: text ? text.slice(0, 40) : '',
+  }, { bytes: Math.max(0, CONTENT_BUDGET - contentBytes) })
+
+  const parts = []
+  const injectedFiles = []
+  let skippedForBudget = 0
+  for (const item of delivery.items) {
+    if (item.kind === 'snippet') {
+      parts.push(item.text)
+      injectedFiles.push(item.file)
+    } else {
+      // pointer / suppress / unresolved 都**不进正文**。
+      // 「被省略几条」这件事由下面的状态卡统一说，正文里再逐条列一行
+      // `### 某某.md（未展开）` 是重复的信息，还白占上下文 —— 卡片本来就带着
+      // 「最佳线索 + 一个可做的动作」。
+      skippedForBudget++
+    }
+  }
+  // 进上下文的这些才算「被用过」—— 台账是自动归档阈值的唯一数据源，记错一步阈值就偏。
+  // recordAccess 同步、绝不抛：台账的问题不许升级成注入失败。
+  recordAccess(injectedFiles, nowMs)
+
+  const contentBytesNext = contentBytes + parts.reduce((n, p) => n + Buffer.byteLength(p, 'utf8'), 0)
+  return { delivery, parts, injectedFiles, skippedForBudget, contentBytes: contentBytesNext }
+}
+
+/**
+ * 缺口状态卡 + 检查点句柄（共用卡池）。
+ *
+ * 返回 `{ cardBody, cardText, cardPart, cardSig, cardBytes }`：
+ *   - `cardBody` 要原样写回状态（签名没变时下一步沿用它，避免换个数字重发）；
+ *   - `cardPart` 是这一步真正要发出去的文本（'' 表示不发）。
+ */
+export function composeStatus({
+  files, selected, bodyRanked, bodySearched, text, parts, injectedFiles, skippedForBudget,
+  deduped, st, toolsReady, checkpointLine, memoryDir, intentHistoryDependent,
+}) {
+  // ── 缺口状态卡 ──
+  // 它**替换**原来那行状态文字，不是额外追加：同一件事不说两遍。
+  // 卡池与正文池互不借用 —— 正文满了照样发得出卡，这正是预留的意义（见 config.js）。
+  const bodyOnly = bodySearched ? dedupeByFile(bodyRanked) : []
+  const unread = Math.max(0, selected.length - injectedFiles.length)
+  // 最佳线索取「正文命中里第一条没被注进去的」——那正是模型下一步最该去读的东西。
+  const beacon = bodyOnly.find(h => !injectedFiles.includes(h.file)) ?? bodyOnly[0] ?? null
+  // 什么时候该说话：
+  //   - **有真缺口**（有候选没读、或有候选被预算省略）→ 说；
+  //   - **没有缺口也没有命中** → 只在「用户这句话在问自己的历史」时说。
+  // 后者是计划里点名的一条：没有历史依赖时不要插「你可能遗漏记忆」，否则提示
+  // 每轮都出现，等真有缺口时它已经被当噪音忽略了。
+  const gapExists = unread > 0 || skippedForBudget > 0
+
+  const wantCard = gapExists || intentHistoryDependent === true || !!checkpointLine
+  // 签名没变时沿用上一步渲染好的那份缺口卡，而不是重渲染一张。
+  // 两条理由：其一，那一步与这一步的检索面**逐字相同**，缺口也相同，重渲染只会把
+  // 同一件事换个数字再说一遍 —— 而局部变量算出来的数字还是错的（上一步注了 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,
+        })
+  // 句柄与卡**共用卡池**：它是同一个通道里的另一句提示，不该另开一份额度。
+  const cardText = [cardBody, checkpointLine].filter(Boolean).join('\n')
+  let cardPart = ''
+  let cardSig = st.cardSig
+  let cardBytes = st.cardBytes
+  // 卡按**内容签名**去重：签名没变就不重复发。否则每一步都追加一张一模一样的卡，
+  // 而每张卡都是落到会话里的持久消息 —— 那不叫提示，那叫刷屏。
+  if (cardText && cardText !== cardSig) {
+    const cardSize = Buffer.byteLength(cardText, 'utf8')
+    if (cardBytes + cardSize <= STATUS_RESERVE) {
+      cardBytes += cardSize
+      cardPart = cardText
+      cardSig = cardText
+    }
+  }
+  return { cardBody, cardText, cardPart, cardSig, cardBytes }
+}

package/lib/recall/debug.js

@@ -0,0 +1,23 @@
+/**
+ * 注入链的调试出口（1.2.0 从 `lib/index.js` 原样搬出）。
+ *
+ * `SAGE_MEM_DEBUG=1` 才出声的一行结构化 JSON：候选数 / 命中数 / 逐条得分 /
+ * 入选与真注入的文件名 / 注入字符数 / 被会话预算挡掉几条。它回答的是
+ * 「这条记忆为什么没被召回」——一个光看上下文永远查不出的问题。
+ *
+ * ⚠️ **不开时零输出、零额外开销**：每个调用点都先 `if (debugEnabled())`，
+ * 不成立时连 payload 对象都不会被构造出来。
+ *
+ * 为什么开关是**每次现读**而不是模块级常量：原来是常量，靠「测试里用 query 重载
+ * `lib/index.js` 重新求值」来切换；1.2.0 把它拆成独立模块后，重载 index.js 不会重载
+ * 它，常量就永远停在旧值（`test/access-test.mjs` 第 4 组当场变红）。现读一次环境变量
+ * 的成本可以忽略，而它换来了「运行时也能打开调试」这个更诚实的行为。
+ */
+export function debugEnabled() {
+  return process.env.SAGE_MEM_DEBUG === '1'
+}
+
+export function debugRecall(payload) {
+  if (!debugEnabled()) return
+  console.log(`[sage-mem] recall ${JSON.stringify(payload)}`)
+}

package/lib/recall/index.js

@@ -0,0 +1,15 @@
+/**
+ * 注入链的公开面（1.2.0 的模块边界）。
+ *
+ * 组合根只通过这个 barrel 认识注入链：它不需要知道选材 / 渲染 / 预算分在几个文件里，
+ * 也不该直接 import 内部碎片 —— 这样将来再拆一个文件，组合根不用跟着改。
+ *
+ * 各函数的行为由 `test/recall-golden-test.mjs`（11 个场景逐字节）与
+ * `test/recall-unit-test.mjs`（直接喂夹具）守着。
+ */
+export { createSessionInjectState } from './state.js'
+export { createRecallInjector } from './injector.js'
+export { dedupeByFile, selectRecall } from './select.js'
+export { buildCandidates, composeDelivery, composeStatus } from './compose.js'
+export { composeRecallText } from './text.js'
+export { debugEnabled, debugRecall } from './debug.js'

package/lib/recall/injector.js

@@ -0,0 +1,181 @@
+/**
+ * 注入链的编排骨架（1.2.0 从 `MemoryGateway` 构造函数里整段搬出）。
+ *
+ * 为什么搬：这段逻辑（约 350 行）以前是构造函数的闭包 —— 想测「压缩后 baseline 会不会
+ * 重来」「正文池满了卡还能不能发」这类分支，只能先搭一个万能 Proxy ctx 再
+ * `new MemoryGateway(ctx)`，测的其实是「组合根能不能被构造」。
+ * 现在它是一等函数：`createRecallInjector({ ctx, state, tools })` 返回监听器，
+ * 而选材 / 渲染 / 预算三段各自是纯函数（`select.js` / `compose.js` / `text.js`）。
+ *
+ * 行为由 `test/recall-golden-test.mjs` 的 11 个场景逐字节守 —— 这个文件里任何一行
+ * 改动如果影响了注入文本，golden 会红，不是「测试太紧」。
+ *
+ * ⚠️ 两条历史坑（搬动时注释与代码必须一起搬，拆开就会重犯）：
+ *   1. 只取 `source.kind === 'user'` 的消息 —— DSH 0.1.5 起注入与工具结果也存成 role:'user'；
+ *   2. 代次处理（`state.begin`）必须在算正文与控制提示**之前**，否则压缩后会拿上一代的账去判重（复审 R03）。
+ */
+import { MEMORY_DIR, RECALL_DISCIPLINE, STATE_ROOT } from '../memory/config.js'
+import { extractText } from '../memory/retrieval.js'
+import { scanMemoryFiles } from '../memory/scan.js'
+import { readCheckpoint } from '../memory/checkpoint.js'
+import { warnLog } from '../memory/util.js'
+import { selectRecall } from './select.js'
+import { buildCandidates, composeDelivery, composeStatus } from './compose.js'
+import { composeRecallText } from './text.js'
+import { debugEnabled, debugRecall } from './debug.js'
+
+/**
+ * @param {object} deps
+ * @param {object} deps.ctx — 宿主 ctx（`scanMemoryFiles` / `warnLog` 用）
+ * @param {object} deps.state — `createSessionInjectState()` 的实例
+ * @param {{ready: () => boolean}} deps.tools — 检索工具是否注册就绪（异步就绪，每步读一次）
+ * @param {(session: object) => string} [deps.taskIdOf] — 任务 id 取值（检查点用）
+ * @returns {(assembly: object, context: object, next: Function) => Promise<object>}
+ */
+export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
+  const resolveTaskId = typeof taskIdOf === 'function'
+    ? taskIdOf
+    // 任务 id：`SAGE_MEM_TASK_ID` 优先（给「跨会话的同一条任务」用），否则用 session id。
+    // **绝不用查询文本自定作用域** —— 那句话是模型或用户写的，不该决定去读哪个目录。
+    : (session) => process.env.SAGE_MEM_TASK_ID || session?.id || ''
+
+  // 按问题检索注入：system-prompt/assemble 是异步 waterfall，监听器可 await。
+  // 从 agent.session 拿当前 user message，扫 memory 目录按摘要匹配选相关
+  // 文件，读全文作为动态 context 段注入——让 agent 第一轮就「想起」。
+  return async function recallInjection(assembly, context, next) {
+    const assembled = await next()
+    // session id 在 try 外先取好：catch 里也要能带上它（拿到什么带什么）。
+    const sessionId = context?.agent?.session?.id ?? ''
+    try {
+      const agent = context?.agent
+      const session = agent?.session
+      if (!session) return assembled
+      // DSH 0.1.7 起 Session 的历史读取接口在陆续调整（snapshotEvents / eventAt /
+      // ownEvents 已弃用）。deriveMessages 在 0.1.7-rc.1 实测仍在且仍同步，但这三行
+      // 不是白写的：方法一旦被改名或改成异步，老写法要么静默不注入、要么把 Promise
+      // 当数组展开成空。宁可日志里响一声，也不要"记忆不注入但日志一字没有"。
+      if (typeof session.deriveMessages !== 'function') {
+        warnLog(ctx, 'session.deriveMessages() 不可用 —— 记忆召回已跳过（DSH session API 变了？）', sessionId)
+        return assembled
+      }
+      const derived = session.deriveMessages()
+      const messages = [...(derived && typeof derived.then === 'function' ? await derived : derived)]
+
+      // 关键：DSH 0.1.5 把工具结果（source.kind === 'tool'）和注入内容
+      // （source.kind === 'plugin'）也存成 role: 'user' 的消息。只按 role 取
+      // 「最后一条」会取到 tool-result，extractText 得到空串，下面的长度检查
+      // 直接返回——表现就是全程静默不注入。只有 source.kind === 'user' 是真人输入。
+      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)
+
+      // ── 代次：**先处理状态转换，再算正文与控制提示** ──
+      // 压缩 / 清空（消息条数下降）在这一行里就让签名、两本账、卡签名、baseline 标记
+      // 一起归零。放到后面（比如去重之后再算）就等于「拿上一代的账本判这一代」——
+      // 复审 R03 的「同题压缩后仍被挡住」正是这么来的。
+      const ledgerKey = session.id || 'no-session-id'
+      const st = state.begin(ledgerKey, messages.length)
+
+      const { picked, baselineTaken, relevant, intentInfo, bodyRanked, bestChunk, selected, signature, deduped } =
+        selectRecall({ text, files, st })
+
+      // ⚠️ 这里**不能**再写「picked 为空就返回」：检查点句柄与未命中提示都不依赖候选，
+      // 提前返回会让它们在「目录为空」或「零命中」时永远不可达（复审 R02）。
+      // 统一的出口在下面 —— 只有**正文与控制提示都为空**才返回。
+
+      const nowMs = Date.now()
+      const candidates = buildCandidates({ picked, bestChunk, nowMs })
+
+      // ── 单会话累计预算：**拆成两本账** ──
+      //   正文池 = CONTENT_BUDGET（总上限 − 状态卡预留）／卡池 = STATUS_RESERVE
+      // 拆的理由见 config.js：到顶之后旧行为是一个字都不注、连「为什么没注、还能怎么查」
+      // 都没有；而那个上限是**本插件自己定的**，完全可以给状态卡留一份固定额度。
+      // 账记在 session id 上；picked 里 baseline 永远排在检索结果之前，所以预算不够时
+      // 先被挤掉的是「更晚才想起来的」那些 —— baseline 有优先权。
+      // 起点来自 `begin()`：它可能刚因压缩把两本账连同卡签名一起归零过。
+      const delivered = composeDelivery({ candidates, text, intent: intentInfo.intent, contentBytes: st.contentBytes, nowMs })
+      const { parts, injectedFiles, skippedForBudget, contentBytes } = delivered
+
+      // ── 任务检查点：压缩后的恢复入口 ──
+      // 宿主**什么时候**压缩上下文，插件控制不了 —— 所以这里**不承诺「压缩前保存」**，
+      // 只保证「存在检查点就给一条短句柄」。压缩后两本账与卡的签名会一起归零，
+      // 句柄因此会重新出现，这就是恢复路径（而不是靠某个压缩前钩子）。
+      const taskId = resolveTaskId(session)
+      let checkpointLine = ''
+      try {
+        const cp = taskId ? await readCheckpoint(taskId, { stateRoot: STATE_ROOT }) : null
+        if (cp?.ok && cp.handle) checkpointLine = cp.handle
+      } catch { /* 读不到检查点就当没有：它是可选的接力棒，不是必需件 */ }
+
+      const bodySearched = typeof text === 'string' && text.length >= 4
+      const status = composeStatus({
+        files, selected, bodyRanked, bodySearched, text, parts, injectedFiles, skippedForBudget,
+        deduped, st, toolsReady: tools.ready(), checkpointLine, memoryDir: MEMORY_DIR,
+        intentHistoryDependent: intentInfo.historyDependent,
+      })
+      const { cardBody, cardPart } = status
+
+      // 正文与卡都没有 → 一个字都不注。注意这与旧行为不同：旧行为「正文池满」就到此为止，
+      // 现在只要卡池还有额度就会发出卡（说清范围、缺口与下一步动作）。
+      if (parts.length === 0 && !cardPart) {
+        if (debugEnabled()) {
+          debugRecall({
+            scanned: files.length, hits: relevant.length,
+            scores: relevant.map(f => [f.file, Number(f.score.toFixed(4))]),
+            picked: picked.map(f => f.file), injected: [], chars: contentBytes, skippedByBudget: skippedForBudget,
+          })
+        }
+        return assembled
+      }
+
+      // 状态一次写回：签名、两本账、卡签名、缺口卡、条数、baseline 标记。
+      // 放在这里（而不是更早）是刻意的 —— 上面每一步都可能没真注进去东西，
+      // 那就不该让状态前进；一次失败把一条记忆永久挡在门外是最难查的一种。
+      state.commit(ledgerKey, {
+        signature,
+        contentBytes,
+        cardBytes: status.cardBytes,
+        cardSig: status.cardSig,
+        gapCard: cardBody,
+        messageCount: messages.length,
+        baselineDone: st.baselineDone || baselineTaken > 0,
+      })
+
+      if (debugEnabled()) {
+        debugRecall({
+          scanned: files.length,
+          hits: relevant.length,
+          scores: relevant.map(f => [f.file, Number(f.score.toFixed(4))]),
+          picked: picked.map(f => f.file),
+          injected: injectedFiles,
+          chars: contentBytes,
+          skippedByBudget: skippedForBudget,
+          card: cardPart ? 'sent' : (status.cardText ? 'deduped-or-over-budget' : 'none'),
+        })
+      }
+
+      const recallText = composeRecallText({
+        parts,
+        cardPart,
+        memoryDir: MEMORY_DIR,
+        discipline: RECALL_DISCIPLINE,
+      })
+
+      return {
+        ...assembled,
+        contexts: [...(assembled.contexts ?? []), {
+          name: 'sage-mem:recall',
+          order: 1000,
+          text: recallText,
+        }],
+      }
+    } catch (err) {
+      // 这是整条注入链的外壳。裸吞的代价就是 :174-193 记的那个坑：权限错、编码坏、
+      // frontmatter 正则哪天不匹配，表现都是「插件在、但记忆不再注入」，日志一字没有。
+      // 现在只降级（返回未注入的 assembly），但一定留痕。
+      warnLog(ctx, `recall injection failed: ${err?.message ?? err}`, sessionId)
+      return assembled
+    }
+  }
+}

package/lib/recall/select.js

@@ -0,0 +1,138 @@
+/**
+ * 注入链的**选材**阶段（1.2.0 从 `lib/index.js` 原样搬出，纯函数化）。
+ *
+ * 输入：`{ text, files, st }`（问题文本、扫到的记忆、会话状态快照）。
+ * 输出：候选文件（`picked`，顺序即注入顺序）、检索签名、各条检索线的中间结果。
+ *
+ * 为什么单独一个文件：这一段以前埋在 348 行监听器里，只能 `new MemoryGateway(ctx)` 间接测；
+ * 现在 `selectRecall()` 是纯函数，`test/recall-unit-test.mjs` 可以直接喂夹具。
+ */
+import { MAX_RESULTS } from '../memory/config.js'
+import { selectBaseline, selectRelevant } from '../memory/retrieval.js'
+import { detectIntent } from '../memory/intent.js'
+import { rankChunks } from '../memory/search.js'
+
+/**
+ * 按文件去重，保留每个文件**首次**（也就是得分最高）出现的那条正文命中。
+ *
+ * 正文检索是段落粒度的，同一份文件可能返回多个段落。注入链要的是「这份文件要不要端上来」，
+ * 所以在这里收成文件粒度 —— 而**不是**把同一文件的多个段落一起端上去：那正是
+ * `retrieval.js` 当初从「全文匹配」退回「只比摘要」要躲开的病（长文靠段数多占满候选位）。
+ */
+export function dedupeByFile(hits) {
+  const seen = new Set()
+  const out = []
+  for (const h of hits) {
+    if (seen.has(h.file)) continue
+    seen.add(h.file)
+    out.push(h)
+  }
+  return out
+}
+
+/**
+ * 选出这一步要端上去的文件。
+ *
+ * @param {{text:string, files:Array, st:object, maxResults?:number}} input
+ * @returns {{picked:Array, baselineTaken:number, relevant:Array, intentInfo:object,
+ *   bodyRanked:Array, bestChunk:Map, selected:Array, signature:string, deduped:boolean}}
+ */
+export function selectRecall({ text, files, st, maxResults = MAX_RESULTS }) {
+  const picked = []
+  const seen = new Set()
+  const take = (f) => {
+    if (seen.has(f.file)) return
+    seen.add(f.file)
+    picked.push(f)
+  }
+
+  // baseline：每个会话注入一次，**不看消息条数**。
+  //
+  // 旧写法 `if (userMessages.length === 0)` 依赖一个真实存在的时序：assemble
+  // 触发时当前这条用户消息还没写进 session。已在 DSH 0.1.7-rc.1 上核实为真 ——
+  //   宿主从 pending 队列取走本轮输入
+  //   组装 system prompt（本监听器在这里跑）
+  //   之后才把这条 user 消息落进 session
+  // 所以全新会话首步 pick 到 0 条 user message，分支命中。
+  //
+  // 但**恢复 / 续聊会话**的历史消息早就在 session 里，条数永远 ≥ 1 → 分支永不
+  // 命中 → 永不注入。而「继续吧」这类短问题在 description 里找不到匹配、检索
+  // 返回 0 条，baseline 恰恰是那时唯一的兜底。这是本会话级状态要修的东西。
+  let baselineTaken = 0
+  if (!st.baselineDone) {
+    selectBaseline(files)
+      .forEach(f => {
+        const before = picked.length
+        take(f)
+        if (picked.length > before) baselineTaken++
+      })
+    // 只有真取到才算「给过」：首步若正好撞上目录读不到（scanMemoryFiles 降级返回 []），
+    // 整场会话就再也没机会补 baseline 了。宁可下一步重算一次。
+    // 标记本身随这一步一起在 commit() 落 —— 与「提交放最后」同一条理由：
+    // 没真注进去的东西不能记成「已经给过」。
+  }
+
+  // 检索签名只覆盖「检索出来的那批」，baseline 不再掺进这个签名。
+  // 旧版两者共用 signature，首步签名一旦与后续某步相同，baseline 会连坐被吞；
+  // 反过来，旧版把 baseline 文件名也算进签名，会让同一步的检索结果在下一步
+  // 因签名变化而被重复注入。现在 baseline 由会话级标记保证只来一次，
+  // 检索由这份签名保证同一问题不重复追加，两条线互不干扰。
+  const relevant = text && text.length >= 2 ? selectRelevant(text, files) : []
+
+  // ── 意图：先判，因为它要影响下面正文检索的**门槛松紧** ──
+  // 用户是不是在问自己的历史（上次 / 之前 / 更正 / 问依据 / 继续）。
+  // 判不出来就是 `none`，不猜 —— 误判的代价是把不该抑制的正文抑制掉。
+  const intentInfo = text ? detectIntent(text) : { intent: 'none', historyDependent: false, suppressible: true }
+
+  // ── 正文检索 ──
+  // 摘要（description + aliases + 文件名）是最省的检索面，代价是**正文里的东西天生检索不到**。
+  // 这里用它做两件事：
+  //   1. 给候选文件定位「最相关的那一段」，注入时替代「文件开头 1500 字」——
+  //      旧写法对任何问题都端同一段开头，等于把「命中在哪」这件事扔掉了；
+  //   2. 摘要一条都没命中时，用正文兜一次底。此前这种情况直接等于「没有记忆可用」。
+  //
+  // query 短于 4 个字符不做正文匹配：`继续` 这种两个字的问题拿去匹配正文，
+  // 命中的全是「继续」这个词本身，与用户问什么毫无关系。
+  //
+  // **门槛按意图放宽**：默认要求「连续命中 ≥ 2 个词元」（那条防的是跨词边界的假词元，
+  // 见 search.js）。代价是整句只对上一个两字专名时会被拦下 —— 那是 0.9.16 有意付的。
+  // 但用户**明确在问自己的历史**时，宁可多给一条也不该让他拿不到依据：这类问题的
+  // 代价不对称（少给 = 答错，多给 = 多花一点上下文）。所以这时把 `minRun` 放到 1。
+  const bodyRanked = typeof text === 'string' && text.length >= 4
+    ? rankChunks(text, files, {
+        limit: maxResults,
+        perFile: 1,
+        ...(intentInfo.historyDependent ? { minEvidence: { minRun: 1 } } : {}),
+      })
+    : []
+  const bestChunk = new Map()
+  for (const h of bodyRanked) if (!bestChunk.has(h.file)) bestChunk.set(h.file, h.chunk)
+
+  // 「摘要命中就按摘要排；一条都没有才让正文接手」这个**保守写法是错的**，
+  // 由评测数据推翻（scripts/eval-retrieval.mjs 的对照 + 注入链实测）：
+  // 摘要只要命中**任何一条**（哪怕很弱、甚至命中错的文件），正文里那份真正相关的
+  // 就再也没有机会——应注入的文件级召回从 87.0% 掉到 60.9%。而噪音并没有因此更低
+  // （正文命中本来就要过相关性门槛，实测误召回 1/10，与保守写法持平）。
+  //
+  // 所以改成**并集**：摘要命中的在前（它经过人工写的 description，精确度高），
+  // 正文独有的在后（按 BM25 + 证据强度排序）。`take` 按文件去重，
+  // 同一份文件不会因为两条检索线都命中而占两个名额。
+  const byFile = new Map(files.map(f => [f.file, f]))
+  const selected = relevant.slice()
+  const taken = new Set(selected.map(f => f.file))
+  for (const h of dedupeByFile(bodyRanked)) {
+    if (taken.has(h.file)) continue
+    taken.add(h.file)
+    const f = byFile.get(h.file)
+    if (f) selected.push(f)
+  }
+
+  const signature = text + '\u0000' + selected.map(f => f.file).join(',')
+  // 检索签名没变 = 这一代里这条问题已经处理过 → 不再重复追加同一份记忆。
+  // ⚠️ 这个判断必须排在代次处理**之后**：压缩后的同题恢复，靠的就是上面 `begin()`
+  // 把签名一起清掉（复审 R03）。
+  const deduped = st.signature === signature
+  if (!deduped) selected.forEach(take)
+
+  return { picked, baselineTaken, relevant, intentInfo, bodyRanked, bestChunk, selected, signature, deduped }
+}