@modusensus/dsh-mneme 0.8.3 → 0.8.5

package/lib/heat.js

@@ -1,136 +1,144 @@
-// 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));
-}
+// dsh-mneme/src/heat.js
+// 热度（heat）纯函数模块：基于广义指数遗忘曲线计算 memory 的当前热度。
+// 零数据库依赖，不引入任何外部依赖。
+//
+// 曲线选型（issue #218，2026-09-18 与维护者对齐）：H = exp(-λ·Δt^β)。
+// FadeMem v2 Eq4 的广义指数族——λ 管速率（per-type 差异），β 管形状
+// （β=1 退化为纯指数，β<1 呈亚线性长尾）；λ=0 免疫位在指数式下同样恒 1。
+// v0.7.0–0.8.3 存量为幂律 H=(1+λΔt)^-α；幂律在 #164 已收集论文集外，
+// 真实负载回放（#218 验收 4）时对两个曲线族做拟合 A/B，幂律更贴合再议。
+
+/**
+ * 默认的 per-type 衰减因子 λ。
+ * λ = 0 表示该类型免疫热度衰减，热度恒为 1.0。
+ */
+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,   // 较快（会话摘要不断被合并）
+});
+
+const HOUR_MS = 3600000;
+const DEFAULT_BETA = 1.0;
+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);
+}
+
+/**
+ * 解析并校验配置，提供安全的 β 与衰减表。
+ */
+function resolveConfig(config) {
+  const safe = config && typeof config === 'object' ? config : {};
+
+  let beta = safe.heatGlobalBeta ?? DEFAULT_BETA;
+  if (!Number.isFinite(beta) || beta <= 0) {
+    beta = DEFAULT_BETA;
+  }
+
+  const decayMap = safe.heatTypeDecay ?? TYPE_DECAY_DEFAULTS;
+
+  return { beta, decayMap };
+}
+
+/**
+ * 构建热度信号对象，便于调试与后续扩展。
+ *
+ * @param {object} memory - memory 记录
+ * @param {object} config - 插件配置
+ * @param {number} [now=Date.now()] - 当前毫秒时间戳
+ * @returns {{ type, ref, lambda, beta, deltaHours }}
+ */
+export function buildHeatSignals(memory, config, now = Date.now()) {
+  const nowMs = Number.isFinite(now) ? now : Date.now();
+  const ref = getRef(memory);
+  const { beta, 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, beta, deltaHours };
+}
+
+/**
+ * 计算 memory 的热度 H ∈ [0, 1]。
+ *
+ * 公式：H = exp(-λ · Δ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 { beta, lambda, deltaHours, ref } = signals;
+
+  // 无有效参考时间、或未来时间，热度视为满格
+  if (!Number.isFinite(ref) || deltaHours <= 0) {
+    return 1.0;
+  }
+
+  // λ = 0 的类型免疫，热度恒满
+  if (lambda === 0) {
+    return 1.0;
+  }
+
+  const heat = Math.exp(-lambda * deltaHours ** beta);
+
+  // 防止浮点误差越界
+  return Math.min(1, Math.max(0, heat));
+}

package/lib/hot-memory.js

@@ -1,46 +1,46 @@
-// Session-scoped hot memory (v0.5.0 召回率优化 1.3): a short-term buffer of
-// the latest dialogue rounds, kept strictly apart from the long-term memory
-// store. The injector renders it ahead of the long-term recall block so the
-// agent sees "what we were just talking about" without those rounds ever
-// being persisted as memories. Bounded two ways: maxRounds (count) and
-// maxTokens (budget) — whichever evicts first.
-
-// CJK-aware token estimate: one Chinese character ≈ 0.6 tokens (clustering
-// behavior of mainstream tokenizers), one ASCII char ≈ 0.25.
-export function estimateTokens(text) {
-  const s = String(text ?? "");
-  let cjk = 0;
-  for (const ch of s) if (ch >= "\u4e00" && ch <= "\u9fff") cjk++;
-  return Math.ceil(cjk * 0.6 + (s.length - cjk) * 0.25);
-}
-
-/**
- * @param {{maxRounds?: number, maxTokens?: number}} opts
- * @returns {{add(round: {query: string, response?: string}): void,
- *            getContext(): string,
- *            rounds(): Array, clear(): void}}
- */
-export function createHotMemory({ maxRounds = 5, maxTokens = 2000 } = {}) {
-  const buffer = [];
-
-  function totalTokens() {
-    return buffer.reduce(
-      (sum, r) => sum + estimateTokens(`Q: ${r.query}\nA: ${r.response ?? ""}`),
-      0
-    );
-  }
-
-  return {
-    add(round) {
-      if (!round?.query) return;
-      buffer.push({ query: String(round.query), response: String(round.response ?? "") });
-      while (buffer.length > maxRounds) buffer.shift();
-      while (buffer.length > 1 && totalTokens() > maxTokens) buffer.shift();
-    },
-    getContext() {
-      return buffer.map((r) => `Q: ${r.query}\nA: ${r.response ?? ""}`).join("\n\n");
-    },
-    rounds: () => [...buffer],
-    clear() { buffer.length = 0; }
-  };
-}
+// Session-scoped hot memory (v0.5.0 召回率优化 1.3): a short-term buffer of
+// the latest dialogue rounds, kept strictly apart from the long-term memory
+// store. The injector renders it ahead of the long-term recall block so the
+// agent sees "what we were just talking about" without those rounds ever
+// being persisted as memories. Bounded two ways: maxRounds (count) and
+// maxTokens (budget) — whichever evicts first.
+
+// CJK-aware token estimate: one Chinese character ≈ 0.6 tokens (clustering
+// behavior of mainstream tokenizers), one ASCII char ≈ 0.25.
+export function estimateTokens(text) {
+  const s = String(text ?? "");
+  let cjk = 0;
+  for (const ch of s) if (ch >= "\u4e00" && ch <= "\u9fff") cjk++;
+  return Math.ceil(cjk * 0.6 + (s.length - cjk) * 0.25);
+}
+
+/**
+ * @param {{maxRounds?: number, maxTokens?: number}} opts
+ * @returns {{add(round: {query: string, response?: string}): void,
+ *            getContext(): string,
+ *            rounds(): Array, clear(): void}}
+ */
+export function createHotMemory({ maxRounds = 5, maxTokens = 2000 } = {}) {
+  const buffer = [];
+
+  function totalTokens() {
+    return buffer.reduce(
+      (sum, r) => sum + estimateTokens(`Q: ${r.query}\nA: ${r.response ?? ""}`),
+      0
+    );
+  }
+
+  return {
+    add(round) {
+      if (!round?.query) return;
+      buffer.push({ query: String(round.query), response: String(round.response ?? "") });
+      while (buffer.length > maxRounds) buffer.shift();
+      while (buffer.length > 1 && totalTokens() > maxTokens) buffer.shift();
+    },
+    getContext() {
+      return buffer.map((r) => `Q: ${r.query}\nA: ${r.response ?? ""}`).join("\n\n");
+    },
+    rounds: () => [...buffer],
+    clear() { buffer.length = 0; }
+  };
+}