@modusensus/dsh-mneme 0.6.11 → 0.7.0

package/dsh-mneme/lib/heat.js

@@ -0,0 +1,136 @@
+// dsh-mneme/src/heat.js
+// 热度（heat）纯函数模块：基于类遗忘曲线计算 memory 的当前热度。
+// 零数据库依赖，不引入任何外部依赖。
+
+/**
+ * 默认的 per-type 衰减因子 λ。
+ * λ = 0 表示该类型免疫热度衰减，热度恒为 1.0。
+ */
+export const TYPE_DECAY_DEFAULTS = Object.freeze({
+  preference: 0,    // 免疫：用户画像需长期保持
+  pattern: 0,       // 免疫：发现型稳定规律
+  summary: 0,       // 免疫：已是压缩产物
+  project: 0.0008,  // 慢衰减
+  decision: 0.002,  // 中速衰减
+  history: 0.006,   // 较快（会话摘要不断被合并）
+});
+
+const HOUR_MS = 3600000;
+const DEFAULT_ALPHA = 1.2;
+const DEFAULT_LAMBDA = 0.002;
+
+/**
+ * 将可能的日期值统一转成毫秒时间戳。
+ * 支持 Date、number、ISO 字符串；无法解析时返回 NaN。
+ */
+function toTimestamp(value) {
+  if (value === null || value === undefined) return NaN;
+
+  if (value instanceof Date) {
+    return Number.isFinite(value.getTime()) ? value.getTime() : NaN;
+  }
+
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : NaN;
+  }
+
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : NaN;
+  }
+
+  return NaN;
+}
+
+/**
+ * 获取用于计算热度的参考时间点 ref。
+ * 优先取 last_accessed_at；缺失时退到 created_at。
+ * 绝不 fallback 到 updated_at。
+ */
+function getRef(memory) {
+  if (!memory || typeof memory !== 'object') return NaN;
+  return toTimestamp(memory.last_accessed_at ?? memory.created_at);
+}
+
+/**
+ * 解析并校验配置，提供安全的 alpha 与衰减表。
+ */
+function resolveConfig(config) {
+  const safe = config && typeof config === 'object' ? config : {};
+
+  let alpha = safe.heatGlobalAlpha ?? DEFAULT_ALPHA;
+  if (!Number.isFinite(alpha) || alpha <= 0) {
+    alpha = DEFAULT_ALPHA;
+  }
+
+  const decayMap = safe.heatTypeDecay ?? TYPE_DECAY_DEFAULTS;
+
+  return { alpha, decayMap };
+}
+
+/**
+ * 构建热度信号对象，便于调试与后续扩展。
+ *
+ * @param {object} memory - memory 记录
+ * @param {object} config - 插件配置
+ * @param {number} [now=Date.now()] - 当前毫秒时间戳
+ * @returns {{ type, ref, lambda, alpha, deltaHours }}
+ */
+export function buildHeatSignals(memory, config, now = Date.now()) {
+  const nowMs = Number.isFinite(now) ? now : Date.now();
+  const ref = getRef(memory);
+  const { alpha, decayMap } = resolveConfig(config);
+
+  const type = memory?.type;
+
+  // 取对应类型的 λ，未知类型走默认
+  let lambda = decayMap[type];
+  if (!Number.isFinite(lambda)) {
+    lambda = DEFAULT_LAMBDA;
+  }
+  // λ < 0 视为非法，回退到默认；λ === 0 保留为免疫
+  if (lambda < 0) {
+    lambda = DEFAULT_LAMBDA;
+  }
+
+  let deltaHours;
+  if (!Number.isFinite(ref)) {
+    deltaHours = NaN;
+  } else if (nowMs < ref) {
+    deltaHours = 0;
+  } else {
+    deltaHours = (nowMs - ref) / HOUR_MS;
+  }
+
+  return { type, ref, lambda, alpha, deltaHours };
+}
+
+/**
+ * 计算 memory 的热度 H ∈ [0, 1]。
+ *
+ * 公式：H = 1 / (1 + λ · ΔtHours)^α
+ *
+ * @param {object} memory - memory 记录
+ * @param {number} [now=Date.now()] - 当前毫秒时间戳
+ * @param {object} [config={}] - 插件配置
+ * @returns {number} 热度值
+ */
+export function computeHeat(memory, now = Date.now(), config = {}) {
+  const signals = buildHeatSignals(memory, config, now);
+  const { alpha, lambda, deltaHours, ref } = signals;
+
+  // 无有效参考时间、或未来时间，热度视为满格
+  if (!Number.isFinite(ref) || deltaHours <= 0) {
+    return 1.0;
+  }
+
+  // λ = 0 的类型免疫，热度恒满
+  if (lambda === 0) {
+    return 1.0;
+  }
+
+  const heat = 1 / Math.pow(1 + lambda * deltaHours, alpha);
+
+  // 防止浮点误差越界
+  return Math.min(1, Math.max(0, heat));
+}

package/{lib → dsh-mneme/lib}/index.js

@@ -52,6 +52,13 @@ export const apply = (ctx, config) => {
       store.deleteOldLlmAudits(new Date(Date.now() - retentionMs * 86400000).toISOString());
     }
   } catch { /* non-fatal */ }
+  // v0.7.0: recall_runs 滚动清理 —— recordRecall 默认开且注入路径也记账，表随
+  // 活跃度增长；启动时按 recallRetentionDays（默认 90 天）清一次，防膨胀。
+  // 与 llm_audit 同策略：纯 bookkeeping，清理失败绝不阻塞插件启动。
+  try {
+    const recallRetentionDays = Number.isInteger(cfg.recallRetentionDays) ? cfg.recallRetentionDays : 90;
+    store.purgeRecallRunsOlderThan(recallRetentionDays);
+  } catch { /* non-fatal */ }
   const mirror = createMirror(memoryDir);
   const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
 

package/{src → dsh-mneme/lib}/service.js

@@ -5,6 +5,7 @@ import { createBM25Index } from "./search/bm25.js";
 import { adaptiveThreshold } from "./search/adaptive.js";
 import { parseWikiLinks } from "./parser/wiki-link.js";
 import { extractQueryTags, applyTagBoost } from "./search/tag-boost.js";
+import { computeHeat } from "./heat.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
@@ -467,14 +468,15 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   }
 
   /**
-   * Sleep touch (v0.4.0): when sleep is enabled, any memory surfaced by recall
-   * or auto-injection gets its last_accessed_at bumped, so the "unrecalled N
-   * days → demote/archive" tiering counts real access. Best-effort and gated on
-   * config.sleepModeEnabled — when sleep is off this is a complete no-op (no
-   * writes on the hot recall path). A touch failure must never break search/inject.
+   * Recall touch (v0.7.0 数据前提): any memory surfaced by recall or
+   * auto-injection gets its last_accessed_at bumped so the heat model has a
+   * truthful access clock. Previously gated on config.sleepModeEnabled — now
+   * gated on config.heatEnabled (default on) so heat data is collected
+   * independently of sleep mode; sleep consumes it when it runs. Best-effort:
+   * a touch failure must never break search/inject.
    */
   function touchRecalled(memories) {
-    if (config?.sleepModeEnabled !== true || !Array.isArray(memories) || memories.length === 0) return;
+    if (config?.heatEnabled === false || !Array.isArray(memories) || memories.length === 0) return;
     for (const m of memories) {
       if (!m?.id) continue;
       try {
@@ -484,7 +486,15 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   }
 
   async function searchMemories(query, options = {}) {
-    const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = false } = options;
+    // v0.7.0: recall_runs 记录默认开（config.recallRecordDefault，默认 true）；
+    // 显式传 recordRecall:false 或配置 recallRecordDefault:false 可关。
+    const {
+      mode = "auto",
+      topK = 20,
+      threshold,
+      useRerank = true,
+      recordRecall = options.recordRecall ?? (config?.recallRecordDefault ?? true)
+    } = options;
     const raw = String(query ?? "").trim();
     if (!raw) return [];
 
@@ -683,12 +693,16 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           mode,
           topK: lim,
           threshold: threshold ?? null,
+          // v0.7.0 recall-layer 强度标记：搜索帧一律 injected:false（被召回 =
+          // 检索直接命中）；注入上下文帧由 injectCandidates 以 injected:true
+          // 单独记账（被注入 = 替对话搭建上下文），两档强度可区分。
           candidates: result.map((m) => ({
             id: m.id,
             title: m.title,
             content: m.content,
             score: m.score ?? null,
-            source: m.source ?? "keyword"
+            source: m.source ?? "keyword",
+            injected: false
           })),
           createdAt: new Date().toISOString()
         });
@@ -1060,6 +1074,32 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       } catch { /* topic re-rank unavailable: keep rule-based order */ }
     }
     const selected = candidates.slice(0, maxItems);
+    // v0.7.0 recall-layer 强度标记：注入场景也走 recall_runs 记账（mode="inject"、
+    // injected:true），与 searchMemories 的搜索帧（injected:false）互补，区分
+    // "被召回"与"被注入上下文"两个消耗强度。与搜索侧同受 recallRecordDefault
+    // 门控；记账失败绝不阻断注入本身。
+    if (recallRecorder && config.recallRecordDefault !== false) {
+      try {
+        recallRecorder({
+          query: q,
+          mode: "inject",
+          topK: selected.length,
+          threshold: null,
+          candidates: selected.map((m) => ({
+            id: m.id,
+            title: m.title,
+            content: m.content,
+            score: m.score ?? null,
+            // 注入帧的 source 固定为帧级标记 "inject"，与搜索帧的
+            // keyword/vector/rerank 对齐（记忆行自带的 source 是来源列，
+            // 与检索层级无关，不混入）。
+            source: "inject",
+            injected: true
+          })),
+          createdAt: new Date().toISOString()
+        });
+      } catch { /* recall receipt is best effort */ }
+    }
     touchRecalled(selected);
     return selected;
   }
@@ -1696,6 +1736,21 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     saveWikiLinks: (r) => store.saveWikiLinks(r),
     listEntities: (o) => store.listEntities(o),
     getRelations: (id) => store.getRelations(id),
+    // v0.7.0 实体热投影：实体热 = 关联记忆 heat 聚合（取 max）。无关联记忆
+    // 或 heatEnabled=false 时返回 null；前端据此决定图谱节点大小/明暗。
+    entityHeat: (entityId) => {
+      if (config.heatEnabled === false) return null;
+      const rels = store.getRelations(entityId) ?? [];
+      let max = -Infinity;
+      for (const rel of rels) {
+        if (!rel.memory_id) continue;
+        const mem = store.getById(rel.memory_id);
+        if (!mem) continue;
+        const h = computeHeat(mem, Date.now(), config);
+        if (h > max) max = h;
+      }
+      return max === -Infinity ? null : max;
+    },
     // Tag system (v0.6.2). setMemoryTags is the manual/user path: gated by
     // config.manualTagEnabled (default true), re-renders the mirror and fires
     // the write hook. applyMemoryTags is the raw write used by the autoDream

package/{lib → dsh-mneme/lib}/store.js

@@ -725,6 +725,9 @@ export function createStore(path) {
     return getById(id);
   }
 
+  // v0.7.0 语义：updated_at 只记录内容变更，绝不当访问（与 last_accessed_at
+  // 正交，sleep/heat 永不 fallback 到它）。合并/更新刷 updated_at 不应
+  // 重置热度时钟 —— 防 autoDream 合并动作伪装成"刚被召回"。
   function update(id, patch) {
     const existing = getById(id);
     if (!existing) throw new Error(`memory not found: ${id}`);
@@ -1288,6 +1291,19 @@ export function createStore(path) {
     return rows.map(toRecallRun);
   }
 
+  /**
+   * Rolling purge of the recall_runs production audit (v0.7.0): with recordRecall
+   * defaulting ON, the table would otherwise grow unboundedly on a busy store.
+   * Drop rows older than `days` (config.recallRetentionDays, default 90).
+   * created_at is an ISO TEXT string, so the ISO bound compares lexicographically.
+   * Returns the number of rows deleted (bookkeeping — never throws on empty).
+   */
+  function purgeRecallRunsOlderThan(days) {
+    const cutoff = new Date(Date.now() - days * 86400000).toISOString();
+    const result = db.prepare("DELETE FROM recall_runs WHERE created_at < ?").run(cutoff);
+    return result.changes;
+  }
+
   // --- recall evaluation trail (方案 B: separate from the production audit) -
 
   /**
@@ -2185,6 +2201,7 @@ export function createStore(path) {
     saveRecallRun,
     getRecallRun,
     listRecallRuns,
+    purgeRecallRunsOlderThan,
     saveRecallEval,
     getRecallEval,
     listRecallEvals,