recallnest 1.4.1

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

@@ -0,0 +1,198 @@
+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("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);
+    });
+  });
+
+  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);
+    });
+  });
+});

package/src/__tests__/llm-consolidation.test.ts

@@ -0,0 +1,226 @@
+/**
+ * Tests for Tier 3.7: LLM-Driven Consolidation
+ *
+ * Validates:
+ * 1. evaluateCluster returns merge decisions from LLM
+ * 2. evaluateCluster falls back conservatively on LLM failure
+ * 3. executeMergeDecisions creates version groups for merge groups
+ * 4. executeMergeDecisions handles empty merge groups
+ * 5. isLLMConsolidationEnabled respects env var
+ */
+import { describe, expect, it, afterEach } from "bun:test";
+import {
+  evaluateCluster,
+  executeMergeDecisions,
+  isLLMConsolidationEnabled,
+} from "../llm-consolidation.js";
+import type { MemoryEntry } from "../store.js";
+import type { LLMClient } from "../llm-client.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEntry(id: string, text: string, importance = 0.7): MemoryEntry {
+  return {
+    id,
+    text,
+    vector: [1, 0, 0],
+    category: "preferences",
+    scope: "project:test",
+    importance,
+    timestamp: Date.now(),
+    metadata: JSON.stringify({ confidence: 0.7, accessCount: 0 }),
+  };
+}
+
+function createMockStore(entries: MemoryEntry[]) {
+  const data = new Map(entries.map(e => [e.id, { ...e }]));
+  const updates: Array<{ id: string; metadata: string }> = [];
+
+  return {
+    data,
+    updates,
+    async getById(id: string) { return data.get(id) ?? null; },
+    async update(id: string, upd: { metadata?: string }, _scope?: string[]) {
+      const entry = data.get(id);
+      if (!entry) return null;
+      if (upd.metadata) {
+        entry.metadata = upd.metadata;
+        updates.push({ id, metadata: upd.metadata });
+      }
+      return entry;
+    },
+  };
+}
+
+function createMockLLM(response: string): LLMClient {
+  return {
+    async synthesizeFragments() {
+      return response;
+    },
+  } as any;
+}
+
+// ---------------------------------------------------------------------------
+// evaluateCluster
+// ---------------------------------------------------------------------------
+
+describe("evaluateCluster", () => {
+  it("returns merge groups from LLM response", async () => {
+    const entries = [
+      makeEntry("a", "User prefers dark mode"),
+      makeEntry("b", "User likes dark theme"),
+      makeEntry("c", "User uses vim keybindings"),
+    ];
+
+    const llm = createMockLLM(JSON.stringify({
+      mergeGroups: [[0, 1]],
+      keepSeparate: [2],
+      reasoning: "0 and 1 express same preference, 2 is different",
+    }));
+
+    const decision = await evaluateCluster(llm, entries);
+
+    expect(decision.mergeGroups.length).toBe(1);
+    expect(decision.mergeGroups[0]).toEqual([0, 1]);
+    expect(decision.keepSeparate).toEqual([2]);
+  });
+
+  it("returns conservative fallback on LLM failure", async () => {
+    const entries = [makeEntry("a", "text a"), makeEntry("b", "text b")];
+    const llm = {
+      async synthesizeFragments() { throw new Error("LLM down"); },
+    } as any;
+
+    const decision = await evaluateCluster(llm, entries);
+
+    expect(decision.mergeGroups.length).toBe(0);
+    expect(decision.keepSeparate.length).toBe(2);
+  });
+
+  it("returns conservative fallback on null response", async () => {
+    const entries = [makeEntry("a", "text a"), makeEntry("b", "text b")];
+    const llm = createMockLLM("");
+
+    // Empty string → null synthesis → fallback
+    const decision = await evaluateCluster({ async synthesizeFragments() { return null; } } as any, entries);
+
+    expect(decision.mergeGroups.length).toBe(0);
+  });
+
+  it("handles single entry", async () => {
+    const entries = [makeEntry("a", "only one")];
+    const llm = createMockLLM("{}");
+
+    const decision = await evaluateCluster(llm, entries);
+
+    expect(decision.mergeGroups.length).toBe(0);
+    expect(decision.keepSeparate).toEqual([0]);
+  });
+
+  it("filters invalid indices from LLM response", async () => {
+    const entries = [makeEntry("a", "text a"), makeEntry("b", "text b")];
+    const llm = createMockLLM(JSON.stringify({
+      mergeGroups: [[0, 5]], // index 5 out of range
+      keepSeparate: [0, 1],
+      reasoning: "test",
+    }));
+
+    const decision = await evaluateCluster(llm, entries);
+
+    // Invalid group should be filtered out
+    expect(decision.mergeGroups.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// executeMergeDecisions
+// ---------------------------------------------------------------------------
+
+describe("executeMergeDecisions", () => {
+  it("creates version groups for merge groups", async () => {
+    const entries = [
+      makeEntry("a", "dark mode pref", 0.9),
+      makeEntry("b", "dark theme pref", 0.5),
+      makeEntry("c", "vim pref", 0.7),
+    ];
+    const store = createMockStore(entries);
+
+    const decision = {
+      mergeGroups: [[0, 1]],
+      keepSeparate: [2],
+      reasoning: "similar preferences",
+    };
+
+    const mergeCount = await executeMergeDecisions(store as any, entries, decision, "project:test");
+
+    expect(mergeCount).toBe(1);
+    // Both a and b should now have version_group
+    const metaA = JSON.parse(store.data.get("a")!.metadata);
+    const metaB = JSON.parse(store.data.get("b")!.metadata);
+    expect(metaA.version_group).toBeTruthy();
+    expect(metaB.version_group).toBe(metaA.version_group);
+  });
+
+  it("handles empty merge groups", async () => {
+    const entries = [makeEntry("a", "text a")];
+    const store = createMockStore(entries);
+
+    const decision = {
+      mergeGroups: [],
+      keepSeparate: [0],
+      reasoning: "nothing to merge",
+    };
+
+    const mergeCount = await executeMergeDecisions(store as any, entries, decision, "project:test");
+
+    expect(mergeCount).toBe(0);
+  });
+
+  it("handles multi-entry merge group", async () => {
+    const entries = [
+      makeEntry("a", "pref 1", 0.9),
+      makeEntry("b", "pref 2", 0.7),
+      makeEntry("c", "pref 3", 0.5),
+    ];
+    const store = createMockStore(entries);
+
+    const decision = {
+      mergeGroups: [[0, 1, 2]],
+      keepSeparate: [],
+      reasoning: "all same",
+    };
+
+    const mergeCount = await executeMergeDecisions(store as any, entries, decision, "project:test");
+
+    // a is canonical, b and c are members → 2 merges
+    expect(mergeCount).toBe(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isLLMConsolidationEnabled
+// ---------------------------------------------------------------------------
+
+describe("isLLMConsolidationEnabled", () => {
+  const originalEnv = process.env.RECALLNEST_LLM_CONSOLIDATION;
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.RECALLNEST_LLM_CONSOLIDATION = originalEnv;
+    } else {
+      delete process.env.RECALLNEST_LLM_CONSOLIDATION;
+    }
+  });
+
+  it("returns false when not set", () => {
+    delete process.env.RECALLNEST_LLM_CONSOLIDATION;
+    expect(isLLMConsolidationEnabled()).toBe(false);
+  });
+
+  it("returns true when set to 'true'", () => {
+    process.env.RECALLNEST_LLM_CONSOLIDATION = "true";
+    expect(isLLMConsolidationEnabled()).toBe(true);
+  });
+});

package/src/__tests__/memory-boundaries.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  buildStructuredMemoryBoundary,
+  buildDefaultCanonicalKey,
+  extractBoundaryMetadata,
+  extractMemoryProvenance,
+  extractPromotedFrom,
+  extractProvenanceHistory,
+  extractProvenanceHistoryCount,
+  resolveIngestBoundary,
+  shouldUseStableMemoryResult,
+} from "../memory-boundaries.js";
+
+describe("memory boundaries", () => {
+  it("downgrades transcript-derived profile facts into evidence events", () => {
+    const resolved = resolveIngestBoundary({
+      source: "cc",
+      scope: "cc:abc123",
+      category: "profile",
+    });
+
+    expect(resolved.category).toBe("events");
+    expect(resolved.boundary.layer).toBe("evidence");
+    expect(resolved.boundary.authority).toBe("transcript-ingest");
+    expect(resolved.boundary.downgradedFrom).toBe("profile");
+  });
+
+  it("keeps transcript cases searchable but marks them as evidence", () => {
+    const resolved = resolveIngestBoundary({
+      source: "codex",
+      scope: "codex:session1",
+      category: "cases",
+    });
+
+    expect(resolved.category).toBe("cases");
+    expect(resolved.boundary.layer).toBe("evidence");
+    expect(resolved.boundary.authority).toBe("transcript-ingest");
+    expect(resolved.boundary.originalCategory).toBe("cases");
+  });
+
+  it("marks structured memory as durable authority", () => {
+    const boundary = buildStructuredMemoryBoundary("preferences");
+
+    expect(boundary).toEqual({
+      layer: "durable",
+      authority: "structured-memory",
+      conflictPolicy: "latest-wins",
+      originalCategory: "preferences",
+      note: "Structured memory writes are the durable source inside RecallNest.",
+    });
+  });
+
+  it("builds slot-aware canonical keys for atomic brand-item preferences", () => {
+    expect(buildDefaultCanonicalKey({
+      category: "preferences",
+      text: "我喜欢吃麦当劳的麦辣鸡翅",
+    })).toBe("preferences:brand-item:麦当劳:麦辣鸡翅");
+
+    expect(buildDefaultCanonicalKey({
+      category: "preferences",
+      text: "User prefers concise, direct replies.",
+    })).toBe("preferences:reply-style:concise:direct");
+
+    expect(buildDefaultCanonicalKey({
+      category: "preferences",
+      text: "Uses Bun over Node.",
+    })).toBe("preferences:tool-choice:bun:over:node");
+
+    expect(buildDefaultCanonicalKey({
+      category: "preferences",
+      text: "我喜欢吃麦当劳的麦旋风、板烧鸡腿堡和麦辣鸡翅",
+    })).toBe("preferences:我喜欢吃麦当劳的麦旋风-板烧鸡腿堡和麦辣鸡翅");
+  });
+
+  it("rejects transcript/evidence stable recall and keeps durable stable recall", () => {
+    expect(shouldUseStableMemoryResult({
+      category: "preferences",
+      scope: "cc:session",
+      metadata: JSON.stringify({
+        boundary: {
+          layer: "evidence",
+          authority: "transcript-ingest",
+          conflictPolicy: "append-only",
+        },
+      }),
+    })).toBe(false);
+
+    expect(shouldUseStableMemoryResult({
+      category: "preferences",
+      scope: "memory:agent",
+      metadata: JSON.stringify({
+        boundary: buildStructuredMemoryBoundary("preferences"),
+      }),
+    })).toBe(true);
+  });
+
+  it("parses valid boundary metadata and ignores malformed payloads", () => {
+    expect(extractBoundaryMetadata(JSON.stringify({
+      boundary: buildStructuredMemoryBoundary("patterns"),
+    }))).toEqual(buildStructuredMemoryBoundary("patterns"));
+
+    expect(extractBoundaryMetadata("{not-json")).toBeNull();
+    expect(extractBoundaryMetadata(JSON.stringify({
+      boundary: { layer: "durable", authority: "oops" },
+    }))).toBeNull();
+  });
+
+  it("extracts promotedFrom provenance and canonical keys", () => {
+    const metadata = JSON.stringify({
+      canonicalKey: "user-reply-style",
+      boundary: buildStructuredMemoryBoundary("preferences"),
+      promotedFrom: {
+        memoryId: "12345678-1234-1234-1234-123456789abc",
+        scope: "cc:session1",
+        category: "events",
+        source: "cc",
+        boundary: {
+          layer: "evidence",
+          authority: "transcript-ingest",
+          conflictPolicy: "append-only",
+          originalCategory: "preferences",
+        },
+      },
+    });
+
+    expect(extractPromotedFrom(metadata)).toEqual({
+      memoryId: "12345678-1234-1234-1234-123456789abc",
+      scope: "cc:session1",
+      category: "events",
+      source: "cc",
+      boundary: {
+        layer: "evidence",
+        authority: "transcript-ingest",
+        conflictPolicy: "append-only",
+        originalCategory: "preferences",
+      },
+    });
+
+    expect(extractProvenanceHistory(metadata)).toEqual([{
+      memoryId: "12345678-1234-1234-1234-123456789abc",
+      scope: "cc:session1",
+      category: "events",
+      source: "cc",
+      boundary: {
+        layer: "evidence",
+        authority: "transcript-ingest",
+        conflictPolicy: "append-only",
+        originalCategory: "preferences",
+      },
+    }]);
+    expect(extractProvenanceHistoryCount(metadata)).toBe(1);
+
+    expect(extractMemoryProvenance({
+      scope: "memory:agent",
+      metadata,
+    })).toEqual({
+      boundary: buildStructuredMemoryBoundary("preferences"),
+      canonicalKey: "user-reply-style",
+      promotedFrom: {
+        memoryId: "12345678-1234-1234-1234-123456789abc",
+        scope: "cc:session1",
+        category: "events",
+        source: "cc",
+        boundary: {
+          layer: "evidence",
+          authority: "transcript-ingest",
+          conflictPolicy: "append-only",
+          originalCategory: "preferences",
+        },
+      },
+      provenanceHistory: [{
+        memoryId: "12345678-1234-1234-1234-123456789abc",
+        scope: "cc:session1",
+        category: "events",
+        source: "cc",
+        boundary: {
+          layer: "evidence",
+          authority: "transcript-ingest",
+          conflictPolicy: "append-only",
+          originalCategory: "preferences",
+        },
+      }],
+      provenanceHistoryCount: 1,
+    });
+  });
+
+  it("prefers explicit provenance history over fallback promotedFrom metadata", () => {
+    const metadata = JSON.stringify({
+      canonicalKey: "preferences:brand-item:麦当劳:麦辣鸡翅",
+      boundary: buildStructuredMemoryBoundary("preferences"),
+      promotedFrom: {
+        memoryId: "12345678-1234-1234-1234-123456789abc",
+        scope: "cc:session1",
+        category: "events",
+        source: "cc",
+      },
+      provenanceHistory: [
+        {
+          memoryId: "aaaaaaaa-1234-1234-1234-123456789abc",
+          scope: "cc:session-food-1",
+          category: "events",
+          source: "cc",
+          observedAt: "2026-03-17T04:00:00.000Z",
+        },
+        {
+          memoryId: "bbbbbbbb-1234-1234-1234-123456789abc",
+          scope: "cc:session-food-2",
+          category: "events",
+          source: "codex",
+          observedAt: "2026-03-17T05:00:00.000Z",
+        },
+      ],
+      provenanceHistoryCount: 2,
+    });
+
+    expect(extractProvenanceHistory(metadata)).toEqual([
+      {
+        memoryId: "aaaaaaaa-1234-1234-1234-123456789abc",
+        scope: "cc:session-food-1",
+        category: "events",
+        source: "cc",
+        observedAt: "2026-03-17T04:00:00.000Z",
+        boundary: null,
+      },
+      {
+        memoryId: "bbbbbbbb-1234-1234-1234-123456789abc",
+        scope: "cc:session-food-2",
+        category: "events",
+        source: "codex",
+        observedAt: "2026-03-17T05:00:00.000Z",
+        boundary: null,
+      },
+    ]);
+    expect(extractProvenanceHistoryCount(metadata)).toBe(2);
+  });
+});