sage-mem 0.9.14 → 0.9.16

package/README.md

@@ -159,9 +159,10 @@ SAGE_MEM_DIR=/path/to/your/memory
 
 透明的东西值得说清楚它怎么选料，因为它直接决定注入多少 token：
 
-- **信号是 `description`，不是全文**。每条记忆的 `description`（「一句话说清这条是什么」）、文件名、以及可选的 `aliases`（别称）一起参与打分，最多注入 **10 条**相关记忆。旧版拿问题里的双字去全文里蒙，长记忆天生占便宜——实测长记忆在全文匹配下连寒暄问句都能注入上千 token；改用 `description` 后噪音大幅下降
-- **换个说法也能命中**：打分是**词面重合**（双字组覆盖率），不是语义的——问「我有什么待办」而文件里写的是「代办清单」，差一个字就完全不命中。给这类记忆加一行 `aliases: [待办, todo]` 就能补上
-- **正文超 1500 字符就截断**并标 `…（截断）`，单条记忆不会吃掉整个上下文
+- **两段式检索：先摘要，再正文**。第一段用 `description`（「一句话说清这条是什么」）+ 文件名 + `aliases`（别称）打分，最多取 **10 条**候选；第二段对这些候选做**正文段落检索**（BM25，中文按双字词元），把最相关的那一段注入。旧版拿问题里的双字去全文里蒙，长记忆天生占便宜——实测长记忆在全文匹配下连寒暄问句都能注入上千 token。新版比的是**段落**，每份文件最多贡献一段，长文不再靠段数多占候选位
+- **摘要没写到的，正文能找回来**。摘要是精准的一句话，代价是正文细节天生检索不到；摘要一条都没命中时改由正文检索兜底——此前这种情况直接等于「没有记忆可用」。正文检索只在问题**至少 4 个字符**时才跑：`继续` 这种两个字的问题拿去做正文匹配，命中的全是「继续」这个词本身
+- **换个说法也能命中**：打分是**词面重合**，不是语义的——问「我有什么待办」而文件里写的是「代办清单」，差一个字就完全不命中。给这类记忆加一行 `aliases: [待办, todo]` 就能补上
+- **注入的是命中段落，不是文件开头**。命中段落标成 `### 项目_部署.md:40-52`，agent 据此能直接跳到那几行核对来源；段落前补一句该记忆的 `description`，补回「这段是从哪条记忆切出来的」。`baseline` 与没命中正文的文件仍注入开头。单条正文超 1500 字符截断并标 `…（截断）`
 - **同一个问题不会重复注入**（按会话记签名），问第二遍不会又追加一遍
 - **单场会话累计注入到 60 KB 就停**（`MAX_SESSION_BYTES`）。条数上限管的是「一次注多少」，这条管「一场会话总共注多少」—— 长会话里问题一直在换、签名一直在变，累积本来没有上限。到顶之后新的记忆不再注入（这时该让 agent 直接读文件），**压缩或清空之后账面自动归零**，又能注进来
 - **每条记忆的标题带新鲜度**：`（保存于 N 天前）`，**优先读 frontmatter 的 `updated:`，缺失才回落文件 mtime** —— 手写的时间戳是权威，文件系统时间会被复制 / 备份还原 / checkout 整批改掉。理由是陈旧记忆被当事实引用时，「引用」这个动作本身会让它显得更权威而不是更可疑，所以注入文本开头还带一节**引用纪律**（提到路径先确认存在、提到函数先 grep、要动手先核实）。它**独立成节**而不是一条 bullet：Claude Code 实测同一句话埋成 bullet 命中 0/3、独立成节 3/3

package/lib/index.js

@@ -23,6 +23,7 @@ import { parseAliases, parseBaseline, parseBaselinePriority, parseFrontmatter, p
 import { isReserved, nameKey, safeName } from './memory/naming.js'
 import { ageDays, bigrams, extractText, score, selectBaseline, selectRelevant } from './memory/retrieval.js'
 import { MEMORY_ARCHIVE_DIR, addArchiveMeta, extractTitle, inspectDir, inspectMemoryEntry, readArchivedMeta, scanArchived, scanMemoryFiles, scanStars, shadowsReserved } from './memory/scan.js'
+import { rankChunks } from './memory/search.js'
 import { archiveMemory, restoreMemory } from './memory/archive.js'
 import { flushAccess, pickArchiveCandidates, readAccessLedger, recordAccess } from './memory/access.js'
 import { warnLog, writeFileAtomic } from './memory/util.js'
@@ -48,6 +49,24 @@ function debugRecall(payload) {
   console.log(`[sage-mem] recall ${JSON.stringify(payload)}`)
 }
 
+/**
+ * 按文件去重，保留每个文件**首次**（也就是得分最高）出现的那条正文命中。
+ *
+ * 正文检索是段落粒度的，同一份文件可能返回多个段落。注入链要的是「这份文件要不要端上来」，
+ * 所以在这里收成文件粒度 —— 而**不是**把同一文件的多个段落一起端上去：那正是
+ * `retrieval.js` 当初从「全文匹配」退回「只比摘要」要躲开的病（长文靠段数多占满候选位）。
+ */
+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
+}
+
 /**
  * 面板可改的 5 项注入上限 —— 与 `memory/config.js` 里的 `SAGE_MEM_*` 一一对应。
  * 边界值照抄那边的 envInt 调用（lo/hi 不许在这里另立一套）。
@@ -280,11 +299,46 @@ export class MemoryGateway extends TypertRemoteService {
         // 因签名变化而被重复注入。现在 baseline 由会话级标记保证只来一次，
         // 检索由这份签名保证同一问题不重复追加，两条线互不干扰。
         const relevant = text && text.length >= 2 ? selectRelevant(text, files) : []
-        const signature = text + '\u0000' + relevant.map(f => f.file).join(',')
+
+        // ── 正文检索 ──
+        // 摘要（description + aliases + 文件名）是最省的检索面，代价是**正文里的东西天生检索不到**。
+        // 这里用它做两件事：
+        //   1. 给候选文件定位「最相关的那一段」，注入时替代「文件开头 1500 字」——
+        //      旧写法对任何问题都端同一段开头，等于把「命中在哪」这件事扔掉了；
+        //   2. 摘要一条都没命中时，用正文兜一次底。此前这种情况直接等于「没有记忆可用」。
+        //
+        // query 短于 4 个字符不做正文匹配：`继续` 这种两个字的问题拿去匹配正文，
+        // 命中的全是「继续」这个词本身，与用户问什么毫无关系。
+        const bodyRanked = typeof text === 'string' && text.length >= 4
+          ? rankChunks(text, files, { limit: MAX_RESULTS, perFile: 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(',')
         if (recallCache.get(session.id) !== signature) {
           recallCache.set(session.id, signature)
           if (recallCache.size > 8) recallCache.delete(recallCache.keys().next().value)
-          relevant.forEach(take)
+          selected.forEach(take)
         }
 
         if (picked.length === 0) {
@@ -305,12 +359,24 @@ export class MemoryGateway extends TypertRemoteService {
         const injectedFiles = []
         let skippedForBudget = 0
         for (const f of picked) {
-          const body = f.content.length > MAX_CHARS_PER_FILE
-            ? f.content.slice(0, MAX_CHARS_PER_FILE) + '\n…（截断）'
-            : f.content
+          // **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} 天前）` : ''
-          const part = `### ${f.file}${stamp}\n${body}`
+          // 段落命中时补两样东西：
+          //   - 行号：模型据此能直接用文件工具跳过去核对来源，「引用可核对」靠它成立；
+          //   - 摘要：段落本身不含 frontmatter，补回「这一段是从哪条记忆里切出来的」。
+          const loc = chunk ? `:${chunk.startLine}-${chunk.endLine}` : ''
+          const brief = chunk && f.description ? ` · ${f.description.slice(0, 80)}` : ''
+          const part = `### ${f.file}${loc}${stamp}${brief}\n${body}`
           const size = Buffer.byteLength(part, 'utf8')
           if (usedBytes + size > MAX_SESSION_BYTES) { skippedForBudget++; continue }
           usedBytes += size

package/lib/memory/bm25.js

@@ -0,0 +1,208 @@
+/**
+ * sage-mem 记忆层 —— 词元化与 BM25 打分（纯函数，无 I/O）。
+ *
+ * 为什么不是「双字覆盖率」：`retrieval.js` 那套是**覆盖率**——分母是 query，不惩罚文档长度。
+ * 它在摘要（一句话）上工作良好，正是因为它没机会被长文本稀释；一旦拿它扫正文，
+ * 长文件什么都能蒙中。BM25 换掉了那个分母：词频饱和（同一词出现 20 次不等于 20 倍相关）
+ * 加上长度归一（长文件不加权），再配 IDF 让「到处都有的词」自动失效。
+ *
+ * 中文没有分词器可用（本插件零外部依赖），所以沿用双字词元。这是有代价的：
+ * 「部署超时」会切出「部署」「署超」「超时」，「署超」是跨词边界的假词元。
+ * 它极少在文档里命中，所以贡献接近 0 —— 这也是为什么下面额外给了一个**覆盖率小项**：
+ * 命中越多的 query 词元越可能是真的要找的那份，用来打破近分平局。
+ */
+
+/** BM25 词频饱和系数。1.2 是文献里的常用起点。 */
+export const BM25_K1 = 1.2
+
+/** BM25 长度归一系数。0.75 同上。两个值都是起始参数，不是实测结论。 */
+export const BM25_B = 0.75
+
+/** 覆盖率在最终得分里的权重。刻意很小：它只该打破近分平局，不该压过 IDF。 */
+export const COVERAGE_WEIGHT = 0.2
+
+/** 汉字 / 假名 / 谚文的连续段。 */
+const CJK_RUN = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]+/u
+
+/** 一段连续的「标识符式」字符：`lib/index.js`、`SAGE_MEM_DEBUG`、`0.9.14`、`FS_STALE_VERSION`。 */
+const ASCII_RUN = /[A-Za-z0-9][A-Za-z0-9_.\-/:\\]*/g
+
+/** 标识符内部的分隔符 —— 切开后作为补充词元（`lib/index.js` 也要能被 `index` 搜到）。 */
+const ASCII_SEP = /[_.\-/:\\]+/
+
+/**
+ * 把文本切成词元数组（**保留重复**，BM25 要的是真实词频）。
+ *
+ * 两类文本走两条路：
+ *   - CJK 连续段 → 双字词元；单字段落退化成那一个字。**按段切，不跨标点**，
+ *     否则「。我」这种跨句假词元也会进索引。
+ *   - ASCII 串 → 整个原形 + 按分隔符切出的长度 ≥ 2 的片段。
+ *     原形保留是为了精确匹配错误码 / 路径 / 版本号；片段是为了「记得大概是哪个文件」也能搜到。
+ */
+export function tokenize(text) {
+  const s = String(text ?? '').toLowerCase()
+  if (!s) return []
+  const out = []
+  // CJK 段优先吃：ASCII 正则会绕过汉字，两者互不重叠。
+  const runs = s.match(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]+|[A-Za-z0-9][A-Za-z0-9_.\-/:\\]*/gu) ?? []
+  for (const run of runs) {
+    if (CJK_RUN.test(run)) {
+      if (run.length === 1) out.push(run)
+      else for (let i = 0; i < run.length - 1; i++) out.push(run.slice(i, i + 2))
+      continue
+    }
+    out.push(run)
+    for (const part of run.split(ASCII_SEP)) {
+      // 长度 1 的片段是噪音（`1.0.0` 会切出三个 `0`），它们 df 极高、IDF 近 0，纯属白占内存。
+      if (part.length >= 2 && part !== run) out.push(part)
+    }
+  }
+  return out
+}
+
+/** 词元数组 → 词频表。 */
+export function termFreq(tokens) {
+  const tf = new Map()
+  for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1)
+  return tf
+}
+
+/**
+ * 语料统计：文档数 N、平均长度 avgdl、逐词元的文档频率 df。
+ *
+ * @param {Array<{tokens:string[]}>} docs
+ */
+export function buildStats(docs) {
+  const df = new Map()
+  let total = 0
+  for (const d of docs) {
+    total += d.tokens.length
+    // 同一文档里出现多次只算一次 —— df 的定义就是「多少篇文档含这个词元」。
+    for (const t of new Set(d.tokens)) df.set(t, (df.get(t) ?? 0) + 1)
+  }
+  const N = docs.length
+  return { N, avgdl: N > 0 ? total / N : 1, df }
+}
+
+/** 单篇文档的 BM25 得分。queryTerms 应先去重。 */
+export function scoreDoc(queryTerms, tf, dl, stats) {
+  if (!stats || stats.N === 0) return 0
+  let score = 0
+  for (const t of queryTerms) {
+    const f = tf.get(t)
+    if (!f) continue
+    const idf = idfOf(stats.df.get(t) ?? 0, stats.N)
+    score += (idf * (f * (BM25_K1 + 1))) / (f + BM25_K1 * (1 - BM25_B + (BM25_B * dl) / stats.avgdl))
+  }
+  return score
+}
+
+/**
+ * 词元的逆文档频率。加 1 的对数形式：df 等于 N 时（到处都是的词元）趋近 0 而不为负。
+ *
+ * 单独抽出来是因为「证据强度」判据（`evidence`）要用同一个口径 —— 两处各写一遍
+ * 迟早会漂。
+ */
+export function idfOf(df, N) {
+  if (!N) return 0
+  return Math.log(1 + (N - df + 0.5) / (df + 0.5))
+}
+
+/**
+ * 证据强度：这份文档到底**凭什么**被认为相关。返回两个数，缺一不可。
+ *
+ * 为什么需要它：BM25 对**任何**问题都能给出非零分——只要有一个常用双字重合。
+ * 「今天天气怎么样」在 900 KB 的中文语料上必然能找到含「怎么」的段落。所以
+ * 「分数 > 0」不是可用的相关性判据，必须有下面这条独立门槛。
+ *
+ * `ratio` = 命中的词元权重 ÷ **在语料里存在过的** query 词元总权重。
+ *   ⚠️ 分母**必须剔除 df=0 的词元**：语料里根本没有的词（错别字、没记过的术语）
+ *   带着最大 IDF 进分母，会把真正相关的题也压到 0.07 这种地板分上。
+ * `sum` = 命中词元的权重绝对和。比值高但绝对量小，等于「匹配上的全是到处都有的词」，
+ *   仍然不算证据 —— 两个条件同时满足才算过门槛。
+ */
+export function evidence(queryTerms, tf, stats) {
+  let have = 0
+  let total = 0
+  let rarestRatio = 1
+  let rarestDf = Number.POSITIVE_INFINITY
+  let matched = 0
+  for (const t of queryTerms) {
+    const df = stats?.df?.get(t) ?? 0
+    if (df === 0) continue          // 语料里不存在 → 不进分母，也不进分子
+    const w = idfOf(df, stats.N)
+    total += w
+    if (tf.has(t)) {
+      have += w
+      matched++
+      rarestRatio = Math.min(rarestRatio, df / stats.N)
+      rarestDf = Math.min(rarestDf, df)
+    }
+  }
+  return {
+    ratio: total > 0 ? have / total : 0,
+    sum: have,
+    /**
+     * 命中词元里**最冷门**那个的两个口径：文档频率占比，与绝对文档频率。
+     *
+     * 为什么两个都要：`df/N` 在小语料上会失真 —— 一个只有 5 份记忆的目录里，
+     * 「全库独一份」的词元算出来也是 0.2，于是真命中会被误判成「不够冷门」而整条被滤掉，
+     * 小目录的记忆检索直接失效。绝对 df 则在大语料上失真（同一个数字在 100 份与
+     * 2000 份语料里含义完全不同）。所以判据是**析取**：
+     * `df ≤ 1`（全库独一份，一定是有内容的）**或** `df/N ≤ 门槛`。
+     * 两个口径都由调用方拿到，怎么组合是策略层的事。
+     *
+     * 为什么单有 ratio/sum 不够：`红烧肉怎么做才好吃` 在中文语料上会命中 `怎么`/`么做`
+     * 这类到处都有的词元 —— 它们数量够多，`sum` 能堆到 4.8，而 `ratio` 会因为
+     * 「红烧/烧肉/好吃」在语料里压根不存在（df=0，被剔出分母）而等于 1.0。
+     * 两个数字都像是强证据，实际命中的**全是虚词**。内容词（连接池、温漂、
+     * FS_STALE_VERSION）天然冷门，虚词天然热门，区分度就在这里。
+     */
+    rarestDfRatio: matched > 0 ? rarestRatio : 1,
+    rarestDf: matched > 0 ? rarestDf : Number.POSITIVE_INFINITY,
+    matched,
+  }
+}
+
+/** query 的独特词元里有多少比例出现在这篇文档里（0~1）。只用来打破近分平局。 */
+export function coverageOf(queryTerms, tf) {
+  if (!queryTerms.length) return 0
+  let hit = 0
+  for (const t of queryTerms) if (tf.has(t)) hit++
+  return hit / queryTerms.length
+}
+
+/** query → 去重后的词元数组。 */
+export function queryTermsOf(query) {
+  return [...new Set(tokenize(query))]
+}
+
+/**
+ * 最长「连续命中」的**词元个数**（0 = 一个都没命中）。
+ *
+ * 为什么必须单独看连续性：中文双字词元会把跨词边界的假词元也造出来。
+ * 「明天会不会下雨」里就有两个——
+ *   - `不会`：真实虚词，df 高；
+ *   - `天会`：来自「那一天**会**缩短」的跨词边界巧合，df=1，于是**IDF 最大**。
+ * 单独看「有没有命中一个冷门词元」，`天会` 这种巧合恰好满足，于是一句完全无关的
+ * 天气问题能把潮汐笔记拉进结果。
+ *
+ * 连续性治的就是它：连续命中 k 个词元 = query 里**至少 k+1 个字连着**出现在文档里。
+ * 巧合通常孤立（k=1），真实内容词通常连成片段（`连接池` k=2、`压测时连接池` k=4）。
+ *
+ * ⚠️ 它也有代价：整句只对上一个两字专名时 k 只有 1，会被判成不连续。
+ * 所以门槛里它是**析取**的一部分，不是唯一判据。
+ */
+export function maxMatchedRun(queryTokens, tf) {
+  let best = 0
+  let cur = 0
+  for (const t of queryTokens) {
+    if (tf.has(t)) {
+      cur++
+      if (cur > best) best = cur
+    } else {
+      cur = 0
+    }
+  }
+  return best
+}

package/lib/memory/chunks.js

@@ -0,0 +1,217 @@
+/**
+ * sage-mem 记忆层 —— 正文分段：把一份记忆切成可检索、可定位的段落。
+ *
+ * 为什么要有这一层：检索原先只比 `description` + `aliases` + 文件名（见 retrieval.js），
+ * 换来的是「噪音大幅下降」，代价是**摘要没写到的内容永远检索不到**。要补这个漏，
+ * 就得让正文参与匹配 —— 但**不能让整份文件参与匹配**：那会重演旧版的病
+ * （长文件什么都能蒙中）。所以改变评分单位：**用段落匹配问题，再把最佳段落归并回文件**，
+ * 而不是把一份文件的所有命中次数加起来。
+ *
+ * 三个必须守住的约束：
+ *   1. **行号是 1-based、相对整份文件**（含 frontmatter 那几行）。`read_memory` 的
+ *      `startLine` 直接吃这个值，中间不许再换算一次 —— 换算是这类功能最常见的错位来源。
+ *   2. **revision 是内容 hash，不是路径或标题**。路径会改名、标题会改写，两者都不是身份。
+ *   3. **frontmatter 不进段落**。它的键名（`name` / `description` / `node_type`…）在每份
+ *      文件里都一样，进了正文索引就等于给每条记忆灌入同一批高频词，正好抬高通用词的 df。
+ */
+
+import { createHash } from 'node:crypto'
+
+/** 目标段落长度（字符）。低于它就与邻居合并，避免碎片段把候选表塞满。 */
+export const CHUNK_TARGET_CHARS = 600
+
+/** 硬上限：超过就切。定在目标的 1.5 倍，留出「一行稍长就整段爆掉」的余量。 */
+export const CHUNK_MAX_CHARS = 900
+
+/**
+ * 独立成段的门槛（字符）。
+ *
+ * 低于它的段落优先并入相邻段：一条 `- 记完了` 这样的项目符号独立成段，既占一个候选位、
+ * 又几乎没有任何可匹配的词。合并是**就近向上**（并进已经攒好的上一段），因为 markdown
+ * 里短行通常是上一段同一主题的补充。
+ */
+export const CHUNK_MIN_CHARS = 60
+
+/**
+ * 内容 revision：`sha256:<前 12 位>`。
+ *
+ * 12 位十六进制 = 48 bit，对本场景（一份记忆目录内区分版本）绰绰有余，而短到能塞进
+ * 注入的状态卡与工具响应里不心疼。**它只表示「内容变了」，不表示「更新了」** ——
+ * 加一行注释也会换 revision，这不是错误信息，是「你之前读到的正文已经不是现在这份」。
+ */
+export function revisionOf(content) {
+  const hex = createHash('sha256').update(String(content ?? ''), 'utf8').digest('hex')
+  return `sha256:${hex.slice(0, 12)}`
+}
+
+/**
+ * frontmatter 块的结束行（1-based）；没有 frontmatter 返回 0。
+ *
+ * 判定刻意与 `frontmatter.js` 的正则同形（首行必须是整行 `---`，结束取**第一个**
+ * 行首 `---`），否则会出现「frontmatter 解析出来有 description，分段却把它当正文」
+ * 这种两边不一致的怪状态。
+ */
+export function frontmatterEndLine(lines) {
+  if (String(lines?.[0] ?? '').trim() !== '---') return 0
+  for (let i = 1; i < lines.length; i++) {
+    if (String(lines[i]).trim() === '---') return i + 1
+  }
+  return 0
+}
+
+/**
+ * 把一份记忆切成段落。
+ *
+ * @param {{file:string, content:string}} f — `scanMemoryFiles` 的条目
+ * @param {string} [knownRevision] — 调用方已经算过 revision 时传进来，省一次对整份正文的 sha256
+ * @returns {Array<{id:string,file:string,revision:string,headingPath:string,startLine:number,endLine:number,text:string}>}
+ */
+export function chunkFile(f, knownRevision) {
+  const file = String(f?.file ?? '')
+  const content = String(f?.content ?? '')
+  const revision = typeof knownRevision === 'string' && knownRevision ? knownRevision : revisionOf(content)
+  const lines = content.split(/\r?\n/)
+  const from = frontmatterEndLine(lines)
+  const out = []
+  // id 去重表：**必须去重**，因为「单行超长」那条路径会把一行按字符切成多片，
+  // 而它们共享同一个行号 → 光用行号当 id 会撞车（实测一份含 5000 字符单行的文件
+  // 产出 10 个片段、去重后只剩 2 个）。撞车会让「按 id 取回某一段」取到错的那片。
+  // 常见情形（一行以内）保持 `file#起-止` 的可读形式，只有撞车时才追加 `~n`。
+  const idSeen = new Map()
+  for (const block of mergeBlocks(splitBlocks(lines, from))) {
+    for (const piece of splitOne(block)) {
+      const base = `${file}#${piece.startLine}-${piece.endLine}`
+      const n = idSeen.get(base) ?? 0
+      idSeen.set(base, n + 1)
+      out.push({
+        id: n === 0 ? base : `${base}~${n}`,
+        file,
+        revision,
+        headingPath: piece.headingPath,
+        startLine: piece.startLine,
+        endLine: piece.endLine,
+        text: piece.text,
+      })
+    }
+  }
+  // 空段落（整块只有空白）不产出：它们没有可匹配的词，只会稀释 df。
+  return out.filter(c => c.text.length > 0)
+}
+
+/**
+ * 第一批：按标题与空行切出「原生块」。
+ *
+ * **每行带着自己的行号**（`{no, text}`），不是裸字符串 —— 合并与再切分之后行号仍要准确，
+ * 而「用内容反查行号」在有重复行的文件里必然出错（`---`、空行、重复的项目符号）。
+ *
+ * 围栏代码块里的空行不算分段点：一段代码被空行切成两半，两边都不再是完整的可读内容，
+ * 第二半的标题路径也指不对。
+ */
+function splitBlocks(lines, from) {
+  const blocks = []
+  const stack = []
+  let cur = null
+  let pendingHead = []
+  let inFence = false
+  const flush = () => {
+    if (cur && cur.raw.length) blocks.push(cur)
+    cur = null
+  }
+  for (let i = from; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence
+    if (!inFence) {
+      const h = line.match(/^(#{1,6})[ \t]+(.+?)[ \t]*$/)
+      if (h) {
+        flush()
+        const level = h[1].length
+        while (stack.length && stack[stack.length - 1].level >= level) stack.pop()
+        stack.push({ level, text: h[2] })
+        // **标题行本身要留在下一段的正文里**（不是只记进 headingPath）。
+        // 只记 headingPath 会丢字：一段横跨 `## 解决办法` 与 `## 无关小节` 的合并段落，
+        // 只有起始标题进索引，「解决办法」这四个字在检索面上等于不存在。
+        // 连续多个标题攒在一起，等下一条正文行来了再一起种进新块（避免产出只有标题的空段）。
+        pendingHead.push({ no: i + 1, text: line })
+        continue
+      }
+      if (line.trim() === '') {
+        flush()
+        continue
+      }
+    }
+    if (!cur) {
+      cur = {
+        startLine: pendingHead[0]?.no ?? i + 1,
+        endLine: i + 1,
+        raw: pendingHead.slice(),
+        headingPath: stack.map(s => s.text).join(' › '),
+      }
+      pendingHead = []
+    }
+    cur.endLine = i + 1
+    cur.raw.push({ no: i + 1, text: line })
+  }
+  flush()
+  return blocks
+}
+
+/** 第二批：过短的块往上一块合并，直到接近目标长度。 */
+function mergeBlocks(rawBlocks) {
+  const out = []
+  for (const b of rawBlocks) {
+    const text = b.raw.map(l => l.text).join('\n').trim()
+    if (!text) continue
+    const prev = out[out.length - 1]
+    // 用 `\n\n` 而不是 `\n` 拼接：两块之间**原本就隔着空行**，用单换行拼起来会让
+    // 注入文本里两段粘成一整段。这条只在「合并」路径上出现；被切分的单块内部是连续行，
+    // 那边的 `\n` 才是对的 —— 两条路径互斥（合并只到 600，切分只对 > 900 的原始块）。
+    if (prev && text.length < CHUNK_MIN_CHARS && prev.text.length + text.length + 2 <= CHUNK_TARGET_CHARS) {
+      prev.text = `${prev.text}\n\n${text}`
+      prev.endLine = b.endLine
+      prev.raw = prev.raw.concat(b.raw)
+      continue
+    }
+    out.push({ startLine: b.startLine, endLine: b.endLine, headingPath: b.headingPath, raw: b.raw, text })
+  }
+  return out
+}
+
+/**
+ * 第三批：超过硬上限的块按行切成多个片段。
+ *
+ * **单行超长的情形单独处理**：一份把日志或代码贴成一行的记忆，按行切分永远切不动
+ * （一个片段 = 那一整行），于是「长度归一」失效、候选位被一行占满。这里按字符硬切，
+ * 该行的行号由所有片段共享 —— 段落级的行号本来就不承诺精确定位到字节。
+ */
+function splitOne(block) {
+  if (block.text.length <= CHUNK_MAX_CHARS) return [block]
+  const out = []
+  let buf = []
+  let start = 0
+  let end = 0
+  const emit = () => {
+    if (!buf.length) return
+    const text = buf.join('\n').trim()
+    if (text) out.push({ startLine: start, endLine: end, headingPath: block.headingPath, text })
+    buf = []
+  }
+  for (const { no, text: line } of block.raw) {
+    if (line.length > CHUNK_MAX_CHARS) {
+      emit()
+      for (let i = 0; i < line.length; i += CHUNK_TARGET_CHARS) {
+        out.push({ startLine: no, endLine: no, headingPath: block.headingPath, text: line.slice(i, i + CHUNK_TARGET_CHARS) })
+      }
+      continue
+    }
+    const pending = buf.length ? buf.join('\n').length + 1 : 0
+    if (pending + line.length > CHUNK_TARGET_CHARS) emit()
+    if (!buf.length) {
+      start = no
+      end = no
+    }
+    end = no
+    buf.push(line)
+  }
+  emit()
+  return out
+}

package/lib/memory/search.js

@@ -0,0 +1,401 @@
+/**
+ * sage-mem 记忆层 —— 正文检索：把「段落打分」收口成一个可复用、可评测的检索面。
+ *
+ * 两层分工（这是本模块最要紧的一条设计）：
+ *   - `rankChunks()` 返回**富对象**（段落 + 逐项分数 + 命中原因），给注入链和评测脚本用；
+ *   - `retrieve()` 返回**线上形状**（wire shape），给 0.9.16 的 search_memory 工具用。
+ *
+ * 两者共用同一套排序，只是出口形状不同。**不要反过来让注入链去吃 wire shape** ——
+ * 那会把「响应契约」和「内部评分」焊在一起，以后改一个字段名就动到注入行为。
+ *
+ * 缓存：段落切分与词元化都很贵（中文双字词元在 900 KB 语料上是十万量级），
+ * 所以按**文件 revision 缓存**。文件没变就直接复用已切好的段落与词频表；
+ * 目录里任何一份文件变了，语料统计（df / avgdl）会跟着重算 —— 语料统计是全局量，
+ * 一篇文档的改动会影响所有词的 IDF。
+ */
+
+import { chunkFile, revisionOf } from './chunks.js'
+import { buildStats, coverageOf, evidence, maxMatchedRun, queryTermsOf, scoreDoc, termFreq, tokenize, COVERAGE_WEIGHT } from './bm25.js'
+import { score as summaryScore, selectRelevant } from './retrieval.js'
+import { extractTitle } from './scan.js'
+
+/** 工具响应的默认条数与上限（稿子 §5.2 的起始值）。 */
+export const DEFAULT_LIMIT = 5
+export const MAX_LIMIT = 10
+
+/** 每个文件最多贡献几个段落 —— 不累加同一文件的所有段落得分，这是「长文不垄断」的关键。 */
+export const PER_FILE_CHUNKS = 2
+
+/** 单条片段的字符上限（稿子 §5.2 的起始值）。 */
+export const EXCERPT_CHARS = 200
+
+/**
+ * 相关性门槛 —— **BM25 分数不是可用的判据**。
+ *
+ * 原因很实在：BM25 对任何问题都能给出非零分，只要有一个常用双字重合。中文语料里
+ * 「怎么」「什么」「一个」这类词元的文档频率极高，任何问句都能撞上几个 ——
+ * 于是「分数 > 0」等于「几乎总是有结果」，无关问题会从「什么都不注」变成「注一堆噪音」。
+ *
+ * 三个条件必须同时满足：
+ *   - `ratio` ≥ 0.35：在「语料里存在过的 query 词元」里，这份文档覆盖了足够大的权重份额；
+ *   - `sum`   ≥ 1.5 ：命中的词元绝对信息量够，不是「全是到处都有的词」凑出来的比值；
+ *   - `rarestDfRatio` ≤ 0.10：至少有一个命中词元是**冷门**的。这条专治一种漏网：
+ *     问句里一半的词在语料里压根不存在（df=0，被剔出分母），剩下的通用词恰好都命中，
+ *     于是 ratio=1.0、sum 靠数量堆高，看起来证据很强 —— 实际命中的全是虚词。
+ *   - **连续命中 ≥ 2 个词元**（= query 里至少 3 个字连着出现在文档里）。这条治的是
+ *     中文双字词元的**跨词边界假词元**：「明天会不会下雨」里 `天会` 来自
+ *     「那一天**会**缩短」，df=1、IDF 最大，单看「有个冷门词元命中」它反而最"强"。
+ *     巧合通常孤立，真实内容词通常连成片段。
+ *
+ * ⚠️ **这三个数是起始参数，不是实测结论**，由 `scripts/eval-retrieval.mjs` 的对照
+ * 结果来定（计划里阶段一的用途就是这个）。要放宽就用 `rankChunks(..., { minEvidence: false })`
+ * 拿掉门槛，别去改这里的常量。
+ *
+ * 0.10 这个值来自一次对抗性扫参（16 份合成语料，其中 4 份**故意塞满通用词**，
+ * 让无关问句一定能找到词面重合）：
+ *
+ * | 门槛 | 相关题留住 | 无关题误召回 |
+ * |---|---|---|
+ * | 无门槛 | 12/12 | 4/12 |
+ * | 只 ratio | 12/12 | 4/12 |
+ * | ratio+sum | 12/12 | 1/12（`红烧肉怎么做才好吃`）|
+ * | +rarest ≤ 0.15 | 12/12 | 1/12 |
+ * | **+rarest ≤ 0.10** | **12/12** | **0/12** |
+ * | +rarest ≤ 0.05 | 0/12 | 0/12 |
+ *
+ * 相关题命中的最冷门词元都是 0.0625，硬负例是 0.125 —— 0.10 落在分离带里。
+ * ⚠️ 该值在**小语料**上定出；真实语料的 df/N 量级不同（段落数越多，同一个词元的 df/N 越小），
+ * 阶段一的评测脚本要在真实量级上复核一次再定稿。
+ */
+export const MIN_EVIDENCE_RATIO = 0.35
+export const MIN_EVIDENCE_SUM = 1.5
+export const MAX_EVIDENCE_DF_RATIO = 0.1
+
+/**
+ * 最少要**连续命中**几个词元（默认 2 = query 里至少 3 个字连着出现在文档里）。
+ *
+ * 设为 1 就等于关掉这条判据。代价与理由见 `bm25.maxMatchedRun` 的注释。
+ */
+export const MIN_MATCHED_RUN = 2
+
+/** 缓存文件数上限。语料只有 109 份时永不触发；它防的是目录被塞进成千上万份文件。 */
+const MAX_CACHE_FILES = 1024
+
+/** file → {revision, title, chunks:[{...,tokens,tf,dl}]} */
+const chunkCache = new Map()
+
+/** 语料统计缓存：`{sig, stats}`。sig 由参与的文件 revision 拼成，变了就重算。 */
+let statsCache = { sig: '', stats: { N: 0, avgdl: 1, df: new Map() } }
+
+/** 只给测试用：清掉进程内缓存，让「改了文件」的场景能从头验。 */
+export function __resetSearchCacheForTest() {
+  chunkCache.clear()
+  statsCache = { sig: '', stats: { N: 0, avgdl: 1, df: new Map() } }
+}
+
+/**
+ * 取得全部段落与语料统计（带缓存）。
+ *
+ * @param {Array<{file:string,content:string,mtimeMs?:number}>} files
+ * @returns {{chunks:Array, stats:object, skipped:number, complete:boolean}}
+ */
+export function chunksOf(files) {
+  const list = Array.isArray(files) ? files : []
+  const chunks = []
+  const revisions = []
+  let skipped = 0
+  for (const f of list) {
+    const file = String(f?.file ?? '')
+    const content = String(f?.content ?? '')
+    if (!file) continue
+    const revision = revisionOf(content)
+    revisions.push(`${file}:${revision}`)
+    const hit = chunkCache.get(file)
+    if (hit && hit.revision === revision) {
+      for (const c of hit.chunks) chunks.push(c)
+      continue
+    }
+    try {
+      const title = extractTitle(content)
+      const built = chunkFile({ file, content }, revision).map(c => {
+        const tokens = tokenize(`${c.headingPath}\n${c.text}`)
+        return { ...c, title, tokens, tf: termFreq(tokens), dl: tokens.length }
+      })
+      chunkCache.set(file, { revision, title, chunks: built })
+      for (const c of built) chunks.push(c)
+    } catch {
+      // 切分失败的文件计入 skipped 并把 complete 置否 —— 检索结果必须能自报「我没查全」，
+      // 不能让一个坏文件静默地变成「这篇没命中」。
+      skipped++
+    }
+  }
+  // LRU 也不做，只做整体清理：超限说明目录形态异常，重算比留着更安全。
+  if (chunkCache.size > MAX_CACHE_FILES) {
+    for (const key of [...chunkCache.keys()].slice(0, chunkCache.size - MAX_CACHE_FILES)) chunkCache.delete(key)
+  }
+  const sig = revisions.join('|')
+  if (statsCache.sig !== sig) {
+    statsCache = { sig, stats: buildStats(chunks) }
+  }
+  return { chunks, stats: statsCache.stats, skipped, complete: skipped === 0 }
+}
+
+/**
+ * 正文排序：段落打分 → 每文件限量 → 全局裁剪。
+ *
+ * @param {string} query
+ * @param {Array} files — `scanMemoryFiles` 的结果
+ * @param {{perFile?:number, limit?:number}} [opts]
+ * @returns {Array<{chunk:object, file:string, revision:string, bm25:number, coverage:number, score:number, matchedBy:string[]}>}
+ */
+export function rankChunks(query, files, opts = {}) {
+  return rankChunksInternal(query, files, opts).hits
+}
+
+/**
+ * 与 `rankChunks` 同一套排序，但额外报告「被相关性门槛滤掉多少条」——
+ * `retrieve` 的 coverage 要如实说明「有候选但不够格」，而不是把它伪装成「没有候选」。
+ *
+ * `opts.minEvidence === false` 关掉门槛（评测脚本对照两组时要它）。
+ * `opts.limit` 只兜底、**不封顶**（`MAX_LIMIT` 是 `retrieve` 那一层的收敛口径）：
+ * 内部调用要用 `Infinity` 拿完整排名。两个入口语义不同是有意的，别记混。
+ */
+export function rankChunksInternal(query, files, opts = {}) {
+  const perFile = Number.isFinite(opts.perFile) ? Math.max(1, opts.perFile) : PER_FILE_CHUNKS
+  // `Infinity` = 不切片，要完整排名（`retrieve` 用它算 `candidates` 与翻页）。
+  // 不能写成 `Number.isFinite(Infinity)` 那条分支：Infinity 不是有限数，会被当成「没传」回落默认值。
+  const limit = opts.limit === Infinity
+    ? Infinity
+    : (Number.isFinite(opts.limit) ? Math.max(1, opts.limit) : DEFAULT_LIMIT)
+  const terms = queryTermsOf(query)
+  if (!terms.length) return { hits: [], filtered: 0, chunks: 0 }
+  // 有序词元（含重复）——「连续命中」判据要顺序，去重后的集合没有位置信息。
+  const queryTokens = tokenize(query)
+  const { chunks, stats } = chunksOf(files)
+  if (!chunks.length) return { hits: [], filtered: 0, chunks: 0 }
+  // `minEvidence` 三态：省略 → 用默认门槛；`false` → 完全不设门槛；
+  // 传对象 → 用自定义门槛（评测脚本扫参要用，免得为了换一个数字去改常量）。
+  const gate = opts.minEvidence === false
+    ? null
+    : {
+        ratio: opts.minEvidence?.ratio ?? MIN_EVIDENCE_RATIO,
+        sum: opts.minEvidence?.sum ?? MIN_EVIDENCE_SUM,
+        maxDfRatio: opts.minEvidence?.maxDfRatio ?? MAX_EVIDENCE_DF_RATIO,
+        minRun: opts.minEvidence?.minRun ?? MIN_MATCHED_RUN,
+      }
+
+  let filtered = 0
+  const scored = []
+  for (const c of chunks) {
+    const bm25 = scoreDoc(terms, c.tf, c.dl, stats)
+    if (bm25 <= 0) continue
+    const ev = evidence(terms, c.tf, stats)
+    // 冷门判据是**析取**：`df ≤ 1`（全库独一份）或 `df/N ≤ 门槛`。
+    // 只用比值会在小语料上把真命中全滤掉（5 份记忆的目录里，独一份的词元比值也是 0.2）。
+    const rare = ev.rarestDf <= 1 || ev.rarestDfRatio <= gate?.maxDfRatio
+    const run = maxMatchedRun(queryTokens, c.tf)
+    // `sum` 用的是 IDF，而 IDF **随语料规模对数增长** —— 绝对阈值同样不可迁移：
+    // 单段语料（N=1）里 df=1 的词元 idf 只有 0.288，一个原样命中的 `FS_STALE_VERSION`
+    // 四个词元加起来才 1.15，会被 `sum ≥ 1.5` 整条滤掉。
+    // 所以给 `sum` 一个**逃生口**：命中的是「全库独一份」的词元**且**连成片段（run 达标）时，
+    // 它就是强证据，不再看绝对量。这与 `rare` 的析取是同一个理由，只是换了个量。
+    const uniqueAndContiguous = ev.rarestDf <= 1 && run >= (gate?.minRun ?? 1)
+    if (gate && (ev.ratio < gate.ratio || (!uniqueAndContiguous && ev.sum < gate.sum) || !rare || run < gate.minRun)) {
+      filtered++
+      continue
+    }
+    const coverage = coverageOf(terms, c.tf)
+    scored.push({
+      chunk: c,
+      file: c.file,
+      revision: c.revision,
+      bm25,
+      coverage,
+      evidence: Number(ev.ratio.toFixed(4)),
+      evidenceSum: Number(ev.sum.toFixed(4)),
+      evidenceRarest: Number(ev.rarestDfRatio.toFixed(4)),
+      evidenceRarestDf: Number.isFinite(ev.rarestDf) ? ev.rarestDf : null,
+      evidenceRun: run,
+      score: bm25 + COVERAGE_WEIGHT * coverage,
+      matchedBy: exactTermHit(String(query), c.text) ? ['body', 'exact-term'] : ['body'],
+    })
+  }
+  scored.sort((a, b) => b.score - a.score)
+
+  // 每文件限量：同一份长文件用五个段落占满候选位，是「长文垄断」的另一种形态。
+  const perFileCount = new Map()
+  const kept = []
+  for (const hit of scored) {
+    const n = perFileCount.get(hit.file) ?? 0
+    if (n >= perFile) continue
+    perFileCount.set(hit.file, n + 1)
+    kept.push(hit)
+    if (kept.length >= limit) break
+  }
+  return { hits: kept, filtered, chunks: chunks.length }
+}
+
+/**
+ * 摘要命中（复用 retrieval.js 的 `selectRelevant`，不另写一套打分）。
+ *
+ * 只额外做一件事：**说清是哪一栏命中的**。摘要命中与正文命中在展示层的处理不同
+ * （前者给指针就够，后者才值得端正文），所以这个理由是行为契约的一部分。
+ */
+export function summaryHits(query, files, limit = DEFAULT_LIMIT) {
+  if (!String(query ?? '').trim()) return []
+  return selectRelevant(query, files).slice(0, limit).map(f => {
+    const fileBase = f.file.replace(/\.md$/, '').replace(/[_-]/g, ' ')
+    const matchedBy = []
+    if (f.description && summaryScore(query, f.description) > 0) matchedBy.push('description')
+    if (Array.isArray(f.aliases) && f.aliases.length && summaryScore(query, f.aliases.join(' ')) > 0) matchedBy.push('alias')
+    if (summaryScore(query, fileBase) > 0) matchedBy.push('filename')
+    return {
+      file: f.file,
+      revision: revisionOf(String(f.content ?? '')),
+      score: f.score,
+      // 回落标签是 `summary` 而不是 `description`：`retrieval.js` 的打分是**三个字段去标点
+      // 拼成一串**之后再算双字，所以跨字段边界也能产生命中（`description: '收尾待'` +
+      // `aliases: ['办清单']` 会被 query「待办」选中）。逐字段复算时三个字段各自为 0，
+      // 回落成 `description` 就是在**谎报命中原因** —— 展示层会据此给出错的解释。
+      matchedBy: matchedBy.length ? matchedBy : ['summary'],
+    }
+  })
+}
+
+/**
+ * 检索。返回线上形状（稿子 §5.2）。
+ *
+ * scope 语义：
+ *   - `summary` 只比摘要 —— 普通问题先走这条，最省；
+ *   - `body` 只扫正文段落；
+ *   - `all`    两者合并，**摘要优先、同文件不重复占位**。
+ *
+ * 「摘要优先」不是偏好，是成本：摘要命中的那条本来就要被注入，正文再给它一个位置等于
+ * 同一份证据占两个候选位。合并时同文件只保留一条，带上它最好的段落。
+ */
+export function retrieve(input = {}) {
+  const query = String(input.query ?? '')
+  const files = Array.isArray(input.files) ? input.files : []
+  const scope = normalizeScope(input.scope)
+  const limit = clampLimit(input.limit)
+  const perFile = Number.isFinite(input.perFile) ? Math.max(1, input.perFile) : PER_FILE_CHUNKS
+  const excerptChars = Number.isFinite(input.excerptChars) ? Math.max(40, input.excerptChars) : EXCERPT_CHARS
+  const cursor = Number.isFinite(input.cursor) && input.cursor > 0 ? Math.floor(input.cursor) : 0
+
+  const corpus = chunksOf(files)
+  const { skipped, complete } = corpus
+  const terms = queryTermsOf(query)
+
+  // ⚠️ 两路的候选池都必须**比本页窗口宽**，否则 `candidates` 是本页条数、`nextCursor` 永远是 null
+  // （summary 一路曾经就是这样：池宽 = `limit + cursor`，于是翻页根本翻不动）。
+  // 取满再切窗口，是本模块唯一正确的做法。
+  const bodyRanked = scope === 'summary'
+    ? { hits: [], filtered: 0, chunks: 0 }
+    : rankChunksInternal(query, files, { perFile, limit: Infinity })
+  const body = bodyRanked.hits
+  const byFile = new Map()
+  for (const hit of body) if (!byFile.has(hit.file)) byFile.set(hit.file, hit)
+
+  // `Infinity` = 取满 `selectRelevant` 给的候选（它自己按 MAX_RESULTS 封顶）。
+  // 曾经这里写的是 `limit + cursor` —— 池宽恰好等于本页窗口，于是 total 恒等于 cursor+limit、
+  // `nextCursor` 恒为 null，翻页**根本翻不动**（只有第一页）。池宽必须大于窗口。
+  const summary = scope === 'body' ? [] : summaryHits(query, files, Infinity)
+  const summaryByFile = new Map()
+  for (const s of summary) if (!summaryByFile.has(s.file)) summaryByFile.set(s.file, s)
+
+  const ordered = []
+  for (const s of summaryByFile.values()) ordered.push(toHit(s.file, s, byFile.get(s.file), terms, excerptChars))
+  for (const [file, b] of byFile) {
+    if (summaryByFile.has(file)) continue
+    ordered.push(toHit(file, null, b, terms, excerptChars))
+  }
+  // 两类都命中 → 排前面（同一份证据被两条独立信号指向）；其余按分数排。
+  ordered.sort((a, b) => Number(b.matchedBy.length > 1) - Number(a.matchedBy.length > 1) || b.score - a.score)
+
+  const total = ordered.length
+  const hits = ordered.slice(cursor, cursor + limit)
+  return {
+    ok: true,
+    scope,
+    cursor,
+    coverage: {
+      searched: files.length,
+      skipped,
+      complete,
+      chunks: corpus.chunks.length,
+      // 被相关性门槛滤掉的条数：必须如实报出来，否则「不够格」会被读成「没有候选」——
+      // 这两件事对模型下一步该干什么的指示完全不同。
+      filteredBelowFloor: bodyRanked.filtered,
+      candidates: total,
+    },
+    hits,
+    nextCursor: cursor + limit < total ? cursor + limit : null,
+  }
+}
+
+function toHit(file, summary, body, terms, excerptChars) {
+  const score = (summary?.score ?? 0) + (body?.score ?? 0)
+  const matchedBy = [...(summary?.matchedBy ?? []), ...(body?.matchedBy ?? [])]
+  const text = body?.chunk?.text ?? ''
+  return {
+    id: body?.chunk?.id ?? `${file}#summary`,
+    file,
+    revision: body?.revision ?? summary?.revision ?? '',
+    title: body?.chunk?.title ?? '',
+    headingPath: body?.chunk?.headingPath ?? '',
+    lines: body?.chunk ? [body.chunk.startLine, body.chunk.endLine] : null,
+    excerpt: text ? excerptAround(text, terms, excerptChars) : '',
+    // 证据强度：调用方要能判别「这条凭什么算相关」，而不只看到一个分数。
+    evidence: body?.evidence ?? null,
+    evidenceSum: body?.evidenceSum ?? null,
+    evidenceRarest: body?.evidenceRarest ?? null,
+    evidenceRarestDf: body?.evidenceRarestDf ?? null,
+    evidenceRun: body?.evidenceRun ?? null,
+    score: Number(score.toFixed(4)),
+    matchedBy: matchedBy.length ? matchedBy : ['body'],
+  }
+}
+
+/** scope 归一：只认三个值，其余一律当 `all`（**不悄悄降级成 summary**，见稿子 §5.2）。 */
+export function normalizeScope(raw) {
+  const s = String(raw ?? '').trim().toLowerCase()
+  return s === 'summary' || s === 'body' ? s : 'all'
+}
+
+function clampLimit(raw) {
+  const n = Number(raw)
+  if (!Number.isFinite(n)) return DEFAULT_LIMIT
+  return Math.max(1, Math.min(MAX_LIMIT, Math.round(n)))
+}
+
+/**
+ * 片段：以**第一个命中位置**为中心截取，而不是永远取开头。
+ *
+ * 取开头是错的：一份 900 字的段落里第 600 字才提到那个错误码，给的片段里没有它 ——
+ * 模型看不到命中在哪，只能把整段读回来，正好抵消掉「先给片段」省下的钱。
+ */
+export function excerptAround(text, terms, maxChars) {
+  const s = String(text ?? '')
+  if (s.length <= maxChars) return s
+  // 小写化**可能改变字符串长度**（`İ` → `i̇` 这类少数语言环境相关字符）。长度一变，
+  // 在 lowercase 串上找到的偏移映射回原串就是错位的。宁可退回「取开头」，
+  // 也不要给出一个从错误位置切出来的片段——片段的价值全在「命中词在不在里面」。
+  const lower = s.toLowerCase()
+  const hay = lower.length === s.length ? lower : s
+  let at = -1
+  for (const t of terms ?? []) {
+    const i = hay.indexOf(t)
+    if (i >= 0 && (at < 0 || i < at)) at = i
+  }
+  if (at < 0) return s.slice(0, maxChars) + '…'
+  const lead = Math.floor(maxChars / 3)
+  const from = Math.max(0, at - lead)
+  return (from > 0 ? '…' : '') + s.slice(from, from + maxChars) + (from + maxChars < s.length ? '…' : '')
+}
+
+/** 整段 query 原样出现（去掉首尾空白、大小写归一）—— 错误码 / 路径 / 版本号的强信号。 */
+function exactTermHit(query, text) {
+  const q = query.trim().toLowerCase().replace(/\s+/g, ' ')
+  if (q.length < 2) return false
+  return String(text ?? '').toLowerCase().replace(/\s+/g, ' ').includes(q)
+}

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.14",
+  "version": "0.9.16",
   "type": "module",
   "main": "lib/index.js",
   "exports": {