@modusensus/dsh-mneme 0.8.4 → 0.8.6

package/lib/dream.js

@@ -6,7 +6,6 @@ import { createHash, randomUUID } from "node:crypto";
 import { STR, langOf } from "./lang.js";
 export { validateDecisions, applyDecisions, withEffortFallback, describeStreamFailure, resolveDreamEffort, resolveRoute };
 
-
 // Extract the first JSON array from LLM output, tolerating markdown fences,
 // leading/trailing prose, and common wrapper noise. Returns an array or null.
 function extractJsonArray(text) {
@@ -232,7 +231,12 @@ async function streamText(ctx, options, onUsage, onStreamError) {
   let text = "";
   for await (const chunk of ctx.llm.stream(options)) {
     if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
-    if (chunk.type === "usage" && typeof onUsage === "function") onUsage(chunk);
+    // DSH 的 StreamChunk 契约把用量嵌在 chunk.usage（TokenUsage：inputTokens /
+    // outputTokens / …），chunk 顶层没有 token 字段——把整个 chunk 当用量对象交给
+    // reporter，input/output 恒为 undefined，审计行落 0（v0.8.4 实测：7 天 49 次
+    // success 调用 token 全 0，面板「LLM 消耗」长期显示 0）。`?? chunk` 兜底把用量
+    // 平铺在顶层的替身。
+    if (chunk.type === "usage" && typeof onUsage === "function") onUsage(chunk.usage ?? chunk);
     if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
       // dsh-llm rc.1 turns adapter-stage failures (unknown provider route,
       // UNSUPPORTED_REASONING_EFFORT from resolveCallWithInfo, …) into a
@@ -382,7 +386,7 @@ async function reEmbedMemory(semantic, memory, logger) {
  * 任何失败降级为 0 条，绝不反噬 dream 主流程。
  */
 async function generateNarratives({ ctx, service, config, route, language, effort, semantic, logger }) {
-  const inputs = service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary");
+  const inputs = service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary" && m.type !== "document");
   const clusters = clusterByTag(inputs, { minCluster: config.dreamNarrativeMinCluster ?? 3 });
   if (!clusters.length) return 0;
 
@@ -740,7 +744,7 @@ export async function maintainIndexAfterDream(decisions, service, semantic) {
   if (embedder.modelHash) vectorIndex.markModel?.(embedder.modelHash, embedder.dimension);
 }
 
-export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChars = 5000, delayMs = 2000, minIntervalMs = 0, logger, semantic = null }) {
+export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChars = 5000, delayMs = 2000, minIntervalMs = 0, logger, semantic = null, lastRunAtSeed = 0 }) {
   let pendingTimer = null;
   let running = false;
   let disposed = false;
@@ -748,10 +752,12 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
   let inFlight = null;
   // Issue #89（请求 2）：上一次实际开跑时刻。失败/degraded 的 run 也占用
   // 最小间隔——节流的目的正是防止失败调用连发；间隔内的触发静默跳过。
-  let lastRunAt = 0;
+  // lastRunAtSeed：调用方从 dream_runs 审计表读出的上次开跑时刻——
+  // 内存变量进程重启即归零，闸门对新实例放行 → 重启后立刻连发（#89 根因）。
+  let lastRunAt = lastRunAtSeed;
 
   function shouldTrigger(service) {
-    const memories = service.all().filter((m) => !m.archived && m.type !== "summary");
+    const memories = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
     const count = memories.length;
     const chars = totalChars(memories);
     const overBase = count >= baseline.count + thresholdCount || chars >= baseline.chars + thresholdChars;
@@ -814,8 +820,10 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
   async function runDream(ctx, service, config) {
     const language = langOf(config);
     const logger = ctx.logger;
-    let memories = service.all().filter((m) => !m.archived && m.type !== "summary");
+    let memories = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
     if (memories.length === 0) return { ok: true, applied: 0, skipped: true, summary: false };
+    // Issue #89：开跑时刻既喂给审计行（created_at），也是调度器闸门的时间基准。
+    const dreamStartedAt = Date.now();
     // v0.4.4 滑动窗口：只 consolidation 最近 dreamMaxSnapshotSize 条记忆，
     // 窗口外的旧记忆不进 snapshot（大记忆量下全量快照会撑爆 LLM 输入，配合
     // 隐式 keep 让 run 始终可收敛）。按 updated_at 倒序取前 maxSize 条。
@@ -882,6 +890,9 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       try {
         service.saveDreamRun({
           id: runId,
+          // Issue #89：审计行记开跑时刻而非完成时刻——lastDreamRunAt 以它做
+          // 重启后的间隔种子，落完成时刻会让 run 耗时白白计入下一轮最小间隔。
+          created_at: new Date(dreamStartedAt).toISOString(),
           status,
           error: result.error,
           provider: route?.provider,
@@ -1206,15 +1217,21 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     let summaryStreamFailure = "";
     const runSummary = (withEffort) => {
       summaryStreamFailure = "";
+      // Issue #258：总览阶段可用 dreamSummaryProvider/dreamSummaryModel 走独立路由
+      //（默认空 = 沿用 dream 路由）；输入侧有 dreamSummaryMaxInputs 硬上限，
+      // 按窗口同款 updated_at 倒序保留最新的（见下方 summaryInputs）。
+      const summaryRoute = (config.dreamSummaryProvider && config.dreamSummaryModel)
+        ? { provider: config.dreamSummaryProvider, model: config.dreamSummaryModel }
+        : route;
       return runAuditedLlm(ctx, service, config, {
       triggerSource: "autoDream",
       operationType: "dream_summarize",
-      modelId: `${route.provider}:${route.model}`,
+      modelId: `${summaryRoute.provider}:${summaryRoute.model}`,
       relatedMemoryIds: [],
       streamError: () => summaryStreamFailure
     }, (reportUsage) => streamText(ctx, {
-      provider: route.provider,
-      model: route.model,
+      provider: summaryRoute.provider,
+      model: summaryRoute.model,
       purpose: "compaction",
       maxTokens: config.dreamMaxTokens ?? 2048,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
@@ -1229,7 +1246,25 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // v1, content_history traceable). Its 口径 (what snapshot produced it) is
     // stamped into the content so the standing answer is always auditable; the
     // formal evidence column lands with the narrative-bars batch.
-    const summaryInputs = service.all().filter((m) => !m.archived && m.type !== "summary");
+    // Issue #258：输入硬上限（条数）——原全库无界，把 dream 路由指向小 ctx
+    // 模型时 120k token 当场 CONTEXT_WINDOW_EXCEEDED（#258 实测），且随库增长
+    // 渐进恶化。倒序排序与 consolidate 窗口同款（updated_at desc, id tiebreak），
+    // 保留最新的；0 = 关闭上限（回归全库行为，调用方自担 ctx）。
+    // #230：document 指针行不进总览（与 dream/sleep 五个候选池的同款排除）。
+    const summaryAll = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
+    const summaryMaxInputs = Number.isInteger(config.dreamSummaryMaxInputs) ? config.dreamSummaryMaxInputs : 0;
+    const summaryInputs = summaryMaxInputs > 0 && summaryAll.length > summaryMaxInputs
+      ? [...summaryAll]
+        .sort((a, b) => {
+          const ta = String(a.updated_at ?? "");
+          const tb = String(b.updated_at ?? "");
+          if (ta < tb) return 1;
+          if (ta > tb) return -1;
+          return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+        })
+        .slice(0, summaryMaxInputs)
+      : summaryAll;
+
     const summaryScope = STR.summaryScope[language](
       summaryInputs.length,
       runId.slice(0, 8),

package/lib/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/lib/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/lib/index.js

@@ -43,7 +43,15 @@ export { Config };
 // unit-testable; the extractor only ever sees a callLLM(messages, options)
 // => Promise<string>. The route always carries a real provider/model (dsh-llm
 // GenerateOptions requires both) — never a bare stream.
-export function createEntityStreamAdapter({ llm, agentDefaultModel, logger }) {
+//
+// Issue #250: it also accounts for itself. Entity extraction is the background
+// LLM path that runs on every memory write, yet it never reached
+// llm_audit_logs — the adapter only ever held an llm handle, so it had no way
+// to call service.saveLlmAudit. It now takes service (+ config for the shared
+// llmAudit.enabled gate) and writes one row per stream attempt, matching the
+// contract of runAuditedLlm in dream.js: a rejected effort attempt records its
+// own error row and the retry records its own success row.
+export function createEntityStreamAdapter({ llm, agentDefaultModel, logger, service, config }) {
   return async function streamEntityText(messages, options = {}) {
     let route = {};
     if (options.provider) route.provider = options.provider;
@@ -58,8 +66,38 @@ export function createEntityStreamAdapter({ llm, agentDefaultModel, logger }) {
       } catch { /* fall through to whatever route we already have */ }
     }
     const effort = options.reasoningEffort;
+    // 没有解析出 provider/model 就没有可归属的模型——与 dream 的 resolveRoute
+    // 无路由早退同口径，那种情况不写审计行。
+    const modelId = route.provider && route.model ? `${route.provider}:${route.model}` : "";
     const tryStream = (withEffort) => {
       let text = "";
+      let inputTokens = 0;
+      let outputTokens = 0;
+      const startedAt = Date.now();
+      const timestamp = new Date(startedAt).toISOString();
+      // 记账是 best-effort：写审计行失败只 warn，绝不反噬抽取本身（CONTRIBUTING
+      // 的 fail-safe 硬约定）。
+      const writeAudit = (status, errorMessage) => {
+        if (config?.llmAudit?.enabled === false || !modelId || typeof service?.saveLlmAudit !== "function") return;
+        try {
+          service.saveLlmAudit({
+            timestamp,
+            trigger_source: "entityExtract",
+            operation_type: "entity_extract",
+            model_id: modelId,
+            input_tokens: inputTokens,
+            output_tokens: outputTokens,
+            total_tokens: inputTokens + outputTokens,
+            cost_usd: 0,
+            duration_ms: Date.now() - startedAt,
+            status,
+            error_message: errorMessage,
+            related_memory_ids: []
+          });
+        } catch (auditError) {
+          logger?.warn?.(`dsh-mneme: entity extraction llm audit write failed: ${String(auditError)}`);
+        }
+      };
       return (async () => {
         for await (const chunk of llm.stream({
           ...route,
@@ -68,11 +106,26 @@ export function createEntityStreamAdapter({ llm, agentDefaultModel, logger }) {
           messages
         })) {
           if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
-          if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) return undefined;
+          // DSH 的 StreamChunk 契约把用量嵌在 chunk.usage（TokenUsage）；兼容直接
+          // 平铺在 chunk 上的旧形态。归一放在这里，下面只需认平铺形状——与
+          // dream.js 的 streamText 同一处理。
+          if (chunk.type === "usage") {
+            const u = chunk.usage ?? chunk;
+            const i = u.input_tokens ?? u.inputTokens ?? u.prompt_tokens ?? u.promptTokens;
+            const o = u.output_tokens ?? u.outputTokens ?? u.completion_tokens ?? u.completionTokens;
+            if (Number.isFinite(i)) inputTokens = i;
+            if (Number.isFinite(o)) outputTokens = o;
+          }
+          if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
+            writeAudit("error", "llm stream aborted or errored");
+            return undefined;
+          }
         }
+        writeAudit("success", null);
         return text;
       })().catch((err) => {
         logger?.warn?.(`[dsh-mneme] entity extraction llm stream failed: ${String(err)}`);
+        writeAudit("error", String(err?.message ?? err));
         return undefined;
       });
     };
@@ -273,6 +326,9 @@ export const apply = (ctx, config) => {
         dimension: cfg.localEmbedDimension,
         device: cfg.localEmbedDevice,
         batchSize: cfg.localEmbedBatchSize,
+        // 池化方式必须与模型的训练口径一致（BGE 系 = CLS）。它既进 embed() 的调用，
+        // 也进 modelHash —— 池化改了就是换向量空间，既有索引会被判失配并重建。
+        pooling: cfg.localEmbedPooling,
         cacheDir: cfg.embedModelCacheDir,
         runtimeDir: cfg.runtimeDir,
         // #188：embedModelMirror 接成 transformers 的下载镜像（此前死配置）。
@@ -403,6 +459,7 @@ export const apply = (ctx, config) => {
       minIntervalMs: (cfg.dreamMinIntervalMinutes ?? 0) * 60000,
       logger: ctx.logger,
       semantic: { embedder, vectorIndex },
+      lastRunAtSeed: store.lastDreamRunAt("auto"),
       onRun: () => (dream ? dream.runDream(ctx, service, cfg) : Promise.resolve({ ok: true, skipped: true }))
     });
     service.setDreamHook(() => dream.maybeSchedule(service));
@@ -419,6 +476,7 @@ export const apply = (ctx, config) => {
       service,
       config: cfg,
       logger: ctx.logger,
+      lastRunAtSeed: store.lastDreamRunAt("sleep"),
       onRun: (signal) => (sleep ? runSleep(ctx, service, cfg, ctx.logger, { embedder, vectorIndex }, signal) : Promise.resolve({ ok: true, skipped: true }))
     });
     service.setSleepHook(() => sleep.noteWrite());
@@ -442,7 +500,11 @@ export const apply = (ctx, config) => {
       const streamEntityText = createEntityStreamAdapter({
         llm: ctx.llm,
         agentDefaultModel: ctx.agentDefaultModel,
-        logger: ctx.logger
+        logger: ctx.logger,
+        // Issue #250: the adapter needs service to write its llm_audit_logs row
+        // (it never had it) and config for the shared llmAudit.enabled gate.
+        service,
+        config: cfg
       });
       service.setEntityExtractor((memory) =>
         extractEntities(memory, { store, config: cfg, callLLM: streamEntityText, logger: ctx.logger })

package/lib/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/lib/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:"

package/lib/local-embedder.js

@@ -21,6 +21,32 @@ function modelHash(model) {
   return `${model}#${hashString(model)}`;
 }
 
+/**
+ * Model families whose embedding is the CLS token rather than a mean over tokens.
+ *
+ * BGE (BAAI/bge-*) is trained that way: the model's own `1_Pooling/config.json`
+ * declares `pooling_mode_cls_token: true` / `pooling_mode_mean_tokens: false`, and
+ * the official README says "select the last hidden state of the first token" plus
+ * L2 normalization. transformers.js's `feature-extraction` defaults to `mean`, so
+ * feeding it a BGE model silently produces slightly-off vectors — no error, just a
+ * worse ranking. This table is the extension point: a family goes in only once its
+ * pooling is confirmed against the model's own `1_Pooling` (or equivalent) config.
+ */
+const CLS_POOLED_MODEL_PATTERNS = [/bge/i];
+
+/**
+ * Resolve the pooling to embed with.
+ *
+ * `auto` (default) picks by model family — BGE → `cls`, everything else → `mean`,
+ * so models that were never affected keep their exact previous behavior. An
+ * explicit `cls` / `mean` wins over the family table.
+ */
+export function resolvePooling(pooling, model) {
+  const mode = String(pooling ?? "auto").trim().toLowerCase();
+  if (mode === "cls" || mode === "mean") return mode;
+  return CLS_POOLED_MODEL_PATTERNS.some((re) => re.test(String(model ?? ""))) ? "cls" : "mean";
+}
+
 /**
  * Lazy default loader: dynamic import keeps module load cheap.
  *
@@ -71,8 +97,9 @@ function tensorToRows(tensor) {
 
 /**
  * ONNX text embedder backed by transformers.js (onnxruntime-node underneath).
- * Runs fully offline with mean pooling + L2 normalization for BERT-style
- * models like bge-small-zh. `engineFactory` is injectable for tests.
+ * Runs fully offline; pooling is resolved per model family (BGE → CLS, else mean —
+ * see resolvePooling) and vectors are L2-normalized. `engineFactory` is injectable
+ * for tests.
  */
 export class LocalEmbedder {
   constructor(opts = {}) {
@@ -87,6 +114,10 @@ export class LocalEmbedder {
     // （含测试）保持裸 fetch 的现状，配置默认值由 index.js 传进来。
     this.resilientModelDownload = opts.resilientModelDownload === true;
     this.useDtype = opts.useDtype || "q8";
+    // 池化：配置值（auto/cls/mean）→ 生效值（cls/mean）。解析结果既进 embed()，
+    // 也进 modelHash —— 换池化就是换向量空间，旧索引必须被判失配后重建。
+    this.poolingMode = String(opts.pooling ?? "auto").trim().toLowerCase();
+    this.pooling = resolvePooling(this.poolingMode, this.model);
     // 模型镜像下载源（embedModelMirror，#188 补充）：空 = transformers 默认。
     this.remoteHost = String(opts.remoteHost ?? "").trim();
     this.logger = opts.logger ?? null;
@@ -114,19 +145,19 @@ export class LocalEmbedder {
     this.extractor = await this.engineFactory("feature-extraction", this.model, options);
     this.ready = true; // service reads this to flush queued re-embeds
     this.logger?.info?.(
-      `[dsh-mneme] local embedder ready: ${this.model} (dim=${this._dimension}, device=${this.device})`
+      `[dsh-mneme] local embedder ready: ${this.model} (dim=${this._dimension}, device=${this.device}, pooling=${this.pooling})`
     );
     return this;
   }
 
-  /** Embed many texts with mean pooling; chunks at batchSize. */
+  /** Embed many texts with the model's pooling; chunks at batchSize. */
   async embed(texts) {
     if (!Array.isArray(texts)) throw new TypeError("embed expects an array of strings");
     if (!this.extractor) throw new Error("LocalEmbedder not initialized");
     const out = [];
     for (let i = 0; i < texts.length; i += this.batchSize) {
       const chunk = texts.slice(i, i + this.batchSize);
-      const tensor = await this.extractor(chunk, { pooling: "mean", normalize: true });
+      const tensor = await this.extractor(chunk, { pooling: this.pooling, normalize: true });
       out.push(...tensorToRows(tensor));
     }
     return out;
@@ -142,7 +173,14 @@ export class LocalEmbedder {
   }
 
   get modelHash() {
-    return modelHash(this.model);
+    // Pooling is part of the vector space: a CLS index cannot be queried with mean
+    // vectors (or vice versa). Keep the historical `model#hash` shape for `mean` so
+    // indexes that were never affected are not invalidated needlessly; every other
+    // pooling gets a fingerprint of its own, which makes the index-consistency gate
+    // flag the stale mean-space index and rebuild it.
+    return this.pooling === "mean"
+      ? modelHash(this.model)
+      : modelHash(`${this.model}@${this.pooling}`);
   }
 
   dispose() {