dsh-memu-memory 1.1.2 → 1.2.0

package/lib/active-memory.js

@@ -0,0 +1,165 @@
+/**
+ * 主动记忆判定：一次闲时检查值不值得花 token。
+ *
+ * 三条输入都是"结构性"的，不做关键词判定：
+ *   H 真人回合数（只算 source.kind === 'user' 的消息）
+ *   C 新增证据量（真人文字 + 助手结论 + 去重后的工具结果，按字符估算）
+ *   U 有效工具工作单元（去重的成功工具结果；轮询、空输出、重复错误只算一次）
+ *
+ * 触发规则（可被 settings 覆盖）：
+ *   - 会话空闲 < activeMemoryStarvationMinutes：分数必须 >= minScore；
+ *   - 空闲 >= 饥饿阈值：小会话无条件检查（保证不会永远轮不到）；
+ *   - 大 transcript（>= largeTranscriptEvents）不吃饥饿豁免：真机回放里
+ *     5913 条事件的会话，一个"继续"回合只有 0.14~0.43 分，却会把整段
+ *     26MB 转录重新种进 fork；这种薄回合必须等分数达标；
+ *   - 近期刚整理过 / 刚注入过记忆：直接抑制，避免"记忆后立刻再 fork 一次"。
+ *
+ * 纯函数，无 IO，便于回放标定与单测。
+ */
+
+export const ACTIVE_MEMORY_VERSION = 1
+
+export const ACTIVE_MEMORY_POLICY = Object.freeze({
+  version: ACTIVE_MEMORY_VERSION,
+  minScore: 0.8,
+  starvationMinutes: 15,
+  consolidatedCooldownMinutes: 60,
+  recallCooldownMinutes: 15,
+  humanTurnsCap: 3,
+  evidenceCharsCap: 4000,
+  toolUnitsCap: 20,
+  partCap: 2,
+  // 超过这个规模，fork 的种子成本随整段转录增长，饥饿不再单独构成理由。
+  largeTranscriptEvents: 2000,
+  // 大 transcript 的守卫只该推迟一次检查，不该无限推迟。待整理区间一旦超过这个规模，
+  // 无论分数多低都要整理一次：游标不前移，那段内容就一直躺在 pending 里等着，
+  // 「省 token」和「永远不记」之间的差别是延迟上界，不是覆盖上界。
+  // 600 事件大约相当于一次中等长度的会话；20k 事件的首轮整理本来就贵，但那是内容
+  // 本身的价格，不是规则造成的浪费。
+  maxPendingEvents: 600,
+  weights: Object.freeze({ human: 0.35, content: 0.45, tool: 0.2 }),
+  // 单个工具结果计入证据量的上限；整段工具日志不能挤掉真人说的话。
+  toolResultCharsCap: 2000,
+})
+
+function textOfContent(content) {
+  if (typeof content === 'string') return content.trim()
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter(block => block && block.type === 'text' && typeof block.text === 'string')
+    .map(block => block.text)
+    .join(' ')
+    .trim()
+}
+
+/**
+ * 从一个事件窗口里收集证据。窗口应当只包含"上次检查之后"的事件；
+ * 调用方负责裁剪，这里不猜测边界。
+ */
+export function collectEvidence(events, policy = ACTIVE_MEMORY_POLICY) {
+  const evidence = {
+    humanTurns: 0,
+    humanChars: 0,
+    assistantChars: 0,
+    toolChars: 0,
+    toolUnits: 0,
+    toolCalls: 0,
+    lastHumanText: '',
+  }
+  const seenUnits = new Set()
+  for (const event of events || []) {
+    const type = event?.type
+    if (type === 'user/message') {
+      if (event.data?.source?.kind !== 'user') continue
+      const text = textOfContent(event.data?.content)
+      if (!text) continue
+      evidence.humanTurns += 1
+      evidence.humanChars += text.length
+      evidence.lastHumanText = text
+      continue
+    }
+    if (type === 'assistant/message') {
+      const blocks = event.data?.message?.content
+      if (!Array.isArray(blocks)) continue
+      for (const block of blocks) {
+        if (block?.type === 'tool-call') evidence.toolCalls += 1
+        else if (block?.type === 'text' && typeof block.text === 'string') evidence.assistantChars += block.text.trim().length
+      }
+      continue
+    }
+    if (type === 'tool/call') {
+      evidence.toolCalls += 1
+      continue
+    }
+    if (type === 'tool/result') {
+      const message = event.data?.message || {}
+      if (message.isError === true) continue
+      const text = textOfContent(message.content)
+      if (!text) continue
+      // 同一份结果重复出现（轮询、重读、重试）只算一次工作单元。
+      const key = text.slice(0, 160) + '|' + text.length
+      if (seenUnits.has(key)) continue
+      seenUnits.add(key)
+      evidence.toolUnits += 1
+      evidence.toolChars += Math.min(text.length, policy.toolResultCharsCap)
+    }
+  }
+  return evidence
+}
+
+/** 可解释评分：每个分项封顶，避免"只刷工具次数"把分数拉满。 */
+export function scoreEvidence(evidence, policy = ACTIVE_MEMORY_POLICY) {
+  const human = Number(evidence?.humanTurns) || 0
+  const contentChars = (Number(evidence?.humanChars) || 0) + (Number(evidence?.assistantChars) || 0) + (Number(evidence?.toolChars) || 0)
+  const units = Number(evidence?.toolUnits) || 0
+  const h = Math.min(human / policy.humanTurnsCap, policy.partCap)
+  const c = Math.min(contentChars / policy.evidenceCharsCap, policy.partCap)
+  const u = Math.min(units / policy.toolUnitsCap, policy.partCap)
+  const score = policy.weights.human * h + policy.weights.content * c + policy.weights.tool * u
+  return {
+    score: Math.round(score * 1000) / 1000,
+    parts: { human: h, content: c, tool: u, humanTurns: human, contentChars, toolUnits: units },
+  }
+}
+
+/**
+ * 是否唤醒检查。真人回合是硬门槛（纯工具轮询不构成检查理由），
+ * 其余交给分数；`starved` 由调用方按空闲时长传入。
+ * `transcriptEvents` 是整段会话的事件数，用来决定饥饿豁免是否还有成本意义。
+ */
+export function assessWake({ evidence, starved = false, transcriptEvents = 0, pendingEvents = 0, policy = ACTIVE_MEMORY_POLICY } = {}) {
+  const scored = scoreEvidence(evidence, policy)
+  if ((Number(evidence?.humanTurns) || 0) === 0) {
+    return { wake: false, reason: 'no-human-turn', ...scored }
+  }
+  // 积压优先于守卫：守卫的理由是「为一句轻话重种整段转录不划算」，但当整段转录本身
+  // 还没整理过时，那不是重种，是欠着。没有这条，一个大 transcript 只要每轮都是轻话，
+  // 就永远等不到检查——延迟没有上界，长会话的早期决定再也进不了记忆。
+  if (Number(pendingEvents) >= Number(policy.maxPendingEvents || Infinity)) {
+    return { wake: true, reason: 'backlog', ...scored }
+  }
+  const large = (Number(transcriptEvents) || 0) >= policy.largeTranscriptEvents
+  if (starved && !large) return { wake: true, reason: 'starved', ...scored }
+  if (scored.score < policy.minScore) {
+    return { wake: false, reason: large && starved ? 'large-transcript-thin' : 'low-score', ...scored }
+  }
+  return { wake: true, reason: 'score', ...scored }
+}
+
+/**
+ * 抑制原因：近期整理过（避免记忆后马上再 fork）或近期注入过记忆。
+ * 返回 null 表示不抑制。
+ */
+export function suppressionReason({
+  now = Date.now(),
+  lastSleepAt = null,
+  lastInjectedAt = null,
+  consolidatedCooldownMinutes = ACTIVE_MEMORY_POLICY.consolidatedCooldownMinutes,
+  recallCooldownMinutes = ACTIVE_MEMORY_POLICY.recallCooldownMinutes,
+} = {}) {
+  const sleep = Date.parse(lastSleepAt || '') || 0
+  if (sleep && now - sleep < consolidatedCooldownMinutes * 60_000) return 'recent-consolidation'
+  const recalled = Date.parse(lastInjectedAt || '') || 0
+  if (recalled && now - recalled < recallCooldownMinutes * 60_000) return 'recent-recall'
+  return null
+}

package/lib/activity-log.js

@@ -0,0 +1,190 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { logsDir, ensureDir, redactSecrets, warn } from './paths.js'
+
+// 记忆链路的活动日志：召回、写入、整理、向量。用途是回答"刚才那一下到底走了哪条路、
+// 召回/写入了什么、为什么没写成"，而不是给开发者看堆栈。
+//
+// 三条硬约束：
+// 1. 永不抛错。日志坏了不能把召回/写入一起弄坏（fail-open），失败只 warn 一次。
+// 2. 永不无限增长。内存里保留最近 MAX_ENTRIES 条，文件超过 MAX_FILE_BYTES 时重写成
+//    最近一半；这是本机诊断用的环形日志，不是审计材料。
+// 3. 出盘前脱敏。message 与 detail 都过 redactSecrets；detail 只留诊断需要的字段，
+//    正文最多 200 字符（召回查询、记忆标题），足够定位问题又不把整段对话抄进日志。
+
+export const ACTIVITY_KINDS = Object.freeze(['recall', 'write', 'consolidate', 'curate', 'vector', 'error', 'system', 'check'])
+const MAX_ENTRIES = 2000
+const MAX_FILE_BYTES = 4 * 1024 * 1024
+const MAX_MESSAGE_CHARS = 300
+const MAX_DETAIL_CHARS = 4000
+const MAX_QUERY_CHARS = 200
+
+let cache = null
+let loadWarned = false
+let writeWarned = false
+
+function activityFile() {
+  return path.join(logsDir(), 'activity.jsonl')
+}
+
+function clamp(value, max) {
+  const text = String(value ?? '')
+  return text.length > max ? text.slice(0, max - 1) + '…' : text
+}
+
+function safeDetail(value) {
+  if (value === undefined || value === null) return null
+  let text
+  try { text = JSON.stringify(value) } catch { text = JSON.stringify({ note: 'detail is not serializable' }) }
+  text = redactSecrets(text)
+  if (text.length > MAX_DETAIL_CHARS) text = text.slice(0, MAX_DETAIL_CHARS - 1) + '…'
+  try { return JSON.parse(text) } catch { return { text: text.slice(0, MAX_DETAIL_CHARS - 20) } }
+}
+
+function normalize(event = {}) {
+  const kind = ACTIVITY_KINDS.includes(event.kind) ? event.kind : 'system'
+  const level = ['info', 'warn', 'error'].includes(event.level) ? event.level : (event.ok === false ? 'warn' : 'info')
+  const at = typeof event.at === 'string' && !Number.isNaN(Date.parse(event.at)) ? event.at : new Date().toISOString()
+  const refs = Array.isArray(event.refs) ? event.refs.filter(item => typeof item === 'string' && item).slice(0, 20) : []
+  return {
+    id: 'act-' + Date.now().toString(36) + '-' + crypto.randomBytes(3).toString('hex'),
+    at,
+    kind,
+    level,
+    scope: event.scope === 'private' || event.scope === 'global' ? event.scope : null,
+    sessionId: typeof event.sessionId === 'string' ? event.sessionId : null,
+    libraryId: typeof event.libraryId === 'string' ? event.libraryId : null,
+    message: redactSecrets(clamp(event.message, MAX_MESSAGE_CHARS)),
+    detail: safeDetail(event.detail),
+    refs,
+    ok: event.ok !== false,
+  }
+}
+
+function parseLines(text) {
+  const out = []
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      const value = JSON.parse(line)
+      if (value && typeof value === 'object' && typeof value.at === 'string') out.push(value)
+    } catch {}
+  }
+  return out
+}
+
+function load() {
+  if (cache) return cache
+  cache = []
+  try {
+    const file = activityFile()
+    if (fs.existsSync(file)) cache = parseLines(fs.readFileSync(file, 'utf8')).slice(-MAX_ENTRIES)
+  } catch (error) {
+    if (!loadWarned) {
+      loadWarned = true
+      try { warn('activity log could not be read: ' + (error?.message || error) + ' (recall and writes continue; the log starts empty)') } catch {}
+    }
+    cache = []
+  }
+  return cache
+}
+
+function rewrite(entries) {
+  const file = activityFile()
+  ensureDir(path.dirname(file))
+  const temp = file + '.tmp-' + process.pid
+  fs.writeFileSync(temp, entries.map(entry => JSON.stringify(entry)).join('\n') + (entries.length ? '\n' : ''), 'utf8')
+  fs.renameSync(temp, file)
+}
+
+/** 记录一条活动。永不抛错；返回写入的条目（失败时返回 null）。 */
+export function record(event) {
+  try {
+    const entry = normalize(event)
+    const entries = load()
+    entries.push(entry)
+    if (entries.length > MAX_ENTRIES) entries.splice(0, entries.length - MAX_ENTRIES)
+    try {
+      const file = activityFile()
+      ensureDir(path.dirname(file))
+      fs.appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8')
+      let size = 0
+      try { size = fs.statSync(file).size } catch {}
+      if (size > MAX_FILE_BYTES) rewrite(entries.slice(-Math.floor(MAX_ENTRIES / 2)))
+    } catch (error) {
+      if (!writeWarned) {
+        writeWarned = true
+        try { warn('activity log could not be written: ' + (error?.message || error) + ' (memory operations are unaffected)') } catch {}
+      }
+    }
+    return entry
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 最近的活动，最新在前。`q` 只做字面包含匹配（大小写不敏感），不解释正则：
+ * 这是给人看的筛选框，不是查询语言。
+ */
+export function listEvents({ limit = 200, kind = null, level = null, scope = null, sessionId = null, since = null, q = null } = {}) {
+  const wanted = ACTIVITY_KINDS.includes(kind) ? kind : null
+  const wantedLevel = ['info', 'warn', 'error'].includes(level) ? level : null
+  const sinceTime = typeof since === 'string' && !Number.isNaN(Date.parse(since)) ? Date.parse(since) : null
+  const needle = typeof q === 'string' && q.trim() ? q.trim().toLowerCase() : null
+  const count = Math.max(1, Math.min(MAX_ENTRIES, Number(limit) || 200))
+  const rows = []
+  const entries = load()
+  for (let index = entries.length - 1; index >= 0 && rows.length < count; index -= 1) {
+    const entry = entries[index]
+    if (wanted && entry.kind !== wanted) continue
+    if (wantedLevel && entry.level !== wantedLevel) continue
+    if (scope && entry.scope !== scope) continue
+    if (sessionId && entry.sessionId !== sessionId) continue
+    if (sinceTime && (Date.parse(entry.at) || 0) < sinceTime) continue
+    if (needle) {
+      const haystack = (entry.message + ' ' + JSON.stringify(entry.detail || {}) + ' ' + (entry.refs || []).join(' ')).toLowerCase()
+      if (!haystack.includes(needle)) continue
+    }
+    rows.push(entry)
+  }
+  return rows
+}
+
+export function logStats() {
+  const entries = load()
+  const counts = {}
+  for (const entry of entries) counts[entry.kind] = (counts[entry.kind] || 0) + 1
+  let bytes = 0
+  try { bytes = fs.statSync(activityFile()).size } catch {}
+  return { total: entries.length, bytes, counts, file: activityFile(), capped: MAX_ENTRIES, maxBytes: MAX_FILE_BYTES }
+}
+
+/** 清空日志（显式操作；不是自动裁剪）。 */
+export function clearEvents() {
+  cache = []
+  try { rewrite([]) } catch (error) {
+    try { warn('activity log could not be cleared: ' + (error?.message || error)) } catch {}
+  }
+  return { ok: true }
+}
+
+/** 导出为可直接贴进 issue 的 JSONL 文本。 */
+export function exportEvents(options = {}) {
+  return listEvents({ limit: Math.min(MAX_ENTRIES, Number(options.limit) || MAX_ENTRIES), ...options })
+    .map(entry => JSON.stringify(entry))
+    .join('\n')
+}
+
+/** 测试用：丢掉进程内缓存，下一次调用重新读盘。 */
+export function resetActivityLogCache() {
+  cache = null
+  loadWarned = false
+  writeWarned = false
+}
+
+// 一个自动裁剪的便捷入口：`query` 是召回/整理里最常要看的东西，统一截断。
+export function clipQuery(value) {
+  return clamp(redactSecrets(String(value ?? '')), MAX_QUERY_CHARS)
+}