sage-mem 2.1.15 → 2.1.16

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.15`** — 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.1.16`** — 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.1.15`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.16`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/memory/retrieval.js

@@ -71,32 +71,43 @@ export const MIN_SUMMARY_EVIDENCE_RATIO = 0.6
  */
 export const MIN_GATE_CORPUS = 8
 
-/** 摘要面的检索文本：`description` + `aliases` + 文件名。**打分与语料统计必须用同一份**。 */
+/**
+ * 摘要面的检索文本：`description` + `aliases` + 文件名。**打分与语料统计必须用同一份**。
+ *
+ * 相关性打分**只看 frontmatter 的 description + 文件名，不扫全文**。旧版拿 query 的
+ * 双字去全文里找，得分是「覆盖率」，分母是 query、不惩罚文件长度 —— 越长的记忆越容易
+ * 蒙中。实测：长记忆在全文匹配下对任何问题都能蒙中足量双字组，连寒暄问句都能注入上千
+ * token；而真正该命中的那条反被挤掉。description 是「一句话说清这条是什么」的精准摘要，
+ * 用它当检索信号，噪音大幅下降。
+ */
 export function summaryHay(f) {
   const aliasText = Array.isArray(f.aliases) && f.aliases.length ? ' ' + f.aliases.join(' ') : ''
   return f.description + aliasText + ' ' + f.file.replace(/\.md$/, '').replace(/[_-]/g, ' ')
 }
 
 /**
- * 相关性打分只用 frontmatter 的 description + 文件名，不扫全文。
+ * 摘要候选的**完整排序**（不施加注入名额）。
+ *
+ * 与 `selectRelevant` 的分工（2.1.16 / 外部审查 Q13）：
+ *   - 自动注入只要前 `MAX_RESULTS` 条 → 用 `selectRelevant`，名额在**消费端**切；
+ *   - 主动检索（`search_memory` / `retrieve`）要按自己的 limit/cursor 翻页 →
+ *     用这个函数拿**完整候选集**，否则下一页无从取起。
  *
- * 旧版拿 query 的双字去全文里找，得分是「覆盖率」，分母是 query，不惩罚
- * 文件长度 —— 越长的记忆越容易蒙中。实测：长记忆在全文匹配下对任何问题都能
- * 蒙中足量双字组，连寒暄问句都能注入上千 token；而真正该命中的那条反被
- * 挤掉。description 是「一句话说清这条是什么」的精准摘要，用它当检索
- * 信号，噪音大幅下降。
+ * 旧版把 `MAX_RESULTS` 焊死在这条排序里：`SAGE_MEM_MAX_RESULTS=3` 时，主动检索
+ * `scope=summary, limit=10` 只看到 3 条、`nextCursor=null`，丢掉的候选翻页也取不回。
  *
  * @param {string} query
  * @param {Array} files
  * @param {{gate?: boolean, minRatio?: number}} [opts] — `gate:false` 关掉证据门槛
  *   （测试「名额上限」这类与相关性无关的用例要它）
+ * @returns {Array} 按分数降序的**全部**命中（每项是原文件对象 + `score`）
  */
-export function selectRelevant(query, files, opts = {}) {
+export function rankSummaries(query, files, opts = {}) {
   const list = Array.isArray(files) ? files : []
   const hay = list.map(summaryHay)
   const entries = list.map((f, i) => ({ f, i, score: score(query, hay[i]) }))
   const hit = entries.filter(e => e.score > 0).sort((a, b) => b.score - a.score)
-  const keep = (arr) => arr.slice(0, MAX_RESULTS).map(e => ({ ...e.f, score: e.score }))
+  const keep = (arr) => arr.map(e => ({ ...e.f, score: e.score }))
   if (opts.gate === false || hit.length === 0) return keep(hit)
   // 语料太小就别用 IDF 判（见 MIN_GATE_CORPUS）。
   if (list.length < MIN_GATE_CORPUS) return keep(hit)
@@ -123,6 +134,20 @@ export function selectRelevant(query, files, opts = {}) {
   return keep(hit.filter(e => evidence(terms, tf[e.i], stats).sum >= minRatio * maxIdf))
 }
 
+/**
+ * 自动注入用的摘要选择：完整排序之后**只取注入名额内的条数**。
+ *
+ * 名额（`MAX_RESULTS`）仍然守自己的配置 —— 2.1.16 只把「排序」与「名额」拆开，
+ * 没有放开注入上限（那是 Q13 的反向对照）。
+ *
+ * @param {string} query
+ * @param {Array} files
+ * @param {{gate?: boolean, minRatio?: number}} [opts]
+ */
+export function selectRelevant(query, files, opts = {}) {
+  return rankSummaries(query, files, opts).slice(0, MAX_RESULTS)
+}
+
 /**
  * 选 baseline 条目：按显式 `baselinePriority` 排，不按文件名。
  *

package/lib/memory/search.js

@@ -16,7 +16,7 @@
 
 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 { rankSummaries, score as summaryScore } from './retrieval.js'
 import { extractTitle } from './scan.js'
 
 /** 工具响应的默认条数与上限（稿子 §5.2 的起始值）。 */
@@ -236,14 +236,18 @@ export function rankChunksInternal(query, files, opts = {}) {
 }
 
 /**
- * 摘要命中（复用 retrieval.js 的 `selectRelevant`，不另写一套打分）。
+ * 摘要命中（复用 retrieval.js 的摘要排序，不另写一套打分）。
+ *
+ * ⚠️ 用 `rankSummaries`（**不带注入名额**）而不是 `selectRelevant`：后者返回前
+ * `MAX_RESULTS` 条，而这里是主动检索的一页 —— 名额若先切一刀，本函数的 limit/cursor
+ * 就作用在**已被截断的集合**上，丢掉的候选翻页也取不回（外部审查 Q13）。
  *
  * 只额外做一件事：**说清是哪一栏命中的**。摘要命中与正文命中在展示层的处理不同
  * （前者给指针就够，后者才值得端正文），所以这个理由是行为契约的一部分。
  */
 export function summaryHits(query, files, limit = DEFAULT_LIMIT) {
   if (!String(query ?? '').trim()) return []
-  return selectRelevant(query, files).slice(0, limit).map(f => {
+  return rankSummaries(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')
@@ -296,7 +300,8 @@ export function retrieve(input = {}) {
   const byFile = new Map()
   for (const hit of body) if (!byFile.has(hit.file)) byFile.set(hit.file, hit)
 
-  // `Infinity` = 取满 `selectRelevant` 给的候选（它自己按 MAX_RESULTS 封顶）。
+  // `Infinity` = 取满摘要排序的**全部**候选（2.1.16 / Q13：注入名额不再焊在这条排序里，
+  // 所以这里拿到的是完整合格集，本函数的 limit/cursor 才真正能翻页）。
   // 曾经这里写的是 `limit + cursor` —— 池宽恰好等于本页窗口，于是 total 恒等于 cursor+limit、
   // `nextCursor` 恒为 null，翻页**根本翻不动**（只有第一页）。池宽必须大于窗口。
   const summary = scope === 'body' ? [] : summaryHits(query, files, Infinity)

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