sage-mem 2.0.0 → 2.0.1

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.0.0`** — 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.0.1`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [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.
@@ -70,7 +70,7 @@ Most memory schemes take the "SQLite + a long-running worker" route: once memori
 | Feature | Description |
 |---|---|
 | **File-based storage** | One `.md` per memory: frontmatter holds metadata, the body holds content. No database, no hidden format |
-| **Automatic injection** | Every turn automatically scans the memory directory and picks the most relevant few by relevance to inject into context. The model "recalls" on the first turn, without having to go and read files itself |
+| **Automatic injection** | Every new question rescans the memory directory and re-picks the most relevant few for that question, injecting them into context before the model speaks — no file reading needed |
 | **The model can look things up too** | Two retrieval tools are also given to the model (`search_memory` / `read_memory`), so it can go through memories on its own and read the original text by line |
 | **Writes are not overwritten** | While you are editing and the model is changing things at the same time, the later write does not silently clobber the earlier one; the conflict is left as a pending record for you to decide which side to keep |
 | **Zero extra services** | No worker, no SQLite, no port, no long-running process, and no extra API key or cloud service (the only runtime dependency is the ordinary npm library `zod`) |
@@ -116,7 +116,7 @@ Then **open a new session** and try three steps:
 
 1. Tell the model "remember: my cat is called Zhima, and it likes sunbathing" — it writes this into the memory directory by its rules
 2. Open another **new session** and ask "what is my cat called"
-3. It should answer "Zhima" on the first turn — the memory was retrieved and injected automatically by the plugin; the model did not go and read files itself
+3. Its first reply should answer "Zhima" — the memory was retrieved and injected automatically by the plugin; the model did not go and read files itself
 
 <details>
 <summary>Manual install (if you do not want the CLI, or want to install a local development build)</summary>
@@ -415,7 +415,7 @@ The two things are moved **differently**, spelled out:
 | `SAGE_MEM_MAX_BASELINE` | `8` (1–50) | number of `baseline` slots |
 | `SAGE_MEM_STALE_DAYS` | `1` (0–365) | threshold for marking a heading 「保存于 N 天前」(saved N days ago); 0 = mark every one |
 | `SAGE_MEM_TASK_ID` | empty | scope of task checkpoints; empty falls back to the session id |
-| `SAGE_MEM_DEBUG` | off | debug logging; when on, the panel's **工具 ▾ → 注入调试** shows the last 8 injection attempts (read-only, never written to disk) |
+| `SAGE_MEM_DEBUG` | off | debug logging; when on, the panel's **工具 ▾ → 注入调试** shows the last 8 injection attempts (read-only, never written to disk; it also lists any memory kept out of the body by an expired `invalid_at` or an unresolved contradiction, with the reason and the conflict id) |
 | `SAGE_MEM_VALIDITY` | on | master switch for invalidity filtering and contradiction suppression. **Only `0` / `false` / `off` turn it off** (empty or misspelled values count as on); off restores the 1.9.x injection behaviour |
 
 Value semantics: **out-of-range values are clamped to the boundary, illegal values (including pure whitespace) fall back to the default.**

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.0.0`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.0.1`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。
@@ -72,7 +72,7 @@ sage-mem 补上这一层，做法是：**把该记住的事写成一张张卡片
 | 特性 | 说明 |
 |---|---|
 | **文件式存储** | 每条记忆一个 `.md`：frontmatter 存元数据，正文存内容。无数据库、无隐藏格式 |
-| **自动注入** | 每轮提问自动扫记忆目录、按相关度挑出最相关的几条注入上下文。模型第一轮就「想起来」，不需要它自己去翻文件 |
+| **自动注入** | 每条新问题都会重新扫一遍记忆目录，按这条问题挑出最相关的几条，在模型开口之前拼进上下文 —— 不用模型自己去翻文件 |
 | **模型也能自己查** | 另给模型两个检索工具（`search_memory` / `read_memory`），它可以主动翻记忆、按行读原文 |
 | **写入不被覆盖** | 你正在编辑、模型同时在改的时候，后写的不会静默盖掉先写的；冲突留成待处理记录，由你决定保留哪边 |
 | **零额外服务** | 无 worker、无 SQLite、无端口、无常驻进程，不需要额外的 API key 或云服务（运行时唯一的依赖是普通 npm 库 `zod`） |
@@ -116,7 +116,7 @@ dsh plugin --profile web list
 
 1. 跟模型说「记住：我的猫叫芝麻，它喜欢晒太阳」—— 它按规则把这条写进记忆目录
 2. 再开一个**新会话**，问「我的猫叫什么」
-3. 第一轮就该答出「芝麻」—— 记忆由插件自动检索并注入，模型没有主动去翻文件
+3. 它的第一个回答就该答出「芝麻」—— 记忆由插件自动检索并注入，模型没有主动去翻文件
 
 <details>
 <summary>手动安装（不想用 CLI，或要装本地开发版本）</summary>
@@ -415,7 +415,7 @@ sage-mem 给记忆目录的写入加了**版本守卫**：写入前记下当前
 | `SAGE_MEM_MAX_BASELINE` | `8`（1–50） | `baseline` 名额 |
 | `SAGE_MEM_STALE_DAYS` | `1`（0–365） | 标题标「保存于 N 天前」的门槛；0 = 每条都标 |
 | `SAGE_MEM_TASK_ID` | 空 | 任务检查点的作用域；空则回落会话 id |
-| `SAGE_MEM_DEBUG` | 关 | 调试日志；打开后面板「工具 ▾ → 注入调试」显示最近 8 次注入的账（只读、不落盘） |
+| `SAGE_MEM_DEBUG` | 关 | 调试日志；打开后面板「工具 ▾ → 注入调试」显示最近 8 次注入的账（只读、不落盘；同时列出被已失效标注 / 未裁决矛盾挡在正文外的记忆与理由，矛盾还带冲突 id） |
 | `SAGE_MEM_VALIDITY` | 开 | 失效过滤与矛盾抑制的总开关。**只认 `0` / `false` / `off` 为关闭**（空值、拼错都按开启）；关掉后回到 1.9.x 的注入行为 |
 
 取值语义：**越界夹到边界，非法值（含纯空格）回落默认。**

package/lib/client.js

@@ -2923,14 +2923,18 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			: null);
 
 		/**
-		 * 「注入调试」面板（1.7.0）。
+		 * 「注入调试」面板（1.7.0；2.0.1 起显示有效性抑制明细）。
 		 *
 		 * 只读：没有「清空 / 重跑」按钮 —— 账是注入链在 `SAGE_MEM_DEBUG=1` 时自动记的，
 		 * 人能做的是看，以及点「刷新」再取一次。入口只在开关打开时出现（宿主告诉我们）。
 		 *
-		 * 每一条记录的口径写在 `lib/recall/debug.js` 的 makeDebug 注释里；这里只负责把
+		 * 每一条记录的口径写在 `lib/recall/injector.js` 的 makeDebug 注释里；这里只负责把
 		 * 「为什么这一步没注入」翻译成人话 —— 那是这个面板存在的唯一理由。**尤其是
 		 * `empty + deduped`**：每轮多步里它占大多数，不解释就会被当成「插件坏了」。
+		 *
+		 * 2.0.0 让失效 / 未裁决矛盾的记忆不再进正文。2.0.1 把这两类的**文件名、理由与
+		 * 冲突 id** 单列一行：否则「这条记忆不见了」在面板上只能看到它不在 injected 里，
+		 * 分不清是没检索到还是被新规则挡住 —— 而那正是 2.0.0 之后最需要解释的一种消失。
 		 */
 		function RecallDebugPanel(props) {
 			const data = props.data || {};
@@ -2965,6 +2969,9 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				}));
 			}
 			const injected = latest && Array.isArray(latest.injected) ? latest.injected : [];
+			// 2.0.1：被有效性挡掉的条目。旧记录没有这个字段 → 空数组（面板显示「无」），
+			// 不因为多一个可选字段就把老账读崩。
+			const validitySuppressed = latest && Array.isArray(latest.validitySuppressed) ? latest.validitySuppressed : [];
 			const histogram = recs.slice(1).map(function (r, i) {
 				return h("div", { className: "smem-dbg-hist-row", key: "h" + i }, [
 					h("span", { className: "smem-dbg-time", key: "t" }, clock(r.at)),
@@ -3008,6 +3015,23 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 								"正文字节 " + String(latest.chars || 0) + "（本代累计 " + String(latest.sessionChars || 0) + "）" +
 								" · 状态卡 " + (latest.cardChars ? String(latest.cardChars) + " 字节" : "未发") +
 								" · 预算挡掉 " + String(latest.skippedByBudget || 0) + " 条"),
+							h("div", { className: "smem-dbg-row", key: "vs" }, [
+								h("span", { className: "smem-label", key: "l" }, "有效性抑制"),
+								validitySuppressed.length
+									? h("span", { className: "smem-dbg-scores", key: "v" }, validitySuppressed.map(function (x, i) {
+										const reason = String((x && x.label) || (x && x.reason) || "未知理由");
+										const cid = x && x.conflictId ? " · " + String(x.conflictId) : "";
+										return h("span", { className: "smem-dbg-score", key: String((x && x.file) || i) + "-" + i }, [
+											h("span", { className: "smem-dbg-file", key: "f" }, String((x && x.file) || "?")),
+											h("span", { className: "smem-dbg-num", key: "r" }, reason + cid),
+										]);
+									}))
+									: h("span", { className: "smem-muted", key: "v" }, "无"),
+							]),
+							validitySuppressed.length
+								? h("div", { className: "smem-ar-hint", key: "vshint" },
+									"被标失效或待裁决矛盾挡掉的记忆不会进正文 —— 这不是检索没命中，是 2.0.0 的有效性规则生效；去「冲突」页签可裁决。")
+								: null,
 							h("div", { className: "smem-ar-hint", key: "hint" },
 								"注入每走一步都会尝试一次；同题同命中集不会重复注入 —— 所以「空」多半是去重生效，不是坏了。"),
 							histogram.length

package/lib/recall/injector.js

@@ -26,6 +26,43 @@ import { buildCandidates, composeDelivery, composeStatus } from './compose.js'
 import { composeRecallText } from './text.js'
 import { debugEnabled, debugRecall, recordInjection } from './debug.js'
 
+/**
+ * 2.0.1：调试账里「被有效性挡掉」的两类理由（2.0.0 新引入的抑制）。
+ *
+ * ⚠️ **只收这两个**：`below_floor` / `budget_omitted` 等老理由在 2.0.0 之前就有，
+ * 它们的解释已经在面板的「预算挡掉 N 条」与得分列表里；而失效与未裁决矛盾是
+ * 2.0.0 让记忆**从正文里消失**的唯一原因 —— 不单列出来，用户与维护侧都只能靠
+ * 猜「这条到底是没检索到，还是被新规则挡住了」。
+ */
+const VALIDITY_SUPPRESS_REASONS = new Set(['expired_source', 'conflict_pending'])
+
+/** reason → 面板上的一句人话（英文由 client 侧字典决定，这里只给稳定键）。 */
+const VALIDITY_REASON_LABEL = Object.freeze({
+  expired_source: '已失效',
+  conflict_pending: '待裁决矛盾',
+})
+
+/**
+ * 从 `decideDelivery` 的逐条处置里挑出被有效性挡掉的，附上文件名、理由与（可选）冲突 id。
+ *
+ * 纯函数，给调试账用；**不影响注入结果** —— items 是决策的产物，这里只是把其中
+ * 两类 reason 摘出来。`conflictIds` 是「文件名 → 冲突记录 id」的映射：同一份文件被
+ * 多条记录牵扯时取第一条（按 `listConflictIndex` 的时间倒序），够定位就行。
+ */
+function validitySuppressedItems(items, conflictIds) {
+  const out = []
+  for (const it of Array.isArray(items) ? items : []) {
+    if (!it || !VALIDITY_SUPPRESS_REASONS.has(it.reason)) continue
+    const row = { file: String(it.file ?? ''), reason: it.reason, label: VALIDITY_REASON_LABEL[it.reason] }
+    if (it.reason === 'conflict_pending' && conflictIds instanceof Map) {
+      const id = conflictIds.get(row.file)
+      if (id) row.conflictId = id
+    }
+    out.push(row)
+  }
+  return out
+}
+
 /**
  * @param {object} deps
  * @param {object} deps.ctx — 宿主 ctx（`scanMemoryFiles` / `warnLog` 用）
@@ -95,6 +132,9 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
       // ⚠️ 只对 `contradiction` 进集合：写失败型记录里盘上那份仍是现行内容（§6.3）。
       let conflictsForDelivery = new Set()
       let pendingConflicts = 0
+      // 2.0.1：调试账用的「文件名 → 冲突记录 id」。只在开关打开时才读得到，但先按需
+      // 建一份空 Map（代价可忽略，比在 makeDebug 里为了 id 再扫一次队列便宜）。
+      const conflictIdByFile = new Map()
       const validity = validityEnabled()
       const expired = validity ? buildExpirySet(files, nowMs) : new Set()
       if (validity) {
@@ -104,6 +144,13 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
           const listed = await listConflictIndex({ stateRoot: STATE_ROOT })
           if (listed.ok) {
             conflictsForDelivery = buildContradictionFileSet(listed.items)
+            for (const c of listed.items) {
+              if (!c || c.status !== 'open' || c.kind !== 'contradiction') continue
+              for (const key of ['file', 'otherFile']) {
+                const name = typeof c[key] === 'string' ? c[key].trim() : ''
+                if (name !== '' && !conflictIdByFile.has(name)) conflictIdByFile.set(name, c.id)
+              }
+            }
             pendingConflicts = listed.items.filter((c) => c.status === 'open' && c.kind === 'contradiction').length
           } else {
             warnLog(ctx, `读冲突队列失败，本轮不做矛盾抑制：${listed.error ?? listed.code}`, sessionId)
@@ -162,7 +209,10 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
       //   - `sessionChars` = 本代累计正文字节（预算账）；
       //   - `cardChars` = 这一步发出去的状态卡字节（没发就是 0）；
       //   - `deduped` = 同题同命中集刚注过，这一步没重复追加 —— 面板上要解释成
-      //     「不是坏了，是去重生效」，否则每轮多步里大部分账看着都是空的。
+      //     「不是坏了，是去重生效」，否则每轮多步里大部分账看着都是空的；
+      //   - `validitySuppressed`（2.0.1）= 被 2.0.0 的有效性规则挡在正文外的条目，
+      //     带 `reason`（expired_source / conflict_pending）与 `label`；矛盾还带
+      //     `conflictId`，便于去「冲突」页签定位。**这不是检索失败**，是规则生效。
       const debugOn = debugEnabled()
       const makeDebug = debugOn
         ? (outcome) => ({
@@ -182,6 +232,7 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
             sessionChars: contentBytes,
             cardChars: cardPart ? Buffer.byteLength(cardPart, 'utf8') : 0,
             skippedByBudget: skippedForBudget,
+            validitySuppressed: validitySuppressedItems(delivered.delivery.items, conflictIdByFile),
             card: cardPart ? 'sent' : (status.cardText ? 'deduped-or-over-budget' : 'none'),
           })
         : () => null

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