dsh-memu-memory 1.1.2 → 1.2.0

package/tests/active-memory.test.mjs

@@ -0,0 +1,129 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const { ACTIVE_MEMORY_POLICY, assessWake, collectEvidence, scoreEvidence, suppressionReason } = await import('../lib/active-memory.js')
+
+// 2026-10-30 的现场：长会话里连续触发整理，每次都把整段转录种进 fork，重复付 token。
+// 这组用例钉住"什么时候值得唤醒"和"什么时候必须抑制"。
+
+const human = text => ({ type: 'user/message', data: { source: { kind: 'user' }, content: [{ type: 'text', text }] } })
+const pluginNotice = text => ({ type: 'user/message', data: { source: { kind: 'plugin:other' }, content: [{ type: 'text', text }] } })
+const assistant = (blocks) => ({ type: 'assistant/message', data: { message: { content: blocks } } })
+const toolResult = (text, extra = {}) => ({ type: 'tool/result', data: { message: { isError: false, content: [{ type: 'text', text }], ...extra } } })
+
+test('evidence only counts what a person actually typed, plus deduped work', () => {
+  const evidence = collectEvidence([
+    human('帮我看一下这个 fork 为什么建不起来'),
+    pluginNotice('（插件提示：本轮召回 3 条）'),
+    assistant([{ type: 'text', text: '看到了，是模型路由没继承。' }, { type: 'tool-call', name: 'read' }]),
+    toolResult('文件内容 A'.repeat(100)),
+    toolResult('文件内容 A'.repeat(100)),
+    toolResult('   '),
+    { type: 'tool/result', data: { message: { isError: true, content: [{ type: 'text', text: 'boom' }] } } },
+  ])
+  assert.equal(evidence.humanTurns, 1)
+  assert.equal(evidence.toolCalls, 1)
+  assert.equal(evidence.toolUnits, 1, 'polling repeats and error results are not work units')
+  assert.ok(evidence.toolChars > 0 && evidence.toolChars <= ACTIVE_MEMORY_POLICY.toolResultCharsCap)
+  assert.ok(evidence.assistantChars > 0)
+})
+
+test('each score part is capped so tool spam cannot reach the threshold alone', () => {
+  const manyTools = { humanTurns: 0, humanChars: 0, assistantChars: 0, toolChars: 200_000, toolUnits: 500 }
+  const scored = scoreEvidence(manyTools)
+  assert.equal(scored.parts.tool, ACTIVE_MEMORY_POLICY.partCap)
+  const absent = assessWake({ evidence: manyTools })
+  assert.equal(absent.wake, false)
+  assert.equal(absent.reason, 'no-human-turn')
+})
+
+test('a real long turn clears the threshold, a greeting does not', () => {
+  const longTurn = collectEvidence([
+    human('把 managed vector 的切换重建链路再核一遍，尤其是回读和失败回滚'),
+    assistant([{ type: 'text', text: '结论：回读缺失会导致整代重建作废。'.repeat(40) }, { type: 'tool-call', name: 'read' }]),
+    toolResult('daemon 日志与调用链摘要'.repeat(80)),
+    toolResult('测试输出摘要'.repeat(80)),
+    toolResult('配置摘要'.repeat(40)),
+    toolResult('失败明细样例'.repeat(60)),
+    toolResult('迁移账本摘要'.repeat(60)),
+    human('继续，把失败明细也加上'),
+    toolResult('权限矩阵摘要'.repeat(50)),
+    toolResult('重建进度样例'.repeat(50)),
+    human('再补一版日志页的筛选项'),
+  ])
+  const wake = assessWake({ evidence: longTurn })
+  assert.equal(wake.wake, true)
+  assert.ok(wake.score >= ACTIVE_MEMORY_POLICY.minScore)
+
+  const greeting = assessWake({ evidence: collectEvidence([human('早'), assistant([{ type: 'text', text: '早！' }])]) })
+  assert.equal(greeting.wake, false)
+  assert.equal(greeting.reason, 'low-score')
+})
+
+test('starvation wakes a quiet-but-long small session, not a large transcript', () => {
+  const thin = collectEvidence([human('嗯，继续')])
+  assert.equal(assessWake({ evidence: thin }).wake, false)
+  const starved = assessWake({ evidence: thin, starved: true })
+  assert.equal(starved.wake, true)
+  assert.equal(starved.reason, 'starved')
+  // 真机会话 5913 条事件：fork 要把整段转录重新种一遍，薄回合不能靠饥饿放行。
+  const largeThin = assessWake({ evidence: thin, starved: true, transcriptEvents: 5913 })
+  assert.equal(largeThin.wake, false)
+  assert.equal(largeThin.reason, 'large-transcript-thin')
+  assert.equal(assessWake({ evidence: thin, starved: false, transcriptEvents: 5913 }).reason, 'low-score')
+})
+
+test('a dense turn still wakes a large transcript on merit', () => {
+  const dense = collectEvidence([
+    human('把这次重建失败的原因和回滚步骤记下来'),
+    assistant([{ type: 'text', text: '根因是提交载荷少了 recall_files。'.repeat(300) }, { type: 'tool-call', name: 'read' }]),
+    ...Array.from({ length: 20 }, (_, i) => toolResult(('回读失败明细 ' + i + ' ').repeat(200))),
+    human('还有迁移账本和失败明细'),
+    human('最后给我一版回滚步骤'),
+  ])
+  const wake = assessWake({ evidence: dense, starved: true, transcriptEvents: 5913 })
+  assert.equal(wake.wake, true)
+  assert.equal(wake.reason, 'score')
+  assert.ok(wake.score >= ACTIVE_MEMORY_POLICY.minScore)
+  assert.equal(ACTIVE_MEMORY_POLICY.largeTranscriptEvents, 2000, 'threshold is part of the calibrated policy')
+})
+
+test('recent consolidation or a recent recall suppresses the idle fork', () => {
+  const now = Date.parse('2026-10-30T05:00:00.000Z')
+  assert.equal(suppressionReason({ now, lastSleepAt: '2026-10-30T04:50:00.000Z' }), 'recent-consolidation')
+  assert.equal(suppressionReason({ now, lastInjectedAt: '2026-10-30T04:55:00.000Z' }), 'recent-recall')
+  assert.equal(suppressionReason({ now, lastSleepAt: '2026-10-30T03:00:00.000Z', lastInjectedAt: '2026-10-30T04:00:00.000Z' }), null)
+  assert.equal(suppressionReason({ now, lastSleepAt: '2026-10-30T04:50:00.000Z', consolidatedCooldownMinutes: 5 }), null, 'cooldown is configurable')
+  // 没有时间戳 = 从未整理/注入，不抑制。
+  assert.equal(suppressionReason({ now }), null)
+})
+
+test('a large unconsolidated backlog wakes even when the turn itself is thin', () => {
+  // 守卫的理由是「为一句轻话重种整段转录不划算」。但当整段转录本身还没整理过，
+  // 那不是重种，是欠着：没有积压上界，一个 20k 事件的会话只要每轮都说「继续」，
+  // 它的早期决定就永远进不了记忆——延迟没有上界，等于丢失。
+  const thin = collectEvidence([
+    human('继续'),
+    assistant([{ type: 'text', text: '还在跑。' }]),
+  ])
+  const blocked = assessWake({ evidence: thin, starved: true, transcriptEvents: 20_000, pendingEvents: 0 })
+  assert.equal(blocked.wake, false)
+  assert.equal(blocked.reason, 'large-transcript-thin')
+
+  const owed = assessWake({ evidence: thin, starved: true, transcriptEvents: 20_000, pendingEvents: 900 })
+  assert.equal(owed.wake, true)
+  assert.equal(owed.reason, 'backlog')
+
+  // 边界：正好达到上界就放行，且没有真人回合时积压不构成理由（那是 no-human-turn）。
+  assert.equal(assessWake({ evidence: thin, starved: true, transcriptEvents: 20_000, pendingEvents: 600 }).reason, 'backlog')
+  assert.equal(assessWake({ evidence: thin, starved: true, transcriptEvents: 20_000, pendingEvents: 599 }).reason, 'large-transcript-thin')
+  const noHuman = collectEvidence([assistant([{ type: 'text', text: '还在跑。' }])])
+  assert.equal(assessWake({ evidence: noHuman, starved: true, transcriptEvents: 20_000, pendingEvents: 900 }).reason, 'no-human-turn')
+})
+
+test('the backlog bound stays out of the way for a session that is already up to date', () => {
+  const thin = collectEvidence([human('继续'), assistant([{ type: 'text', text: '好。' }])])
+  // 已整理到最新：待整理区间很小，规则回到原来的分数/饥饿判定。
+  assert.equal(assessWake({ evidence: thin, starved: false, transcriptEvents: 20_000, pendingEvents: 3 }).wake, false)
+  assert.equal(assessWake({ evidence: thin, starved: true, transcriptEvents: 900, pendingEvents: 3 }).reason, 'starved')
+})

package/tests/activity-log.test.mjs

@@ -0,0 +1,126 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-memu-memory-activity-'))
+process.env.DSH_MEMU_HOME = home
+process.env.DSH_MEMU_MEMORY_HOME = home
+
+const activity = await import('../lib/activity-log.js')
+const paths = await import('../lib/paths.js')
+
+test.after(() => {
+  try { fs.rmSync(home, { recursive: true, force: true }) } catch {}
+})
+
+test.beforeEach(() => {
+  activity.clearEvents()
+  activity.resetActivityLogCache()
+  paths.setWarnSink(null)
+})
+
+test('records newest first and persists a JSONL line', () => {
+  activity.record({ kind: 'recall', scope: 'private', sessionId: 's1', libraryId: 'lib', message: 'first' })
+  activity.record({ kind: 'write', sessionId: 's1', message: 'second', detail: { ids: ['mem-1'] }, refs: ['mem-1'] })
+  const rows = activity.listEvents()
+  assert.deepEqual(rows.map(row => row.message), ['second', 'first'])
+  assert.deepEqual(rows[0].refs, ['mem-1'])
+  const file = path.join(home, 'logs', 'activity.jsonl')
+  assert.ok(fs.existsSync(file))
+  assert.equal(fs.readFileSync(file, 'utf8').trim().split('\n').length, 2)
+})
+
+test('filters by kind, session, scope and free text', () => {
+  activity.record({ kind: 'recall', scope: 'private', sessionId: 'a', message: 'recall a', detail: { route: 'managed-vector-rrf' } })
+  activity.record({ kind: 'recall', scope: 'global', sessionId: 'b', message: 'recall b', detail: { route: 'local' } })
+  activity.record({ kind: 'write', scope: 'private', sessionId: 'a', message: 'write a' })
+  assert.equal(activity.listEvents({ kind: 'recall' }).length, 2)
+  assert.equal(activity.listEvents({ kind: 'recall', sessionId: 'b' }).length, 1)
+  assert.equal(activity.listEvents({ scope: 'private' }).length, 2)
+  assert.equal(activity.listEvents({ q: 'managed-vector' }).length, 1)
+  assert.equal(activity.listEvents({ q: 'nothing-here' }).length, 0)
+})
+
+test('secrets are redacted before they reach the file', () => {
+  activity.record({
+    kind: 'error',
+    message: 'failed with sk-abcdefghijklmnop and Bearer abcdefghijklmnop',
+    detail: { apiKey: 'sk-zyxwvutsrqponmlk', note: 'Authorization: Bearer abcdefghijklmnopqrst' },
+  })
+  const [row] = activity.listEvents()
+  const text = JSON.stringify(row)
+  assert.doesNotMatch(text, /sk-abcdefghijklmnop/)
+  assert.doesNotMatch(text, /Bearer abcdefghijklmnop/)
+  assert.match(text, /REDACTED/)
+})
+
+test('long messages and details are clipped instead of bloating the log', () => {
+  activity.record({ kind: 'write', message: 'x'.repeat(5000), detail: { body: 'y'.repeat(9000) } })
+  const [row] = activity.listEvents()
+  assert.ok(row.message.length <= 300)
+  assert.ok(JSON.stringify(row.detail).length <= 4001)
+})
+
+test('a corrupt log starts empty and leaves a warning instead of throwing', () => {
+  activity.clearEvents()
+  const file = path.join(home, 'logs', 'activity.jsonl')
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, '{not json\n', 'utf8')
+  activity.resetActivityLogCache()
+  const warnings = []
+  paths.setWarnSink(message => warnings.push(String(message)))
+  assert.deepEqual(activity.listEvents(), [])
+  assert.equal(warnings.length, 0, 'a bad line is skipped silently, not treated as an error')
+  const entry = activity.record({ kind: 'recall', message: 'after corruption' })
+  assert.ok(entry)
+  assert.equal(activity.listEvents()[0].message, 'after corruption')
+})
+
+test('an unwritable directory degrades to memory-only and warns once', () => {
+  activity.clearEvents()
+  const warnings = []
+  paths.setWarnSink(message => warnings.push(String(message)))
+  const original = fs.appendFileSync
+  fs.appendFileSync = () => { throw Object.assign(new Error('EACCES: fixture'), { code: 'EACCES' }) }
+  try {
+    activity.record({ kind: 'write', message: 'one' })
+    activity.record({ kind: 'write', message: 'two' })
+  } finally {
+    fs.appendFileSync = original
+  }
+  assert.deepEqual(activity.listEvents().map(row => row.message), ['two', 'one'], 'memory keeps working')
+  assert.equal(warnings.filter(message => /activity log could not be written/.test(message)).length, 1)
+})
+
+test('clear empties both the cache and the file; export emits JSONL', () => {
+  activity.record({ kind: 'write', message: 'a' })
+  activity.record({ kind: 'write', message: 'b' })
+  const text = activity.exportEvents()
+  assert.equal(text.split('\n').length, 2)
+  for (const line of text.split('\n')) JSON.parse(line)
+  activity.clearEvents()
+  assert.deepEqual(activity.listEvents(), [])
+  const file = path.join(home, 'logs', 'activity.jsonl')
+  assert.equal(fs.readFileSync(file, 'utf8'), '')
+})
+
+test('the ring keeps the newest entries and reports its own size', () => {
+  for (let index = 0; index < 30; index += 1) activity.record({ kind: 'recall', message: 'row ' + index })
+  const rows = activity.listEvents({ limit: 5 })
+  assert.deepEqual(rows.map(row => row.message), ['row 29', 'row 28', 'row 27', 'row 26', 'row 25'])
+  const stats = activity.logStats()
+  assert.equal(stats.total, 30)
+  assert.ok(stats.bytes > 0)
+  assert.equal(stats.file, path.join(home, 'logs', 'activity.jsonl'))
+})
+
+test('a level is inferred from ok=false and kept when explicit', () => {
+  activity.record({ kind: 'consolidate', ok: false, message: 'timed out' })
+  activity.record({ kind: 'consolidate', ok: true, level: 'error', message: 'explicit' })
+  const rows = activity.listEvents({ kind: 'consolidate' })
+  assert.equal(rows[0].level, 'error')
+  assert.equal(rows[1].level, 'warn')
+  assert.equal(activity.listEvents({ level: 'warn' }).length, 1)
+})

package/tests/activity-wiring.test.mjs

@@ -0,0 +1,103 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-memu-memory-wiring-'))
+process.env.DSH_MEMU_HOME = home
+process.env.DSH_MEMU_MEMORY_HOME = home
+
+const state = await import('../lib/state.js')
+const memory = await import('../lib/memory.js')
+const inject = await import('../lib/inject.js')
+const activity = await import('../lib/activity-log.js')
+const { requestPrivateConsolidation } = await import('../lib/private.js')
+const { record } = activity
+
+test.after(() => {
+  try { fs.rmSync(home, { recursive: true, force: true }) } catch {}
+})
+
+test.beforeEach(() => {
+  activity.clearEvents()
+  state.updateSettings({ memoryBackend: 'agent', vectorSource: 'local', relevanceThreshold: 0, sleepConsolidation: false })
+})
+
+function bind(sessionId) {
+  const cwd = path.join(home, 'ws', sessionId)
+  state.ensureSession(sessionId, { cwd, agentPreset: 'coding' })
+  return { cwd, exec: { agent: { session: { header: { id: sessionId, cwd, agentPreset: 'coding' } } } } }
+}
+
+test('a private write lands in the activity log with its id', async () => {
+  const { exec } = bind('wiring-write')
+  const written = await memory.privateRemember({ exec, content: '写入链路必须留一条日志', title: '写入链路' })
+  const rows = activity.listEvents({ kind: 'write' })
+  assert.equal(rows.length, 1)
+  assert.equal(rows[0].scope, 'private')
+  assert.equal(rows[0].sessionId, 'wiring-write')
+  assert.deepEqual(rows[0].refs, [written.id])
+  assert.match(rows[0].message, /写入/)
+  assert.ok(rows[0].libraryId, 'the library is recorded so the log row can be traced back')
+})
+
+test('a turn recall records the ids it injected and the route it took', async () => {
+  const { exec } = bind('wiring-recall')
+  const written = await memory.privateRemember({ exec, content: '海边的黄昏散步', title: '海边的黄昏' })
+  activity.clearEvents()
+  const binding = state.getSessionBinding('wiring-recall')
+  const result = await inject.buildRecall(binding, '海边的黄昏', 1, state.getSettings(), exec, 'wiring-recall')
+  const rows = activity.listEvents({ kind: 'recall' })
+  assert.equal(rows.length, 1)
+  assert.equal(rows[0].sessionId, 'wiring-recall')
+  assert.equal(rows[0].ok, true)
+  assert.deepEqual(rows[0].detail.ids, result.ids)
+  assert.deepEqual(rows[0].refs, result.ids)
+  assert.ok(result.ids.includes(written.id), 'the seeded memory is what got recalled')
+  assert.equal(rows[0].detail.route, undefined, 'the route is reported per layer')
+  assert.ok(['local', 'managed-vector-rrf'].includes(rows[0].detail.privateRoute))
+})
+
+test('a recall with a degraded semantic leg is logged as not-ok', async () => {
+  const { exec } = bind('wiring-recall-error')
+  state.updateSettings({ memoryBackend: 'api', vectorSource: 'local' })
+  const binding = state.getSessionBinding('wiring-recall-error')
+  const result = await inject.buildRecall(binding, 'anything', 1, state.getSettings(), exec, 'wiring-recall-error')
+  const [row] = activity.listEvents({ kind: 'recall' })
+  assert.equal(row.ok, false)
+  assert.ok(row.detail.errors.length > 0)
+  assert.ok(result.errors.length > 0, 'the caller still sees the error')
+})
+
+test('a consolidation that cannot start is logged with its reason', async () => {
+  bind('wiring-consolidate')
+  const result = await requestPrivateConsolidation({ get: () => undefined }, 'wiring-consolidate')
+  assert.equal(result.ok, false)
+  const [row] = activity.listEvents({ kind: 'consolidate' })
+  assert.equal(row.ok, false)
+  assert.equal(row.sessionId, 'wiring-consolidate')
+  assert.equal(row.level, 'error')
+  assert.match(row.message, /整理失败/)
+  assert.match(row.message, /readSession/)
+})
+
+test('a vector write outside an active generation is logged as a warning', async () => {
+  const { exec } = bind('wiring-vector')
+  state.updateSettings({ memoryBackend: 'api', vectorSource: 'local' })
+  await memory.privateRemember({ exec, content: '没有代际时也要落库', title: '退化写入' })
+  const rows = activity.listEvents({ kind: 'vector' })
+  assert.equal(rows.length, 1)
+  assert.equal(rows[0].level, 'warn')
+  assert.match(rows[0].message, /降级/)
+})
+
+test('the log stays queryable by session and kind together', async () => {
+  const a = bind('wiring-a')
+  const b = bind('wiring-b')
+  await memory.privateRemember({ exec: a.exec, content: 'a 的写入', title: 'a' })
+  await memory.privateRemember({ exec: b.exec, content: 'b 的写入', title: 'b' })
+  record({ kind: 'recall', sessionId: 'wiring-a', message: 'a 的召回' })
+  assert.equal(activity.listEvents({ sessionId: 'wiring-a' }).length, 2)
+  assert.equal(activity.listEvents({ sessionId: 'wiring-a', kind: 'write' }).length, 1)
+})

package/tests/appendix-b.test.mjs

@@ -0,0 +1,212 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-memu-memory-appb-'))
+process.env.DSH_MEMU_HOME = home
+
+const state = await import('../lib/state.js')
+const memory = await import('../lib/memory.js')
+const inject = await import('../lib/inject.js')
+const mood = await import('../lib/mood.js')
+
+test.after(() => {
+  try { fs.rmSync(home, { recursive: true, force: true }) } catch {}
+})
+
+function execFor(sessionId, cwd) {
+  return { agent: { session: { header: { id: sessionId, cwd, agentPreset: 'coding' } } } }
+}
+
+function setup(name) {
+  const cwd = path.join(home, 'proj-' + name)
+  const sessionId = 'appb-' + name
+  const binding = state.ensureSession(sessionId, { cwd, agentPreset: 'coding' })
+  return { cwd, sessionId, binding, exec: execFor(sessionId, cwd) }
+}
+
+// ---- source: default, explicit, and illegal ----
+
+test('source defaults to inferred, not user_said', async () => {
+  const { exec, binding } = setup('source')
+  const { id } = await memory.privateRemember({ exec, content: 'The build script probably wipes dist before bundling.', title: 'build wipe' })
+  const entry = state.loadPrivateIndex(binding.libraryId).entries[id]
+  // Defaulting to user_said made every model conclusion read as a quotable quote.
+  assert.equal(entry.source, 'inferred')
+
+  const quoted = await memory.privateRemember({ exec, content: 'He said the ledger lives in docs/ledger.md.', title: 'ledger', source: 'user_said' })
+  assert.equal(state.loadPrivateIndex(binding.libraryId).entries[quoted.id].source, 'user_said')
+})
+
+test('an unknown source is refused instead of stored', async () => {
+  const { exec } = setup('source-bad')
+  await assert.rejects(
+    () => memory.privateRemember({ exec, content: 'x', title: 'x', source: 'user-stated' }),
+    /source must be/,
+  )
+})
+
+// ---- cue derivation ----
+
+test('cue candidates skip side-event, unspeakable, secret, and too-new entries', async () => {
+  const { sessionId, binding, exec } = setup('candidates')
+  const old = new Date(Date.now() - 40 * 3600_000).toISOString()
+  const keep = await memory.privateRemember({ exec, content: 'The hiss of the kettle at four in the morning.', title: 'kettle' })
+  // A cue-born memory is a side_event pin, which the host only accepts while that
+  // exact cue is still alive — so the cue has to be armed first.
+  state.armCue(sessionId, { id: 'cue-seed', text: 'a seed cue', createdAt: new Date().toISOString() })
+  const fromCue = await memory.privateRemember({
+    exec, content: 'A memory born of a cue.', title: 'born',
+    layer: 'must_remember', pinReason: '它一直挥之不去，我放不下那只杯子。', pinSource: 'side_event', sideEventId: 'cue-seed',
+  })
+  const silent = await memory.privateRemember({ exec, content: 'Cannot be told.', title: 'silent', disclosure: 'never_say' })
+  const secret = await memory.privateRemember({ exec, content: 'Hidden body.', title: 'secret', visibility: 'secret' })
+  const fresh = await memory.privateRemember({ exec, content: 'Just written a moment ago.', title: 'fresh' })
+
+  // Age everything so the 12h gate is what decides, except the fresh one.
+  const index = state.loadPrivateIndex(binding.libraryId)
+  for (const id of [keep.id, fromCue.id, silent.id, secret.id]) index.entries[id].updatedAt = old
+  state.savePrivateIndex(binding.libraryId, index)
+
+  const ids = memory.cueCandidates({ libraryId: binding.libraryId, sessionId }).map((c) => c.id)
+  assert.ok(ids.includes(keep.id))
+  assert.ok(!ids.includes(fromCue.id), 'a cue-born memory must not become a cue source')
+  assert.ok(!ids.includes(silent.id), 'disclosure never_say cannot surface as a cue')
+  assert.ok(!ids.includes(secret.id))
+  assert.ok(!ids.includes(fresh.id), 'a memory needs some age before it can echo')
+
+  // skipIds has to win over everything else.
+  const skipped = memory.cueCandidates({ libraryId: binding.libraryId, sessionId, skipIds: [keep.id] }).map((c) => c.id)
+  assert.ok(!skipped.includes(keep.id))
+})
+
+test('cue candidates put the least-used memory first', async () => {
+  const { sessionId, binding, exec } = setup('order')
+  const old = new Date(Date.now() - 40 * 3600_000).toISOString()
+  const used = await memory.privateRemember({ exec, content: 'The noisy one.', title: 'used' })
+  const quiet = await memory.privateRemember({ exec, content: 'The quiet one.', title: 'quiet' })
+  const index = state.loadPrivateIndex(binding.libraryId)
+  index.entries[used.id].updatedAt = old
+  index.entries[quiet.id].updatedAt = old
+  index.entries[used.id].accessCount = 9
+  index.entries[used.id].injectCount = 4
+  state.savePrivateIndex(binding.libraryId, index)
+
+  const ids = memory.cueCandidates({ libraryId: binding.libraryId, sessionId }).map((c) => c.id)
+  assert.equal(ids[0], quiet.id, 'an echo is more interesting when it was forgotten')
+})
+
+test('deriveCue returns a memory-backed cue, or null when it has nothing', async () => {
+  const { sessionId, binding } = setup('derive')
+  assert.deepEqual(inject.deriveCue({ libraryId: null }, sessionId), null)
+  assert.deepEqual(inject.deriveCue({ libraryId: binding.libraryId, useLibrary: false }, sessionId), null)
+  assert.deepEqual(inject.deriveCue(binding, sessionId), null, 'no aged memory means no derived cue')
+
+  const exec = execFor(sessionId, path.join(home, 'proj-derive'))
+  const { id } = await memory.privateRemember({ exec, content: 'The cat knocked the cup off the desk and just watched it fall.', title: 'the cup' })
+  const index = state.loadPrivateIndex(binding.libraryId)
+  index.entries[id].updatedAt = new Date(Date.now() - 30 * 3600_000).toISOString()
+  state.savePrivateIndex(binding.libraryId, index)
+
+  const cue = inject.deriveCue(binding, sessionId)
+  assert.ok(cue, 'an aged memory should be derivable')
+  assert.equal(cue.sourceId, id)
+  assert.match(cue.id, /^cue-/)
+  assert.ok(cue.text.includes('knocked the cup'), 'the cue quotes the memory, not a fixed sentence')
+  assert.ok(!inject.CUE_TEXTS.includes(cue.text))
+  assert.ok(cue.recallQuery.includes('the cup'))
+})
+
+test('maybeCue arms the cue with its source and returns related ids', async () => {
+  const { sessionId, binding } = setup('maybe')
+  state.updateSettings({ randomCueChance: 1 })
+  const exec = execFor(sessionId, path.join(home, 'proj-maybe'))
+  const { id } = await memory.privateRemember({ exec, content: 'The lamp buzzed all evening and nobody fixed it.', title: 'the lamp' })
+  const index = state.loadPrivateIndex(binding.libraryId)
+  index.entries[id].updatedAt = new Date(Date.now() - 30 * 3600_000).toISOString()
+  state.savePrivateIndex(binding.libraryId, index)
+
+  const out = await inject.maybeCue({ sessionId, turn: 2, settings: { ...state.getSettings(), randomCueChance: 1 }, binding, exec })
+  assert.ok(out && typeof out.text === 'string')
+  assert.ok(Array.isArray(out.ids))
+  const armed = state.getActiveCue(sessionId)
+  assert.equal(armed.sourceId, id, 'the cue records where it came from')
+  assert.ok(armed.recallQuery.includes('lamp'))
+  assert.ok(out.text.includes('这不是用户说的话'), 'a derived cue says so instead of claiming a random sense impression')
+})
+
+test('maybeCue falls back to a fixed sentence when no memory qualifies', async () => {
+  const { sessionId, binding } = setup('fallback')
+  const out = await inject.maybeCue({ sessionId, turn: 2, settings: { ...state.getSettings(), randomCueChance: 1 }, binding, exec: null })
+  assert.ok(inject.CUE_TEXTS.some((t) => out.text.includes(t)), 'the fixed pool still backs the feature')
+  const armed = state.getActiveCue(sessionId)
+  assert.equal(armed.sourceId, null)
+})
+
+// ---- arousal in retrieval ----
+
+test('a tense room pulls charged memories further ahead than a quiet one', async () => {
+  const { sessionId, exec } = setup('arousal')
+  const calm = await memory.privateRemember({
+    exec, content: 'The hallway smelled of rain on warm stone.', title: 'hallway calm', arousal: 0.1, moodValence: 0.05,
+  })
+  const loud = await memory.privateRemember({
+    exec, content: 'The hallway smelled of rain on warm stone.', title: 'hallway loud', arousal: 0.95, moodValence: 0.05,
+  })
+
+  async function gapAt(arousal) {
+    state.setSessionMood(sessionId, { valence: 0, arousal })
+    const out = await memory.privateRecall({ exec, query: 'hallway rain stone', topK: 2, relevanceThreshold: 0 })
+    const byId = new Map((out.files || []).map((f) => [f.name, f.score]))
+    assert.deepEqual(new Set(byId.keys()), new Set([calm.id, loud.id]), 'both stay in range: arousal only reorders')
+    return byId.get(loud.id) / byId.get(calm.id)
+  }
+
+  const tense = await gapAt(0.95)
+  const quiet = await gapAt(0.1)
+  // The factor is bounded, so it must never invert the ranking — it only changes
+  // how far ahead the charged memory sits.
+  assert.ok(tense > 1 && quiet > 1, 'the charged memory wins in both rooms')
+  assert.ok(tense > quiet, 'a tense present favours the charged memory more than a calm one')
+})
+
+test('arousal cannot outrank a clearly better semantic hit', async () => {
+  const { sessionId, exec } = setup('arousal-weak')
+  const relevant = await memory.privateRemember({
+    exec, content: 'The deployment key is stored in the vault under dsh-memu-memory-prod.', title: 'deployment key', arousal: 0.05,
+  })
+  const charged = await memory.privateRemember({
+    exec, content: 'A door slammed somewhere in the building.', title: 'a door', arousal: 1, peak: true,
+  })
+  state.setSessionMood(sessionId, { valence: 0, arousal: 1 })
+  const out = await memory.privateRecall({ exec, query: 'where is the deployment key for dsh-memu-memory-prod', topK: 2, relevanceThreshold: 0 })
+  const ids = (out.files || []).map((f) => f.name)
+  assert.equal(ids[0], relevant.id, 'intensity is a nudge, not a trump card')
+  assert.ok(ids.includes(charged.id))
+})
+
+test('a mood that is tense but neither good nor bad still counts as a mood', async () => {
+  const { sessionId, exec } = setup('tense')
+  const flat = await memory.privateRemember({ exec, content: 'The invoice is due on the fourteenth.', title: 'invoice', arousal: 0.1, moodValence: 0 })
+  const edge = await memory.privateRemember({ exec, content: 'The invoice is due on the fourteenth.', title: 'invoice edge', arousal: 0.9, moodValence: 0 })
+  // valence is exactly neutral here, so without the arousal gate this room would be
+  // treated as "no mood at all" and arousal would never reach recallScore.
+  state.setSessionMood(sessionId, { valence: 0, arousal: 0.9 })
+  const tense = await memory.privateRecall({ exec, query: 'invoice due fourteenth', topK: 2, relevanceThreshold: 0 })
+  const tenseScores = new Map((tense.files || []).map((f) => [f.name, f.score]))
+  assert.deepEqual(new Set(tenseScores.keys()), new Set([flat.id, edge.id]))
+  const ratio = tenseScores.get(edge.id) / tenseScores.get(flat.id)
+
+  state.setSessionMood(sessionId, { valence: 0, arousal: 0.1 })
+  const calm = await memory.privateRecall({ exec, query: 'invoice due fourteenth', topK: 2, relevanceThreshold: 0 })
+  const calmScores = new Map((calm.files || []).map((f) => [f.name, f.score]))
+  const calmRatio = calmScores.get(edge.id) / calmScores.get(flat.id)
+  assert.ok(ratio > calmRatio, 'the tense read widens the same gap')
+})
+
+test('BASE_AROUSAL is exported and is a real baseline, not zero', () => {
+  assert.equal(typeof mood.BASE_AROUSAL, 'number')
+  assert.ok(mood.BASE_AROUSAL > 0 && mood.BASE_AROUSAL < 1)
+})