claude-memory-layer 1.0.11 → 1.0.13

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');
+  });
+});

package/tests/retriever.memu-adoption.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest';
+import { Retriever } from '../src/core/retriever.js';
+import type { MemoryEvent, MatchResult } from '../src/core/types.js';
+import type { SearchResult } from '../src/core/vector-store.js';
+
+class FakeEventStore {
+  constructor(private readonly events: Record<string, MemoryEvent>) {}
+
+  async getEvent(id: string): Promise<MemoryEvent | null> {
+    return this.events[id] || null;
+  }
+
+  async getSessionEvents(sessionId: string): Promise<MemoryEvent[]> {
+    return Object.values(this.events).filter((e) => e.sessionId === sessionId);
+  }
+
+  async getRecentEvents(): Promise<MemoryEvent[]> {
+    return Object.values(this.events);
+  }
+
+  async keywordSearch(query: string): Promise<Array<{ event: MemoryEvent; rank: number }>> {
+    const lowered = query.toLowerCase();
+    const matches = Object.values(this.events)
+      .filter((event) => event.content.toLowerCase().includes(lowered))
+      .map((event, index) => ({ event, rank: -(index + 1) }));
+    return matches;
+  }
+}
+
+class FakeVectorStore {
+  constructor(private readonly results: SearchResult[]) {}
+
+  async search(): Promise<SearchResult[]> {
+    return this.results;
+  }
+}
+
+class FakeEmbedder {
+  async embed(): Promise<{ vector: number[] }> {
+    return { vector: [0.1, 0.2, 0.3] };
+  }
+}
+
+class FakeMatcher {
+  matchSearchResults(results: SearchResult[]): MatchResult {
+    if (results.length === 0) {
+      return { match: null, confidence: 'none' };
+    }
+
+    const top = results[0];
+    return {
+      match: {
+        event: {
+          id: top.eventId,
+          eventType: top.eventType as MemoryEvent['eventType'],
+          sessionId: top.sessionId,
+          timestamp: new Date(top.timestamp),
+          content: top.content,
+          canonicalKey: top.eventId,
+          dedupeKey: top.eventId,
+          metadata: {}
+        },
+        score: top.score
+      },
+      confidence: 'suggested'
+    };
+  }
+}
+
+function makeEvent(id: string, content: string, metadata?: Record<string, unknown>): MemoryEvent {
+  return {
+    id,
+    eventType: 'user_prompt',
+    sessionId: 's1',
+    timestamp: new Date('2026-01-01T00:00:00.000Z'),
+    content,
+    canonicalKey: id,
+    dedupeKey: id,
+    metadata
+  };
+}
+
+describe('Retriever memU-inspired enhancements', () => {
+  it('applies metadata scope filter with hierarchical key path', async () => {
+    const e1 = makeEvent('e1', 'first memory', { scope: { project: { id: 'alpha' } } });
+    const e2 = makeEvent('e2', 'second memory', { scope: { project: { id: 'beta' } } });
+
+    const retriever = new Retriever(
+      new FakeEventStore({ e1, e2 }) as any,
+      new FakeVectorStore([
+        { id: '1', eventId: 'e1', content: e1.content, score: 0.9, sessionId: 's1', eventType: e1.eventType, timestamp: e1.timestamp.toISOString() },
+        { id: '2', eventId: 'e2', content: e2.content, score: 0.89, sessionId: 's1', eventType: e2.eventType, timestamp: e2.timestamp.toISOString() }
+      ]) as any,
+      new FakeEmbedder() as any,
+      new FakeMatcher() as any
+    );
+
+    const result = await retriever.retrieve('memory', {
+      scope: { metadata: { 'scope.project.id': 'alpha' } }
+    });
+
+    expect(result.memories).toHaveLength(1);
+    expect(result.memories[0].event.id).toBe('e1');
+  });
+
+  it('uses fast strategy keyword retrieval when requested', async () => {
+    const e1 = makeEvent('e1', 'fix deployment issue with nginx');
+    const e2 = makeEvent('e2', 'random unrelated text');
+
+    const retriever = new Retriever(
+      new FakeEventStore({ e1, e2 }) as any,
+      new FakeVectorStore([]) as any,
+      new FakeEmbedder() as any,
+      new FakeMatcher() as any
+    );
+
+    const result = await retriever.retrieve('deployment', { strategy: 'fast', topK: 5 });
+
+    expect(result.memories.length).toBeGreaterThan(0);
+    expect(result.memories[0].event.id).toBe('e1');
+  });
+});

package/tests/sqlite-event-store-replication.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Tests for SQLiteEventStore replication helpers used by Mongo sync.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+import { SQLiteEventStore } from '../src/core/sqlite-event-store.js';
+
+describe('SQLiteEventStore replication helpers', () => {
+  let tempDir: string;
+  let storeA: SQLiteEventStore;
+  let storeB: SQLiteEventStore;
+
+  beforeEach(async () => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-memory-layer-test-'));
+    storeA = new SQLiteEventStore(path.join(tempDir, 'a.sqlite'));
+    storeB = new SQLiteEventStore(path.join(tempDir, 'b.sqlite'));
+    await storeA.initialize();
+    await storeB.initialize();
+  });
+
+  afterEach(() => {
+    try { storeA.close(); } catch {}
+    try { storeB.close(); } catch {}
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('getEventsSinceRowid returns incremental batches in insertion order', async () => {
+    const sessionId = 'session-1';
+
+    await storeA.append({ eventType: 'user_prompt', sessionId, timestamp: new Date(), content: 'a' });
+    await storeA.append({ eventType: 'user_prompt', sessionId, timestamp: new Date(), content: 'b' });
+    await storeA.append({ eventType: 'user_prompt', sessionId, timestamp: new Date(), content: 'c' });
+
+    const batch1 = await storeA.getEventsSinceRowid(0, 10);
+    expect(batch1).toHaveLength(3);
+    expect(batch1.map(x => x.event.content)).toEqual(['a', 'b', 'c']);
+
+    // rowid should be strictly increasing
+    expect(batch1[0].rowid).toBeLessThan(batch1[1].rowid);
+    expect(batch1[1].rowid).toBeLessThan(batch1[2].rowid);
+
+    const lastRowid = batch1[2].rowid;
+
+    await storeA.append({ eventType: 'user_prompt', sessionId, timestamp: new Date(), content: 'd' });
+
+    const batch2 = await storeA.getEventsSinceRowid(lastRowid, 10);
+    expect(batch2).toHaveLength(1);
+    expect(batch2[0].event.content).toBe('d');
+  });
+
+  it('importEvents preserves stable IDs and is idempotent via dedupeKey', async () => {
+    const sessionId = 'session-2';
+    const appendRes = await storeA.append({
+      eventType: 'user_prompt',
+      sessionId,
+      timestamp: new Date(),
+      content: 'hello world'
+    });
+
+    expect(appendRes.success).toBe(true);
+    const sourceEvent = await storeA.getEvent(appendRes.eventId!);
+    expect(sourceEvent).not.toBeNull();
+
+    const imported1 = await storeB.importEvents([sourceEvent!]);
+    expect(imported1.inserted).toBe(1);
+    expect(imported1.skipped).toBe(0);
+
+    const importedEvent = await storeB.getEvent(sourceEvent!.id);
+    expect(importedEvent?.content).toBe('hello world');
+
+    // Importing again should be a no-op
+    const imported2 = await storeB.importEvents([sourceEvent!]);
+    expect(imported2.inserted).toBe(0);
+    expect(imported2.skipped).toBe(1);
+
+    // append() should treat it as duplicate due to event_dedup entry
+    const dup = await storeB.append({
+      eventType: 'user_prompt',
+      sessionId,
+      timestamp: new Date(),
+      content: 'hello world'
+    });
+    expect(dup.success).toBe(true);
+    expect(dup.isDuplicate).toBe(true);
+    expect(dup.eventId).toBe(sourceEvent!.id);
+  });
+});
+