claude-memory-layer 1.0.11 → 1.0.12

package/tests/bootstrap-organizer.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+import { bootstrapKnowledgeBase } from '../src/services/bootstrap-organizer.js';
+
+async function makeTempRepo(): Promise<string> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'cml-bootstrap-'));
+  execSync('git init', { cwd: root, stdio: 'ignore' });
+  execSync('git config user.email test@example.com', { cwd: root, stdio: 'ignore' });
+  execSync('git config user.name test-bot', { cwd: root, stdio: 'ignore' });
+
+  await fs.mkdir(path.join(root, 'src'), { recursive: true });
+  await fs.mkdir(path.join(root, 'tests'), { recursive: true });
+
+  await fs.writeFile(path.join(root, 'src', 'index.ts'), 'export const hello = () => "world";\n', 'utf8');
+  await fs.writeFile(path.join(root, 'src', 'worker.ts'), 'export const runWorker = () => true;\n', 'utf8');
+  await fs.writeFile(path.join(root, 'tests', 'index.test.ts'), 'describe("x", () => {});\n', 'utf8');
+
+  execSync('git add .', { cwd: root, stdio: 'ignore' });
+  execSync('git commit -m "feat: initial project scaffolding"', { cwd: root, stdio: 'ignore' });
+
+  await fs.writeFile(path.join(root, 'src', 'worker.ts'), 'export const runWorker = () => "ok";\n', 'utf8');
+  execSync('git add src/worker.ts', { cwd: root, stdio: 'ignore' });
+  execSync('git commit -m "refactor: stabilize worker return type"', { cwd: root, stdio: 'ignore' });
+
+  return root;
+}
+
+describe('bootstrapKnowledgeBase', () => {
+  it('generates structured bootstrap outputs with metadata', async () => {
+    const repo = await makeTempRepo();
+    const outDir = path.join(repo, '.generated-kb');
+
+    const result = await bootstrapKnowledgeBase({
+      repoPath: repo,
+      outDir,
+      since: '365 days ago',
+      maxCommits: 50
+    });
+
+    expect(result.fileCount).toBeGreaterThan(0);
+    expect(result.commitCount).toBeGreaterThan(0);
+
+    const expected = [
+      path.join(outDir, 'overview', 'overview.md'),
+      path.join(outDir, 'modules', 'src.md'),
+      path.join(outDir, 'decisions', 'decisions.md'),
+      path.join(outDir, 'timeline', 'timeline.md'),
+      path.join(outDir, 'glossary', 'glossary.md'),
+      path.join(outDir, 'sources', 'manifest.md'),
+      path.join(outDir, 'sources', 'manifest.json')
+    ];
+
+    for (const file of expected) {
+      const stat = await fs.stat(file);
+      expect(stat.isFile()).toBe(true);
+    }
+
+    const overview = await fs.readFile(path.join(outDir, 'overview', 'overview.md'), 'utf8');
+    expect(overview).toContain('deterministicPipeline: true');
+    expect(overview).toContain('- confidence:');
+    expect(overview).toContain('- source:');
+
+    const decisions = await fs.readFile(path.join(outDir, 'decisions', 'decisions.md'), 'utf8');
+    expect(decisions).toContain('commit:');
+
+    const manifestJson = JSON.parse(await fs.readFile(path.join(outDir, 'sources', 'manifest.json'), 'utf8')) as {
+      deterministicPipeline: boolean;
+      outputs: string[];
+    };
+    expect(manifestJson.deterministicPipeline).toBe(true);
+    expect(manifestJson.outputs.length).toBeGreaterThan(0);
+  });
+
+  it('supports incremental bootstrap mode with manifest baseline', async () => {
+    const repo = await makeTempRepo();
+    const outDir = path.join(repo, '.generated-kb');
+
+    await bootstrapKnowledgeBase({
+      repoPath: repo,
+      outDir,
+      since: '365 days ago',
+      maxCommits: 50,
+      incremental: false
+    });
+
+    await fs.writeFile(path.join(repo, 'src', 'index.ts'), 'export const hello = () => "world2";\n', 'utf8');
+    execSync('git add src/index.ts', { cwd: repo, stdio: 'ignore' });
+    execSync('git commit -m "feat: change index output"', { cwd: repo, stdio: 'ignore' });
+
+    const result = await bootstrapKnowledgeBase({
+      repoPath: repo,
+      outDir,
+      maxCommits: 50,
+      incremental: true
+    });
+
+    expect(result.commitCount).toBeGreaterThan(0);
+
+    const manifestJson = JSON.parse(await fs.readFile(path.join(outDir, 'sources', 'manifest.json'), 'utf8')) as {
+      mode: string;
+      options?: { incremental?: boolean };
+      stats?: { modulesGenerated?: number };
+    };
+    expect(manifestJson.mode).toBe('incremental');
+    expect(manifestJson.options?.incremental).toBe(true);
+    expect((manifestJson.stats?.modulesGenerated ?? 0)).toBeGreaterThan(0);
+  });
+});

package/tests/consolidation-worker.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+
+import { ConsolidationWorker } from '../src/core/consolidation-worker.js';
+import type { EndlessModeConfig, MemoryEvent } from '../src/core/types.js';
+
+function makeEvent(id: string, content: string, hoursAgo = 20): MemoryEvent {
+  return {
+    id,
+    eventType: 'user_prompt',
+    sessionId: 's1',
+    timestamp: new Date(Date.now() - hoursAgo * 60 * 60 * 1000),
+    content,
+    canonicalKey: id,
+    dedupeKey: id,
+    metadata: {},
+  };
+}
+
+describe('ConsolidationWorker hierarchy automation', () => {
+  it('creates consolidated memories, promotes rules, and returns cost-quality report', async () => {
+    const events = [
+      makeEvent('e1', 'implement auth bug fix and add tests for token refresh'),
+      makeEvent('e2', 'fix auth error in middleware and update tests'),
+      makeEvent('e3', 'auth feature update with regression test and bug notes'),
+      makeEvent('e4', 'implement retry logic for auth and fix issue with token cache'),
+      makeEvent('e5', 'add integration test for auth flow and bug reproduction'),
+    ];
+
+    const created: Array<{ memoryId: string; summary: string; topics: string[]; sourceEvents: string[]; confidence: number }> = [];
+    const rules: Array<{ rule: string; sourceMemoryIds: string[] }> = [];
+
+    const workingSetStore = {
+      async get() {
+        return { recentEvents: events, lastActivity: new Date(), continuityScore: 0.8 };
+      },
+      async prune(_ids: string[]) {
+        return;
+      }
+    };
+
+    const consolidatedStore = {
+      async isAlreadyConsolidated() { return false; },
+      async create(input: any) {
+        const memoryId = `m-${created.length + 1}`;
+        created.push({ memoryId, ...input });
+        return memoryId;
+      },
+      async get(memoryId: string) {
+        return created.find((m) => m.memoryId === memoryId) || null;
+      },
+      async hasRuleForSourceMemory() { return false; },
+      async createRule(input: any) {
+        rules.push({ rule: input.rule, sourceMemoryIds: input.sourceMemoryIds });
+        return `r-${rules.length}`;
+      }
+    };
+
+    const config: EndlessModeConfig = {
+      enabled: true,
+      workingSet: { maxEvents: 100, timeWindowHours: 24, minRelevanceScore: 0.5 },
+      consolidation: { triggerIntervalMs: 3600000, triggerEventCount: 3, triggerIdleMs: 1000, useLLMSummarization: false },
+      continuity: { minScoreForSeamless: 0.7, topicDecayHours: 48 }
+    };
+
+    const worker = new ConsolidationWorker(workingSetStore as any, consolidatedStore as any, config);
+    const out = await worker.forceRunWithReport();
+
+    expect(out.consolidatedCount).toBeGreaterThan(0);
+    expect(out.promotedRuleCount).toBeGreaterThan(0);
+    expect(out.report.beforeTokenEstimate).toBeGreaterThan(0);
+    expect(out.report.reductionRatio).toBeGreaterThanOrEqual(0);
+    expect(out.report.qualityGuardPassed).toBe(true);
+    expect(rules[0]?.sourceMemoryIds?.length).toBeGreaterThan(0);
+  });
+});

package/tests/ingest-interceptor.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+import { IngestInterceptorRegistry, mergeHierarchicalMetadata } from '../src/core/ingest-interceptor.js';
+
+describe('IngestInterceptorRegistry', () => {
+  it('runs before/after interceptors in staged order', async () => {
+    const registry = new IngestInterceptorRegistry();
+    const stages: string[] = [];
+
+    registry.registerBefore((ctx) => stages.push(`before:${ctx.operation}`));
+    registry.registerAfter((ctx) => stages.push(`after:${ctx.operation}`));
+
+    const event = {
+      eventType: 'user_prompt' as const,
+      sessionId: 's1',
+      timestamp: new Date(),
+      content: 'hello'
+    };
+
+    await registry.run('before', { operation: 'user_prompt', sessionId: 's1', event });
+    await registry.run('after', { operation: 'user_prompt', sessionId: 's1', event });
+
+    expect(stages).toEqual(['before:user_prompt', 'after:user_prompt']);
+  });
+});
+
+describe('mergeHierarchicalMetadata', () => {
+  it('deep merges nested metadata without clobbering siblings', () => {
+    const merged = mergeHierarchicalMetadata(
+      { scope: { project: { id: 'alpha', env: 'dev' } }, ingest: { source: 'hook' } },
+      { scope: { project: { env: 'prod' }, turn: { id: 't1' } } }
+    );
+
+    expect(merged).toEqual({
+      scope: { project: { id: 'alpha', env: 'prod' }, turn: { id: 't1' } },
+      ingest: { source: 'hook' }
+    });
+  });
+});

package/tests/markdown-mirror.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { randomUUID } from 'crypto';
+import { buildMirrorPath, MarkdownMirror } from '../src/core/markdown-mirror.js';
+import { SQLiteEventStore } from '../src/core/sqlite-event-store.js';
+
+describe('markdown mirror', () => {
+  it('builds sanitized path with defaults', () => {
+    const event = {
+      id: randomUUID(),
+      eventType: 'user_prompt' as const,
+      sessionId: 's1',
+      timestamp: new Date('2026-02-24T00:49:00.000Z'),
+      content: 'hello',
+      canonicalKey: 'k',
+      dedupeKey: 'd',
+      metadata: {
+        namespace: 'Team ../Prod',
+        categoryPath: ['Ops & Alerts', 'Night Shift']
+      }
+    };
+
+    const out = buildMirrorPath('/tmp/root', event);
+    expect(out).toContain(path.join('memory', 'team-prod', 'ops-alerts', 'night-shift', '2026-02-24.md'));
+  });
+
+  it('appends without overwriting existing content', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'cml-md-mirror-'));
+    try {
+      const file = path.join(root, 'memory', 'default', 'session_summary', '2026-02-24.md');
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, 'PREEXISTING\n', 'utf8');
+
+      const mirror = new MarkdownMirror(root);
+      await mirror.append({
+        id: randomUUID(),
+        eventType: 'session_summary',
+        sessionId: 's2',
+        timestamp: new Date('2026-02-24T11:00:00.000Z'),
+        content: 'summary line',
+        canonicalKey: 'k2',
+        dedupeKey: 'd2',
+        metadata: {}
+      });
+
+      const content = await fs.readFile(file, 'utf8');
+      expect(content.startsWith('PREEXISTING\n')).toBe(true);
+      expect(content).toContain('summary line');
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('is wired to sqlite append flow', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'cml-md-flow-'));
+    try {
+      const store = new SQLiteEventStore(path.join(root, 'events.sqlite'), {
+        markdownMirrorRoot: root
+      });
+      const ts = new Date('2026-02-24T12:00:00.000Z');
+      const result = await store.append({
+        eventType: 'agent_response',
+        sessionId: 'sess-flow',
+        timestamp: ts,
+        content: 'flow content',
+        metadata: { namespace: 'app', category: 'responses' }
+      });
+
+      expect(result.success).toBe(true);
+
+      // mirror append is async fire-and-forget; allow small delay
+      await new Promise((r) => setTimeout(r, 50));
+
+      const file = path.join(root, 'memory', 'app', 'responses', '2026-02-24.md');
+      const content = await fs.readFile(file, 'utf8');
+      expect(content).toContain('flow content');
+
+      await store.close();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/tests/md-mirror.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { buildMirrorPath, MarkdownMirror } from '../src/core/md-mirror.js';
+import type { MemoryEventInput } from '../src/core/types.js';
+
+function makeEvent(): MemoryEventInput {
+  return {
+    eventType: 'user_prompt',
+    sessionId: 'agent:main:test',
+    timestamp: new Date('2026-02-24T01:00:00.000Z'),
+    content: '아침 브리핑 포맷 기억해줘',
+    metadata: {
+      namespace: 'Briefing',
+      categoryPath: ['Preferences', 'Morning']
+    }
+  };
+}
+
+describe('MarkdownMirror', () => {
+  it('builds sanitized categorized path', () => {
+    const p = buildMirrorPath('/tmp/demo', makeEvent());
+    expect(p).toContain(path.join('memory', 'briefing', 'preferences', 'morning', '2026-02-24.md'));
+  });
+
+  it('uses uncategorized when category is missing', () => {
+    const ev = { ...makeEvent(), metadata: { namespace: 'Briefing' } };
+    const p = buildMirrorPath('/tmp/demo', ev);
+    expect(p).toContain(path.join('memory', 'briefing', 'uncategorized', '2026-02-24.md'));
+  });
+
+  it('appends without overwrite', async () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cl-md-mirror-'));
+    const mirror = new MarkdownMirror(tmp);
+    const ev = makeEvent();
+
+    await mirror.append(ev, 'e1');
+    await mirror.append({ ...ev, content: '두번째 기록' }, 'e2');
+
+    const out = buildMirrorPath(tmp, ev);
+    const text = fs.readFileSync(out, 'utf8');
+    expect(text).toContain('e1');
+    expect(text).toContain('e2');
+    expect(text).toContain('두번째 기록');
+
+    const index = fs.readFileSync(path.join(tmp, 'memory', '_index.md'), 'utf8');
+    expect(index).toContain('memory/briefing/preferences/morning/2026-02-24.md');
+  });
+});

package/tests/retriever-fallback-chain.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect } from 'vitest';
+import { Retriever } from '../src/core/retriever.js';
+import { Matcher } from '../src/core/matcher.js';
+import type { MemoryEvent } from '../src/core/types.js';
+
+function ev(id: string, content: string): MemoryEvent {
+  return {
+    id,
+    eventType: 'user_prompt',
+    sessionId: 's1',
+    timestamp: new Date('2026-02-24T00:00:00.000Z'),
+    content,
+    canonicalKey: id,
+    dedupeKey: id,
+    metadata: {}
+  };
+}
+
+describe('Retriever fallback chain', () => {
+  it('falls back from fast to deep when fast has no result', async () => {
+    const e = ev('e1', 'deep result memory');
+    let vectorCalls = 0;
+
+    const fakeEventStore = {
+      async keywordSearch() {
+        return [];
+      },
+      async getRecentEvents() {
+        return [e];
+      },
+      async getEvent(id: string) {
+        return id === 'e1' ? e : null;
+      },
+      async getSessionEvents() {
+        return [e];
+      }
+    };
+
+    const fakeVectorStore = {
+      async search() {
+        vectorCalls += 1;
+        return [{ id: 'v1', eventId: 'e1', content: e.content, score: 0.9, sessionId: 's1', eventType: e.eventType, timestamp: e.timestamp.toISOString() }];
+      }
+    };
+
+    const fakeEmbedder = { async embed() { return { vector: [0.1, 0.2] }; } };
+
+    const retriever = new Retriever(fakeEventStore as any, fakeVectorStore as any, fakeEmbedder as any, new Matcher());
+    const out = await retriever.retrieve('result', { strategy: 'auto', topK: 3, includeSessionContext: false });
+
+    expect(out.memories.length).toBeGreaterThan(0);
+    expect(vectorCalls).toBeGreaterThan(0);
+    expect(out.fallbackTrace).toContain('fallback:deep');
+  });
+
+  it('applies custom rerank weights when provided', async () => {
+    const e1 = ev('a', 'keyword hit exact');
+    const e2 = ev('b', 'less related');
+
+    const fakeEventStore = {
+      async keywordSearch() { return []; },
+      async getRecentEvents() { return [e1, e2]; },
+      async getEvent(id: string) { return id === 'a' ? e1 : id === 'b' ? e2 : null; },
+      async getSessionEvents() { return [e1, e2]; }
+    };
+
+    const fakeVectorStore = {
+      async search() {
+        return [
+          { id: 'v1', eventId: 'b', content: e2.content, score: 0.95, sessionId: 's1', eventType: e2.eventType, timestamp: e2.timestamp.toISOString() },
+          { id: 'v2', eventId: 'a', content: e1.content, score: 0.7, sessionId: 's1', eventType: e1.eventType, timestamp: e1.timestamp.toISOString() },
+        ];
+      }
+    };
+
+    const fakeEmbedder = { async embed() { return { vector: [0.1, 0.2] }; } };
+    const retriever = new Retriever(fakeEventStore as any, fakeVectorStore as any, fakeEmbedder as any, new Matcher());
+
+    const out = await retriever.retrieve('keyword hit', {
+      strategy: 'deep',
+      topK: 3,
+      includeSessionContext: false,
+      rerankWeights: { semantic: 0.2, lexical: 0.7, recency: 0.1 }
+    });
+
+    expect(out.memories[0]?.event.id).toBe('a');
+  });
+
+  it('applies TTL/decay penalty for stale low-overlap memories', async () => {
+    const old = {
+      ...ev('old', 'generic memory'),
+      timestamp: new Date(Date.now() - 1000 * 60 * 60 * 24 * 120),
+    };
+    const fresh = {
+      ...ev('fresh', 'generic memory'),
+      timestamp: new Date(),
+    };
+
+    const fakeEventStore = {
+      async keywordSearch() { return []; },
+      async getRecentEvents() { return [old, fresh]; },
+      async getEvent(id: string) { return id === 'old' ? old : id === 'fresh' ? fresh : null; },
+      async getSessionEvents() { return [old, fresh]; }
+    };
+
+    const fakeVectorStore = {
+      async search() {
+        return [
+          { id: 'v1', eventId: 'old', content: old.content, score: 0.9, sessionId: old.sessionId, eventType: old.eventType, timestamp: old.timestamp.toISOString() },
+          { id: 'v2', eventId: 'fresh', content: fresh.content, score: 0.85, sessionId: fresh.sessionId, eventType: fresh.eventType, timestamp: fresh.timestamp.toISOString() },
+        ];
+      }
+    };
+
+    const fakeEmbedder = { async embed() { return { vector: [0.1, 0.2] }; } };
+    const retriever = new Retriever(fakeEventStore as any, fakeVectorStore as any, fakeEmbedder as any, new Matcher());
+
+    const out = await retriever.retrieve('different query', {
+      strategy: 'deep',
+      topK: 2,
+      includeSessionContext: false,
+      decayPolicy: { enabled: true, windowDays: 30, maxPenalty: 0.3 }
+    });
+
+    expect(out.memories[0]?.event.id).toBe('fresh');
+  });
+
+  it('merges rewritten deep query results when intentRewrite is enabled', async () => {
+    const a = ev('a', '원문 질의에서는 약한 결과');
+    const b = ev('b', '재작성 질의에서 강한 결과');
+
+    const fakeEventStore = {
+      async keywordSearch() { return []; },
+      async getRecentEvents() { return [a, b]; },
+      async getEvent(id: string) { return id === 'a' ? a : id === 'b' ? b : null; },
+      async getSessionEvents() { return [a, b]; }
+    };
+
+    let call = 0;
+    const fakeVectorStore = {
+      async search() {
+        call += 1;
+        if (call === 1) {
+          return [{ id: 'v1', eventId: 'a', content: a.content, score: 0.8, sessionId: 's1', eventType: a.eventType, timestamp: a.timestamp.toISOString() }];
+        }
+        return [{ id: 'v2', eventId: 'b', content: b.content, score: 0.95, sessionId: 's1', eventType: b.eventType, timestamp: b.timestamp.toISOString() }];
+      }
+    };
+
+    const fakeEmbedder = { async embed() { return { vector: [0.1, 0.2] }; } };
+    const retriever = new Retriever(fakeEventStore as any, fakeVectorStore as any, fakeEmbedder as any, new Matcher());
+    retriever.setQueryRewriter(async () => '확장된 재작성 질의');
+
+    const out = await retriever.retrieve('원문 질의', {
+      strategy: 'deep',
+      topK: 3,
+      includeSessionContext: false,
+      intentRewrite: true,
+    });
+
+    expect(out.memories[0]?.event.id).toBe('b');
+  });
+
+  it('expands related events with graph-hop retrieval', async () => {
+    const seed = ev('seed', 'seed event');
+    const neighbor = {
+      ...ev('neighbor', 'related artifact memory'),
+      metadata: { relatedEventIds: ['seed'] },
+    };
+    const seedWithEdge = { ...seed, metadata: { relatedEventIds: ['neighbor'] } };
+
+    const fakeEventStore = {
+      async keywordSearch() { return []; },
+      async getRecentEvents() { return [seedWithEdge, neighbor]; },
+      async getEvent(id: string) {
+        if (id === 'seed') return seedWithEdge;
+        if (id === 'neighbor') return neighbor;
+        return null;
+      },
+      async getSessionEvents() { return [seedWithEdge, neighbor]; }
+    };
+
+    const fakeVectorStore = {
+      async search() {
+        return [{ id: 'v1', eventId: 'seed', content: seedWithEdge.content, score: 0.95, sessionId: 's1', eventType: seedWithEdge.eventType, timestamp: seedWithEdge.timestamp.toISOString() }];
+      }
+    };
+
+    const fakeEmbedder = { async embed() { return { vector: [0.1, 0.2] }; } };
+    const retriever = new Retriever(fakeEventStore as any, fakeVectorStore as any, fakeEmbedder as any, new Matcher());
+
+    const out = await retriever.retrieve('seed event', {
+      strategy: 'deep',
+      topK: 5,
+      includeSessionContext: false,
+      graphHop: { enabled: true, maxHops: 1, hopPenalty: 0.1 }
+    });
+
+    const ids = out.memories.map((m) => m.event.id);
+    expect(ids).toContain('seed');
+    expect(ids).toContain('neighbor');
+  });
+
+  it('uses summary fallback when both fast and deep fail', async () => {
+    const e = ev('e2', 'keyword overlap fallback candidate');
+
+    const fakeEventStore = {
+      async keywordSearch() { return []; },
+      async getRecentEvents() { return [e]; },
+      async getEvent(id: string) { return id === 'e2' ? e : null; },
+      async getSessionEvents() { return [e]; }
+    };
+
+    const fakeVectorStore = { async search() { return []; } };
+    const fakeEmbedder = { async embed() { return { vector: [0.1, 0.2] }; } };
+
+    const retriever = new Retriever(fakeEventStore as any, fakeVectorStore as any, fakeEmbedder as any, new Matcher());
+    const out = await retriever.retrieve('fallback candidate', { strategy: 'auto', topK: 3, includeSessionContext: false });
+
+    expect(out.fallbackTrace).toContain('fallback:summary');
+    expect(out.memories[0]?.event.id).toBe('e2');
+  });
+});

package/tests/retriever-strategy-scope.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import { Retriever } from '../src/core/retriever.js';
+import { Matcher } from '../src/core/matcher.js';
+import type { MemoryEvent } from '../src/core/types.js';
+
+function ev(id: string, sessionId: string, eventType: MemoryEvent['eventType'], content: string, canonicalKey: string): MemoryEvent {
+  return {
+    id,
+    sessionId,
+    eventType,
+    content,
+    canonicalKey,
+    dedupeKey: `${sessionId}:${id}`,
+    timestamp: new Date('2026-02-24T00:00:00.000Z'),
+    metadata: {}
+  };
+}
+
+describe('Retriever strategy/scope', () => {
+  const e1 = ev('e1', 'agent:main:alpha', 'user_prompt', '아침 브리핑 선호', 'pref/briefing/morning');
+  const e2 = ev('e2', 'agent:main:beta', 'agent_response', '점심 이후 요약은 잘 안봄', 'pref/briefing/lunch');
+
+  const fakeEventStore = {
+    async keywordSearch() {
+      return [
+        { event: e1, rank: -0.1 },
+        { event: e2, rank: -0.2 }
+      ];
+    },
+    async getRecentEvents() {
+      return [e1, e2];
+    },
+    async getEvent(id: string) {
+      return id === 'e1' ? e1 : id === 'e2' ? e2 : null;
+    },
+    async getSessionEvents(sessionId: string) {
+      return [e1, e2].filter((x) => x.sessionId === sessionId);
+    }
+  };
+
+  const fakeVectorStore = {
+    async search() {
+      return [
+        {
+          id: 'v1',
+          eventId: 'e2',
+          content: e2.content,
+          score: 0.92,
+          sessionId: e2.sessionId,
+          eventType: e2.eventType,
+          timestamp: e2.timestamp.toISOString()
+        },
+        {
+          id: 'v2',
+          eventId: 'e1',
+          content: e1.content,
+          score: 0.8,
+          sessionId: e1.sessionId,
+          eventType: e1.eventType,
+          timestamp: e1.timestamp.toISOString()
+        }
+      ];
+    }
+  };
+
+  const fakeEmbedder = {
+    async embed() {
+      return { vector: [0.1, 0.2, 0.3] };
+    }
+  };
+
+  it('uses fast strategy keyword path', async () => {
+    const retriever = new Retriever(fakeEventStore as any, fakeVectorStore as any, fakeEmbedder as any, new Matcher());
+    const out = await retriever.retrieve('브리핑', { strategy: 'fast', topK: 2, includeSessionContext: false });
+
+    expect(out.memories.length).toBe(2);
+    expect(out.memories[0].event.id).toBe('e1');
+  });
+
+  it('applies scoped filters (session prefix + canonical prefix + includes)', async () => {
+    const retriever = new Retriever(fakeEventStore as any, fakeVectorStore as any, fakeEmbedder as any, new Matcher());
+
+    const out = await retriever.retrieve('브리핑', {
+      strategy: 'deep',
+      topK: 5,
+      includeSessionContext: false,
+      scope: {
+        sessionIdPrefix: 'agent:main:alpha',
+        canonicalKeyPrefix: 'pref/briefing/morning',
+        contentIncludes: ['아침']
+      }
+    });
+
+    expect(out.memories.length).toBe(1);
+    expect(out.memories[0].event.id).toBe('e1');
+  });
+});