@modusensus/dsh-mneme 0.8.4 → 0.8.5

package/lib/summarize.js

@@ -256,13 +256,136 @@ function enqueueDistill(task, intervalMs = 0) {
   return run;
 }
 
-export function createSummarizer(ctx, service, config) {
+// Issue #239（第 4 项，错峰队列）：高峰时段解析与判定。纯函数、可单测——排程判断
+// 不绑死真实时钟，测试才能确定性地覆盖跨零点、多段、星期过滤与非法写法。
+// spec 语法：`[<星期> ]<时段>[,<时段>...]`，星期前缀可省（省 = 每天）：
+//   "09:00-18:00"                        每天 09:00-18:00
+//   "mon-fri 08:00-12:00,14:00-18:00"    工作日两段（ISO 1=周一…7=周日，也认 mon..sun）
+//   "sat,sun 23:00-06:00"                周末跨零点段
+// 时间取宿主本地时区。任一写法非法 → 整串视为未配置（返回 null）：排程是省钱手段，
+// 绝不该因为写错格式把蒸馏停掉。
+const DAY_NAMES = { mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6, sun: 7 };
+
+function parseDayToken(token) {
+  const days = new Set();
+  const normalize = (value) => (/^\d$/.test(value) ? Number(value) : DAY_NAMES[value] ?? null);
+  for (const piece of token.split(",")) {
+    const matched = /^([a-z]{3}|\d)(?:-([a-z]{3}|\d))?$/.exec(piece.trim().toLowerCase());
+    if (!matched) return null;
+    const from = normalize(matched[1]);
+    const to = matched[2] === undefined ? from : normalize(matched[2]);
+    if (from === null || to === null || from < 1 || from > 7 || to < 1 || to > 7) return null;
+    // 支持跨周环绕（fri-mon）：从 from 起逐天推进到 to，最多绕一圈。
+    for (let day = from; ; day = (day % 7) + 1) {
+      days.add(day);
+      if (day === to) break;
+    }
+  }
+  return days.size > 0 ? [...days].sort((a, b) => a - b) : null;
+}
+
+/** JS 的 getDay() 是 0=周日…6=周六；这里统一成 ISO（1=周一…7=周日）。 */
+function isoDay(date) {
+  const day = date.getDay();
+  return day === 0 ? 7 : day;
+}
+
+export function parsePeakSpec(spec) {
+  if (typeof spec !== "string" || spec.trim() === "") return null;
+  let rest = spec.trim();
+  let days = null;
+  // 星期前缀 = 第一个空白之前的部分，但**头段含冒号就不是前缀**（那是时段本身，
+  // 例如 "09:00-12:00, 14:00-18:00" 里的逗号空格）。前缀解析失败一律按未配置处理，
+  // 不做猜测——宁可不省，也不能误停。
+  const sep = rest.search(/\s/);
+  if (sep > 0) {
+    const head = rest.slice(0, sep);
+    if (!head.includes(":")) {
+      days = parseDayToken(head);
+      if (days === null) return null;
+      rest = rest.slice(sep).trim();
+    }
+  }
+  const windows = [];
+  for (const part of rest.split(",")) {
+    const matched = /^\s*(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})\s*$/.exec(part);
+    if (!matched) return null;
+    const [sh, sm, eh, em] = [Number(matched[1]), Number(matched[2]), Number(matched[3]), Number(matched[4])];
+    if (sh > 23 || eh > 23 || sm > 59 || em > 59) return null;
+    const start = sh * 60 + sm;
+    const end = eh * 60 + em;
+    if (start === end) return null;
+    windows.push({ start, end });
+  }
+  return windows.length > 0 ? { days, windows } : null;
+}
+
+/**
+ * 该时刻是否落在高峰内。跨零点段（start > end）按「窗口所属的那一天」认星期：
+ * `mon-fri 23:00-06:00` 的周六 02:00 属于周五开的那个窗口，仍算高峰。
+ */
+export function isInPeakWindow(date, spec) {
+  const parsed = parsePeakSpec(spec);
+  if (!parsed) return false;
+  const minutes = date.getHours() * 60 + date.getMinutes();
+  const today = isoDay(date);
+  const yesterday = today === 1 ? 7 : today - 1;
+  const allowed = (day) => !parsed.days || parsed.days.includes(day);
+  return parsed.windows.some(({ start, end }) => {
+    if (start < end) return minutes >= start && minutes < end && allowed(today);
+    return (minutes >= start && allowed(today)) || (minutes < end && allowed(yesterday));
+  });
+}
+
+/**
+ * 高峰内则返回「距当前最近的一个高峰结束时刻」（择时补跑用），否则 null。
+ * 落在多个时段重叠处时取最早结束的那个——早跑不亏，晚跑才亏。
+ */
+export function nextOffPeakAt(date, spec) {
+  const parsed = parsePeakSpec(spec);
+  if (!parsed) return null;
+  const minutes = date.getHours() * 60 + date.getMinutes();
+  const today = isoDay(date);
+  const yesterday = today === 1 ? 7 : today - 1;
+  const allowed = (day) => !parsed.days || parsed.days.includes(day);
+  let bestDelta = null;
+  const consider = (delta) => {
+    if (bestDelta === null || delta < bestDelta) bestDelta = delta;
+  };
+  for (const { start, end } of parsed.windows) {
+    if (start < end) {
+      if (minutes >= start && minutes < end && allowed(today)) consider(end - minutes);
+      continue;
+    }
+    if (minutes >= start && allowed(today)) consider((1440 - minutes) + end);
+    else if (minutes < end && allowed(yesterday)) consider(end - minutes);
+  }
+  if (bestDelta === null) return null;
+  const at = new Date(date.getTime());
+  at.setSeconds(0, 0);
+  at.setMinutes(at.getMinutes() + bestDelta);
+  return at;
+}
+
+export function createSummarizer(ctx, service, config, deps = {}) {
   if (!config.autoSummarize) return { dispose: () => {} };
 
+  // Issue #239（第 4 项）：时钟与定时器可注入——排程不绑死真实时钟，测试才能确定性
+  // 覆盖「高峰顺延 → 非高峰补跑」。房型同 dream/sleep.js 的注入参数。
+  const now = typeof deps.now === "function" ? deps.now : () => Date.now();
+  const setTimer = typeof deps.setTimeoutFn === "function" ? deps.setTimeoutFn : setTimeout;
+  const clearTimer = typeof deps.clearTimeoutFn === "function" ? deps.clearTimeoutFn : clearTimeout;
+
   const inFlight = new Map();
   // Issue #127：per-session 上一次实际开跑时刻（最小间隔闸门用）。与 inFlight
   // 同生命周期，dispose 时一并清空。
   const lastRunAt = new Map();
+  // Issue #239：per-session 已发起的蒸馏次数（有界检查点用）。只在实际发起 LLM
+  // 调用时自增，因此被零 LLM 预判挡下的窗口不消耗预算。
+  const runsUsed = new Map();
+  // Issue #239（第 4 项）：每会话最多挂一个待补跑定时器（错峰队列用）；dispose 时
+  // 一并清理，避免插件卸载后还留着一个会调模型的定时器。
+  const deferredRuns = new Map();
   // Issue #210：只在一次蒸馏完整成功后记录已消费的最后事件 seq。
   const lastDistilledSeq = new Map();
   let disposed = false;
@@ -282,7 +405,52 @@ export function createSummarizer(ctx, service, config) {
     }
   }
 
-  async function summarize(session, triggerEvent) {
+  function persistCursor(sessionId, nextSeq) {
+    if (!Number.isFinite(nextSeq)) return;
+    if (typeof service.setDistillCursor !== "function") {
+      // 第三方宿主拿旧版 service 构造时没有持久化游标能力：降级为内存游标
+      // （#274 之前的行为），本进程内不重复蒸馏，重启后窗口重放由
+      // saveWithDedupe 三元组兜底。方法存在但抛错仍向上传播——那是
+      // 「写失败须回滚」的恰一次语义，不能吞（见 summarize.test.js 回滚用例）。
+      ctx.logger?.warn?.("dsh-mneme: service.setDistillCursor unavailable, distill cursor falls back to in-memory");
+      return;
+    }
+    service.setDistillCursor(sessionId, nextSeq);
+  }
+
+  function commitCursor(sessionId, nextSeq) {
+    persistCursor(sessionId, nextSeq);
+    if (Number.isFinite(nextSeq)) lastDistilledSeq.set(sessionId, nextSeq);
+  }
+
+  /**
+   * Issue #239（第 4 项）：把这一轮蒸馏推迟到最近的「高峰结束」时刻。每会话只挂
+   * 一个定时器（重复触发不叠加）；被 summarizePeakMaxDeferMinutes 截断时到点照跑
+   * （bypassPeak），长高峰不会把蒸馏饿死。定时器 unref——不阻止宿主退出。
+   */
+  function scheduleDeferredRun(session) {
+    if (disposed || deferredRuns.has(session.id)) return;
+    const at = nextOffPeakAt(new Date(now()), config.summarizePeakHours ?? "");
+    if (!at) return;
+    const maxDeferMs = (config.summarizePeakMaxDeferMinutes ?? 0) * 60000;
+    let delay = Math.max(0, at.getTime() - now());
+    const capped = maxDeferMs > 0 && delay > maxDeferMs;
+    if (capped) delay = maxDeferMs;
+    const timer = setTimer(() => {
+      deferredRuns.delete(session.id);
+      if (disposed) return;
+      // 不传触发事件：补跑要蒸的是「累积后的整窗」（从上次成功游标到最新事件），
+      // 拿老 triggerEvent 反而会把窗口卡在它那个 seq 上。
+      summarize(session, undefined, { bypassPeak: capped }).catch((error) => {
+        if (disposed || error?.name === "AbortError") return;
+        ctx.logger?.warn?.(`dsh-mneme: deferred summarization failed: ${String(error)}`);
+      });
+    }, delay);
+    timer?.unref?.();
+    deferredRuns.set(session.id, timer);
+  }
+
+  async function summarize(session, triggerEvent, opts = {}) {
     if (disposed || inFlight.has(session.id)) return;
 
     const header = session.requestHeader?.()?.config;
@@ -308,6 +476,37 @@ export function createSummarizer(ctx, service, config) {
       });
       return;
     }
+    // Issue #239（有界检查点）：每会话 run 预算。放在间隔门之后，两者都命中时
+    // 先报间隔——间隔是「刚刚跑过」，预算是「额度用尽」，前者信息量更大。skip
+    // 仍写审计（沿用间隔门的 error_message 口径），否则「为什么不再蒸馏了」对
+    // 用户不可观测。prevRuns 在这里捕获、finally 里按 aborted 回滚（同 lastRunAt）。
+    // 游标刻意不消费：预算是「这个会话先不再蒸馏了」，把窗口留在原地，日后调高
+    // 额度（或宿主重启）仍能蒸馏到它；这与 window-too-small 主动消费游标相反——
+    // 后者是「这些事件不值得蒸馏」，留着只会每个 turn/end 重评一次。
+    // Issue #239（第 4 项，错峰队列）：高峰期不调模型——只登记一行 skip 审计并择时
+    // 补跑。游标刻意不消费：窗口继续累积，留到非高峰一次性蒸馏（批量比逐轮碎蒸更
+    // 省）。被 maxDefer 截断后到点仍处高峰时，由 opts.bypassPeak 放行。
+    if (!opts.bypassPeak && isInPeakWindow(new Date(now()), config.summarizePeakHours ?? "")) {
+      writeAudit({
+        timestamp: new Date(now()).toISOString(),
+        model_id: route ? `${route.provider}:${route.model}` : "unknown",
+        status: "skipped",
+        error_message: "peak-hours"
+      });
+      scheduleDeferredRun(session);
+      return;
+    }
+    const prevRuns = runsUsed.get(session.id);
+    const maxRuns = config.summarizeMaxRunsPerSession ?? 0;
+    if (maxRuns > 0 && (prevRuns ?? 0) >= maxRuns) {
+      writeAudit({
+        timestamp: new Date().toISOString(),
+        model_id: route ? `${route.provider}:${route.model}` : "unknown",
+        status: "skipped",
+        error_message: "max-runs-per-session"
+      });
+      return;
+    }
     const controller = new AbortController();
     inFlight.set(session.id, controller);
     // audit state for the compression call. null = no audit for this run
@@ -319,7 +518,10 @@ export function createSummarizer(ctx, service, config) {
     let abortedRun = false;
     try {
       if (!route) return;
-      const previousSeq = lastDistilledSeq.get(session.id);
+      const persistedCursor = typeof service.getDistillCursor === "function"
+        ? service.getDistillCursor(session.id)
+        : undefined;
+      const previousSeq = persistedCursor?.last_seq ?? lastDistilledSeq.get(session.id);
       const triggerSeq = eventSeq(triggerEvent);
       // 只读取上次成功游标之后、当前 turn/end 之前的事件。旧版 snapshotEvents
       // 即使忽略范围参数，collectMessages 仍会按事件 seq 二次过滤。
@@ -338,13 +540,37 @@ export function createSummarizer(ctx, service, config) {
       if (!collected.messages.length) {
         // 没有可蒸馏的公开文本也算成功消费当前事件窗口，避免每个 turn/end
         // 都重新扫描同一批无内容事件；没有 seq 时则不提交不可验证的游标。
-        if (Number.isFinite(nextSeq)) lastDistilledSeq.set(session.id, nextSeq);
+        commitCursor(session.id, nextSeq);
         return;
       }
       const messages = collected.messages;
-      // 只有真正准备发起一次 LLM 蒸馏时才占用最小间隔；失败路径仍按原语义
-      // 占用，aborted 则由 finally 回滚。
+      // Issue #239（成本感知级联第一级）：零 LLM 预判。窗口内可蒸馏文本不足阈值
+      // 时直接跳过——短窗口交给模型的产出多是泛泛而谈，代价却是一次完整调用。
+      // 判定纯规则（字符数），无模型参与；被挡下的窗口照常消费游标，否则每个
+      // turn/end 都会重新评估同一段短文本。skip 原因进审计，作为后续按真实负载
+      // 决定下一级规则的依据。
+      const minWindowChars = config.summarizeMinWindowChars ?? 0;
+      if (minWindowChars > 0) {
+        const distillChars = messages.reduce(
+          (total, message) => total + (Array.isArray(message.content) ? message.content : [])
+            .reduce((n, part) => n + (typeof part?.text === "string" ? part.text.length : 0), 0),
+          0
+        );
+        if (distillChars < minWindowChars) {
+          commitCursor(session.id, nextSeq);
+          writeAudit({
+            timestamp: new Date().toISOString(),
+            model_id: route ? `${route.provider}:${route.model}` : "unknown",
+            status: "skipped",
+            error_message: "window-too-small"
+          });
+          return;
+        }
+      }
+      // 只有真正准备发起一次 LLM 蒸馏时才占用最小间隔与 run 预算；失败路径仍按
+      // 原语义占用（调用确实发生过），aborted 则由 finally 回滚。
       lastRunAt.set(session.id, Date.now());
+      runsUsed.set(session.id, (prevRuns ?? 0) + 1);
 
       if (config?.llmAudit?.enabled !== false && typeof service.saveLlmAudit === "function") {
         audit = {
@@ -385,8 +611,11 @@ export function createSummarizer(ctx, service, config) {
                 text += chunk.text ?? chunk.delta ?? "";
               }
               if (chunk.type === "usage" && audit) {
-                const i = chunk.input_tokens ?? chunk.inputTokens ?? chunk.prompt_tokens ?? chunk.promptTokens;
-                const o = chunk.output_tokens ?? chunk.outputTokens ?? chunk.completion_tokens ?? chunk.completionTokens;
+                // 同 dream.js：真实协议是 {type:"usage", usage:TokenUsage}，用量不在
+                // chunk 顶层；顶层读取只作为把用量平铺的替身兜底。
+                const usage = chunk.usage ?? chunk;
+                const i = usage.input_tokens ?? usage.inputTokens ?? usage.prompt_tokens ?? usage.promptTokens;
+                const o = usage.output_tokens ?? usage.outputTokens ?? usage.completion_tokens ?? usage.completionTokens;
                 if (Number.isFinite(i)) audit.inputTokens = i;
                 if (Number.isFinite(o)) audit.outputTokens = o;
               }
@@ -504,7 +733,11 @@ export function createSummarizer(ctx, service, config) {
               ...(dup ? { _mergeInto: dup.memory.id } : {})
             });
           }
+          persistCursor(session.id, nextSeq);
         });
+      } else {
+        // 空数组是合法成功：没有记忆写入，但本次事件窗口仍然应被持久消费。
+        persistCursor(session.id, nextSeq);
       }
       if (audit && (capped > 0 || deduped > 0)) {
         audit.metadata = {
@@ -516,12 +749,22 @@ export function createSummarizer(ctx, service, config) {
       // 记忆写入和解析都成功后才提交窗口；流失败、中止、解析失败或写入异常
       // 都会在此之前退出，从而保留窗口供下一次重试。
       if (Number.isFinite(nextSeq)) lastDistilledSeq.set(session.id, nextSeq);
+    } catch (error) {
+      if (audit) {
+        audit.status = "error";
+        audit.errorMessage = String(error?.message ?? error);
+      }
+      throw error;
     } finally {
       // Issue #127：aborted（会话关闭 / 插件 dispose）不占间隔，避免误伤该会话的
       // 下一次蒸馏；其余情况（含失败）的打点保留，与 dreamMinIntervalMinutes 一致。
       if (abortedRun || controller.signal.aborted) {
         if (prevClaim === undefined) lastRunAt.delete(session.id);
         else lastRunAt.set(session.id, prevClaim);
+        // Issue #239：aborted 同样不占 run 预算——调用没有真正发生，占了会误伤
+        // 该会话后续的蒸馏（与上面的间隔回滚同一口径）。
+        if (prevRuns === undefined) runsUsed.delete(session.id);
+        else runsUsed.set(session.id, prevRuns);
       }
       if (audit) {
         try {
@@ -566,6 +809,8 @@ export function createSummarizer(ctx, service, config) {
       if (disposed) return;
       disposed = true;
       unsubscribe?.();
+      for (const timer of deferredRuns.values()) clearTimer(timer);
+      deferredRuns.clear();
       for (const controller of inFlight.values()) controller.abort();
       inFlight.clear();
       lastRunAt.clear();

package/lib/tools.js

@@ -5,6 +5,7 @@ import { defaultRuntimeDir } from "./runtime/layout.js";
 import { hostModulesDir, loadRuntimeManifest, provisionRuntime } from "./runtime/provision.js";
 import { matchesPlatform } from "./runtime/closure.js";
 import { verifyPayload } from "./runtime/verify.js";
+import { TOOL_GUIDE } from "./guide.js";
 
 const TEXT_OUTPUT = (text) => [{ type: "text", text }];
 // Per-registry tool-name registry: guards against duplicate registration on
@@ -35,6 +36,8 @@ const MEMORY_ITEM_SCHEMA = {
     scope_decided_at: { type: "string" },
     sensitivity: { type: "string" },
     occurred_at: { type: "string" },
+    // #230：document 指针行的文件定位——「全文按需读」的入口；普通行缺省。
+    doc_path: { type: "string" },
     created_at: { type: "string", required: true },
     updated_at: { type: "string", required: true }
   }
@@ -81,6 +84,11 @@ export function createTools(ctx, service, config, embedder) {
   // flag 关闭时恒返回 null——写入不标注，检索不加权，行为与 A1 前完全一致。
   // logger 透传：registry 反查失败时 warnOnce 才有出口（否则静默降级无观测）。
   const resolveSessionScope = createScopeResolver({ ctx, config, logger: ctx.logger });
+  // #249 第一批：能力说明（injectGuidanceEnabled）开启时，给「何时用」最有歧义
+  // 的两个工具补一句判断指引。工具描述常驻、不进每轮上下文，这个位子零注入
+  // 成本；关闭时描述逐字节不变，也不动其他工具的文案。
+  const withToolGuide = (name, description) =>
+    config?.injectGuidanceEnabled === true && TOOL_GUIDE[name] ? `${description}${TOOL_GUIDE[name]}` : description;
 
   // 复核项 4（issue #170）：strictScope 下他 scope（explicit）的行对工具侧按
   // 「不存在」处理——update/delete 与 memory_get 同款无存在性泄漏。strictScope
@@ -104,11 +112,16 @@ export function createTools(ctx, service, config, embedder) {
   const tools = [
     defineTool({
       name: "memory_save",
-      description:
+      description: withToolGuide(
+        "memory_save",
         "Persist one memory entry for future sessions (user preferences, project state, decisions). " +
-        "Call this when the user states a durable preference, a project decision is made, or a lesson is learned. " +
-        "Merges into an existing entry of the same type when the title matches.",
+          "Call this when the user states a durable preference, a project decision is made, or a lesson is learned. " +
+          "Merges into an existing entry of the same type when the title matches."
+      ),
       parameters: {
+        // document 不在此列（#230）：document 行只能经 memory_register_document
+        // 铸造（注册校验 + doc_path + evidence），防止 memory_save 造出无指针
+        // 无回链的伪行。
         type: { type: "string", required: true, enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"], description: "preference=user profile; project=project knowledge/state; decision=key decision; history=conversation summary; rejected_solution=rejected/abandoned implementation approach; pitfall=debugging lesson (symptom+root cause+fix); constraint=engineering constraint" },
         title: { type: "string", required: true, description: "Short unique title" },
         content: { type: "string", required: true, description: "Memory body" },
@@ -166,7 +179,10 @@ export function createTools(ctx, service, config, embedder) {
 
     defineTool({
       name: "memory_search",
-      description: "Search the cross-session memory store. Use when you need past context: how a problem was solved, user preferences, project decisions. Substring-matches title/content/tags, and augments results with semantic (vector) recall + optional rerank when an embeddings provider is configured. Returns matching entries with source and timestamps.",
+      description: withToolGuide(
+        "memory_search",
+        "Search the cross-session memory store for past context (solved problems, user preferences, project decisions). IMPORTANT: relevant cross-session memories are already injected into your context every turn — only call this when the injected memory block does NOT contain what you need, or you need to look something specific up. Substring-matches title/content/tags, and augments results with semantic (vector) recall + optional rerank when an embeddings provider is configured. Returns matching entries with source and timestamps."
+      ),
       // A2 检索接线：occurred 时间窗 + 会话 scope 加成（见 execute）。
       parameters: {
         query: { type: "string", required: true, description: "Search text; substring match over title/content/tags" },
@@ -224,7 +240,7 @@ export function createTools(ctx, service, config, embedder) {
       name: "memory_list",
       description: "List memory entries by type, high-importance first, then newest, paginated. Set include_archived=true to also list archived (hidden) entries so they can be located and restored.",
       parameters: {
-        type: { type: "string", enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"], description: "Filter by type; omit for all" },
+        type: { type: "string", enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint", "document"], description: "Filter by type; omit for all. 'document' (#230) = agent-registered document pointer rows" },
         limit: { type: "integer", description: "Page size (default 50)" },
         offset: { type: "integer", description: "Page offset (default 0)" },
         include_archived: { type: "boolean", description: "Include archived (hidden) entries so they can be found and restored (default false)" },
@@ -287,7 +303,9 @@ export function createTools(ctx, service, config, embedder) {
         },
         render: (_args, value) => {
           const m = value.memory;
-          return TEXT_OUTPUT(`${m.title}\nID: ${m.id} | type: ${m.type} | importance: ${m.importance}${MEMORY_PROVENANCE(m)}\n\n${m.content}`);
+          // #230：document 指针行把文件路径亮在首行——「全文按需读」从这里拿路径。
+          const doc = m.doc_path ? ` | doc: ${m.doc_path}` : "";
+          return TEXT_OUTPUT(`${m.title}\nID: ${m.id} | type: ${m.type} | importance: ${m.importance}${doc}${MEMORY_PROVENANCE(m)}\n\n${m.content}`);
         }
       },
       async execute(args) {
@@ -311,6 +329,8 @@ export function createTools(ctx, service, config, embedder) {
         id: { type: "string", required: true, description: "Memory id" },
         title: { type: "string" },
         content: { type: "string" },
+        // document 不在此列（#230）：type 不许改入 document——既有 document 行
+        // 的摘要修复（只改 content/title）不受影响。
         type: { type: "string", enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"] },
         tags: { type: "array", items: { type: "string" } },
         importance: { type: "integer", description: "1-5" },
@@ -415,7 +435,8 @@ export function createTools(ctx, service, config, embedder) {
       description:
         "Archive a memory (hide it from active lists, search, injection and dream consolidation) or restore it. " +
         "Archived entries stay in storage and are recoverable: pass archived=false to restore, and use memory_list with " +
-        "include_archived=true to find archived entries.",
+        "include_archived=true to find archived entries. " +
+        "Only archive when the user asks, or an entry is clearly stale/no longer relevant — do not archive proactively mid-session to tidy up.",
       parameters: {
         id: { type: "string", required: true, description: "Memory id" },
         archived: { type: "boolean", description: "Archive (true, default) or restore (false) the entry" }
@@ -446,6 +467,101 @@ export function createTools(ctx, service, config, embedder) {
       }
     }),
 
+    // #230（#164 设计稿评审线）：document 型记忆注册——agent 产长文档的指针
+    // 行铸造口。写入权分离：全文归 agent（管线对文件零读零写零改），库里只
+    // 存摘要 + doc_path + evidence 三样；C2 比对去重、supersede 记账在
+    // service.registerDocument（src/document.js）内完成。判断指引：调研报告/
+    // 设计稿/长整理产物「存外档」用本工具；原子事实（偏好/决策/教训）仍走
+    // memory_save；tag 与章节名建议用英文（跨语言稳定键），摘要正文可多语言。
+    defineTool({
+      name: "memory_register_document",
+      description:
+        "Register an agent-authored document (research report, design doc, long digest) into memory as a pointer row. " +
+        "Write-ownership split: the full text stays agent-owned on disk — the pipeline never reads or rewrites it; the DB " +
+        "stores only the summary + doc_path + evidence. Validates the file exists (absolute path, non-empty regular file), " +
+        "intersects evidence with real memory ids (all-fabricated evidence is rejected; unknown ids are dropped and the row " +
+        "is tagged evidence_degraded), and dedupes: re-registering the same path or title supersedes the old row (the old " +
+        "file is never touched; content_history stays traceable), while a merely near-duplicate summary of a different " +
+        "document row is rejected — update that row instead. Use for 'where is the conclusion doc for this project?' " +
+        "lookups; atomic facts still go to memory_save.",
+      parameters: {
+        path: { type: "string", required: true, description: "Absolute path of the document file (~ is expanded); must already exist as a non-empty regular file. The full text stays agent-owned — this pipeline never touches it." },
+        title: { type: "string", required: true, description: "Short unique title (English recommended: it is the cross-language stable dedupe/supersede key)" },
+        summary: { type: "string", required: true, description: "One-paragraph summary stored in the DB and used for injection (any language)" },
+        tags: { type: "array", items: { type: "string" }, description: "Optional tags (English recommended)" },
+        importance: { type: "integer", description: "1-5 (default 3); the summary row injects at the next-priority tier within documentInjectBudget when importance >= threshold" },
+        evidence: { type: "array", items: { type: "string" }, description: "Memory ids this document is grounded in; each is verified against the store (fabricated evidence is rejected; unknown/archived ids are dropped and the row is tagged evidence_degraded)" },
+        source: { type: "string", description: "Optional provenance" },
+        sensitivity: { type: "string", description: "Optional sensitivity label (free-form, e.g. personal). Part of the supersede matching key — same path/title with a different sensitivity stays a separate document." },
+        agent_scope: { type: "string", description: "Optional explicit agent-scope declaration (issue #170): 'global' or '*' makes this document visible to every agent; any other value narrows it to that label. Overrides the automatic carrier label for this write; honored even when automatic scope labeling is disabled." },
+        workspace_scope: { type: "string", description: "Optional explicit workspace-scope declaration (issue #170): 'global' or '*' makes this document visible in every workspace; any other value narrows it to that label. Overrides the automatic carrier label for this write; honored even when automatic scope labeling is disabled." }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            action: { type: "string", required: true, enum: ["created", "superseded"] },
+            id: { type: "string", required: true },
+            superseded_id: { type: "string" },
+            evidence_kept: { type: "integer", required: true },
+            evidence_dropped: { type: "integer", required: true },
+            degraded: { type: "boolean", required: true }
+          }
+        },
+        render: (_args, value) => {
+          const sup = value.superseded_id ? ` (supersedes ${value.superseded_id})` : "";
+          const ev = ` | evidence: ${value.evidence_kept} kept, ${value.evidence_dropped} dropped${value.degraded ? " [degraded]" : ""}`;
+          return TEXT_OUTPUT(`document ${value.action}: ${value.id}${sup}${ev}`);
+        }
+      },
+      async execute(args, exec) {
+        // scope 标注与 memory_save 同款（#170）：默认会话身份自动标注，显式
+        // 参数逐维覆盖。校验/去重/supersede 全在 service.registerDocument。
+        const scope = resolveSessionScope(exec);
+        const autoStamping = config?.scopeEnabled === true;
+        const agentLabel = args.agent_scope !== undefined
+          ? { value: normalizeExplicitScope(args.agent_scope), source: "explicit" }
+          : autoStamping && scope ? { value: scope.agent_scope, source: "auto" } : null;
+        const workspaceLabel = args.workspace_scope !== undefined
+          ? { value: normalizeExplicitScope(args.workspace_scope), source: "explicit" }
+          : autoStamping && scope ? { value: scope.workspace_scope, source: "auto" } : null;
+        // strictScope（#170 复核项 4 同款无存在性泄漏）：他 scope 的 evidence id
+        // 按「不存在」处理——注册器用全局 getById 求交，看不见的行在这里先标出，
+        // 与 unknown/archived 同落 dropped，不进持久化 evidence（不得为跨 scope
+        // id 建立引用）。
+        const hiddenEvidence = [];
+        if (config?.strictScope === true && scope && Array.isArray(args.evidence)) {
+          for (const raw of args.evidence) {
+            const id = String(raw ?? "").trim();
+            if (!id) continue;
+            const row = service.getById(id);
+            if (row && !service.isVisibleInScope(row, scope)) hiddenEvidence.push(id);
+          }
+        }
+        const result = await service.registerDocument({
+          path: args.path,
+          title: args.title,
+          summary: args.summary,
+          tags: args.tags ?? [],
+          ...(args.importance !== undefined ? { importance: args.importance } : {}),
+          evidence: args.evidence ?? [],
+          source: args.source ?? "tool",
+          ...(args.sensitivity !== undefined ? { sensitivity: args.sensitivity } : {}),
+          ...(agentLabel ? { agent_scope: agentLabel.value, agent_scope_source: agentLabel.source } : {}),
+          ...(workspaceLabel ? { workspace_scope: workspaceLabel.value, workspace_scope_source: workspaceLabel.source } : {})
+        }, { hiddenEvidenceIds: hiddenEvidence });
+        return {
+          action: result.action,
+          id: result.memory.id,
+          ...(result.superseded ? { superseded_id: result.superseded.id } : {}),
+          evidence_kept: result.evidence_kept,
+          evidence_dropped: result.evidence_dropped,
+          degraded: result.degraded
+        };
+      }
+    }),
+
     // 运行时口子（issue #131 / PR-C）。
     //
     // 为什么要有这个工具：mneme 的取向是「本体保持完善但轻量；重的功能存在、默认不开、不被依赖」。
@@ -561,8 +677,20 @@ export function createTools(ctx, service, config, embedder) {
     })
   ];
 
+  // Tool-exposure gate (v0.8.5): 跨会话记忆已自动注入，memory_search /
+  // memory_archive 在慢/轻量模型上是多余往返，面板开关可直接隐藏工具——
+  // 模型看不到就不会调，比在描述里劝它少调用更可靠。注意：live patch reload
+  // 下已注册的工具不会被宿主反注册，排除只对全新会话生效。
+  const hiddenTools = new Set();
+  if (config?.disableMemorySearch === true) hiddenTools.add("memory_search");
+  if (config?.disableMemoryArchive === true) hiddenTools.add("memory_archive");
+
   for (const tool of tools) {
-          if (registeredTools.has(tool.name)) {
+    if (hiddenTools.has(tool.name)) {
+      ctx.logger?.info?.(`[dsh-mneme] tool "${tool.name}" hidden by config (disableMemorySearch/disableMemoryArchive)`);
+      continue;
+    }
+    if (registeredTools.has(tool.name)) {
         ctx.logger?.warn?.(`[dsh-mneme] tool "${tool.name}" already registered, skipping duplicate`);
         continue;
       }

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 9 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/modusensus/dsh-mneme.git"
+    "url": "git+https://github.com/slow-stack/dsh-mneme.git"
   },
-  "homepage": "https://github.com/modusensus/dsh-mneme#readme",
+  "homepage": "https://github.com/slow-stack/dsh-mneme#readme",
   "bugs": {
-    "url": "https://github.com/modusensus/dsh-mneme/issues"
+    "url": "https://github.com/slow-stack/dsh-mneme/issues"
   },
   "type": "module",
   "main": "lib/index.js",
@@ -72,7 +72,7 @@
     "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@huggingface/transformers": "^4.2.0",
+    "@huggingface/transformers": "^4.3.0",
     "c8": "^12.0.0",
     "lucide": "^1.42.0"
   },
@@ -100,7 +100,7 @@
     "morphicons": "^1.7.1"
   },
   "overrides": {
-    "adm-zip": "0.6.0"
+    "adm-zip": "0.6.1"
   },
   "allowScripts": {
     "onnxruntime-node@1.24.3": true,