dsh-memu-memory 1.1.3 → 1.2.0

package/tests/consolidation-snapshot.test.mjs

@@ -0,0 +1,321 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const { captureSessionSnapshot, safePrefix, toolPairing, lastClosedTurnSeq, snapshotHash } = await import('../lib/consolidation-snapshot.js')
+const { probeToolSurface, lastHeaderTools, buildWorkerBrief } = await import('../lib/consolidation-worker.js')
+
+// C 包第 1、2 条：安全前缀必须可解释。这里逐条钉住「什么算完整」，
+// 因为把半步喂给 worker 的代价是它对没发生的事编出结论。
+
+function turn(turnNo, step, extra = {}) {
+  return [
+    { seq: 0, type: 'turn/start', data: { turn: turnNo } },
+    { seq: 1, type: 'step/start', data: { turn: turnNo, step } },
+    { seq: 2, type: 'user/message', data: { source: { kind: 'user' }, content: [{ type: 'text', text: '我把 API key 放到 1password 了' }] } },
+    { seq: 3, type: 'assistant/message', data: { message: { content: [{ type: 'text', text: '收到' }] } } },
+    { seq: 4, type: 'step/end', data: { turn: turnNo, step } },
+    { seq: 5, type: 'turn/end', data: { turn: turnNo, reason: { kind: 'completed' } } },
+  ].map((event) => ({ ...event, ...extra }))
+}
+
+function closeTurn(events, turnNo, base) {
+  return [
+    ...events,
+    { seq: base, type: 'turn/start', data: { turn: turnNo } },
+    { seq: base + 1, type: 'step/start', data: { turn: turnNo, step: 1 } },
+    { seq: base + 2, type: 'user/message', data: { source: { kind: 'user' }, content: [{ type: 'text', text: '第二轮：别删那条记忆' }] } },
+    { seq: base + 3, type: 'step/end', data: { turn: turnNo, step: 1 } },
+    { seq: base + 4, type: 'turn/end', data: { turn: turnNo, reason: { kind: 'completed' } } },
+  ]
+}
+
+test('a live lease is cut at the last closed turn', () => {
+  const events = [
+    ...turn(1, 1),
+    // 第二轮只开了头：turn/start + step/start + 一条真人消息，没有 turn/end。
+    { seq: 6, type: 'turn/start', data: { turn: 2 } },
+    { seq: 7, type: 'step/start', data: { turn: 2, step: 1 } },
+    { seq: 8, type: 'user/message', data: { source: { kind: 'user' }, content: [{ type: 'text', text: '这句话还没答完' }] } },
+  ]
+  const safe = safePrefix(events, { requireClosedTurn: true })
+  assert.equal(safe.ok, true)
+  assert.equal(safe.throughSeq, 5, 'the open second turn is not part of the snapshot')
+  assert.equal(safe.eventCount, 6)
+  assert.equal(safe.dropped, 3)
+})
+
+test('a live transcript with no closed turn is deferred, not consolidated', () => {
+  const events = [
+    { seq: 0, type: 'turn/start', data: { turn: 1 } },
+    { seq: 1, type: 'step/start', data: { turn: 1, step: 1 } },
+  ]
+  const safe = safePrefix(events, { requireClosedTurn: true })
+  assert.equal(safe.ok, false)
+  assert.equal(safe.reasonCode, 'no-closed-turn')
+})
+
+test('a tool call without its result is a half step and is trimmed', () => {
+  const events = [
+    ...turn(1, 1),
+    { seq: 6, type: 'turn/start', data: { turn: 2 } },
+    { seq: 7, type: 'step/start', data: { turn: 2, step: 1 } },
+    { seq: 8, type: 'assistant/message', data: { message: { content: [{ type: 'tool-call', id: 'call-1', name: 'read' }] } } },
+    { seq: 9, type: 'tool/call', data: { turn: 2, step: 1, callId: 'call-1', name: 'read', arguments: '{}' } },
+    { seq: 10, type: 'step/end', data: { turn: 2, step: 1 } },
+    { seq: 11, type: 'turn/end', data: { turn: 2, reason: { kind: 'aborted' } } },
+  ]
+  const pairing = toolPairing(events)
+  assert.equal(pairing.unpaired.length, 1)
+  assert.equal(pairing.firstUnpairedSeq, 8)
+  const safe = safePrefix(events, { requireClosedTurn: true })
+  assert.equal(safe.ok, true)
+  assert.equal(safe.throughSeq, 5, 'the turn whose call never resolved is dropped whole')
+})
+
+test('a paired tool call keeps its turn', () => {
+  const events = [
+    ...turn(1, 1),
+    { seq: 6, type: 'turn/start', data: { turn: 2 } },
+    { seq: 7, type: 'step/start', data: { turn: 2, step: 1 } },
+    { seq: 8, type: 'tool/call', data: { turn: 2, step: 1, callId: 'call-1', name: 'read', arguments: '{}' } },
+    { seq: 9, type: 'tool/result', data: { turn: 2, step: 1, message: { toolCallId: 'call-1', source: { kind: 'tool', callId: 'call-1' }, content: [{ type: 'text', text: 'ok' }], isError: false } } },
+    { seq: 10, type: 'step/end', data: { turn: 2, step: 1 } },
+    { seq: 11, type: 'turn/end', data: { turn: 2, reason: { kind: 'completed' } } },
+  ]
+  const safe = safePrefix(events, { requireClosedTurn: true })
+  assert.equal(safe.ok, true)
+  assert.equal(safe.throughSeq, 11)
+  assert.equal(safe.pairing.unpaired, 0)
+})
+
+test('host tool result identities pair in both live and validated snapshot modes', async () => {
+  for (const message of [
+    { toolCallId: 'host-call', source: { kind: 'tool', callId: 'host-call' } },
+    { source: { kind: 'tool', callId: 'host-call' } },
+    { callId: 'host-call' },
+  ]) {
+    const events = [
+      { seq: 0, type: 'turn/start', data: { turn: 1 } },
+      { seq: 1, type: 'step/start', data: { turn: 1, step: 1 } },
+      { seq: 2, type: 'assistant/message', data: { message: { content: [{ type: 'tool-call', id: 'host-call', name: 'read' }] } } },
+      { seq: 3, type: 'tool/call', data: { callId: 'host-call', name: 'read' } },
+      { seq: 4, type: 'tool/result', data: { message: { ...message, content: [{ type: 'text', text: 'ok' }] } } },
+      { seq: 5, type: 'step/end', data: { turn: 1, step: 1 } },
+      { seq: 6, type: 'turn/end', data: { turn: 1 } },
+    ]
+    assert.equal(toolPairing(events).unpaired.length, 0)
+    for (const requireClosedTurn of [true, false]) {
+      const safe = safePrefix(events, { requireClosedTurn })
+      assert.equal(safe.ok, true)
+      assert.equal(safe.throughSeq, 6)
+    }
+    const captured = await captureSessionSnapshot(leaseHost({ events }), 'host-pair')
+    assert.equal(captured.ok, true)
+    assert.equal(captured.snapshot.throughSeq, 6)
+    const unmatched = events.filter(event => event.type !== 'tool/result')
+    assert.equal(toolPairing(unmatched).firstUnpairedSeq, 2)
+    assert.equal(safePrefix(unmatched, { requireClosedTurn: true }).ok, false)
+  }
+})
+
+test('a validated log keeps its full range but still drops a trailing step/start', () => {
+  const events = [
+    ...turn(1, 1),
+    { seq: 6, type: 'turn/start', data: { turn: 2 } },
+    { seq: 7, type: 'step/start', data: { turn: 2, step: 1 } },
+  ]
+  const safe = safePrefix(events, { requireClosedTurn: false })
+  assert.equal(safe.ok, true)
+  assert.equal(safe.throughSeq, 5, 'an open step at the tail is not part of the prefix')
+  assert.equal(lastClosedTurnSeq(events), 5)
+})
+
+test('an empty transcript has nothing to snapshot', () => {
+  assert.equal(safePrefix([], { requireClosedTurn: true }).reasonCode, 'no-events')
+})
+
+test('the snapshot hash is stable for the same range and changes with content', () => {
+  const events = turn(1, 1)
+  const a = snapshotHash(events, 0, 5)
+  const b = snapshotHash(events, 0, 5)
+  const c = snapshotHash([...events.slice(0, 5), { seq: 5, type: 'turn/end', data: { turn: 1, reason: { kind: 'error' } } }], 0, 5)
+  const equalLength = snapshotHash(events.map((event) => event.type === 'user/message' ? { ...event, data: { ...event.data, content: [{ type: 'text', text: '同样长度' }] } } : event), 0, 5)
+  assert.equal(a, b)
+  assert.notEqual(a, c, 'a different last event means a different snapshot identity')
+  assert.notEqual(a, equalLength, 'different equal-length event bodies must have different identities')
+  assert.equal(a.length, 64, 'content-addressed sha256 of the canonical events')
+})
+
+// ---- captureSessionSnapshot：只用公开 API，缺能力就明确失败 ----
+
+function leaseHost({ events, source = 'live', cursor = null, dispose = null, onObserve = null }) {
+  const rec = { disposed: 0, projectionMode: null, readSessionCalls: 0 }
+  return {
+    rec,
+    on: () => () => {},
+    get: (name) => {
+      if (name !== 'sessionQuery') return undefined
+      return {
+        observeSession: async (id, options) => {
+          rec.projectionMode = options?.projectionMode ?? null
+          if (onObserve) onObserve(id, options)
+          return {
+            source,
+            header: { cwd: 'D:/proj', agentPreset: 'standard' },
+            inheritedEventCount: 0,
+            events,
+            cursor: cursor === null ? (events.at(-1)?.seq ?? -1) : cursor,
+            retain: () => ({ [Symbol.dispose]: () => {} }),
+            [Symbol.dispose]: () => { rec.disposed += 1; dispose?.() },
+          }
+        },
+        readSession: async () => { rec.readSessionCalls += 1; return { events, session: { cwd: 'D:/proj' } } },
+      }
+    },
+  }
+}
+
+test('captureSessionSnapshot uses the public lease, pins the cut and disposes the lease', async () => {
+  const events = turn(1, 1)
+  const ctx = leaseHost({ events })
+  const captured = await captureSessionSnapshot(ctx, 'sess-lease')
+  assert.equal(captured.ok, true)
+  assert.equal(captured.snapshot.source, 'lease-live')
+  assert.equal(captured.snapshot.throughSeq, 5)
+  assert.equal(captured.snapshot.eventCount, 6)
+  assert.equal(captured.snapshot.cursor, 5)
+  assert.equal(ctx.rec.projectionMode, 'none', 'raw events, not the model-visible projection')
+  assert.equal(ctx.rec.disposed, 1, 'the lease is always released')
+  assert.equal(ctx.rec.readSessionCalls, 0, 'a lease read must not fall back to a full log read')
+})
+
+test('a prepared lease is a balanced log, so it does not need a closed turn', async () => {
+  const events = [
+    { seq: 0, type: 'user/message', data: { source: { kind: 'user' }, content: [{ type: 'text', text: '我更喜欢简短回答' }] } },
+    { seq: 1, type: 'assistant/message', data: { message: { content: [{ type: 'text', text: '好' }] } } },
+  ]
+  const ctx = leaseHost({ events, source: 'prepared' })
+  const captured = await captureSessionSnapshot(ctx, 'sess-prepared')
+  assert.equal(captured.ok, true)
+  assert.equal(captured.snapshot.source, 'lease-prepared')
+  assert.equal(captured.snapshot.throughSeq, 1)
+})
+
+test('a live lease with an open turn is deferred instead of consolidated', async () => {
+  const ctx = leaseHost({ events: [{ seq: 0, type: 'turn/start', data: { turn: 1 } }] })
+  const captured = await captureSessionSnapshot(ctx, 'sess-open')
+  assert.equal(captured.ok, false)
+  assert.equal(captured.code, 'deferred')
+  assert.equal(captured.reasonCode, 'no-closed-turn')
+  assert.equal(ctx.rec.disposed, 1, 'a deferred read still releases the lease')
+})
+
+test('a host with readSession only is used as a validated log', async () => {
+  const ctx = { on: () => () => {}, get: (name) => (name === 'sessionQuery'
+    ? { readSession: async () => ({ events: turn(1, 1), session: { cwd: 'D:/p' }, inheritedEventCount: 0 }) }
+    : undefined) }
+  const captured = await captureSessionSnapshot(ctx, 'sess-legacy')
+  assert.equal(captured.ok, true)
+  assert.equal(captured.snapshot.source, 'validated-log')
+  assert.equal(captured.snapshot.throughSeq, 5)
+})
+
+test('a host without any snapshot API is unavailable, not an empty success', async () => {
+  const none = await captureSessionSnapshot({ on: () => () => {}, get: () => undefined }, 'sess-none')
+  assert.equal(none.ok, false)
+  assert.equal(none.code, 'unavailable')
+  assert.equal(none.reasonCode, 'no-session-query')
+  const partial = await captureSessionSnapshot({ on: () => () => {}, get: () => ({}) }, 'sess-partial')
+  assert.equal(partial.reasonCode, 'no-snapshot-api')
+})
+
+test('a failing observeSession is a retryable failure with the host message', async () => {
+  const ctx = { on: () => () => {}, get: () => ({ observeSession: async () => { throw new Error('SESSION_QUERY_PERSISTENCE_FAILED: disk gone') } }) }
+  const captured = await captureSessionSnapshot(ctx, 'sess-boom')
+  assert.equal(captured.ok, false)
+  assert.equal(captured.code, 'failed')
+  assert.match(captured.error, /disk gone/)
+})
+
+// ---- 工具面：标准 / PTC / 未知 三种都要能分辨 ----
+
+const MEMU_TOOLS = [
+  { name: 'memu_private_remember' },
+  { name: 'memu_private_update' },
+  { name: 'memu_private_recall' },
+  { name: 'read' },
+]
+
+test('a standard header that lists memu_* tools proves the worker can write', () => {
+  const events = [{ seq: 0, type: 'request/header', data: { header: { config: { provider: 'p', model: 'm' }, tools: MEMU_TOOLS } } }]
+  const probe = probeToolSurface({ ctx: null, sessionId: 's', events })
+  assert.equal(probe.ok, true)
+  assert.equal(probe.hasWrite, true)
+  assert.equal(probe.source, 'header-event')
+  assert.deepEqual(probe.tools, ['memu_private_remember', 'memu_private_update', 'memu_private_recall', 'read'])
+})
+
+test('a header without memory tools is unavailable rather than a silent wasted fork', () => {
+  const events = [{ seq: 0, type: 'request/header', data: { header: { config: { provider: 'p', model: 'm' }, tools: [{ name: 'read' }, { name: 'write' }] } } }]
+  const probe = probeToolSurface({ ctx: null, sessionId: 's', events })
+  assert.equal(probe.ok, false)
+  assert.equal(probe.reasonCode, 'worker-tools-missing')
+})
+
+test('a PTC-only turn is reported as PTC, not as a generic missing tool', () => {
+  const events = [
+    { seq: 0, type: 'request/header', data: { header: { config: { provider: 'p', model: 'm' }, tools: [{ name: 'ptc_exec' }] } } },
+    { seq: 1, type: 'tool/ptc-dispatch', data: {} },
+  ]
+  const probe = probeToolSurface({ ctx: null, sessionId: 's', events })
+  assert.equal(probe.ok, false)
+  assert.equal(probe.reasonCode, 'worker-tools-ptc-only')
+  assert.equal(probe.ptcObserved, true)
+})
+
+test('a missing tool list is unknown, not a refusal', () => {
+  const probe = probeToolSurface({ ctx: null, sessionId: 's', events: [{ seq: 0, type: 'request/header', data: { header: { config: {} } } }] })
+  assert.equal(probe.ok, true)
+  assert.equal(probe.source, 'unknown-tools')
+  assert.equal(probe.tools, null)
+  assert.equal(probeToolSurface({ ctx: null, sessionId: 's', events: [] }).source, 'unknown')
+})
+
+test('the live request header wins over an older logged one', () => {
+  const ctx = {
+    get: (name) => (name === 'agents' ? { get: () => ({ session: { requestHeader: () => ({ config: {}, tools: MEMU_TOOLS }) } }) } : undefined),
+  }
+  const events = [{ seq: 9, type: 'request/header', data: { header: { config: {}, tools: [{ name: 'read' }] } } }]
+  const probe = probeToolSurface({ ctx, sessionId: 'live', events })
+  assert.equal(probe.ok, true)
+  assert.equal(probe.source, 'live-header')
+})
+
+test('lastHeaderTools folds to the latest header only', () => {
+  const events = [
+    { seq: 0, type: 'request/header', data: { header: { tools: [{ name: 'old' }] } } },
+    { seq: 1, type: 'request/header', data: { header: { tools: MEMU_TOOLS } } },
+  ]
+  const folded = lastHeaderTools(events)
+  assert.equal(folded.found, true)
+  assert.ok(folded.tools.includes('memu_private_remember'))
+  assert.equal(folded.tools.includes('old'), false)
+})
+
+test('the worker brief carries the range, the tools and the receipt contract', () => {
+  const brief = buildWorkerBrief({
+    snapshot: { fromSeq: 0, throughSeq: 41, eventCount: 42, hash: 'abc123' },
+    probe: { tools: ['memu_private_remember', 'memu_private_recall'] },
+    contract: 'RECEIPT-CONTRACT-MARKER',
+    reason: 'manual',
+    jobId: 'cons-1',
+  })
+  assert.match(brief, /不是这场对话里的角色/)
+  assert.match(brief, /第 0 到第 41 条事件/)
+  assert.match(brief, /快照 abc123/)
+  assert.match(brief, /memu_private_remember/)
+  assert.match(brief, /不写全局记忆/)
+  assert.match(brief, /RECEIPT-CONTRACT-MARKER/)
+  assert.match(brief, /手动/)
+  assert.match(brief, /tools-unavailable/)
+})

package/tests/consolidation-value.test.mjs

@@ -0,0 +1,89 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const { assessConsolidationValue, unconsolidatedEvents } = await import('../lib/private.js')
+
+function human(seq, text) {
+  return { seq, type: 'user/message', data: { source: { kind: 'user' }, content: [{ type: 'text', text }] } }
+}
+
+function notice(seq, text) {
+  return { seq, type: 'user/message', data: { source: { kind: 'plugin:dsh-memu-memory' }, content: [{ type: 'text', text }] } }
+}
+
+function assistant(seq, blocks) {
+  return { seq, type: 'assistant/message', data: { message: { content: blocks } } }
+}
+
+test('an empty tail is not worth a fork', () => {
+  const value = assessConsolidationValue([])
+  assert.equal(value.worth, false)
+  assert.equal(value.reason, 'no-human-turn')
+  assert.equal(value.humanTurns, 0)
+})
+
+test('plugin notices and tool chatter are not human turns', () => {
+  const value = assessConsolidationValue([
+    notice(0, '整理这场对话的私有记忆'),
+    { seq: 1, type: 'tool/result', data: { message: { content: [{ type: 'text', text: 'ok' }] } } },
+    notice(2, 'short_term · 快到期了'),
+  ])
+  assert.equal(value.worth, false)
+  assert.equal(value.humanTurns, 0)
+})
+
+test('a bare thank-you is small talk', () => {
+  const value = assessConsolidationValue([human(0, '谢谢'), assistant(1, [{ type: 'text', text: '不客气' }])])
+  assert.equal(value.worth, false)
+  assert.equal(value.reason, 'small-talk')
+  assert.equal(value.humanTurns, 1)
+})
+
+test('one substantive message is enough', () => {
+  const value = assessConsolidationValue([human(0, '以后发版前不要动 AGENTS.md 里那行预算，它一超就被静默截断，模型永远看不到后半段。')])
+  assert.equal(value.worth, true)
+  assert.equal(value.reason, 'substantive')
+  assert.ok(value.humanChars >= 12)
+})
+
+test('tool work counts even when the person types little', () => {
+  const value = assessConsolidationValue([
+    human(0, '跑一下'),
+    assistant(1, [{ type: 'tool-call', name: 'bash', arguments: '{"command":"npm test"}' }]),
+    { seq: 2, type: 'tool/call', data: { name: 'bash', arguments: '{}' } },
+  ])
+  assert.equal(value.worth, true)
+  assert.equal(value.toolCalls, 2, 'both shapes of tool call are counted')
+})
+
+test('a short message can be the whole point', () => {
+  // Length is not substance: five characters are a durable preference.
+  const value = assessConsolidationValue([human(0, '我不吃香菜')])
+  assert.equal(value.worth, true)
+  assert.equal(value.humanTurns, 1)
+})
+
+test('an acknowledgement is refused, a short question is not', () => {
+  assert.equal(assessConsolidationValue([human(0, '好的，继续')]).worth, false)
+  assert.equal(assessConsolidationValue([human(0, '这个怎么配')]).worth, true, 'a question is worth reading even when it is short')
+  assert.equal(assessConsolidationValue([human(0, '这个怎么配'), human(1, '我按文档试了还是不行')]).worth, true)
+})
+
+test('only the events after the last consolidation are judged', () => {
+  const events = [human(0, '很久以前的一次长对话，已经整理过了，内容足够长足够长足够长足够长。'), human(1, '谢谢')]
+  // No marker recorded yet: the whole transcript is the tail, so the old material
+  // still counts once. That is deliberate — the first pass after an upgrade should
+  // not decide "small talk" from a transcript it has never read.
+  assert.equal(unconsolidatedEvents({}, events).length, 2)
+  assert.equal(assessConsolidationValue(unconsolidatedEvents({}, events)).worth, true)
+  // Once a marker exists, the tail is only what came after it.
+  const tail = unconsolidatedEvents({ lastSleepSeq: 0 }, events)
+  assert.equal(tail.length, 1)
+  assert.equal(assessConsolidationValue(tail).worth, false)
+})
+
+test('a zero marker is honoured (seq 0 is a real position)', () => {
+  const events = [human(0, '旧消息'), human(1, '新的一次决定，内容足够长足够长足够长足够长足够长足够长。')]
+  const tail = unconsolidatedEvents({ lastSleepSeq: 0 }, events)
+  assert.deepEqual(tail.map((event) => event.seq), [1])
+})

package/tests/context-scope.test.mjs

@@ -0,0 +1,40 @@
+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-scope-'))
+process.env.DSH_MEMU_HOME = home
+const state = await import('../lib/state.js')
+const memory = await import('../lib/memory.js')
+const { dispatch } = await import('../lib/rpc.js')
+test.after(() => { state.flushState(); fs.rmSync(home, { recursive: true, force: true }) })
+function exec(id) { return { agent: { session: { header: { id } } } } }
+for (const id of ['a', 'b']) state.ensureSession(id, { cwd: path.join(home, 'shared-rp'), agentPreset: 'rp' })
+
+test('same-title claims from distinct speakers do not become contradictions', async () => {
+  const a = await memory.privateRemember({ exec: exec('a'), title: '饮品偏好', content: '小甲喜欢红茶。', context: { speakerId: 'user-a' } })
+  const b = await memory.privateRemember({ exec: exec('a'), title: '饮品偏好', content: '小乙不喜欢红茶。', context: { speakerId: 'user-b' } })
+  assert.equal(a.entry.status, 'active')
+  assert.equal(b.entry.status, 'active')
+})
+
+test('world, branch and channel isolate every recall and list surface', async () => {
+  await dispatch({}, 'setMemoryContext', { sessionId: 'a', context: { channelId: 'group-1', characterId: 'hero', worldId: 'world-1', branchId: 'west' } })
+  await dispatch({}, 'setMemoryContext', { sessionId: 'b', context: { channelId: 'group-2', characterId: 'hero', worldId: 'world-1', branchId: 'west' } })
+  const secret = await memory.privateRemember({ exec: exec('a'), title: '剧场钥匙', content: '剧场钥匙在台灯旁。', context: { knownBy: ['hero'] } })
+  assert.ok((await memory.privateRecall({ exec: exec('a'), query: secret.id })).files.length)
+  assert.equal((await memory.privateRecall({ exec: exec('b'), query: secret.id })).files.length, 0)
+  assert.ok(!(await memory.privateList({ exec: exec('b') })).files.some(file => file.name === secret.id))
+  await dispatch({}, 'setMemoryContext', { sessionId: 'b', context: { channelId: 'group-1', characterId: 'hero', worldId: 'world-1', branchId: 'east' } })
+  assert.equal((await memory.privateRecall({ exec: exec('b'), query: secret.id })).files.length, 0)
+  await assert.rejects(memory.privateRemember({ exec: exec('b'), content: 'scope bypass', context: { branchId: 'west' } }), /cannot widen/)
+  await assert.rejects(memory.privateRemember({ exec: exec('b'), content: 'scope widening', context: { branchId: '' } }), /cannot widen/)
+})
+
+test('knownBy is a character knowledge boundary, not a relationship score', async () => {
+  await dispatch({}, 'setMemoryContext', { sessionId: 'a', context: { characterId: 'hero' } })
+  const record = await memory.privateRemember({ exec: exec('a'), title: '反派的计划', content: '叙事者记录了反派的计划，主角不知道。', context: { knownBy: ['villain'] } })
+  assert.equal((await memory.privateRecall({ exec: exec('a'), query: record.id })).files.length, 0)
+  assert.ok(!(await memory.privateList({ exec: exec('a') })).files.some(file => file.name === record.id))
+})

package/tests/cue.test.mjs

@@ -0,0 +1,44 @@
+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-cue-'))
+process.env.DSH_MEMU_HOME = home
+
+const state = await import('../lib/state.js')
+const inject = await import('../lib/inject.js')
+
+test.after(() => {
+  try { fs.rmSync(home, { recursive: true, force: true }) } catch {}
+})
+
+test('random cue is injected once and armed', async () => {
+  state.updateSettings({ randomCueChance: 1 })
+  const cwd = path.join(home, 'project-cue')
+  state.ensureSession('cue-session', { cwd, agentPreset: 'rp' })
+  const user = {
+    id: 'u-cue', role: 'user', source: { kind: 'user' }, content: [{ type: 'text', text: '今天发生了什么，你还记得吗？' }],
+  }
+  const decision = { kind: 'enter', messages: [user] }
+  const agent = { session: { header: { id: 'cue-session', cwd, agentPreset: 'rp' } } }
+  const out = await inject.injectForStep({ agent, decision, turn: 2, step: 1, signal: { aborted: false } })
+  const text = out.messages[0]?.content?.[0]?.text || ''
+  assert.ok(text.includes('<memory-cue id="'))
+  const active = state.getActiveCue('cue-session')
+  assert.ok(active && active.id)
+
+  const again = await inject.injectForStep({ agent, decision, turn: 3, step: 1, signal: { aborted: false } })
+  const textAgain = again.messages?.[0]?.content?.[0]?.text || ''
+  assert.ok(!textAgain.includes('<memory-cue id="'))
+  assert.equal(state.consumeCue('cue-session', active.id), true)
+  assert.equal(state.getActiveCue('cue-session'), null)
+})
+
+test('makeCue returns a stable shape', () => {
+  const cue = inject.makeCue()
+  assert.match(cue.id, /^cue-/)
+  assert.ok(cue.text.length > 0)
+  assert.ok(inject.CUE_TEXTS.includes(cue.text))
+})