recallnest 2.2.1 → 2.5.4

package/src/__tests__/recall-governor.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  GovernorSession,
+  governResults,
+  resolveGovernorConfig,
+  truncateQuery,
+} from "../recall-governor.js";
+import type { RetrievalResult } from "../retriever.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeResult(
+  id: string,
+  text: string,
+  score: number,
+  metadata = "{}",
+): RetrievalResult {
+  return {
+    entry: {
+      id,
+      text,
+      vector: [],
+      category: "events",
+      scope: "project:test",
+      importance: 0.8,
+      timestamp: Date.now(),
+      metadata,
+    },
+    score,
+    sources: { fused: { score } },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// truncateQuery
+// ---------------------------------------------------------------------------
+
+describe("truncateQuery", () => {
+  it("returns query unchanged when within limit", () => {
+    expect(truncateQuery("short", 1000)).toBe("short");
+  });
+
+  it("truncates query exceeding maxQueryChars", () => {
+    const long = "a".repeat(2000);
+    const result = truncateQuery(long, 500);
+    expect(result.length).toBe(500);
+  });
+
+  it("handles exact boundary", () => {
+    const exact = "x".repeat(100);
+    expect(truncateQuery(exact, 100)).toBe(exact);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveGovernorConfig
+// ---------------------------------------------------------------------------
+
+describe("resolveGovernorConfig", () => {
+  it("returns defaults when no overrides", () => {
+    const cfg = resolveGovernorConfig();
+    expect(cfg.maxQueryChars).toBe(1000);
+    expect(cfg.charBudget).toBe(8000);
+    expect(cfg.maxItems).toBe(10);
+  });
+
+  it("merges partial overrides", () => {
+    const cfg = resolveGovernorConfig({ charBudget: 4000 });
+    expect(cfg.charBudget).toBe(4000);
+    expect(cfg.maxItems).toBe(10); // unchanged
+  });
+});
+
+// ---------------------------------------------------------------------------
+// GovernorSession
+// ---------------------------------------------------------------------------
+
+describe("GovernorSession", () => {
+  it("tracks injected IDs", () => {
+    const session = new GovernorSession();
+    expect(session.wasInjected("a")).toBe(false);
+    session.markInjected("a");
+    expect(session.wasInjected("a")).toBe(true);
+    expect(session.size).toBe(1);
+  });
+
+  it("markAll registers all result IDs", () => {
+    const session = new GovernorSession();
+    const results = [makeResult("x", "hi", 0.9), makeResult("y", "hello", 0.8)];
+    session.markAll(results);
+    expect(session.wasInjected("x")).toBe(true);
+    expect(session.wasInjected("y")).toBe(true);
+    expect(session.size).toBe(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// governResults — evolution state filter
+// ---------------------------------------------------------------------------
+
+describe("governResults — evolution filter", () => {
+  it("keeps active memories", () => {
+    const results = [makeResult("a1", "active memory", 0.9, '{"evolution":{"status":"active"}}')];
+    const governed = governResults(results);
+    expect(governed).toHaveLength(1);
+  });
+
+  it("keeps pending_review memories", () => {
+    const results = [makeResult("p1", "pending review", 0.9, '{"evolution":{"status":"pending_review"}}')];
+    const governed = governResults(results);
+    expect(governed).toHaveLength(1);
+  });
+
+  it("drops archived memories", () => {
+    const results = [makeResult("ar1", "archived", 0.9, '{"evolution":{"status":"archived"}}')];
+    const governed = governResults(results);
+    expect(governed).toHaveLength(0);
+  });
+
+  it("drops superseded memories", () => {
+    const results = [makeResult("s1", "superseded", 0.9, '{"evolution":{"status":"superseded"}}')];
+    const governed = governResults(results);
+    expect(governed).toHaveLength(0);
+  });
+
+  it("keeps memories with no evolution (defaults to active)", () => {
+    const results = [makeResult("n1", "no status", 0.9, "{}")];
+    const governed = governResults(results);
+    expect(governed).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// governResults — budget control
+// ---------------------------------------------------------------------------
+
+describe("governResults — budget control", () => {
+  it("respects maxItems limit", () => {
+    const results = Array.from({ length: 5 }, (_, i) =>
+      makeResult(`b${i}`, "x".repeat(10), 0.9 - i * 0.01),
+    );
+    const governed = governResults(results, undefined, { maxItems: 3 });
+    expect(governed).toHaveLength(3);
+  });
+
+  it("respects charBudget limit", () => {
+    const results = [
+      makeResult("c1", "a".repeat(3000), 0.95),
+      makeResult("c2", "b".repeat(3000), 0.90),
+      makeResult("c3", "c".repeat(3000), 0.85),
+    ];
+    const governed = governResults(results, undefined, { charBudget: 5000 });
+    // First item (3000) fits, second (6000 total) would exceed 5000 → stops after first
+    expect(governed).toHaveLength(1);
+  });
+
+  it("always allows at least one result even if it exceeds budget", () => {
+    const results = [makeResult("big", "x".repeat(10000), 0.95)];
+    const governed = governResults(results, undefined, { charBudget: 100 });
+    expect(governed).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// governResults — session dedup
+// ---------------------------------------------------------------------------
+
+describe("governResults — session dedup", () => {
+  it("drops already-injected IDs", () => {
+    const session = new GovernorSession();
+    session.markInjected("dup1");
+
+    const results = [
+      makeResult("dup1", "already seen", 0.95),
+      makeResult("new1", "fresh memory", 0.90),
+    ];
+    const governed = governResults(results, session);
+    expect(governed).toHaveLength(1);
+    expect(governed[0].entry.id).toBe("new1");
+  });
+
+  it("marks newly governed results in the session", () => {
+    const session = new GovernorSession();
+    const results = [makeResult("x1", "hello", 0.9)];
+    governResults(results, session);
+    expect(session.wasInjected("x1")).toBe(true);
+  });
+
+  it("skips dedup when no session provided", () => {
+    const results = [makeResult("a", "text", 0.9), makeResult("a", "text", 0.8)];
+    // Without session, same ID can appear (though unusual from retriever)
+    const governed = governResults(results);
+    expect(governed).toHaveLength(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// governResults — empty input
+// ---------------------------------------------------------------------------
+
+describe("governResults — edge cases", () => {
+  it("returns empty array for empty input", () => {
+    expect(governResults([])).toHaveLength(0);
+  });
+
+  it("composes all layers correctly", () => {
+    const session = new GovernorSession();
+    session.markInjected("already");
+
+    const results = [
+      makeResult("already", "seen before", 0.99),                                     // dedup
+      makeResult("archived", "old", 0.95, '{"evolution":{"status":"archived"}}'),        // evolution
+      makeResult("keep1", "a".repeat(4000), 0.90),                                    // kept
+      makeResult("keep2", "b".repeat(4000), 0.85),                                    // kept
+      makeResult("over-budget", "c".repeat(4000), 0.80),                              // budget
+    ];
+    const governed = governResults(results, session, { charBudget: 8000 });
+    // archived dropped by evolution, already dropped by dedup,
+    // keep1 (4000) + keep2 (8000) = at budget, over-budget dropped
+    expect(governed.map((r) => r.entry.id)).toEqual(["keep1", "keep2"]);
+    expect(session.wasInjected("keep1")).toBe(true);
+    expect(session.wasInjected("keep2")).toBe(true);
+  });
+});

package/src/__tests__/recall-mode.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { resolveRecallMode, type LocalMemoryConfig } from "../runtime-config.js";
+
+const baseConfig: LocalMemoryConfig = {
+  dbPath: "./data/lancedb",
+  embedding: {
+    provider: "jina",
+    apiKey: "test",
+    model: "test-model",
+  },
+  sources: {},
+};
+
+describe("resolveRecallMode", () => {
+  const originalEnv = process.env.RECALLNEST_RECALL_MODE;
+
+  beforeEach(() => {
+    delete process.env.RECALLNEST_RECALL_MODE;
+  });
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.RECALLNEST_RECALL_MODE;
+    } else {
+      process.env.RECALLNEST_RECALL_MODE = originalEnv;
+    }
+  });
+
+  it("defaults to 'summary' when no config, no env, no override", () => {
+    delete process.env.RECALLNEST_RECALL_MODE;
+    expect(resolveRecallMode(baseConfig)).toBe("summary");
+  });
+
+  it("reads from config.recallMode", () => {
+    delete process.env.RECALLNEST_RECALL_MODE;
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "full" })).toBe("full");
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "off" })).toBe("off");
+  });
+
+  it("env var overrides config", () => {
+    process.env.RECALLNEST_RECALL_MODE = "off";
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "full" })).toBe("off");
+  });
+
+  it("per-call override takes highest priority", () => {
+    process.env.RECALLNEST_RECALL_MODE = "off";
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "full" }, "summary")).toBe("summary");
+  });
+
+  it("ignores invalid per-call override, falls back to env", () => {
+    process.env.RECALLNEST_RECALL_MODE = "full";
+    expect(resolveRecallMode(baseConfig, "invalid")).toBe("full");
+  });
+
+  it("ignores invalid env var, falls back to config", () => {
+    process.env.RECALLNEST_RECALL_MODE = "garbage";
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "off" })).toBe("off");
+  });
+
+  it("ignores invalid env var and no config, falls back to default", () => {
+    process.env.RECALLNEST_RECALL_MODE = "garbage";
+    expect(resolveRecallMode(baseConfig)).toBe("summary");
+  });
+});

package/src/__tests__/result-synthesizer.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Tests for Tier 3.5: Result Synthesizer
+ *
+ * Validates:
+ * 1. synthesize() with enough fragments calls LLM
+ * 2. synthesize() returns fragments when below threshold
+ * 3. synthesize() returns fragments when no LLM
+ * 4. synthesize() handles LLM failure gracefully
+ * 5. synthesizeSection() respects RECALLNEST_SYNTHESIZE env
+ * 6. synthesizeSection() passes through when disabled
+ * 7. Single fragment returned as-is (no LLM call)
+ */
+import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import {
+  synthesize,
+  synthesizeSection,
+  isSynthesisEnabled,
+  DEFAULT_SYNTHESIZER_CONFIG,
+} from "../result-synthesizer.js";
+import type { LLMClient } from "../llm-client.js";
+
+// ---------------------------------------------------------------------------
+// Mock LLM Client
+// ---------------------------------------------------------------------------
+
+function createMockLLM(response: string | null = "Synthesized narrative."): LLMClient & { calls: Array<{ fragments: string[]; query: string }> } {
+  const calls: Array<{ fragments: string[]; query: string }> = [];
+  return {
+    calls,
+    async synthesizeFragments(fragments: string[], query: string) {
+      calls.push({ fragments, query });
+      return response;
+    },
+  } as any;
+}
+
+function createFailingLLM(): LLMClient {
+  return {
+    async synthesizeFragments() {
+      throw new Error("LLM connection failed");
+    },
+  } as any;
+}
+
+// ---------------------------------------------------------------------------
+// synthesize() tests
+// ---------------------------------------------------------------------------
+
+describe("synthesize", () => {
+  it("calls LLM when fragments >= minFragments", async () => {
+    const llm = createMockLLM("Combined narrative about user preferences.");
+    const fragments = ["Pref A: dark mode", "Pref B: vim keys", "Pref C: compact layout"];
+
+    const result = await synthesize(fragments, "user preferences", llm);
+
+    expect(result.synthesized).toBe(true);
+    expect(result.text).toBe("Combined narrative about user preferences.");
+    expect(result.reason).toBe("ok");
+    expect(llm.calls.length).toBe(1);
+    expect(llm.calls[0].query).toBe("user preferences");
+  });
+
+  it("skips synthesis when fragments < minFragments", async () => {
+    const llm = createMockLLM();
+    const fragments = ["Only one", "Two items"];
+
+    const result = await synthesize(fragments, "test", llm);
+
+    expect(result.synthesized).toBe(false);
+    expect(result.reason).toBe("below-threshold");
+    expect(result.fragments).toEqual(fragments);
+    expect(llm.calls.length).toBe(0);
+  });
+
+  it("skips synthesis when no LLM provided", async () => {
+    const fragments = ["A", "B", "C"];
+    const result = await synthesize(fragments, "test", null);
+
+    expect(result.synthesized).toBe(false);
+    expect(result.reason).toBe("no-llm");
+  });
+
+  it("handles LLM failure gracefully", async () => {
+    const llm = createFailingLLM();
+    const fragments = ["A", "B", "C"];
+
+    const result = await synthesize(fragments, "test", llm);
+
+    expect(result.synthesized).toBe(false);
+    expect(result.reason).toBe("error");
+    expect(result.fragments).toEqual(fragments);
+  });
+
+  it("handles empty LLM response", async () => {
+    const llm = createMockLLM(null);
+    const fragments = ["A", "B", "C"];
+
+    const result = await synthesize(fragments, "test", llm);
+
+    expect(result.synthesized).toBe(false);
+    expect(result.reason).toBe("empty-response");
+  });
+
+  it("handles empty fragments array", async () => {
+    const llm = createMockLLM();
+    const result = await synthesize([], "test", llm);
+
+    expect(result.synthesized).toBe(false);
+    expect(result.reason).toBe("below-threshold");
+  });
+
+  it("respects custom minFragments config", async () => {
+    const llm = createMockLLM("ok");
+    const fragments = ["A", "B"];
+
+    // Default minFragments=3, so 2 items would be below threshold
+    const result2 = await synthesize(fragments, "test", llm, { ...DEFAULT_SYNTHESIZER_CONFIG, minFragments: 2 });
+    expect(result2.synthesized).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// synthesizeSection() tests
+// ---------------------------------------------------------------------------
+
+describe("synthesizeSection", () => {
+  const originalEnv = process.env.RECALLNEST_SYNTHESIZE;
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.RECALLNEST_SYNTHESIZE = originalEnv;
+    } else {
+      delete process.env.RECALLNEST_SYNTHESIZE;
+    }
+  });
+
+  it("returns original items when RECALLNEST_SYNTHESIZE is not set", async () => {
+    delete process.env.RECALLNEST_SYNTHESIZE;
+    const items = ["A", "B", "C", "D"];
+    const llm = createMockLLM("synthesized");
+
+    const result = await synthesizeSection(items, "test", llm);
+
+    expect(result).toEqual(items);
+    expect(llm.calls.length).toBe(0);
+  });
+
+  it("synthesizes when RECALLNEST_SYNTHESIZE=true", async () => {
+    process.env.RECALLNEST_SYNTHESIZE = "true";
+    const items = ["Profile: developer", "Preference: dark mode", "Entity: project X"];
+    const llm = createMockLLM("User is a developer who prefers dark mode and works on project X.");
+
+    const result = await synthesizeSection(items, "user context", llm);
+
+    expect(result).toEqual(["User is a developer who prefers dark mode and works on project X."]);
+  });
+
+  it("returns original items when synthesis fails", async () => {
+    process.env.RECALLNEST_SYNTHESIZE = "true";
+    const items = ["A", "B", "C"];
+    const llm = createFailingLLM();
+
+    const result = await synthesizeSection(items, "test", llm);
+
+    expect(result).toEqual(items);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isSynthesisEnabled() tests
+// ---------------------------------------------------------------------------
+
+describe("isSynthesisEnabled", () => {
+  const originalEnv = process.env.RECALLNEST_SYNTHESIZE;
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.RECALLNEST_SYNTHESIZE = originalEnv;
+    } else {
+      delete process.env.RECALLNEST_SYNTHESIZE;
+    }
+  });
+
+  it("returns false when env not set", () => {
+    delete process.env.RECALLNEST_SYNTHESIZE;
+    expect(isSynthesisEnabled()).toBe(false);
+  });
+
+  it("returns true when env is 'true'", () => {
+    process.env.RECALLNEST_SYNTHESIZE = "true";
+    expect(isSynthesisEnabled()).toBe(true);
+  });
+
+  it("returns false when env is other value", () => {
+    process.env.RECALLNEST_SYNTHESIZE = "false";
+    expect(isSynthesisEnabled()).toBe(false);
+  });
+});