@modusensus/dsh-mneme 0.8.4 → 0.8.5

package/src/guide.js

@@ -0,0 +1,44 @@
+// #249（第一批）：能力说明——写给模型的「怎么用这套记忆」，不是给用户的文案。
+//
+// 为什么英文、且只留一份正本：注入指引的参照实现全部用英文（ACP 的
+// ACP_SYSTEM_PROMPT + HOW_TO_COMPRESS_RULES、mnemon 的 ROUTING_GUIDANCE、
+// 宿主压缩摘要规则），仓库既有先例也是 src/tools.js 的工具描述硬编码英文。
+// src/lang.js 的 memory.language 管的是「生成出来的记忆内容与块内标题」，与本
+// 模块是两件事，故不并入 STR、不做 zh/en 双写（双写只会让两份文本日后漂移）。
+//
+// 两个承载位（#249 §5）：①工具描述——常驻、零注入成本，放「何时用这个工具」
+// 这类单工具指引（TOOL_GUIDE）；②系统提示段 order 150——放工具描述装不下的
+// 总则（优先序、何时查 / 何时写 / 何时 no-op）。该段必须同会话内稳定，否则
+// 每轮变化会作废其后的前缀缓存，因此这里全是常量，不含任何运行时插值。
+//
+// 前缀 `[dsh-mneme memory]` 是机械校验用的：测试按它断言「只在开时出现、且不
+// 逐轮复读」，也让维护者能一眼认出这段文本的归属。
+
+const SECTION_LINES = [
+  "[dsh-mneme memory] Read once; it applies to every turn of this session.",
+  "1. Precedence: the current instruction and the repository's actual state outrank any stored memory. " +
+    "When a memory contradicts either, check the instruction or the repository itself before relying on it — memory_search " +
+    "searches stored memories only, so it finds earlier context, never the present state. Never treat an old memory as current fact.",
+  "2. Recall on demand: call memory_search when the task depends on earlier decisions, user preferences, or project history " +
+    "that is not already in context. Do not search for facts you can read directly from the repository.",
+  "3. Write back sparingly: use memory_save for durable, cross-session value — a preference, a decision with its rationale, " +
+    "an engineering constraint, a pitfall with its root cause. Trivial single-turn work is not worth a memory.",
+  "4. When unsure, do nothing. Not acting is a valid outcome: a useless memory is paid for by every future session.",
+  "5. Prefer the reversible tools. memory_archive hides an entry from lists, search, injection and consolidation, and " +
+    "memory_forget suppresses it from injection, search results and lists — both are recoverable. memory_delete is permanent, " +
+    "so reach for it only when an entry is wrong or unwanted, not merely stale."
+];
+
+/** 系统提示段（order 150）的总则文本。常量：同会话内稳定是硬约束。 */
+export const MEMORY_GUIDE_SECTION = SECTION_LINES.join("\n");
+
+/** 单工具判断指引，追加到对应工具描述尾部（`injectGuidanceEnabled` 开启时）。 */
+export const TOOL_GUIDE = {
+  memory_search:
+    " Use this when the task depends on earlier decisions, preferences, or project history that is not already in context, " +
+    "or to look for a newer memory behind one that seems stale. " +
+    "Skip it for facts you can read directly from the repository.",
+  memory_save:
+    " Save only durable, cross-session value (a preference, a decision with its rationale, an engineering constraint, " +
+    "a pitfall with its root cause). Trivial single-turn work does not belong here, and when unsure, do not save."
+};

package/src/heat.js

@@ -16,6 +16,8 @@ export const TYPE_DECAY_DEFAULTS = Object.freeze({
   preference: 0,    // 免疫：用户画像需长期保持
   pattern: 0,       // 免疫：发现型稳定规律
   summary: 0,       // 免疫：已是压缩产物
+  document: 0,      // 免疫：指针行（#230）——全文在文件系统，行失效靠 supersede
+                    // 记账而非遗忘；遗忘曲线灭掉指针 = 按需读全文的入口消失
   project: 0.0008,  // 慢衰减
   decision: 0.002,  // 中速衰减
   history: 0.006,   // 较快（会话摘要不断被合并）

package/src/inject.js

@@ -1,6 +1,19 @@
 import { createScopeResolver } from "./scope.js";
 import { createHotMemory } from "./hot-memory.js";
 import { STR, langOf } from "./lang.js";
+import { MEMORY_GUIDE_SECTION } from "./guide.js";
+import { adaptiveInjectBudget } from "./search/adaptive.js";
+
+// Issue #179：注入预览的数据底座。systemPrompt 渲染是同步回调，面板只能事后
+// 拉取，所以在这里旁路缓存「最近一帧组装」——快照就是本次渲染用过的同一份
+// candidates/hotText/body，不重新检索、不二次组装，零额外开销。模块级单例：
+// 注入器全局唯一（index.js 仅在 autoInject 开启时注册一个），面板经 api.js 的
+// 只读 getter 读取；autoInject 关闭时注入器不存在，快照保持 null——「预览
+// 不可用」本身就是「注入关闭」的诚实呈现。
+let injectionSnapshot = null;
+export function getInjectionSnapshot() {
+  return injectionSnapshot;
+}
 
 // Best-effort extraction of the current user's latest message text from the
 // live session, for semantic-first injection (Bug4). The system-prompt
@@ -92,7 +105,7 @@ function extractRounds(ctx, maxRounds) {
 
 export function createInjector(ctx, service, settings, config) {
   const language = langOf(config);
-  const maxItems = config.maxInjectedItems ?? 5;
+  const baseMaxItems = config.maxInjectedItems ?? 5;
   const threshold = config.importanceThreshold ?? 3;
   // Issue #205：注入位跨轮轮换。rotationTurns = 最近 N 个「不同用户查询」轮次
   // 注入过的记忆本轮不再优先（0 = 关闭，保持既有行为）。历史按会话维护——
@@ -143,13 +156,18 @@ export function createInjector(ctx, service, settings, config) {
   // stale 1500) and an entry that would exceed it collapses to its title only.
   const maxContent = config.injectContentMaxChars ?? 300;
   const MAX_BLOCK = Math.max(1500, maxContent + 600);
+  // #249 第一批：pin 条目的正文硬顶。逐字保真不等于无界——单条上限取
+  // injectContentMaxChars 与 2000 的较大者，默认档下约束/偏好不会因常规截断
+  // 失真，同时给「一条超长约束每轮吃满常驻段」留一道闸（超顶仍带截断提示）。
+  const PINNED_CONTENT_MAX = Math.max(maxContent, 2000);
 
-  // Compressed injection (v0.5.0 2.1): a sleep-demoted row already carries its
-  // summary in `content` with the original parked in `_full_content` — inject
-  // the summary verbatim instead of re-truncating the (already short) text.
-  // Regular long rows keep the hard truncate.
+  // Compressed injection (v0.5.0 2.1): a sleep-demoted row carries its summary in
+  // `content` with the original parked in `_full_content` — inject the summary
+  // verbatim instead of re-truncating the (already short) text. 但「降级过」不等于
+  // 「天然够短」：原先那条 `_full_content` 早返回的唯一效果就是**跳过 maxLength**
+  // （两条分支取的都是 m.content），于是 pin 的硬顶在这一路上形同不存在（#266 评审）。
+  // 现在只有一条截断路径：超限照旧带提示，原文永远可通过 memory_get 取回。
   function injectMemory(m, maxLength = maxContent) {
-    if (m?._full_content) return String(m.content ?? "");
     const text = String(m?.content ?? "");
     if (text.length <= maxLength) return text;
     return `${text.slice(0, maxLength)}…${STR.truncatedHint[language](maxLength, text.length, m.id)}`;
@@ -192,26 +210,41 @@ export function createInjector(ctx, service, settings, config) {
     return escapePromptVars(STR.hotHeader[language](rounds.length, body));
   }
 
-  function render(candidates) {
+  function render(candidates, pinnedStats = null) {
     if (!candidates.length) return "";
     const header = STR.memoryHeader[language];
     const lines = [header];
     let budget = MAX_BLOCK - header.length;
-    for (const m of candidates) {
+    // #249 第一批：pin 池（约束/偏好）排在块头且不参与块的塌缩预算——「与情景
+    // 日志抢同一份预算后被降级」正是本议题要修的结构缺陷。单条仍有硬顶
+    // （PINNED_CONTENT_MAX），超出照旧带截断提示，不静默。
+    const pinnedCount = Math.max(0, Math.min(candidates.length, pinnedStats?.shown ?? 0));
+    for (let i = 0; i < candidates.length; i++) {
+      const m = candidates[i];
+      const pinned = i < pinnedCount;
       // Epistemic trust (v0.4.5): when enabled, measured observations are
       // flagged so the agent can weigh them above guesses/opinions.
       const verified = config.trustEpistemicWeighting === true && m.epistemic_status === "observation"
         ? STR.verified[language]
         : "";
       const title = STR.entryTitle[language](m.title, m.importance);
-      const content = injectMemory(m);
+      const content = injectMemory(m, pinned ? PINNED_CONTENT_MAX : maxContent);
       const full = STR.entryLine[language](m.type, verified, title, content);
-      if (budget - full.length >= 0) {
+      if (pinned) {
+        // pin 不扣块预算（上面那条设计注释的落地）：pin 一条就够击穿 MAX_BLOCK
+        // （PINNED_CONTENT_MAX 2000 > MAX_BLOCK 1500），照扣会把 budget 压成负数，
+        // 同一轮随后的普通候选全部退化成标题行——正是本议题要修的结构缺陷。
+        lines.push(full);
+      } else if (budget - full.length >= 0) {
         lines.push(full);
         budget -= full.length;
       } else {
         lines.push(`- [${m.type}] ${verified}${title}`);
       }
+      if (pinned && i === pinnedCount - 1) {
+        const hidden = Math.max(0, pinnedStats?.suppressed ?? 0);
+        if (hidden > 0) lines.push(STR.pinnedOverflow[language](hidden));
+      }
     }
     return escapePromptVars(lines.join("\n"));
   }
@@ -250,7 +283,17 @@ export function createInjector(ctx, service, settings, config) {
     return escapePromptVars(lines.join("\n"));
   }
 
+  // #249 第一批：能力说明的系统提示段。order 150 = 插件指引段的既有惯例
+  // （ACP 的 ACP_SYSTEM_PROMPT 与 mnemon 的 routing 段都在 150）。文本是常量、
+  // 同会话内不随轮次变化，故不影响其后的前缀缓存，也不逐轮复读。宿主若不提供
+  // section seam 就静默跳过——#249 §3 的口径是「只用现成 seam，拿不到位的语义
+  // 降级处理」：能力说明仍落在工具描述上，不算失败。
+  const guideSection = config.injectGuidanceEnabled === true && typeof ctx.systemPrompt?.section === "function"
+    ? ctx.systemPrompt.section({ name: "memory-guide", order: 150, text: MEMORY_GUIDE_SECTION })
+    : null;
+
   const disposers = [
+    ...(guideSection ? [guideSection] : []),
     ctx.systemPrompt.context({
       name: "memory",
       order: 90,
@@ -270,16 +313,48 @@ export function createInjector(ctx, service, settings, config) {
         const rotate = recentInjectedIds(sessionId, query);
         // rotateWindow 随集合一起传入：候选池按 maxItems×(N+1) 扩容——窗口要的
         // 牌比既有 maxItems×2 池多时，轮换才有新鲜牌可换（#205 补测）。
-        const candidates = service.injectCandidates({ query, queryVector, maxItems, threshold, scope, rotate, rotateWindow: rotationTurns });
-        recordInjection(sessionId, query, candidates);
+        // Issue #239（第 5 项）：注入条数的查询自适应（默认关）。确定性强的话题收缩
+        // 条数、模糊话题维持上限——单向收缩，绝不越过 maxInjectedItems；判据只看查询
+        // 本身，不做额外检索（先探针检索等于白付一次 fuseRecall）。
+        const maxItems = config.injectUncertaintyAdaptive === true
+          ? adaptiveInjectBudget(query, baseMaxItems)
+          : baseMaxItems;
+        // #249 第一批：pin 池统计走可选出参，不动 injectCandidates 的数组契约。
+        const pinnedStats = {};
+        const candidates = service.injectCandidates({ query, queryVector, maxItems, threshold, scope, rotate, rotateWindow: rotationTurns, pinnedStats });
+        // #249：pin 条目不进轮换历史——它们每轮固定前置，记进去只会占满轮换
+        // 窗口、挤掉情景候选的新鲜度（验收：pin 不参与跨轮轮换）。
+        recordInjection(sessionId, query, pinnedStats.shown > 0 ? candidates.slice(pinnedStats.shown) : candidates);
         // Hot memory (v0.5.0 1.3) leads the single memory block: the agent
         // sees the short-term rounds first, then the cross-session recall —
         // the documented injection order 1→2. Folding it here (instead of a
         // separate context) keeps the prompt assembly stable at two blocks.
         const hotText = renderHotContext(ctx);
-        const body = render(candidates);
-        if (!hotText) return body;
-        return body ? `${hotText}\n\n${body}` : hotText;
+        const body = render(candidates, pinnedStats);
+        const finalBody = !hotText ? body : body ? `${hotText}\n\n${body}` : hotText;
+        // Issue #179：旁路缓存一帧——面板「注入预览」卡据此展示构成与体积。
+        // chars 为条目内容的截断后近似值（与 render 同一函数计长），totalChars
+        // 是本次实际返回块的精确长度。maxItems 反映自适应收缩后的生效值。
+        injectionSnapshot = {
+          at: Date.now(),
+          sessionId,
+          query: query || "",
+          maxItems,
+          threshold,
+          adaptive: config.injectUncertaintyAdaptive === true,
+          scoped: scope && (scope.agent_scope || scope.workspace_scope) ? scope : null,
+          rotated: rotate ? rotate.size : 0,
+          hotChars: hotText.length,
+          entries: candidates.map((m) => ({
+            id: m.id,
+            type: m.type,
+            title: m.title,
+            importance: m.importance,
+            chars: injectMemory(m).length
+          })),
+          totalChars: finalBody.length
+        };
+        return finalBody;
       }
     }),
     ctx.systemPrompt.context({
@@ -292,6 +367,7 @@ export function createInjector(ctx, service, settings, config) {
   return () => {
     queryVectorCache.clear();
     rotationHistory.clear();
+    injectionSnapshot = null; // 注入器卸载即失效：快照不得跨生命周期存留
     for (const dispose of disposers) {
       if (typeof dispose === "function") dispose();
     }

package/src/lang.js

@@ -75,6 +75,12 @@ export const STR = {
     zh: (max, len, id) => `〔已截断：上限 ${max}，原 ${len} 字符；全文用 memory_get "${id}" 查看〕`,
     en: (max, len, id) => `[truncated: limit ${max}, original ${len} chars; memory_get "${id}" for full text]`
   },
+  // Issue #249（第一批）：pin 池超预算时的如实标注——分层不等于丢弃，也不允许
+  // 静默省略未展示条数（agent 才知道库里的约束不止这几条，需按需 memory_search）。
+  pinnedOverflow: {
+    zh: (n) => `〔约束/偏好类另有 ${n} 条未展示〕`,
+    en: (n) => `[${n} more constraint/preference entries not shown]`
+  },
   userSettingsHeader: {
     zh: "[用户设置] 来自 dsh-mneme 的用户画像与规则：",
     en: "[User settings] Profile and rules from dsh-mneme:"