claude-memory-layer 1.0.26 → 1.0.28

package/tests/core/memory-engine-services.test.ts

@@ -0,0 +1,240 @@
+import * as path from 'path';
+import * as os from 'os';
+import { mkdtemp, rm, stat } from 'fs/promises';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  createMemoryEngineServices,
+  type MemoryEngineServicesFactories
+} from '../../src/core/engine/memory-engine-services.js';
+import type { MemoryEvent, MemoryEventInput, ToolObservationPayload } from '../../src/core/types.js';
+import type { RetrievalServicesDeps } from '../../src/core/engine/retrieval-services.js';
+
+function event(id = 'e1'): MemoryEvent {
+  return {
+    id,
+    sessionId: 's1',
+    eventType: 'user_prompt',
+    content: 'thin core factory event',
+    canonicalKey: `test/${id}`,
+    dedupeKey: `s1:${id}`,
+    timestamp: new Date('2026-05-02T00:00:00.000Z'),
+    metadata: {}
+  };
+}
+
+describe('createMemoryEngineServices', () => {
+  it('creates the storage directory and wires storage-backed engine services', async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), 'memory-engine-services-'));
+    const storagePath = path.join(root, 'memory');
+    const initialize = vi.fn(async () => {});
+    const createToolEmbedding = vi.fn((payload: ToolObservationPayload) => `${payload.toolName}:${payload.success}`);
+    const enqueueForEmbedding = vi.fn(async (_eventId: string, _content: string) => {});
+    const append = vi.fn(async (_input: MemoryEventInput) => ({
+      success: true as const,
+      eventId: 'event:user_prompt',
+      isDuplicate: false as const
+    }));
+    const sqliteStore = {
+      initialize: vi.fn(async () => {}),
+      append,
+      enqueueForEmbedding,
+      upsertSession: vi.fn(async () => {}),
+      keywordSearch: vi.fn(async (_query: string, _topK: number) => [{ event: event('keyword'), rank: -0.1 }]),
+      getSessionEvents: vi.fn(async (_sessionId: string) => [event('session')]),
+      getSessionsWithoutSummary: vi.fn(async () => []),
+      getRecentEvents: vi.fn(async (_limit?: number) => [event('recent')]),
+      getEvent: vi.fn(async (id: string) => event(id)),
+      recordRetrievalTrace: vi.fn(async (_input: Record<string, unknown>) => {}),
+      incrementAccessCount: vi.fn(async (_eventIds: string[]) => {}),
+      recordRetrieval: vi.fn(async (_eventId: string, _sessionId: string, _score: number, _query: string) => {}),
+      getRetrievalTraceStats: vi.fn(async () => ({
+        totalQueries: 0,
+        avgCandidateCount: 0,
+        avgSelectedCount: 0,
+        selectionRate: 0
+      })),
+      getRecentRetrievalTraces: vi.fn(async () => []),
+      getMostAccessed: vi.fn(async () => []),
+      evaluateSessionHelpfulness: vi.fn(async (_sessionId: string) => {}),
+      getUnevaluatedSessions: vi.fn(async () => []),
+      getHelpfulMemories: vi.fn(async () => []),
+      getHelpfulnessStats: vi.fn(async () => ({
+        avgScore: 0,
+        totalEvaluated: 0,
+        totalRetrievals: 0,
+        helpful: 0,
+        neutral: 0,
+        unhelpful: 0
+      }))
+    };
+    const vectorStore = {
+      marker: 'vector',
+      count: vi.fn(async () => 5)
+    };
+    const embedder = { marker: 'embedder' };
+    const matcher = { marker: 'matcher' };
+    const graduation = {
+      marker: 'graduation',
+      getStats: vi.fn(async () => [{ level: 'working', count: 2 }])
+    };
+    const mdMirror = { marker: 'mirror', append: vi.fn(async (_input: MemoryEventInput, _eventId?: string) => {}) };
+    const retrievalBundle = {
+      retriever: { marker: 'retriever' },
+      retrievalOrchestrator: { marker: 'orchestrator' },
+      retrievalDisclosureService: { marker: 'disclosure' },
+      retrievalAnalyticsService: { marker: 'analytics' }
+    };
+    let retrievalDeps: RetrievalServicesDeps | null = null;
+
+    const factories: MemoryEngineServicesFactories = {
+      createSQLiteEventStore: vi.fn((dbPath, options) => {
+        expect(dbPath).toBe(path.join(storagePath, 'events.sqlite'));
+        expect(options).toEqual({ readonly: false, markdownMirrorRoot: storagePath });
+        return sqliteStore as any;
+      }),
+      createVectorStore: vi.fn((vectorsPath) => {
+        expect(vectorsPath).toBe(path.join(storagePath, 'vectors'));
+        return vectorStore as any;
+      }),
+      createEmbedder: vi.fn((model: string) => {
+        expect(model).toBe('custom-embedding-model');
+        return embedder as any;
+      }),
+      getDefaultEmbedder: vi.fn(() => {
+        throw new Error('custom model should use createEmbedder');
+      }),
+      getDefaultMatcher: vi.fn(() => matcher as any),
+      createMarkdownMirror: vi.fn((cwd: string) => {
+        expect(cwd).toBe('/workspace/project');
+        return mdMirror as any;
+      }),
+      createGraduationPipeline: vi.fn((store) => {
+        expect(store).toBe(sqliteStore);
+        return graduation as any;
+      }),
+      createRetrievalServices: vi.fn((deps) => {
+        retrievalDeps = deps;
+        return retrievalBundle as any;
+      })
+    };
+
+    try {
+      const services = createMemoryEngineServices({
+        storagePath,
+        readOnly: false,
+        embeddingModel: 'custom-embedding-model',
+        cwd: '/workspace/project',
+        initialize,
+        getProjectHash: () => 'project-1',
+        getProjectPath: () => '/workspace/project',
+        hasSharedStore: () => false,
+        sharedStore: { get: async () => null },
+        createToolObservationEmbedding: createToolEmbedding,
+        factories
+      });
+
+      await expect(stat(storagePath)).resolves.toMatchObject({});
+      expect(services).toMatchObject({
+        storagePath,
+        sqliteStore,
+        vectorStore,
+        embedder,
+        matcher,
+        graduation,
+        mdMirror,
+        retriever: retrievalBundle.retriever,
+        retrievalOrchestrator: retrievalBundle.retrievalOrchestrator,
+        retrievalDisclosureService: retrievalBundle.retrievalDisclosureService,
+        retrievalAnalyticsService: retrievalBundle.retrievalAnalyticsService
+      });
+      expect(retrievalDeps).toMatchObject({
+        initialize,
+        eventStore: sqliteStore,
+        vectorStore,
+        embedder,
+        matcher,
+        sharedStore: { get: expect.any(Function) }
+      });
+      expect(retrievalDeps?.getProjectHash()).toBe('project-1');
+      expect(retrievalDeps?.hasSharedStore()).toBe(false);
+
+      await services.ingestService.storeUserPrompt('s1', 'remember factory wiring', { source: 'test' });
+      expect(initialize).not.toHaveBeenCalled();
+      expect(sqliteStore.append).toHaveBeenCalledWith(expect.objectContaining({
+        eventType: 'user_prompt',
+        sessionId: 's1',
+        content: 'remember factory wiring',
+        metadata: expect.objectContaining({
+          source: 'test',
+          ingest: expect.objectContaining({ operation: 'user_prompt', pipeline: 'default' }),
+          scope: { project: { hash: 'project-1', path: '/workspace/project' } },
+          tags: ['proj:project-1']
+        })
+      }));
+      expect(sqliteStore.enqueueForEmbedding).toHaveBeenCalledWith('event:user_prompt', 'remember factory wiring');
+      expect(mdMirror.append).toHaveBeenCalledWith(expect.any(Object), 'event:user_prompt');
+
+      await services.queryService.getRecentEvents(3);
+      expect(sqliteStore.getRecentEvents).toHaveBeenCalledWith(3);
+      expect(sqliteStore.initialize).toHaveBeenCalledTimes(1);
+      expect(initialize).not.toHaveBeenCalled();
+
+      await expect(services.queryService.getStats()).resolves.toEqual({
+        totalEvents: 1,
+        vectorCount: 5,
+        levelStats: [{ level: 'working', count: 2 }]
+      });
+      expect(sqliteStore.getRecentEvents).toHaveBeenCalledWith(10000);
+      expect(sqliteStore.initialize).toHaveBeenCalledTimes(2);
+      expect(initialize).not.toHaveBeenCalled();
+      expect(vectorStore.count).toHaveBeenCalledOnce();
+      expect(graduation.getStats).toHaveBeenCalledOnce();
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('does not create the storage directory before sqlite store construction in read-only mode', async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), 'memory-engine-services-readonly-'));
+    const storagePath = path.join(root, 'readonly-memory');
+    const factories: MemoryEngineServicesFactories = {
+      createSQLiteEventStore: vi.fn(() => ({}) as any),
+      createVectorStore: vi.fn(() => ({}) as any),
+      getDefaultEmbedder: vi.fn(() => ({}) as any),
+      getDefaultMatcher: vi.fn(() => ({}) as any),
+      createMarkdownMirror: vi.fn(() => ({}) as any),
+      createGraduationPipeline: vi.fn(() => ({}) as any),
+      createRetrievalServices: vi.fn(() => ({
+        retriever: {},
+        retrievalOrchestrator: {},
+        retrievalDisclosureService: {},
+        retrievalAnalyticsService: {}
+      }) as any)
+    };
+
+    try {
+      createMemoryEngineServices({
+        storagePath,
+        readOnly: true,
+        cwd: '/workspace/project',
+        initialize: async () => {},
+        getProjectHash: () => null,
+        hasSharedStore: () => false,
+        createToolObservationEmbedding: () => 'embedding',
+        factories
+      });
+
+      // This asserts the extracted factory does not eagerly mkdir in read-only mode
+      // before delegating to the sqlite-store constructor. The production sqlite
+      // layer may still require/open an existing read-only database.
+      await expect(stat(storagePath)).rejects.toMatchObject({ code: 'ENOENT' });
+      expect(factories.createSQLiteEventStore).toHaveBeenCalledWith(
+        path.join(storagePath, 'events.sqlite'),
+        { readonly: true, markdownMirrorRoot: storagePath }
+      );
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/tests/core/memory-ingest-service.test.ts

@@ -0,0 +1,296 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { MemoryIngestService } from '../../src/core/engine/memory-ingest-service.js';
+import type { AppendResult, MemoryEvent, MemoryEventInput, ToolObservationPayload } from '../../src/core/types.js';
+
+function event(overrides: Partial<MemoryEvent>): MemoryEvent {
+  return {
+    id: '11111111-1111-4111-8111-111111111111',
+    eventType: 'user_prompt',
+    sessionId: 'session-1',
+    timestamp: new Date('2026-04-30T00:00:00.000Z'),
+    content: 'default content',
+    canonicalKey: 'default-content',
+    dedupeKey: 'session-1:default-content',
+    metadata: {},
+    ...overrides
+  };
+}
+
+interface CreateServiceOptions {
+  eventsBySession?: Record<string, MemoryEvent[]>;
+  projectHash?: string | null;
+  projectPath?: string | null;
+  appendResult?: AppendResult;
+}
+
+function createService(options: CreateServiceOptions = {}) {
+  const eventsBySession = options.eventsBySession ?? {};
+  const appended: MemoryEventInput[] = [];
+  const initialize = vi.fn(async () => {});
+  const store = {
+    upsertSession: vi.fn(async () => {}),
+    getSessionEvents: vi.fn(async (sessionId: string) => eventsBySession[sessionId] ?? []),
+    getSessionsWithoutSummary: vi.fn(async () => Object.keys(eventsBySession)),
+    append: vi.fn(async (input: MemoryEventInput): Promise<AppendResult> => {
+      appended.push(input);
+      return options.appendResult ?? { success: true, eventId: `event-${appended.length}`, isDuplicate: false };
+    }),
+    enqueueForEmbedding: vi.fn(async (_eventId: string, _content: string) => {})
+  };
+  const markdownMirror = {
+    append: vi.fn(async (_input: MemoryEventInput, _eventId?: string) => {})
+  };
+  const createToolEmbedding = vi.fn((payload: ToolObservationPayload) => `${payload.toolName}:${payload.success}`);
+
+  return {
+    service: new MemoryIngestService({
+      initialize,
+      eventStore: store,
+      markdownMirror,
+      createToolEmbedding,
+      getProjectHash: () => options.projectHash ?? null,
+      getProjectPath: () => options.projectPath ?? null
+    }),
+    initialize,
+    store,
+    markdownMirror,
+    createToolEmbedding,
+    appended
+  };
+}
+
+describe('MemoryIngestService ingest pipeline', () => {
+  it('normalizes metadata, runs interceptors, appends, enqueues embeddings, and mirrors successful events', async () => {
+    const { service, store, markdownMirror, appended } = createService({
+      projectHash: 'project-hash-1',
+      projectPath: '/workspace/project'
+    });
+    const stages: string[] = [];
+
+    service.registerIngestBefore((context) => {
+      stages.push(`${context.stage}:${context.operation}`);
+      expect(context.sessionId).toBe('session-1');
+      expect(context.event.metadata).toMatchObject({
+        ingest: { operation: 'user_prompt', pipeline: 'default' },
+        scope: {
+          project: { hash: 'project-hash-1', path: '/workspace/project' },
+          turn: { id: 'turn-1' }
+        },
+        tags: ['user:alice', 'legacy', 'proj:project-hash-1']
+      });
+    });
+    service.registerIngestAfter((context) => {
+      stages.push(`${context.stage}:${context.operation}`);
+      expect(context.event).toBe(appended[0]);
+    });
+
+    const result = await service.storeUserPrompt('session-1', 'remember this', {
+      scope: { turn: { id: 'turn-1' } },
+      tags: [' user:alice ', 'bad:tag', 'legacy']
+    });
+
+    expect(result).toEqual({ success: true, eventId: 'event-1', isDuplicate: false });
+    expect(store.append).toHaveBeenCalledOnce();
+    expect(appended[0]).toMatchObject({
+      eventType: 'user_prompt',
+      sessionId: 'session-1',
+      content: 'remember this',
+      metadata: {
+        ingest: { operation: 'user_prompt', pipeline: 'default' },
+        scope: {
+          project: { hash: 'project-hash-1', path: '/workspace/project' },
+          turn: { id: 'turn-1' }
+        },
+        tags: ['user:alice', 'legacy', 'proj:project-hash-1']
+      }
+    });
+    expect((appended[0].metadata as Record<string, unknown>).ingest).toMatchObject({
+      ts: expect.any(String)
+    });
+    expect(store.enqueueForEmbedding).toHaveBeenCalledWith('event-1', 'remember this');
+    expect(markdownMirror.append).toHaveBeenCalledWith(appended[0], 'event-1');
+    expect(stages).toEqual(['before:user_prompt', 'after:user_prompt']);
+  });
+
+  it('does not enqueue embeddings or mirror duplicate append results', async () => {
+    const { service, store, markdownMirror } = createService({
+      appendResult: { success: true, eventId: 'duplicate-event', isDuplicate: true }
+    });
+
+    await expect(service.storeAgentResponse('session-1', 'duplicate response')).resolves.toEqual({
+      success: true,
+      eventId: 'duplicate-event',
+      isDuplicate: true
+    });
+
+    expect(store.enqueueForEmbedding).not.toHaveBeenCalled();
+    expect(markdownMirror.append).not.toHaveBeenCalled();
+  });
+
+  it('keeps markdown mirror failures non-breaking after a successful append', async () => {
+    const { service, store, markdownMirror } = createService();
+    markdownMirror.append.mockRejectedValueOnce(new Error('mirror is read-only'));
+
+    await expect(service.storeSessionSummary('session-1', 'summary')).resolves.toEqual({
+      success: true,
+      eventId: 'event-1',
+      isDuplicate: false
+    });
+
+    expect(store.enqueueForEmbedding).toHaveBeenCalledWith('event-1', 'summary');
+    expect(markdownMirror.append).toHaveBeenCalledOnce();
+  });
+
+  it('runs error interceptors and skips side effects when append returns a failure result', async () => {
+    const { service, store, markdownMirror } = createService({
+      appendResult: { success: false, error: 'sqlite append failed' }
+    });
+    const stages: string[] = [];
+    const errors: Error[] = [];
+    service.registerIngestAfter((context) => {
+      stages.push(context.stage);
+    });
+    service.registerIngestOnError((context) => {
+      stages.push(context.stage);
+      errors.push(context.error!);
+      expect(context.operation).toBe('agent_response');
+      expect(context.event.eventType).toBe('agent_response');
+    });
+
+    await expect(service.storeAgentResponse('session-1', 'failed append')).resolves.toEqual({
+      success: false,
+      error: 'sqlite append failed'
+    });
+
+    expect(errors.map((error) => error.message)).toEqual(['sqlite append failed']);
+    expect(stages).toEqual(['error']);
+    expect(store.enqueueForEmbedding).not.toHaveBeenCalled();
+    expect(markdownMirror.append).not.toHaveBeenCalled();
+  });
+
+  it('runs error interceptors and skips side effects when append throws', async () => {
+    const { service, store, markdownMirror } = createService();
+    const error = new Error('sqlite unavailable');
+    store.append.mockRejectedValueOnce(error);
+    const errors: Error[] = [];
+    service.registerIngestOnError((context) => {
+      errors.push(context.error!);
+      expect(context.stage).toBe('error');
+      expect(context.operation).toBe('tool_observation');
+      expect(context.event.eventType).toBe('tool_observation');
+    });
+
+    await expect(service.storeToolObservation('session-1', {
+      toolName: 'terminal',
+      success: false,
+      metadata: { turnId: 'turn-2' },
+      output: 'failed'
+    })).rejects.toThrow('sqlite unavailable');
+
+    expect(errors).toEqual([error]);
+    expect(store.enqueueForEmbedding).not.toHaveBeenCalled();
+    expect(markdownMirror.append).not.toHaveBeenCalled();
+  });
+});
+
+describe('MemoryIngestService session summary generation', () => {
+  it('generates the legacy rule-based summary and stores it through the ingest pipeline', async () => {
+    const { service, initialize, store, appended } = createService({
+      eventsBySession: {
+        'session-1': [
+          event({ id: '11111111-1111-4111-8111-111111111111', eventType: 'user_prompt', content: '첫 번째 작업 요청\n자세한 설명', timestamp: new Date('2026-04-30T01:00:00.000Z') }),
+          event({ id: '22222222-2222-4222-8222-222222222222', eventType: 'agent_response', content: '응답', timestamp: new Date('2026-04-30T01:01:00.000Z') }),
+          event({ id: '33333333-3333-4333-8333-333333333333', eventType: 'tool_observation', content: '{}', timestamp: new Date('2026-04-30T01:02:00.000Z'), metadata: { toolName: 'terminal', exitCode: 1 } }),
+          event({ id: '44444444-4444-4444-8444-444444444444', eventType: 'tool_observation', content: '{}', timestamp: new Date('2026-04-30T01:03:00.000Z'), metadata: { toolName: 'terminal', exitCode: 0 } }),
+          event({ id: '55555555-5555-4555-8555-555555555555', eventType: 'user_prompt', content: '두 번째 요청', timestamp: new Date('2026-04-30T01:04:00.000Z') })
+        ]
+      }
+    });
+
+    await service.generateSessionSummary('session-1');
+
+    expect(initialize).toHaveBeenCalledOnce();
+    expect(store.getSessionEvents).toHaveBeenCalledWith('session-1');
+    expect(appended).toHaveLength(1);
+    expect(store.enqueueForEmbedding).toHaveBeenCalledWith(
+      'event-1',
+      '[2026-04-30] 2턴 세션. 주요 작업: 첫 번째 작업 요청 자세한 설명. 사용 툴: terminal. 오류 1건 발생'
+    );
+    expect(appended[0]).toMatchObject({
+      eventType: 'session_summary',
+      sessionId: 'session-1',
+      content: '[2026-04-30] 2턴 세션. 주요 작업: 첫 번째 작업 요청 자세한 설명. 사용 툴: terminal. 오류 1건 발생',
+      metadata: {
+        ingest: { operation: 'session_summary', pipeline: 'default' },
+        generated: 'rule-based',
+        eventCount: 5
+      }
+    });
+  });
+
+  it('does not create another summary for too-short or already summarized sessions', async () => {
+    const { service, appended } = createService({
+      eventsBySession: {
+        short: [
+          event({ id: '11111111-1111-4111-8111-111111111111', sessionId: 'short' }),
+          event({ id: '22222222-2222-4222-8222-222222222222', sessionId: 'short', eventType: 'agent_response' })
+        ],
+        summarized: [
+          event({ id: '33333333-3333-4333-8333-333333333333', sessionId: 'summarized' }),
+          event({ id: '44444444-4444-4444-8444-444444444444', sessionId: 'summarized', eventType: 'agent_response' }),
+          event({ id: '55555555-5555-4555-8555-555555555555', sessionId: 'summarized', eventType: 'session_summary', content: 'already summarized' })
+        ]
+      }
+    });
+
+    await service.generateSessionSummary('short');
+    await service.generateSessionSummary('summarized');
+
+    expect(appended).toEqual([]);
+  });
+
+  it('backfills only missing summary candidates and keeps failures non-critical', async () => {
+    const { service, store, appended } = createService({
+      eventsBySession: {
+        candidate: [
+          event({ id: '11111111-1111-4111-8111-111111111111', sessionId: 'candidate', eventType: 'user_prompt', content: '분석 작업' }),
+          event({ id: '22222222-2222-4222-8222-222222222222', sessionId: 'candidate', eventType: 'agent_response', content: '응답' }),
+          event({ id: '33333333-3333-4333-8333-333333333333', sessionId: 'candidate', eventType: 'tool_observation', content: '{}', metadata: { toolName: 'read_file' } })
+        ],
+        tooShort: [
+          event({ id: '44444444-4444-4444-8444-444444444444', sessionId: 'tooShort', eventType: 'user_prompt' })
+        ],
+        broken: [
+          event({ id: '55555555-5555-4555-8555-555555555555', sessionId: 'broken', eventType: 'user_prompt' }),
+          event({ id: '66666666-6666-4666-8666-666666666666', sessionId: 'broken', eventType: 'agent_response' }),
+          event({ id: '77777777-7777-4777-8777-777777777777', sessionId: 'broken', eventType: 'tool_observation' })
+        ]
+      }
+    });
+    store.getSessionsWithoutSummary.mockResolvedValueOnce(['candidate', 'tooShort', 'broken']);
+    store.getSessionEvents.mockImplementation(async (sessionId: string) => {
+      if (sessionId === 'broken') throw new Error('corrupt session');
+      return (store as any).__eventsBySession?.[sessionId] ?? [];
+    });
+    (store as any).__eventsBySession = {
+      candidate: [
+        event({ id: '11111111-1111-4111-8111-111111111111', sessionId: 'candidate', eventType: 'user_prompt', content: '분석 작업' }),
+        event({ id: '22222222-2222-4222-8222-222222222222', sessionId: 'candidate', eventType: 'agent_response', content: '응답' }),
+        event({ id: '33333333-3333-4333-8333-333333333333', sessionId: 'candidate', eventType: 'tool_observation', content: '{}', metadata: { toolName: 'read_file' } })
+      ],
+      tooShort: [
+        event({ id: '44444444-4444-4444-8444-444444444444', sessionId: 'tooShort', eventType: 'user_prompt' })
+      ]
+    };
+
+    await expect(service.backfillMissingSummaries('current-session', 7)).resolves.toBeUndefined();
+
+    expect(store.getSessionsWithoutSummary).toHaveBeenCalledWith('current-session', 7);
+    expect(store.getSessionEvents).toHaveBeenCalledWith('candidate');
+    expect(store.getSessionEvents).toHaveBeenCalledWith('tooShort');
+    expect(store.getSessionEvents).toHaveBeenCalledWith('broken');
+    expect(appended).toHaveLength(1);
+    expect(appended[0].sessionId).toBe('candidate');
+  });
+});

package/tests/core/memory-query-service.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { MemoryQueryService } from '../../src/core/engine/memory-query-service.js';
+import type { MemoryEvent } from '../../src/core/types.js';
+
+function event(overrides: Partial<MemoryEvent> = {}): MemoryEvent {
+  return {
+    id: '11111111-1111-4111-8111-111111111111',
+    eventType: 'user_prompt',
+    sessionId: 'session-1',
+    timestamp: new Date('2026-05-02T00:00:00.000Z'),
+    content: 'default content',
+    canonicalKey: 'default-content',
+    dedupeKey: 'session-1:default-content',
+    metadata: {},
+    ...overrides
+  };
+}
+
+function createService() {
+  const initialize = vi.fn(async () => {});
+  const events = [event()];
+  const turn = {
+    turnId: 'turn-1',
+    events,
+    startedAt: new Date('2026-05-02T00:00:00.000Z'),
+    promptPreview: 'default content',
+    eventCount: 1,
+    toolCount: 0,
+    hasResponse: false
+  };
+  const outboxStats = {
+    embedding: { pending: 1, processing: 2, failed: 3, total: 6 },
+    vector: { pending: 4, processing: 5, failed: 6, total: 15 }
+  };
+  const queryStore = {
+    keywordSearch: vi.fn(async () => [{ event: events[0], rank: -0.5 }]),
+    getSessionEvents: vi.fn(async () => events),
+    getRecentEvents: vi.fn(async () => events),
+    rebuildFtsIndex: vi.fn(async () => 7),
+    getOutboxStats: vi.fn(async () => outboxStats),
+    getEventsByLevel: vi.fn(async () => events),
+    getEventLevel: vi.fn(async () => 'working'),
+    getSessionTurns: vi.fn(async () => [turn]),
+    getEventsByTurn: vi.fn(async () => events),
+    countSessionTurns: vi.fn(async () => 11),
+    backfillTurnIds: vi.fn(async () => 13),
+    deleteSessionEvents: vi.fn(async () => 17)
+  };
+  const vectorStore = {
+    count: vi.fn(async () => 19)
+  };
+  const graduation = {
+    getStats: vi.fn(async () => [{ level: 'working', count: 23 }])
+  };
+
+  return {
+    service: new MemoryQueryService(initialize, queryStore, { vectorStore, graduation }),
+    initialize,
+    queryStore,
+    vectorStore,
+    graduation,
+    events,
+    turn,
+    outboxStats
+  };
+}
+
+describe('MemoryQueryService', () => {
+  it('delegates read and maintenance methods through the initialized store boundary', async () => {
+    const { service, initialize, queryStore, events, turn, outboxStats } = createService();
+
+    await expect(service.rebuildFtsIndex()).resolves.toBe(7);
+    await expect(service.getOutboxStats()).resolves.toEqual(outboxStats);
+    await expect(service.getEventsByLevel('working', { limit: 2, offset: 3 })).resolves.toEqual(events);
+    await expect(service.getEventLevel('event-1')).resolves.toBe('working');
+    await expect(service.getSessionTurns('session-1', { limit: 5, offset: 8 })).resolves.toEqual([turn]);
+    await expect(service.getEventsByTurn('turn-1')).resolves.toEqual(events);
+    await expect(service.countSessionTurns('session-1')).resolves.toBe(11);
+    await expect(service.backfillTurnIds()).resolves.toBe(13);
+    await expect(service.deleteSessionEvents('session-1')).resolves.toBe(17);
+
+    expect(initialize).toHaveBeenCalledTimes(9);
+    expect(queryStore.rebuildFtsIndex).toHaveBeenCalledOnce();
+    expect(queryStore.getOutboxStats).toHaveBeenCalledOnce();
+    expect(queryStore.getEventsByLevel).toHaveBeenCalledWith('working', { limit: 2, offset: 3 });
+    expect(queryStore.getEventLevel).toHaveBeenCalledWith('event-1');
+    expect(queryStore.getSessionTurns).toHaveBeenCalledWith('session-1', { limit: 5, offset: 8 });
+    expect(queryStore.getEventsByTurn).toHaveBeenCalledWith('turn-1');
+    expect(queryStore.countSessionTurns).toHaveBeenCalledWith('session-1');
+    expect(queryStore.backfillTurnIds).toHaveBeenCalledOnce();
+    expect(queryStore.deleteSessionEvents).toHaveBeenCalledWith('session-1');
+  });
+
+  it('composes memory statistics from event, vector, and graduation stores', async () => {
+    const { service, initialize, queryStore, vectorStore, graduation } = createService();
+
+    await expect(service.getStats()).resolves.toEqual({
+      totalEvents: 1,
+      vectorCount: 19,
+      levelStats: [{ level: 'working', count: 23 }]
+    });
+
+    expect(initialize).toHaveBeenCalledOnce();
+    expect(queryStore.getRecentEvents).toHaveBeenCalledWith(10000);
+    expect(vectorStore.count).toHaveBeenCalledOnce();
+    expect(graduation.getStats).toHaveBeenCalledOnce();
+  });
+
+  it('keeps lightweight read methods usable with only the narrow query store', async () => {
+    const initialize = vi.fn(async () => {});
+    const events = [event({ id: '22222222-2222-4222-8222-222222222222' })];
+    const queryStore = {
+      keywordSearch: vi.fn(async () => [{ event: events[0], rank: -0.5 }]),
+      getSessionEvents: vi.fn(async () => events),
+      getRecentEvents: vi.fn(async () => events)
+    };
+    const service = new MemoryQueryService(initialize, queryStore);
+
+    await expect(service.keywordSearch('query', { topK: 3 })).resolves.toEqual([{ event: events[0], score: 1 }]);
+    await expect(service.getSessionHistory('session-1')).resolves.toBe(events);
+    await expect(service.getRecentEvents(2)).resolves.toBe(events);
+
+    expect(initialize).toHaveBeenCalledTimes(3);
+    expect(queryStore.keywordSearch).toHaveBeenCalledWith('query', 3);
+    expect(queryStore.getSessionEvents).toHaveBeenCalledWith('session-1');
+    expect(queryStore.getRecentEvents).toHaveBeenCalledWith(2);
+  });
+});