@onmars/lunar-core 0.1.0

package/src/__tests__/memory-orchestrator.test.ts

@@ -0,0 +1,552 @@
+/**
+ * # MemoryOrchestrator — Functional Specification
+ *
+ * Coordinates multiple MemoryProviders behind a single MemoryProvider interface.
+ *
+ * ## Core responsibilities:
+ * - Parallel recall across all providers
+ * - Deduplication of merged results (Dice/MinHash/Adaptive)
+ * - Score-based ranking (highest first)
+ * - maxResults enforcement post-dedup
+ * - Non-fatal: individual provider failures don't block others
+ * - Session lifecycle broadcast (onSessionEnd → all providers)
+ * - Health aggregation (all OK = OK, any fail = fail with details)
+ * - Agent instructions merging from all providers
+ * - Lifecycle hooks via HookRunner at every stage
+ *
+ * ## Key design decisions:
+ * - Implements MemoryProvider → plugs into Router as a single provider
+ * - Single provider → use directly (no orchestrator overhead)
+ * - Zero providers → valid state (returns empty results)
+ * - Dedup threshold 0.85 (conservative: prefer false negatives)
+ * - Hooks are best-effort, never block core flow
+ */
+import { describe, expect, it } from 'bun:test'
+import type { HooksConfig } from '../lib/config-loader'
+import { MemoryOrchestrator } from '../lib/memory-orchestrator'
+import type { Fact, MemoryProvider, MemoryResult, SearchOptions } from '../types/memory'
+
+// ═══════════════════════════════════════════════════════════════════
+// Test helpers
+// ═══════════════════════════════════════════════════════════════════
+
+function createMockProvider(
+  id: string,
+  results: MemoryResult[],
+  options?: {
+    failRecall?: boolean
+    failSave?: boolean
+    failHealth?: boolean
+    instructions?: string
+    onSessionEnd?: (ctx: unknown) => void
+    savedFacts?: Fact[][]
+  },
+): MemoryProvider {
+  const savedFacts: Fact[][] = options?.savedFacts ?? []
+
+  return {
+    id,
+    name: `Mock ${id}`,
+    async init() {},
+    async destroy() {},
+    async recall(_query: string, _opts?: SearchOptions): Promise<MemoryResult[]> {
+      if (options?.failRecall) throw new Error(`${id} recall failed`)
+      return results
+    },
+    async save(facts: Fact[]) {
+      if (options?.failSave) throw new Error(`${id} save failed`)
+      savedFacts.push(facts)
+    },
+    async onSessionEnd(ctx: {
+      messages: Array<{ role: string; content: string }>
+      sessionSummary?: string
+      topics?: string[]
+    }) {
+      if (options?.onSessionEnd) options.onSessionEnd(ctx)
+    },
+    async health() {
+      if (options?.failHealth) return { ok: false, error: `${id} is down` }
+      return { ok: true }
+    },
+    agentInstructions() {
+      return options?.instructions || ''
+    },
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Provider management
+// ═══════════════════════════════════════════════════════════════════
+
+describe('provider management', () => {
+  it('starts with zero providers', () => {
+    const orch = new MemoryOrchestrator()
+    expect(orch.providerCount).toBe(0)
+    expect(orch.providerIds).toEqual([])
+  })
+
+  it('adds providers and tracks count', () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(createMockProvider('brain', []))
+    orch.addProvider(createMockProvider('engram', []))
+
+    expect(orch.providerCount).toBe(2)
+    expect(orch.providerIds).toEqual(['brain', 'engram'])
+  })
+
+  it('has id "orchestrator" and name "Memory Orchestrator"', () => {
+    const orch = new MemoryOrchestrator()
+    expect(orch.id).toBe('orchestrator')
+    expect(orch.name).toBe('Memory Orchestrator')
+  })
+
+  it('supports custom config name for providers', () => {
+    const orch = new MemoryOrchestrator()
+    const provider = createMockProvider('my-brain-v2', [])
+    orch.addProvider(provider, 'brain')
+
+    expect(orch.providerIds).toEqual(['my-brain-v2'])
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Recall — parallel fetch + merge + dedup
+// ═══════════════════════════════════════════════════════════════════
+
+describe('recall', () => {
+  it('returns empty array with zero providers', async () => {
+    const orch = new MemoryOrchestrator()
+    const results = await orch.recall('anything')
+    expect(results).toEqual([])
+  })
+
+  it('returns results from a single provider', async () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(
+      createMockProvider('brain', [{ content: 'Mars is a software engineer', score: 0.9 }]),
+    )
+
+    const results = await orch.recall('Mars')
+    expect(results).toHaveLength(1)
+    expect(results[0].content).toBe('Mars is a software engineer')
+  })
+
+  it('merges results from multiple providers', async () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(
+      createMockProvider('brain', [{ content: 'Mars works at Sngular', score: 0.9 }]),
+    )
+    orch.addProvider(
+      createMockProvider('engram', [{ content: 'Recent session: Mars was debugging', score: 0.7 }]),
+    )
+
+    const results = await orch.recall('Mars')
+    expect(results).toHaveLength(2)
+  })
+
+  it('sorts results by score (highest first)', async () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(createMockProvider('brain', [{ content: 'Low score fact', score: 0.3 }]))
+    orch.addProvider(createMockProvider('engram', [{ content: 'High score fact', score: 0.95 }]))
+
+    const results = await orch.recall('test')
+    expect(results[0].score).toBe(0.95)
+    expect(results[1].score).toBe(0.3)
+  })
+
+  it('deduplicates near-identical content from different providers', async () => {
+    const orch = new MemoryOrchestrator({ dedup: { threshold: 0.85 } })
+    orch.addProvider(
+      createMockProvider('brain', [
+        { content: 'Mars is a software engineer at Sngular', score: 0.9 },
+      ]),
+    )
+    orch.addProvider(
+      createMockProvider('engram', [
+        { content: 'Mars is a software engineer at Sngular', score: 0.8 },
+      ]),
+    )
+
+    const results = await orch.recall('Mars')
+    expect(results).toHaveLength(1) // deduped!
+    expect(results[0].score).toBe(0.9) // keeps higher score
+  })
+
+  it('keeps distinct content even when similar topic', async () => {
+    const orch = new MemoryOrchestrator({ dedup: { threshold: 0.85 } })
+    orch.addProvider(
+      createMockProvider('brain', [
+        { content: 'Mars works at Sngular as a Software Tech Lead', score: 0.9 },
+      ]),
+    )
+    orch.addProvider(
+      createMockProvider('engram', [
+        { content: 'Mars is studying computer engineering at UOC', score: 0.8 },
+      ]),
+    )
+
+    const results = await orch.recall('Mars')
+    expect(results).toHaveLength(2) // different content, both kept
+  })
+
+  it('respects maxResults after dedup', async () => {
+    const orch = new MemoryOrchestrator({ maxResults: 2 })
+    orch.addProvider(
+      createMockProvider('brain', [
+        { content: 'Fact A from brain', score: 0.9 },
+        { content: 'Fact B from brain', score: 0.8 },
+      ]),
+    )
+    orch.addProvider(
+      createMockProvider('engram', [
+        { content: 'Fact C from engram', score: 0.85 },
+        { content: 'Fact D from engram', score: 0.7 },
+      ]),
+    )
+
+    const results = await orch.recall('test')
+    expect(results.length).toBeLessThanOrEqual(2)
+  })
+
+  it('tags results with provider source', async () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(createMockProvider('brain', [{ content: 'From brain', score: 0.9 }]))
+    orch.addProvider(createMockProvider('engram', [{ content: 'From engram', score: 0.8 }]))
+
+    const results = await orch.recall('test')
+    expect(results.find((r) => r.source === 'brain')).toBeDefined()
+    expect(results.find((r) => r.source === 'engram')).toBeDefined()
+  })
+
+  it('filters by minScore', async () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(
+      createMockProvider('brain', [
+        { content: 'High relevance', score: 0.9 },
+        { content: 'Low relevance', score: 0.1 },
+      ]),
+    )
+
+    const results = await orch.recall('test', { minScore: 0.5 })
+    expect(results).toHaveLength(1)
+    expect(results[0].content).toBe('High relevance')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Non-fatal failures — provider crashes don't block others
+// ═══════════════════════════════════════════════════════════════════
+
+describe('non-fatal failures', () => {
+  it('returns results from healthy providers when one fails recall', async () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(createMockProvider('brain', [{ content: 'Brain is fine', score: 0.9 }]))
+    orch.addProvider(createMockProvider('engram', [], { failRecall: true }))
+
+    const results = await orch.recall('test')
+    expect(results).toHaveLength(1)
+    expect(results[0].content).toBe('Brain is fine')
+  })
+
+  it('returns empty when all providers fail recall', async () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(createMockProvider('brain', [], { failRecall: true }))
+    orch.addProvider(createMockProvider('engram', [], { failRecall: true }))
+
+    const results = await orch.recall('test')
+    expect(results).toEqual([])
+  })
+
+  it('save continues even when one provider fails', async () => {
+    let brainSaved = false
+    const orch = new MemoryOrchestrator()
+
+    const brainProvider = createMockProvider('brain', [])
+    const origSave = brainProvider.save.bind(brainProvider)
+    brainProvider.save = async (facts) => {
+      brainSaved = true
+      return origSave(facts)
+    }
+
+    orch.addProvider(brainProvider)
+    orch.addProvider(createMockProvider('engram', [], { failSave: true }))
+
+    // Should not throw
+    await orch.save([{ content: 'Test fact' }])
+    expect(brainSaved).toBe(true)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Session lifecycle — broadcast to all providers
+// ═══════════════════════════════════════════════════════════════════
+
+describe('session lifecycle', () => {
+  it('broadcasts onSessionEnd to all providers', async () => {
+    const calls: string[] = []
+    const orch = new MemoryOrchestrator()
+
+    orch.addProvider(
+      createMockProvider('brain', [], {
+        onSessionEnd: () => calls.push('brain'),
+      }),
+    )
+    orch.addProvider(
+      createMockProvider('engram', [], {
+        onSessionEnd: () => calls.push('engram'),
+      }),
+    )
+
+    await orch.onSessionEnd({
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary: 'Test session',
+    })
+
+    expect(calls).toContain('brain')
+    expect(calls).toContain('engram')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Health — aggregate status from all providers
+// ═══════════════════════════════════════════════════════════════════
+
+describe('health', () => {
+  it('returns ok when all providers are healthy', async () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(createMockProvider('brain', []))
+    orch.addProvider(createMockProvider('engram', []))
+
+    const health = await orch.health()
+    expect(health.ok).toBe(true)
+    expect(health.error).toBeUndefined()
+  })
+
+  it('returns not ok when any provider is unhealthy', async () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(createMockProvider('brain', []))
+    orch.addProvider(createMockProvider('engram', [], { failHealth: true }))
+
+    const health = await orch.health()
+    expect(health.ok).toBe(false)
+    expect(health.error).toContain('engram')
+  })
+
+  it('returns ok with zero providers', async () => {
+    const orch = new MemoryOrchestrator()
+    const health = await orch.health()
+    expect(health.ok).toBe(true)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Agent instructions — merged from all providers
+// ═══════════════════════════════════════════════════════════════════
+
+describe('agent instructions', () => {
+  it('merges instructions from all providers', () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(createMockProvider('brain', [], { instructions: 'Use /recall for brain.' }))
+    orch.addProvider(createMockProvider('engram', [], { instructions: 'Engram tracks sessions.' }))
+
+    const instructions = orch.agentInstructions()
+    expect(instructions).toContain('Use /recall for brain.')
+    expect(instructions).toContain('Engram tracks sessions.')
+  })
+
+  it('skips empty instructions', () => {
+    const orch = new MemoryOrchestrator()
+    orch.addProvider(createMockProvider('brain', [], { instructions: 'Brain instructions' }))
+    orch.addProvider(createMockProvider('engram', []))
+
+    const instructions = orch.agentInstructions()
+    expect(instructions).toBe('Brain instructions')
+    expect(instructions).not.toContain('\n\n\n') // no empty gaps
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Hooks integration — HookRunner wired into lifecycle
+// ═══════════════════════════════════════════════════════════════════
+
+describe('hooks integration', () => {
+  it('reports hasHooks false when no hooks configured', () => {
+    const orch = new MemoryOrchestrator()
+    expect(orch.hasHooks).toBe(false)
+  })
+
+  it('reports hasHooks true when hooks configured', () => {
+    const hooks: HooksConfig = {
+      afterRecall: [{ action: 'boost', factor: 1.3 }],
+    }
+    const orch = new MemoryOrchestrator({ hooks })
+    expect(orch.hasHooks).toBe(true)
+  })
+
+  it('afterRecall boost modifies scores in recall results', async () => {
+    const hooks: HooksConfig = {
+      afterRecall: [
+        {
+          action: 'boost',
+          provider: 'engram',
+          factor: 1.5,
+          recencyWindow: '24h',
+        },
+      ],
+    }
+    const orch = new MemoryOrchestrator({ hooks })
+
+    const recentDate = new Date(Date.now() - 3_600_000)
+    orch.addProvider(
+      createMockProvider('engram', [
+        { content: 'Recent engram fact', score: 0.6, source: 'engram', storedAt: recentDate },
+      ]),
+    )
+    orch.addProvider(
+      createMockProvider('brain', [{ content: 'Old brain fact', score: 0.7, source: 'brain' }]),
+    )
+
+    const results = await orch.recall('test')
+
+    // Engram result should be boosted (0.6 * 1.5 = 0.9)
+    const engramResult = results.find((r) => r.source === 'engram')
+    expect(engramResult).toBeDefined()
+    expect(engramResult!.score).toBeCloseTo(0.9)
+  })
+
+  it('sessionEnd hooks run before provider onSessionEnd', async () => {
+    const order: string[] = []
+    const savedFacts: Fact[][] = []
+
+    const hooks: HooksConfig = {
+      sessionEnd: [
+        {
+          action: 'summarize',
+          provider: 'brain',
+        },
+      ],
+    }
+    const orch = new MemoryOrchestrator({ hooks })
+
+    orch.addProvider(
+      createMockProvider('brain', [], {
+        savedFacts,
+        onSessionEnd: () => order.push('provider-end'),
+      }),
+    )
+
+    await orch.onSessionEnd({
+      messages: [{ role: 'user', content: 'test' }],
+    })
+
+    // summarize should have saved before provider's onSessionEnd
+    expect(savedFacts.length).toBe(1)
+    expect(savedFacts[0][0].category).toBe('session-summary')
+  })
+
+  it('afterSessionEnd hooks run after provider onSessionEnd', async () => {
+    const order: string[] = []
+    const brainFacts: Fact[][] = []
+
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'extraction',
+          when: { providersAvailable: ['engram', 'brain'] },
+        },
+      ],
+    }
+    const orch = new MemoryOrchestrator({ hooks })
+
+    orch.addProvider(
+      createMockProvider('engram', [], {
+        onSessionEnd: () => order.push('engram-end'),
+      }),
+    )
+    orch.addProvider(
+      createMockProvider('brain', [], {
+        savedFacts: brainFacts,
+        onSessionEnd: () => order.push('brain-end'),
+      }),
+    )
+
+    await orch.onSessionEnd({
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary: 'Session summary for promotion',
+    })
+
+    // Promote should have saved the summary to brain
+    expect(brainFacts.length).toBe(1)
+    expect(brainFacts[0][0].content).toBe('Session summary for promotion')
+    expect(brainFacts[0][0].tags).toContain('from:engram')
+  })
+
+  it('hooks with failing guards are silently skipped', async () => {
+    const brainFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'extraction',
+          when: { minMessages: 100 }, // won't be met
+        },
+      ],
+    }
+    const orch = new MemoryOrchestrator({ hooks })
+    orch.addProvider(createMockProvider('engram', []))
+    orch.addProvider(createMockProvider('brain', [], { savedFacts: brainFacts }))
+
+    await orch.onSessionEnd({
+      messages: [{ role: 'user', content: 'test' }],
+    })
+
+    expect(brainFacts.length).toBe(0)
+  })
+
+  it('beforeSave hooks can modify facts', async () => {
+    // Use a custom action to test beforeSave
+    const { registerAction } = await import('../lib/hook-runner')
+    registerAction('tag-facts', async (_hook, context, _providers) => {
+      if (context.facts) {
+        for (const fact of context.facts) {
+          fact.tags = [...(fact.tags ?? []), 'auto-tagged']
+        }
+      }
+    })
+
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      beforeSave: [{ action: 'tag-facts' }],
+    }
+    const orch = new MemoryOrchestrator({ hooks })
+    orch.addProvider(createMockProvider('brain', [], { savedFacts }))
+
+    await orch.save([{ content: 'Test fact' }])
+
+    expect(savedFacts.length).toBe(1)
+    expect(savedFacts[0][0].tags).toContain('auto-tagged')
+  })
+
+  it('compaction hooks trigger via onCompaction', async () => {
+    let compactionRan = false
+    const { registerAction } = await import('../lib/hook-runner')
+    registerAction('compaction-handler', async () => {
+      compactionRan = true
+    })
+
+    const hooks: HooksConfig = {
+      compaction: [{ action: 'compaction-handler' }],
+    }
+    const orch = new MemoryOrchestrator({ hooks })
+    orch.addProvider(createMockProvider('brain', []))
+
+    await orch.onCompaction({ messageCount: 50 })
+
+    expect(compactionRan).toBe(true)
+  })
+})