recallnest 2.3.0 → 2.6.0

package/src/__tests__/interference-detector.test.ts

@@ -0,0 +1,203 @@
+/**
+ * F2: Interference Detection + Active Forgetting Gate — tests for
+ * cluster detection, density measurement, RIF enhancement, and checkup.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  detectInterference,
+  measureInterferenceDensity,
+  type InterferenceResult,
+} from "../interference-detector.js";
+import { filterInterference } from "../rif.js";
+import type { MemoryEntry } from "../store.js";
+import type { RetrievalResult } from "../retriever.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Create a memory entry with a specific vector for clustering. */
+function makeMemory(id: string, vector: number[], importance = 0.7): MemoryEntry {
+  return {
+    id,
+    text: `memory ${id}`,
+    vector,
+    category: "events",
+    scope: "test",
+    importance,
+    timestamp: Date.now(),
+    metadata: JSON.stringify({ confidence: 0.7 }),
+  };
+}
+
+/** Create a unit vector in the given direction (for predictable cosine sim). */
+function unitVec(direction: number[], dims = 4): number[] {
+  const v = Array(dims).fill(0);
+  for (let i = 0; i < direction.length && i < dims; i++) v[i] = direction[i];
+  const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0));
+  return norm > 0 ? v.map(x => x / norm) : v;
+}
+
+function makeRetrievalResult(id: string, vector: number[], score: number): RetrievalResult {
+  return {
+    entry: makeMemory(id, vector),
+    score,
+    sources: {},
+  };
+}
+
+// ---------------------------------------------------------------------------
+// detectInterference
+// ---------------------------------------------------------------------------
+
+describe("F2: detectInterference", () => {
+  test("empty input returns empty array", () => {
+    expect(detectInterference([])).toEqual([]);
+  });
+
+  test("singleton memories have low risk", () => {
+    const m1 = makeMemory("a", unitVec([1, 0, 0, 0]));
+    const m2 = makeMemory("b", unitVec([0, 1, 0, 0])); // orthogonal — different cluster
+    const results = detectInterference([m1, m2]);
+    expect(results.length).toBe(2);
+    expect(results.every(r => r.interferenceRisk === "low")).toBe(true);
+  });
+
+  test("similar vectors form a cluster", () => {
+    const base = [1, 0.1, 0, 0];
+    const similar = [1, 0.15, 0, 0]; // very similar to base
+    const m1 = makeMemory("a", unitVec(base));
+    const m2 = makeMemory("b", unitVec(similar));
+    const m3 = makeMemory("c", unitVec([0, 0, 1, 0])); // different cluster
+    const results = detectInterference([m1, m2, m3]);
+    // m1 and m2 should be in same cluster, m3 alone
+    const clusterIds = new Set(results.map(r => r.clusterId));
+    expect(clusterIds.size).toBe(2); // 2 clusters
+  });
+
+  test("cluster rank 0 has low risk, rank 3+ has high risk", () => {
+    const v = unitVec([1, 0, 0, 0]);
+    const memories = [
+      makeMemory("a", v, 0.9),
+      makeMemory("b", v, 0.8),
+      makeMemory("c", v, 0.7),
+      makeMemory("d", v, 0.3), // weakest — should be high risk
+    ];
+    const results = detectInterference(memories);
+    // All in one cluster
+    const clusterIds = new Set(results.map(r => r.clusterId));
+    expect(clusterIds.size).toBe(1);
+    // Rank 0 is low risk
+    const topRanked = results.find(r => r.clusterRank === 0);
+    expect(topRanked?.interferenceRisk).toBe("low");
+    // Rank 3 is high risk
+    const bottomRanked = results.find(r => r.clusterRank === 3);
+    expect(bottomRanked?.interferenceRisk).toBe("high");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// measureInterferenceDensity
+// ---------------------------------------------------------------------------
+
+describe("F2: measureInterferenceDensity", () => {
+  test("no clusters → zero density", () => {
+    const memories = [
+      makeMemory("a", unitVec([1, 0, 0, 0])),
+      makeMemory("b", unitVec([0, 1, 0, 0])),
+      makeMemory("c", unitVec([0, 0, 1, 0])),
+    ];
+    const density = measureInterferenceDensity(memories);
+    expect(density.clusterCount).toBe(0);
+    expect(density.highRiskCount).toBe(0);
+    expect(density.avgClusterSize).toBe(0);
+  });
+
+  test("one cluster → density reflects cluster size", () => {
+    const v = unitVec([1, 0, 0, 0]);
+    const memories = [
+      makeMemory("a", v, 0.9),
+      makeMemory("b", v, 0.7),
+      makeMemory("c", v, 0.5),
+      makeMemory("d", v, 0.3),
+    ];
+    const density = measureInterferenceDensity(memories);
+    expect(density.clusterCount).toBe(1);
+    expect(density.avgClusterSize).toBe(4);
+    expect(density.highRiskCount).toBe(1); // rank 3 = high
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Enhanced RIF (cluster top-K)
+// ---------------------------------------------------------------------------
+
+describe("F2: Enhanced RIF with cluster top-K", () => {
+  test("cluster within top-K not demoted", () => {
+    const v = unitVec([1, 0, 0, 0]);
+    const results = [
+      makeRetrievalResult("a", v, 0.9),
+      makeRetrievalResult("b", v, 0.85),
+      makeRetrievalResult("c", v, 0.80),
+    ];
+    const filtered = filterInterference(results, 0.85, 0.80, 3);
+    // All 3 should be kept (within top-K=3)
+    expect(filtered.length).toBe(3);
+    expect(filtered[0].entry.id).toBe("a");
+  });
+
+  test("4th cluster member gets 50% score demotion", () => {
+    const v = unitVec([1, 0, 0, 0]);
+    const results = [
+      makeRetrievalResult("a", v, 0.9),
+      makeRetrievalResult("b", v, 0.85),
+      makeRetrievalResult("c", v, 0.80),
+      makeRetrievalResult("d", v, 0.75), // 4th member
+    ];
+    const filtered = filterInterference(results, 0.85, 0.80, 3);
+    // d should be at the end with 50% score
+    const d = filtered.find(r => r.entry.id === "d");
+    expect(d).toBeDefined();
+    expect(d!.score).toBeCloseTo(0.375, 2); // 0.75 * 0.5
+  });
+
+  test("diverse results unaffected by cluster top-K", () => {
+    const results = [
+      makeRetrievalResult("a", unitVec([1, 0, 0, 0]), 0.9),
+      makeRetrievalResult("b", unitVec([0, 1, 0, 0]), 0.85),
+      makeRetrievalResult("c", unitVec([0, 0, 1, 0]), 0.80),
+      makeRetrievalResult("d", unitVec([0, 0, 0, 1]), 0.75),
+    ];
+    const filtered = filterInterference(results, 0.85, 0.80, 3);
+    // All diverse — no demotion
+    expect(filtered.length).toBe(4);
+    expect(filtered.map(r => r.entry.id)).toEqual(["a", "b", "c", "d"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// data-checkup integration
+// ---------------------------------------------------------------------------
+
+describe("F2: data-checkup interference check", () => {
+  // We test the check function indirectly through measureInterferenceDensity
+  test("healthy density has low high-risk ratio", () => {
+    const memories = [
+      makeMemory("a", unitVec([1, 0, 0, 0])),
+      makeMemory("b", unitVec([0, 1, 0, 0])),
+      makeMemory("c", unitVec([0, 0, 1, 0])),
+    ];
+    const density = measureInterferenceDensity(memories);
+    // high-risk should be < 20% of total
+    expect(density.highRiskCount / density.totalMemories).toBeLessThan(0.2);
+  });
+
+  test("unhealthy density detected in identical vectors", () => {
+    const v = unitVec([1, 0, 0, 0]);
+    const memories = Array.from({ length: 10 }, (_, i) => makeMemory(`m${i}`, v, 0.5 - i * 0.01));
+    const density = measureInterferenceDensity(memories);
+    expect(density.clusterCount).toBe(1);
+    expect(density.highRiskCount).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/kg-extractor.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from "bun:test";
+import { normalizeEntity, normalizePredicate, KGExtractor, isKGModeEnabled } from "../kg-extractor.js";
+
+function createMockLlm(response: unknown) {
+  return {
+    lastSystem: null as string | null,
+    lastUser: null as string | null,
+    async chatJson(_system: string, _user: string) {
+      this.lastSystem = _system;
+      this.lastUser = _user;
+      return response;
+    },
+    // Stub remaining LLMClient methods
+    async generateL0() { return null; },
+    async generateL1() { return null; },
+    async smartExtract() { return null; },
+    async smartExtractBatch() { return []; },
+    async dedupDecision() { return null; },
+    async dedupBatch() { return []; },
+    async mergeTexts() { return null; },
+    async preferenceMatch() { return null; },
+    async ping() { return false; },
+  } as any;
+}
+
+function createMockKGStore() {
+  return {
+    storedTriples: [] as any[],
+    async createTriples(triples: any[]) {
+      const result = triples.map((t: any, i: number) => ({
+        ...t,
+        id: `mock-${i}`,
+        timestamp: Date.now(),
+      }));
+      this.storedTriples.push(...result);
+      return result;
+    },
+  } as any;
+}
+
+describe("normalizeEntity", () => {
+  it("trims and collapses whitespace", () => {
+    expect(normalizeEntity("  Hello   World  ")).toBe("Hello World");
+  });
+  it("converts to title case", () => {
+    expect(normalizeEntity("alice")).toBe("Alice");
+    expect(normalizeEntity("PYTHON")).toBe("Python");
+  });
+  it("preserves CJK text", () => {
+    expect(normalizeEntity("张三")).toBe("张三");
+  });
+  it("strips quotes", () => {
+    expect(normalizeEntity('"Alice"')).toBe("Alice");
+  });
+  it("returns empty for empty input", () => {
+    expect(normalizeEntity("")).toBe("");
+  });
+});
+
+describe("normalizePredicate", () => {
+  it("converts to snake_case", () => {
+    expect(normalizePredicate("works with")).toBe("works_with");
+    expect(normalizePredicate("Created By")).toBe("created_by");
+  });
+  it("preserves CJK predicates", () => {
+    expect(normalizePredicate("属于")).toBe("属于");
+  });
+});
+
+describe("isKGModeEnabled", () => {
+  it("reads env var", () => {
+    const orig = process.env.RECALLNEST_KG_MODE;
+    try {
+      process.env.RECALLNEST_KG_MODE = "true";
+      expect(isKGModeEnabled()).toBe(true);
+      delete process.env.RECALLNEST_KG_MODE;
+      expect(isKGModeEnabled()).toBe(false);
+    } finally {
+      if (orig !== undefined) process.env.RECALLNEST_KG_MODE = orig;
+      else delete process.env.RECALLNEST_KG_MODE;
+    }
+  });
+});
+
+describe("KGExtractor.extract", () => {
+  it("extracts valid triples", async () => {
+    const llm = createMockLlm({
+      triples: [
+        { subject: "Alice", predicate: "uses", object: "Python", confidence: 0.9 },
+        { subject: "Alice", predicate: "works_at", object: "Google", confidence: 0.85 },
+      ],
+    });
+    const ext = new KGExtractor({ llmClient: llm, kgStore: createMockKGStore() });
+    const triples = await ext.extract("Alice uses Python at Google");
+    expect(triples.length).toBe(2);
+    expect(triples[0].subject).toBe("Alice");
+  });
+
+  it("filters low confidence", async () => {
+    const llm = createMockLlm({
+      triples: [
+        { subject: "Alice", predicate: "uses", object: "Python", confidence: 0.9 },
+        { subject: "Alice", predicate: "maybe", object: "Bob", confidence: 0.3 },
+      ],
+    });
+    const ext = new KGExtractor({ llmClient: llm, kgStore: createMockKGStore() });
+    const triples = await ext.extract("Alice uses Python and maybe Bob");
+    expect(triples.length).toBe(1);
+  });
+
+  it("normalizes entities", async () => {
+    const llm = createMockLlm({
+      triples: [{ subject: "  alice  ", predicate: "WORKS WITH", object: "bob", confidence: 0.9 }],
+    });
+    const ext = new KGExtractor({ llmClient: llm, kgStore: createMockKGStore() });
+    const triples = await ext.extract("alice works with bob");
+    expect(triples[0].subject).toBe("Alice");
+    expect(triples[0].predicate).toBe("works_with");
+    expect(triples[0].object).toBe("Bob");
+  });
+
+  it("skips self-referencing triples", async () => {
+    const llm = createMockLlm({
+      triples: [
+        { subject: "Alice", predicate: "is", object: "Alice", confidence: 0.9 },
+        { subject: "Bob", predicate: "uses", object: "Go", confidence: 0.9 },
+      ],
+    });
+    const ext = new KGExtractor({ llmClient: llm, kgStore: createMockKGStore() });
+    const triples = await ext.extract("Alice is Alice, Bob uses Go");
+    expect(triples.length).toBe(1);
+    expect(triples[0].subject).toBe("Bob");
+  });
+
+  it("deduplicates within batch", async () => {
+    const llm = createMockLlm({
+      triples: [
+        { subject: "Alice", predicate: "uses", object: "Python", confidence: 0.9 },
+        { subject: "Alice", predicate: "uses", object: "Python", confidence: 0.85 },
+      ],
+    });
+    const ext = new KGExtractor({ llmClient: llm, kgStore: createMockKGStore() });
+    expect((await ext.extract("Alice uses Python a lot")).length).toBe(1);
+  });
+
+  it("handles null LLM response", async () => {
+    const llm = createMockLlm(null);
+    const ext = new KGExtractor({ llmClient: llm, kgStore: createMockKGStore() });
+    expect((await ext.extract("Some text here")).length).toBe(0);
+  });
+
+  it("propagates LLM transport failure (not silently zero triples)", async () => {
+    const llm = createMockLlm(null);
+    llm.chatJson = async () => { throw new Error("rate limited"); };
+    const ext = new KGExtractor({ llmClient: llm, kgStore: createMockKGStore() });
+    // Backfill relies on this to avoid journaling failed extractions as processed
+    await expect(ext.extract("Some text long enough here")).rejects.toThrow("rate limited");
+  });
+
+  it("skips short text", async () => {
+    const llm = createMockLlm({ triples: [] });
+    const ext = new KGExtractor({ llmClient: llm, kgStore: createMockKGStore() });
+    expect((await ext.extract("hi")).length).toBe(0);
+    expect(llm.lastUser).toBeNull(); // LLM not called
+  });
+});
+
+describe("KGExtractor.extractAndStore", () => {
+  it("persists triples to KG store", async () => {
+    const llm = createMockLlm({
+      triples: [
+        { subject: "Alice", predicate: "uses", object: "Python", confidence: 0.9 },
+      ],
+    });
+    const kgStore = createMockKGStore();
+    const ext = new KGExtractor({ llmClient: llm, kgStore });
+    const count = await ext.extractAndStore("Alice uses Python", "mem-001", "global");
+    expect(count).toBe(1);
+    expect(kgStore.storedTriples[0].scope).toBe("global");
+    expect(kgStore.storedTriples[0].source_memory_id).toBe("mem-001");
+  });
+
+  it("caps source_text at 500 chars", async () => {
+    const llm = createMockLlm({
+      triples: [{ subject: "A", predicate: "uses", object: "B", confidence: 0.9 }],
+    });
+    const kgStore = createMockKGStore();
+    const ext = new KGExtractor({ llmClient: llm, kgStore });
+    await ext.extractAndStore("x".repeat(1000), "mem-001", "global");
+    expect(kgStore.storedTriples[0].source_text.length).toBe(500);
+  });
+});

package/src/__tests__/kg-store.test.ts

@@ -0,0 +1,300 @@
+import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { KGStore, tripleId } from "../kg-store.js";
+
+let workDir: string;
+
+function makeTriple(overrides: Record<string, unknown> = {}) {
+  return {
+    scope: "global",
+    subject: "Alice",
+    predicate: "uses",
+    object: "Python",
+    confidence: 0.9,
+    source_memory_id: "mem-001",
+    source_text: "Alice uses Python",
+    ...overrides,
+  };
+}
+
+describe("tripleId", () => {
+  it("produces deterministic IDs", () => {
+    const id1 = tripleId("global", "Alice", "uses", "Python");
+    const id2 = tripleId("global", "Alice", "uses", "Python");
+    expect(id1).toBe(id2);
+  });
+
+  it("different triples produce different IDs", () => {
+    const id1 = tripleId("global", "Alice", "uses", "Python");
+    const id2 = tripleId("global", "Alice", "uses", "JavaScript");
+    expect(id1).not.toBe(id2);
+  });
+
+  it("scope affects ID", () => {
+    const id1 = tripleId("global", "Alice", "uses", "Python");
+    const id2 = tripleId("agent:bob", "Alice", "uses", "Python");
+    expect(id1).not.toBe(id2);
+  });
+});
+
+describe("KGStore", () => {
+  beforeEach(() => {
+    workDir = mkdtempSync(join(tmpdir(), "kg-store-test-"));
+  });
+  afterEach(() => {
+    try { rmSync(workDir, { recursive: true, force: true }); } catch {}
+  });
+
+  describe("createTriple", () => {
+    it("stores a triple", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      const t = await store.createTriple(makeTriple());
+      expect(t.id).toBeTruthy();
+      expect(t.subject).toBe("Alice");
+      expect(t.predicate).toBe("uses");
+      expect(t.object).toBe("Python");
+      expect(t.timestamp).toBeGreaterThan(0);
+    });
+
+    it("upserts on duplicate", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      const t1 = await store.createTriple(makeTriple({ confidence: 0.8 }));
+      const t2 = await store.createTriple(makeTriple({ confidence: 0.95 }));
+      expect(t1.id).toBe(t2.id);
+      expect(await store.countTriples()).toBe(1);
+    });
+  });
+
+  describe("mention counting", () => {
+    it("new triple starts at mention_count 1 with its source recorded", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      const t = await store.createTriple(makeTriple());
+      expect(t.mention_count).toBe(1);
+      expect(t.first_seen).toBeGreaterThan(0);
+      expect(JSON.parse(t.source_memory_ids)).toEqual(["mem-001"]);
+    });
+
+    it("same triple from a different source memory increments count", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      const t1 = await store.createTriple(makeTriple({ source_memory_id: "mem-001" }));
+      const t2 = await store.createTriple(makeTriple({ source_memory_id: "mem-002" }));
+      expect(t2.id).toBe(t1.id);
+      expect(t2.mention_count).toBe(2);
+      expect(JSON.parse(t2.source_memory_ids).sort()).toEqual(["mem-001", "mem-002"]);
+      expect(t2.first_seen).toBe(t1.first_seen);
+      expect(await store.countTriples()).toBe(1);
+    });
+
+    it("same triple from the same source memory does NOT increment count", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      const t1 = await store.createTriple(makeTriple({ confidence: 0.8 }));
+      const t2 = await store.createTriple(makeTriple({ confidence: 0.95 }));
+      expect(t2.mention_count).toBe(1);
+      expect(JSON.parse(t2.source_memory_ids)).toEqual(["mem-001"]);
+      // confidence keeps the max seen
+      expect(t2.confidence).toBe(0.95);
+      const again = await store.createTriple(makeTriple({ confidence: 0.5 }));
+      expect(again.confidence).toBe(0.95);
+    });
+
+    it("batch with same triple from different sources counts each source once", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      const triples = await store.createTriples([
+        makeTriple({ source_memory_id: "mem-001" }),
+        makeTriple({ source_memory_id: "mem-002" }),
+        makeTriple({ source_memory_id: "mem-002" }), // duplicate source in batch
+      ]);
+      expect(triples.length).toBe(1);
+      expect(triples[0].mention_count).toBe(2);
+      expect(await store.countTriples()).toBe(1);
+    });
+
+    it("count survives across batch and single writes", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriples([makeTriple({ source_memory_id: "mem-001" })]);
+      await store.createTriples([makeTriple({ source_memory_id: "mem-002" })]);
+      const t = await store.createTriple(makeTriple({ source_memory_id: "mem-003" }));
+      expect(t.mention_count).toBe(3);
+    });
+  });
+
+  describe("createTriples (batch)", () => {
+    it("stores multiple triples", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      const triples = await store.createTriples([
+        makeTriple({ subject: "Alice", object: "Python" }),
+        makeTriple({ subject: "Alice", object: "JavaScript" }),
+        makeTriple({ subject: "Bob", object: "Go" }),
+      ]);
+      expect(triples.length).toBe(3);
+      expect(await store.countTriples()).toBe(3);
+    });
+
+    it("deduplicates within batch", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      const triples = await store.createTriples([
+        makeTriple({ subject: "Alice", object: "Python" }),
+        makeTriple({ subject: "Alice", object: "Python" }),
+      ]);
+      expect(triples.length).toBe(1);
+    });
+
+    it("handles empty batch", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      expect(await store.createTriples([])).toEqual([]);
+    });
+  });
+
+  describe("edge queries", () => {
+    it("getOutgoingEdges", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriples([
+        makeTriple({ subject: "Alice", predicate: "uses", object: "Python" }),
+        makeTriple({ subject: "Alice", predicate: "knows", object: "Bob" }),
+        makeTriple({ subject: "Bob", predicate: "uses", object: "Go" }),
+      ]);
+      const edges = await store.getOutgoingEdges("Alice");
+      expect(edges.length).toBe(2);
+      expect(edges.every((e) => e.subject === "Alice")).toBe(true);
+    });
+
+    it("getIncomingEdges", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriples([
+        makeTriple({ subject: "Alice", predicate: "knows", object: "Bob" }),
+        makeTriple({ subject: "Charlie", predicate: "knows", object: "Bob" }),
+        makeTriple({ subject: "Bob", predicate: "uses", object: "Go" }),
+      ]);
+      const edges = await store.getIncomingEdges("Bob");
+      expect(edges.length).toBe(2);
+      expect(edges.every((e) => e.object === "Bob")).toBe(true);
+    });
+  });
+
+  describe("getNeighborhood (BFS)", () => {
+    it("returns 1-hop neighborhood", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriples([
+        makeTriple({ subject: "Alice", predicate: "knows", object: "Bob" }),
+        makeTriple({ subject: "Alice", predicate: "uses", object: "Python" }),
+        makeTriple({ subject: "Bob", predicate: "uses", object: "Go" }),
+        makeTriple({ subject: "Charlie", predicate: "uses", object: "Rust" }),
+      ]);
+      const hood = await store.getNeighborhood(["Alice"], 1);
+      const entities = hood.map((n) => n.entity).sort();
+      expect(entities).toContain("Alice");
+      expect(entities).toContain("Bob");
+      expect(entities).toContain("Python");
+      expect(entities).not.toContain("Charlie");
+    });
+
+    it("returns 2-hop neighborhood", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriples([
+        makeTriple({ subject: "Alice", predicate: "knows", object: "Bob" }),
+        makeTriple({ subject: "Bob", predicate: "knows", object: "Charlie" }),
+      ]);
+      const hood = await store.getNeighborhood(["Alice"], 2);
+      const entities = hood.map((n) => n.entity);
+      expect(entities).toContain("Charlie");
+    });
+  });
+
+  describe("scope isolation", () => {
+    it("edge queries respect scope filter", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriples([
+        makeTriple({ scope: "agent:alice", subject: "Alice", object: "Python" }),
+        makeTriple({ scope: "agent:bob", subject: "Alice", object: "Go" }),
+      ]);
+      const edges = await store.getOutgoingEdges("Alice", "agent:alice");
+      expect(edges.length).toBe(1);
+      expect(edges[0].object).toBe("Python");
+    });
+  });
+
+  describe("deleteBySource", () => {
+    it("deletes all triples from a source memory", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriples([
+        makeTriple({ source_memory_id: "mem-001", subject: "Alice", object: "Python" }),
+        makeTriple({ source_memory_id: "mem-001", subject: "Alice", object: "Go" }),
+        makeTriple({ source_memory_id: "mem-002", subject: "Bob", object: "Rust" }),
+      ]);
+      await store.deleteBySource("mem-001");
+      expect(await store.countTriples()).toBe(1);
+    });
+
+    it("multi-source triple survives forgetting one source (count decremented)", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriple(makeTriple({ source_memory_id: "mem-001" }));
+      await store.createTriple(makeTriple({ source_memory_id: "mem-002" }));
+
+      await store.deleteBySource("mem-001");
+      // Fact still evidenced by mem-002 — row survives with decremented count
+      expect(await store.countTriples()).toBe(1);
+      const edges = await store.getOutgoingEdges("Alice");
+      expect(edges.length).toBe(1);
+      expect(edges[0].mention_count).toBe(1);
+      expect(JSON.parse(edges[0].source_memory_ids)).toEqual(["mem-002"]);
+
+      await store.deleteBySource("mem-002");
+      // Last evidence gone — row deleted
+      expect(await store.countTriples()).toBe(0);
+    });
+  });
+
+  describe("getTriplesBySourceMemories", () => {
+    it("maps each memory id to the triples it contributed", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriples([
+        makeTriple({ source_memory_id: "mem-001", subject: "Alice", object: "Python" }),
+        makeTriple({ source_memory_id: "mem-001", subject: "Alice", object: "Go" }),
+        makeTriple({ source_memory_id: "mem-002", subject: "Bob", object: "Rust" }),
+      ]);
+      const map = await store.getTriplesBySourceMemories(["mem-001", "mem-002", "mem-404"]);
+      expect(map.get("mem-001")?.length).toBe(2);
+      expect(map.get("mem-002")?.length).toBe(1);
+      expect(map.has("mem-404")).toBe(false);
+    });
+
+    it("a multi-source triple appears under every contributing memory", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriple(makeTriple({ source_memory_id: "mem-001" }));
+      await store.createTriple(makeTriple({ source_memory_id: "mem-002" }));
+      const map = await store.getTriplesBySourceMemories(["mem-001", "mem-002"]);
+      expect(map.get("mem-001")?.length).toBe(1);
+      expect(map.get("mem-002")?.length).toBe(1);
+      expect(map.get("mem-001")?.[0].id).toBe(map.get("mem-002")?.[0].id);
+      expect(map.get("mem-001")?.[0].mention_count).toBe(2);
+    });
+
+    it("returns empty map for empty input", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      expect((await store.getTriplesBySourceMemories([])).size).toBe(0);
+    });
+  });
+
+  describe("entity queries", () => {
+    it("getAllEntities returns unique entities", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriples([
+        makeTriple({ subject: "Alice", object: "Python" }),
+        makeTriple({ subject: "Bob", object: "Python" }),
+      ]);
+      const entities = await store.getAllEntities();
+      expect(entities).toContain("Alice");
+      expect(entities).toContain("Bob");
+      expect(entities).toContain("Python");
+    });
+
+    it("hasEntity checks existence", async () => {
+      const store = new KGStore({ dbPath: workDir });
+      await store.createTriple(makeTriple());
+      expect(await store.hasEntity("Alice")).toBe(true);
+      expect(await store.hasEntity("Charlie")).toBe(false);
+    });
+  });
+});