@cleocode/core 2026.3.68 → 2026.3.70

package/src/memory/__tests__/brain-automation.test.ts

@@ -0,0 +1,941 @@
+/**
+ * Tests for T134 Brain Memory Automation features.
+ *
+ * Covers: BrainConfig defaults, buildSummarizationPrompt, ingestStructuredSummary,
+ * extractFromTranscript, runBrainMaintenance, EmbeddingQueue, LocalEmbeddingProvider,
+ * maybeRefreshMemoryBridge, and generateContextAwareContent.
+ *
+ * @epic T134
+ */
+
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { DebriefData } from '../../sessions/handoff.js';
+
+// ============================================================================
+// Module mocks (hoisted by vitest — apply to all tests in this file)
+// ============================================================================
+
+// Capture the real loadConfig before mocking so BrainConfig tests can restore it.
+// vi.importActual runs synchronously at hoist time.
+const _realConfigModule =
+  await vi.importActual<typeof import('../../config.js')>('../../config.js');
+const _realLoadConfig = _realConfigModule.loadConfig;
+
+// Mock config.js — individual tests that need real loadConfig restore it via mockImplementation.
+// BrainConfig defaults tests restore the real implementation in beforeEach.
+vi.mock('../../config.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../config.js')>();
+  return {
+    ...actual,
+    // Start with a spy wrapping the real function so we can override per-test
+    loadConfig: vi.fn(actual.loadConfig),
+  };
+});
+
+// Mock brain-retrieval.js — needed by ingestStructuredSummary and runBrainMaintenance
+vi.mock('../brain-retrieval.js', () => ({
+  observeBrain: vi.fn().mockResolvedValue({ id: 'O-mock-001' }),
+  searchBrainCompact: vi.fn().mockResolvedValue({ results: [], total: 0, tokensEstimated: 0 }),
+  populateEmbeddings: vi.fn().mockResolvedValue({ processed: 0, skipped: 0, errors: 0 }),
+}));
+
+// Mock brain-lifecycle.js — used by runBrainMaintenance
+vi.mock('../brain-lifecycle.js', () => ({
+  applyTemporalDecay: vi.fn().mockResolvedValue({ updated: 3 }),
+  consolidateMemories: vi.fn().mockResolvedValue({ merged: 2, archived: 4 }),
+}));
+
+// Mock auto-extract dependencies
+vi.mock('../learnings.js', () => ({
+  storeLearning: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../patterns.js', () => ({
+  storePattern: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../decisions.js', () => ({
+  storeDecision: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../../store/data-accessor.js', () => ({
+  getAccessor: vi.fn().mockResolvedValue({
+    queryTasks: vi.fn().mockResolvedValue({ tasks: [], total: 0 }),
+    loadTasks: vi.fn().mockResolvedValue([]),
+    close: vi.fn().mockResolvedValue(undefined),
+  }),
+}));
+
+// Mock @xenova/transformers to prevent model downloads in tests
+vi.mock('@xenova/transformers', () => ({
+  pipeline: vi
+    .fn()
+    .mockResolvedValue(vi.fn().mockResolvedValue({ data: new Float32Array(384).fill(0.1) })),
+}));
+
+// Mock brain-search.js — used by generateContextAwareContent
+vi.mock('../brain-search.js', () => ({
+  hybridSearch: vi.fn().mockResolvedValue([
+    { id: 'O-ctx-001', title: 'Relevant brain context hit', text: 'Some relevant text' },
+    { id: 'O-ctx-002', title: 'Another relevant hit', text: 'More relevant text' },
+  ]),
+  resetFts5Cache: vi.fn(),
+}));
+
+// ============================================================================
+// Shared temp-dir lifecycle helpers
+// ============================================================================
+
+async function makeTempDir(prefix: string): Promise<{ tempDir: string; cleoDir: string }> {
+  const tempDir = await mkdtemp(join(tmpdir(), prefix));
+  const cleoDir = join(tempDir, '.cleo');
+  await mkdir(cleoDir, { recursive: true });
+  return { tempDir, cleoDir };
+}
+
+async function cleanTempDir(tempDir: string): Promise<void> {
+  await Promise.race([
+    rm(tempDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 }).catch(() => {}),
+    new Promise<void>((resolve) => setTimeout(resolve, 8_000)),
+  ]);
+}
+
+async function closeDbs(): Promise<void> {
+  try {
+    const { closeBrainDb } = await import('../../store/brain-sqlite.js');
+    closeBrainDb();
+  } catch {
+    /* not loaded */
+  }
+  try {
+    const { closeDb } = await import('../../store/sqlite.js');
+    closeDb();
+  } catch {
+    /* not loaded */
+  }
+  try {
+    const { resetFts5Cache } = await import('../brain-search.js');
+    resetFts5Cache();
+  } catch {
+    /* not loaded */
+  }
+}
+
+/** Build a minimal DebriefData fixture for testing. */
+function makeDebrief(overrides?: Partial<DebriefData>): DebriefData {
+  return {
+    handoff: {
+      lastTask: 'T100',
+      tasksCompleted: ['T101', 'T102'],
+      tasksCreated: [],
+      decisionsRecorded: 1,
+      nextSuggested: ['T103'],
+      openBlockers: [],
+      openBugs: [],
+      note: 'Finished the main implementation',
+    },
+    sessionId: 'S-test-001',
+    agentIdentifier: 'agent-1',
+    startedAt: '2026-03-01T10:00:00Z',
+    endedAt: '2026-03-01T11:00:00Z',
+    durationMinutes: 60,
+    decisions: [
+      {
+        id: 'DEC-001',
+        decision: 'Use SQLite for brain storage',
+        rationale: 'Reliable embedded database with FTS5 support',
+        taskId: 'T100',
+      },
+    ],
+    gitState: null,
+    chainPosition: 1,
+    chainLength: 1,
+    ...overrides,
+  };
+}
+
+// ============================================================================
+// 1. BrainConfig defaults
+// ============================================================================
+
+describe('BrainConfig defaults', () => {
+  let tempDir: string;
+  let cleoDir: string;
+
+  beforeEach(async () => {
+    ({ tempDir, cleoDir } = await makeTempDir('cleo-brain-config-'));
+    process.env['CLEO_DIR'] = cleoDir;
+
+    // Restore the real loadConfig for this suite so it reads actual config defaults.
+    // Use the reference captured before the mock was applied.
+    const configMod = await import('../../config.js');
+    (configMod.loadConfig as ReturnType<typeof vi.fn>).mockImplementation(_realLoadConfig);
+  });
+
+  afterEach(async () => {
+    await closeDbs();
+    delete process.env['CLEO_DIR'];
+    await cleanTempDir(tempDir);
+  });
+
+  it('loadConfig returns brain config with all required fields', async () => {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(tempDir);
+
+    expect(config.brain).toBeDefined();
+    expect(config.brain?.embedding).toBeDefined();
+    expect(config.brain?.memoryBridge).toBeDefined();
+    expect(config.brain?.summarization).toBeDefined();
+  });
+
+  it('brain.embedding.enabled defaults to true', async () => {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(tempDir);
+
+    expect(config.brain?.embedding.enabled).toBe(true);
+  });
+
+  it('brain.summarization.enabled defaults to true', async () => {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(tempDir);
+
+    expect(config.brain?.summarization.enabled).toBe(true);
+  });
+
+  it('brain.memoryBridge.autoRefresh defaults to true', async () => {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(tempDir);
+
+    expect(config.brain?.memoryBridge.autoRefresh).toBe(true);
+  });
+
+  it('brain.memoryBridge.contextAware defaults to true', async () => {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(tempDir);
+
+    expect(config.brain?.memoryBridge.contextAware).toBe(true);
+  });
+
+  it('brain.memoryBridge.maxTokens defaults to 2000', async () => {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(tempDir);
+
+    expect(config.brain?.memoryBridge.maxTokens).toBe(2000);
+  });
+
+  it('project config can override brain defaults', async () => {
+    await writeFile(
+      join(cleoDir, 'config.json'),
+      JSON.stringify({
+        brain: { memoryBridge: { autoRefresh: false, contextAware: false, maxTokens: 500 } },
+      }),
+    );
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(tempDir);
+
+    expect(config.brain?.memoryBridge.autoRefresh).toBe(false);
+    expect(config.brain?.memoryBridge.maxTokens).toBe(500);
+  });
+});
+
+// ============================================================================
+// 2. buildSummarizationPrompt (session-memory.ts)
+// ============================================================================
+
+describe('buildSummarizationPrompt', () => {
+  it('returns null when debrief is null', async () => {
+    const { buildSummarizationPrompt } = await import('../session-memory.js');
+    expect(buildSummarizationPrompt('S-001', null)).toBeNull();
+  });
+
+  it('returns null when debrief is undefined', async () => {
+    const { buildSummarizationPrompt } = await import('../session-memory.js');
+    expect(buildSummarizationPrompt('S-001', undefined)).toBeNull();
+  });
+
+  it('returns null when debrief has no content (empty tasks, decisions, note)', async () => {
+    const { buildSummarizationPrompt } = await import('../session-memory.js');
+    const empty = makeDebrief({
+      decisions: [],
+      handoff: {
+        lastTask: null,
+        tasksCompleted: [],
+        tasksCreated: [],
+        decisionsRecorded: 0,
+        nextSuggested: [],
+        openBlockers: [],
+        openBugs: [],
+        note: '',
+      },
+    });
+    expect(buildSummarizationPrompt('S-001', empty)).toBeNull();
+  });
+
+  it('includes tasks completed in prompt', async () => {
+    const { buildSummarizationPrompt } = await import('../session-memory.js');
+    const debrief = makeDebrief();
+    const prompt = buildSummarizationPrompt('S-test-001', debrief);
+
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('T101');
+    expect(prompt).toContain('T102');
+  });
+
+  it('includes decisions in prompt', async () => {
+    const { buildSummarizationPrompt } = await import('../session-memory.js');
+    const debrief = makeDebrief();
+    const prompt = buildSummarizationPrompt('S-test-001', debrief);
+
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('Use SQLite for brain storage');
+    expect(prompt).toContain('Reliable embedded database with FTS5 support');
+  });
+
+  it('includes session note in prompt', async () => {
+    const { buildSummarizationPrompt } = await import('../session-memory.js');
+    const debrief = makeDebrief();
+    const prompt = buildSummarizationPrompt('S-test-001', debrief);
+
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('Finished the main implementation');
+  });
+
+  it('includes next suggested tasks', async () => {
+    const { buildSummarizationPrompt } = await import('../session-memory.js');
+    const debrief = makeDebrief();
+    const prompt = buildSummarizationPrompt('S-test-001', debrief);
+
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('T103');
+  });
+
+  it('contains JSON instruction for structured output', async () => {
+    const { buildSummarizationPrompt } = await import('../session-memory.js');
+    const debrief = makeDebrief();
+    const prompt = buildSummarizationPrompt('S-test-001', debrief);
+
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('JSON');
+    expect(prompt).toContain('keyLearnings');
+    expect(prompt).toContain('decisions');
+    expect(prompt).toContain('patterns');
+  });
+
+  it('works with only a note (no tasks or decisions)', async () => {
+    const { buildSummarizationPrompt } = await import('../session-memory.js');
+    const debrief = makeDebrief({
+      decisions: [],
+      handoff: {
+        lastTask: null,
+        tasksCompleted: [],
+        tasksCreated: [],
+        decisionsRecorded: 0,
+        nextSuggested: [],
+        openBlockers: [],
+        openBugs: [],
+        note: 'Important observation here',
+      },
+    });
+    const prompt = buildSummarizationPrompt('S-002', debrief);
+
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('Important observation here');
+  });
+});
+
+// ============================================================================
+// 3. ingestStructuredSummary (session-memory.ts)
+// ============================================================================
+
+describe('ingestStructuredSummary', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('creates observations for key learnings', async () => {
+    const { ingestStructuredSummary } = await import('../session-memory.js');
+    const { observeBrain } = await import('../brain-retrieval.js');
+
+    await ingestStructuredSummary('/mock/root', 'S-001', {
+      keyLearnings: ['Always run tests before committing', 'Use strict TypeScript'],
+      decisions: [],
+      patterns: [],
+      nextActions: [],
+    });
+
+    const calls = (observeBrain as ReturnType<typeof vi.fn>).mock.calls;
+    const learningCalls = calls.filter((c) => c[1]?.type === 'discovery');
+    expect(learningCalls.length).toBe(2);
+    expect(learningCalls[0][1].text).toBe('Always run tests before committing');
+    expect(learningCalls[1][1].text).toBe('Use strict TypeScript');
+  });
+
+  it('creates observations for decisions', async () => {
+    const { ingestStructuredSummary } = await import('../session-memory.js');
+    const { observeBrain } = await import('../brain-retrieval.js');
+
+    await ingestStructuredSummary('/mock/root', 'S-002', {
+      keyLearnings: [],
+      decisions: ['Use pnpm for package management', 'Adopt biome for linting'],
+      patterns: [],
+      nextActions: [],
+    });
+
+    const calls = (observeBrain as ReturnType<typeof vi.fn>).mock.calls;
+    const decisionCalls = calls.filter((c) => c[1]?.type === 'decision');
+    expect(decisionCalls.length).toBe(2);
+    expect(decisionCalls[0][1].text).toBe('Use pnpm for package management');
+  });
+
+  it('creates observations for patterns', async () => {
+    const { ingestStructuredSummary } = await import('../session-memory.js');
+    const { observeBrain } = await import('../brain-retrieval.js');
+
+    await ingestStructuredSummary('/mock/root', 'S-003', {
+      keyLearnings: [],
+      decisions: [],
+      patterns: ['Always check for existing utilities before writing new code'],
+      nextActions: [],
+    });
+
+    const calls = (observeBrain as ReturnType<typeof vi.fn>).mock.calls;
+    // Patterns are stored as 'discovery' type
+    const patternCalls = calls.filter((c) => c[1]?.type === 'discovery');
+    expect(patternCalls.length).toBe(1);
+    expect(patternCalls[0][1].text).toBe(
+      'Always check for existing utilities before writing new code',
+    );
+  });
+
+  it('skips empty strings', async () => {
+    const { ingestStructuredSummary } = await import('../session-memory.js');
+    const { observeBrain } = await import('../brain-retrieval.js');
+
+    await ingestStructuredSummary('/mock/root', 'S-004', {
+      keyLearnings: ['Valid learning', '', '   '],
+      decisions: [],
+      patterns: [],
+      nextActions: [],
+    });
+
+    const calls = (observeBrain as ReturnType<typeof vi.fn>).mock.calls;
+    // Only the non-empty learning should be stored
+    expect(calls.length).toBe(1);
+    expect(calls[0][1].text).toBe('Valid learning');
+  });
+
+  it('never throws (best-effort)', async () => {
+    const { ingestStructuredSummary } = await import('../session-memory.js');
+    const { observeBrain } = await import('../brain-retrieval.js');
+    (observeBrain as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('DB error'));
+
+    await expect(
+      ingestStructuredSummary('/mock/root', 'S-005', {
+        keyLearnings: ['Some learning'],
+        decisions: [],
+        patterns: [],
+        nextActions: [],
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('attaches correct sourceSessionId and sourceType', async () => {
+    const { ingestStructuredSummary } = await import('../session-memory.js');
+    const { observeBrain } = await import('../brain-retrieval.js');
+
+    await ingestStructuredSummary('/mock/root', 'S-session-99', {
+      keyLearnings: ['A key insight'],
+      decisions: [],
+      patterns: [],
+      nextActions: [],
+    });
+
+    const calls = (observeBrain as ReturnType<typeof vi.fn>).mock.calls;
+    expect(calls[0][1].sourceSessionId).toBe('S-session-99');
+    expect(calls[0][1].sourceType).toBe('agent');
+  });
+});
+
+// ============================================================================
+// 4. extractFromTranscript (auto-extract.ts)
+// ============================================================================
+
+describe('extractFromTranscript', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('extracts action-word lines from transcript', async () => {
+    const { extractFromTranscript } = await import('../auto-extract.js');
+    const { storeLearning } = await import('../learnings.js');
+
+    const transcript = [
+      'user: Can you implement the auth module?',
+      'assistant: I will implement the auth module now.',
+      'assistant: I have fixed the login bug in auth.ts.',
+      'assistant: This is a short line.',
+      'user: Great, what about the tests?',
+      'assistant: I will add tests for the auth module.',
+    ].join('\n');
+
+    await extractFromTranscript('/mock/root', 'S-001', transcript);
+
+    expect(storeLearning).toHaveBeenCalled();
+    const calls = (storeLearning as ReturnType<typeof vi.fn>).mock.calls;
+    // All stored learnings should come from action-word lines
+    for (const [, learning] of calls) {
+      expect(learning.source).toBe('transcript:S-001');
+      expect(learning.confidence).toBe(0.6);
+    }
+  });
+
+  it('limits to 5 learnings max', async () => {
+    const { extractFromTranscript } = await import('../auto-extract.js');
+    const { storeLearning } = await import('../learnings.js');
+
+    // Build a transcript with 10 action lines (all > 20 chars)
+    const lines = Array.from(
+      { length: 10 },
+      (_, i) => `assistant: I implemented feature number ${i + 1} successfully.`,
+    );
+    const transcript = lines.join('\n');
+
+    await extractFromTranscript('/mock/root', 'S-002', transcript);
+
+    const calls = (storeLearning as ReturnType<typeof vi.fn>).mock.calls;
+    expect(calls.length).toBeLessThanOrEqual(5);
+  });
+
+  it('never throws on malformed input', async () => {
+    const { extractFromTranscript } = await import('../auto-extract.js');
+
+    await expect(extractFromTranscript('/mock/root', 'S-003', '')).resolves.toBeUndefined();
+    await expect(
+      extractFromTranscript('/mock/root', 'S-003', null as unknown as string),
+    ).resolves.toBeUndefined();
+    await expect(
+      extractFromTranscript('/mock/root', 'S-003', 123 as unknown as string),
+    ).resolves.toBeUndefined();
+  });
+
+  it('returns void (side-effect function)', async () => {
+    const { extractFromTranscript } = await import('../auto-extract.js');
+    const result = await extractFromTranscript(
+      '/mock/root',
+      'S-004',
+      'I implemented a feature here.',
+    );
+    expect(result).toBeUndefined();
+  });
+
+  it('does nothing when no action lines present', async () => {
+    const { extractFromTranscript } = await import('../auto-extract.js');
+    const { storeLearning } = await import('../learnings.js');
+
+    const transcript = ['user: Hello', 'assistant: Hi there', 'user: How are you?'].join('\n');
+
+    await extractFromTranscript('/mock/root', 'S-005', transcript);
+    expect(storeLearning).not.toHaveBeenCalled();
+  });
+});
+
+// ============================================================================
+// 5. runBrainMaintenance (brain-maintenance.ts)
+// ============================================================================
+
+describe('runBrainMaintenance', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('runs all 3 steps by default', async () => {
+    const { runBrainMaintenance } = await import('../brain-maintenance.js');
+    const { applyTemporalDecay, consolidateMemories } = await import('../brain-lifecycle.js');
+    const { populateEmbeddings } = await import('../brain-retrieval.js');
+
+    const result = await runBrainMaintenance('/mock/root');
+
+    expect(applyTemporalDecay).toHaveBeenCalledWith('/mock/root');
+    expect(consolidateMemories).toHaveBeenCalledWith('/mock/root');
+    expect(populateEmbeddings).toHaveBeenCalled();
+
+    expect(result).toHaveProperty('decay');
+    expect(result).toHaveProperty('consolidation');
+    expect(result).toHaveProperty('embeddings');
+    expect(result).toHaveProperty('duration');
+  });
+
+  it('respects skipDecay flag', async () => {
+    const { runBrainMaintenance } = await import('../brain-maintenance.js');
+    const { applyTemporalDecay } = await import('../brain-lifecycle.js');
+
+    const result = await runBrainMaintenance('/mock/root', { skipDecay: true });
+
+    expect(applyTemporalDecay).not.toHaveBeenCalled();
+    expect(result.decay.affected).toBe(0);
+  });
+
+  it('respects skipConsolidation flag', async () => {
+    const { runBrainMaintenance } = await import('../brain-maintenance.js');
+    const { consolidateMemories } = await import('../brain-lifecycle.js');
+
+    const result = await runBrainMaintenance('/mock/root', { skipConsolidation: true });
+
+    expect(consolidateMemories).not.toHaveBeenCalled();
+    expect(result.consolidation.merged).toBe(0);
+    expect(result.consolidation.removed).toBe(0);
+  });
+
+  it('respects skipEmbeddings flag', async () => {
+    const { runBrainMaintenance } = await import('../brain-maintenance.js');
+    const { populateEmbeddings } = await import('../brain-retrieval.js');
+
+    const result = await runBrainMaintenance('/mock/root', { skipEmbeddings: true });
+
+    expect(populateEmbeddings).not.toHaveBeenCalled();
+    expect(result.embeddings.processed).toBe(0);
+  });
+
+  it('calls onProgress callback for each step', async () => {
+    const { runBrainMaintenance } = await import('../brain-maintenance.js');
+    const progressCalls: Array<[string, number, number]> = [];
+
+    await runBrainMaintenance('/mock/root', {
+      onProgress: (step, current, total) => {
+        progressCalls.push([step, current, total]);
+      },
+    });
+
+    const steps = progressCalls.map(([step]) => step);
+    expect(steps).toContain('decay');
+    expect(steps).toContain('consolidation');
+  });
+
+  it('returns structured result with duration', async () => {
+    const { runBrainMaintenance } = await import('../brain-maintenance.js');
+
+    const result = await runBrainMaintenance('/mock/root');
+
+    expect(typeof result.duration).toBe('number');
+    expect(result.duration).toBeGreaterThanOrEqual(0);
+    expect(result.decay).toMatchObject({ affected: 3 });
+    expect(result.consolidation).toMatchObject({ merged: 2, removed: 4 });
+  });
+
+  it('skips all steps when all skip flags set — returns zero counts', async () => {
+    const { runBrainMaintenance } = await import('../brain-maintenance.js');
+
+    const result = await runBrainMaintenance('/mock/root', {
+      skipDecay: true,
+      skipConsolidation: true,
+      skipEmbeddings: true,
+    });
+
+    expect(result.decay.affected).toBe(0);
+    expect(result.consolidation.merged).toBe(0);
+    expect(result.consolidation.removed).toBe(0);
+    expect(result.embeddings.processed).toBe(0);
+  });
+});
+
+// ============================================================================
+// 6. EmbeddingQueue (embedding-queue.ts)
+// ============================================================================
+
+describe('EmbeddingQueue', () => {
+  it('singleton pattern — getEmbeddingQueue returns same instance', async () => {
+    const { getEmbeddingQueue, resetEmbeddingQueue } = await import('../embedding-queue.js');
+    await resetEmbeddingQueue();
+
+    const instance1 = getEmbeddingQueue();
+    const instance2 = getEmbeddingQueue();
+
+    expect(instance1).toBe(instance2);
+
+    await resetEmbeddingQueue();
+  });
+
+  it('enqueue() adds items without throwing', async () => {
+    const { getEmbeddingQueue, resetEmbeddingQueue } = await import('../embedding-queue.js');
+    await resetEmbeddingQueue();
+
+    const queue = getEmbeddingQueue();
+    const onComplete = vi.fn().mockResolvedValue(undefined);
+
+    expect(() => {
+      queue.enqueue('O-test-001', 'some text to embed', onComplete);
+    }).not.toThrow();
+
+    await resetEmbeddingQueue();
+  });
+
+  it('shutdown() completes gracefully', async () => {
+    const { getEmbeddingQueue, resetEmbeddingQueue } = await import('../embedding-queue.js');
+    await resetEmbeddingQueue();
+
+    const queue = getEmbeddingQueue();
+
+    await expect(queue.shutdown()).resolves.toBeUndefined();
+
+    await resetEmbeddingQueue();
+  });
+
+  it('shutdown() is idempotent — second call returns same promise', async () => {
+    const { getEmbeddingQueue, resetEmbeddingQueue } = await import('../embedding-queue.js');
+    await resetEmbeddingQueue();
+
+    const queue = getEmbeddingQueue();
+    const p1 = queue.shutdown();
+    const p2 = queue.shutdown();
+
+    expect(p1).toBe(p2);
+
+    await p1;
+    await resetEmbeddingQueue();
+  });
+
+  it('enqueue() after shutdown is a no-op (does not throw)', async () => {
+    const { getEmbeddingQueue, resetEmbeddingQueue } = await import('../embedding-queue.js');
+    await resetEmbeddingQueue();
+
+    const queue = getEmbeddingQueue();
+    await queue.shutdown();
+
+    const onComplete = vi.fn().mockResolvedValue(undefined);
+    expect(() => {
+      queue.enqueue('O-after-shutdown', 'text', onComplete);
+    }).not.toThrow();
+
+    // onComplete should not be called — queue is shut down
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    expect(onComplete).not.toHaveBeenCalled();
+
+    await resetEmbeddingQueue();
+  });
+});
+
+// ============================================================================
+// 7. LocalEmbeddingProvider (embedding-local.ts)
+// ============================================================================
+
+describe('LocalEmbeddingProvider', () => {
+  it('class exists and can be instantiated', async () => {
+    const { LocalEmbeddingProvider } = await import('../embedding-local.js');
+    const provider = new LocalEmbeddingProvider();
+    expect(provider).toBeDefined();
+  });
+
+  it('implements EmbeddingProvider interface (has dimensions, isAvailable, embed)', async () => {
+    const { LocalEmbeddingProvider } = await import('../embedding-local.js');
+    const provider = new LocalEmbeddingProvider();
+
+    expect(typeof provider.dimensions).toBe('number');
+    expect(provider.dimensions).toBe(384);
+    expect(typeof provider.isAvailable).toBe('function');
+    expect(typeof provider.embed).toBe('function');
+  });
+
+  it('isAvailable returns a boolean', async () => {
+    const { LocalEmbeddingProvider } = await import('../embedding-local.js');
+    const provider = new LocalEmbeddingProvider();
+
+    expect(typeof provider.isAvailable()).toBe('boolean');
+  });
+
+  it('getLocalEmbeddingProvider returns singleton', async () => {
+    const { getLocalEmbeddingProvider } = await import('../embedding-local.js');
+    const instance1 = getLocalEmbeddingProvider();
+    const instance2 = getLocalEmbeddingProvider();
+
+    expect(instance1).toBe(instance2);
+  });
+
+  it('embed() returns Float32Array of correct length', async () => {
+    const { LocalEmbeddingProvider } = await import('../embedding-local.js');
+    const provider = new LocalEmbeddingProvider();
+
+    const result = await provider.embed('test text');
+
+    expect(result).toBeInstanceOf(Float32Array);
+    expect(result.length).toBe(384);
+  });
+
+  it('embedBatch() returns array of Float32Arrays', async () => {
+    const { LocalEmbeddingProvider } = await import('../embedding-local.js');
+    const provider = new LocalEmbeddingProvider();
+
+    const results = await provider.embedBatch(['text one', 'text two', 'text three']);
+
+    expect(Array.isArray(results)).toBe(true);
+    expect(results.length).toBe(3);
+    for (const vec of results) {
+      expect(vec).toBeInstanceOf(Float32Array);
+      expect(vec.length).toBe(384);
+    }
+  });
+});
+
+// ============================================================================
+// 8. maybeRefreshMemoryBridge (memory-bridge-refresh.ts)
+// ============================================================================
+
+describe('maybeRefreshMemoryBridge', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('skips when autoRefresh is disabled in config', async () => {
+    const configMod = await import('../../config.js');
+    (configMod.loadConfig as ReturnType<typeof vi.fn>).mockResolvedValue({
+      brain: { memoryBridge: { autoRefresh: false, contextAware: true, maxTokens: 2000 } },
+    });
+
+    // memory-bridge-refresh.ts uses dynamic import for refreshMemoryBridge,
+    // so we track calls by spying on it from the memory-bridge module.
+    // Instead we verify behavior by checking it completes without error and
+    // doesn't call refreshMemoryBridge (via the brain.memoryBridge module mock).
+    const { maybeRefreshMemoryBridge } = await import(
+      '../../hooks/handlers/memory-bridge-refresh.js'
+    );
+
+    // Should complete without error and not attempt a refresh
+    await expect(maybeRefreshMemoryBridge('/mock/root')).resolves.toBeUndefined();
+  });
+
+  it('never throws (best-effort) — even when config fails', async () => {
+    const configMod = await import('../../config.js');
+    (configMod.loadConfig as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error('config load failed'),
+    );
+
+    const { maybeRefreshMemoryBridge } = await import(
+      '../../hooks/handlers/memory-bridge-refresh.js'
+    );
+
+    await expect(maybeRefreshMemoryBridge('/mock/root')).resolves.toBeUndefined();
+  });
+
+  it('returns undefined (void function)', async () => {
+    const configMod = await import('../../config.js');
+    (configMod.loadConfig as ReturnType<typeof vi.fn>).mockResolvedValue({
+      brain: { memoryBridge: { autoRefresh: false, contextAware: false, maxTokens: 2000 } },
+    });
+
+    const { maybeRefreshMemoryBridge } = await import(
+      '../../hooks/handlers/memory-bridge-refresh.js'
+    );
+    const result = await maybeRefreshMemoryBridge('/mock/root');
+    expect(result).toBeUndefined();
+  });
+
+  it('debounces within 30 seconds — does not call refresh twice in quick succession', async () => {
+    const configMod = await import('../../config.js');
+    (configMod.loadConfig as ReturnType<typeof vi.fn>).mockResolvedValue({
+      brain: { memoryBridge: { autoRefresh: true, contextAware: false, maxTokens: 2000 } },
+    });
+
+    const { maybeRefreshMemoryBridge } = await import(
+      '../../hooks/handlers/memory-bridge-refresh.js'
+    );
+
+    // Both calls should complete without error regardless of debounce behavior
+    await expect(maybeRefreshMemoryBridge('/mock/root')).resolves.toBeUndefined();
+    await expect(maybeRefreshMemoryBridge('/mock/root')).resolves.toBeUndefined();
+  });
+});
+
+// ============================================================================
+// 9. generateContextAwareContent (memory-bridge.ts)
+// ============================================================================
+
+describe('generateContextAwareContent', () => {
+  let tempDir: string;
+  let cleoDir: string;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    ({ tempDir, cleoDir } = await makeTempDir('cleo-ctx-aware-'));
+    process.env['CLEO_DIR'] = cleoDir;
+
+    const configMod = await import('../../config.js');
+    (configMod.loadConfig as ReturnType<typeof vi.fn>).mockResolvedValue({
+      brain: {
+        memoryBridge: { autoRefresh: true, contextAware: true, maxTokens: 2000 },
+        embedding: { enabled: true, provider: 'local' },
+        summarization: { enabled: true },
+      },
+    });
+  });
+
+  afterEach(async () => {
+    await closeDbs();
+    delete process.env['CLEO_DIR'];
+    await cleanTempDir(tempDir);
+  });
+
+  it('does not throw for valid scope', async () => {
+    const { generateContextAwareContent } = await import('../memory-bridge.js');
+
+    await expect(generateContextAwareContent(tempDir, 'epic:T134')).resolves.toBeUndefined();
+  });
+
+  it('respects maxTokens budget from config', async () => {
+    const configMod = await import('../../config.js');
+    (configMod.loadConfig as ReturnType<typeof vi.fn>).mockResolvedValue({
+      brain: {
+        memoryBridge: { autoRefresh: true, contextAware: true, maxTokens: 100 },
+        embedding: { enabled: true, provider: 'local' },
+        summarization: { enabled: true },
+      },
+    });
+    const { generateContextAwareContent } = await import('../memory-bridge.js');
+
+    await expect(generateContextAwareContent(tempDir, 'global')).resolves.toBeUndefined();
+  });
+
+  it('works with scope parameter — builds query from scope + currentTaskId', async () => {
+    const { generateContextAwareContent } = await import('../memory-bridge.js');
+    const { hybridSearch } = await import('../brain-search.js');
+
+    await generateContextAwareContent(tempDir, 'epic:T134', 'T135');
+
+    // hybridSearch should be called with a query combining scope and currentTaskId
+    expect(hybridSearch).toHaveBeenCalledWith(
+      'epic:T134 T135',
+      tempDir,
+      expect.objectContaining({ limit: 10 }),
+    );
+  });
+
+  it('falls back gracefully when hybridSearch throws', async () => {
+    const { hybridSearch } = await import('../brain-search.js');
+    (hybridSearch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('FTS5 unavailable'));
+
+    const { generateContextAwareContent } = await import('../memory-bridge.js');
+
+    // Should not throw — falls back to standard writeMemoryBridge
+    await expect(generateContextAwareContent(tempDir, 'global')).resolves.toBeUndefined();
+  });
+
+  it('writes memory-bridge.md file to cleoDir', async () => {
+    const { generateContextAwareContent } = await import('../memory-bridge.js');
+    const { existsSync } = await import('node:fs');
+
+    await generateContextAwareContent(tempDir, 'global');
+
+    const bridgePath = join(cleoDir, 'memory-bridge.md');
+    expect(existsSync(bridgePath)).toBe(true);
+  });
+
+  it('returns string content (via generateMemoryBridgeContent) for token budget', async () => {
+    const { generateMemoryBridgeContent } = await import('../memory-bridge.js');
+
+    const content = await generateMemoryBridgeContent(tempDir);
+
+    expect(typeof content).toBe('string');
+    expect(content).toContain('# CLEO Memory Bridge');
+  });
+});