recallnest 2.3.0 → 2.6.0

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__/resolve-db-path.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "bun:test";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { readdirSync, readFileSync } from "node:fs";
+
+import { resolveDbPath, resolveDataDir, type LocalMemoryConfig } from "../runtime-config.js";
+
+const REPO_ROOT = resolve(import.meta.dir, "../..");
+
+function cfg(dbPath: string): LocalMemoryConfig {
+  return {
+    dbPath,
+    embedding: { provider: "jina", apiKey: "x", model: "m" },
+    sources: {},
+  };
+}
+
+/**
+ * Regression guard for the 2026-07-19 audit finding: maintenance scripts each
+ * resolved the database on their own — some hardcoded "./data/lancedb", others
+ * read `config.database?.path`, a key that does not exist in LocalMemoryConfig
+ * and therefore always fell through to the hardcoded default. A health check or
+ * cleanup could then report on an empty directory while the server used a
+ * different database entirely.
+ */
+describe("resolveDbPath", () => {
+  it("resolves a relative dbPath against the repo root, not process.cwd()", () => {
+    expect(resolveDbPath(cfg("./data/lancedb"))).toBe(resolve(REPO_ROOT, "data/lancedb"));
+    expect(resolveDbPath(cfg("data/lancedb"))).toBe(resolve(REPO_ROOT, "data/lancedb"));
+  });
+
+  it("expands a leading ~/ to the home directory", () => {
+    expect(resolveDbPath(cfg("~/.recallnest/data/lancedb"))).toBe(
+      resolve(homedir(), ".recallnest/data/lancedb")
+    );
+  });
+
+  it("keeps an absolute dbPath unchanged", () => {
+    expect(resolveDbPath(cfg("/tmp/rn-abs/lancedb"))).toBe("/tmp/rn-abs/lancedb");
+  });
+
+  it("always returns an absolute path", () => {
+    for (const p of ["./data/lancedb", "data/lancedb", "~/x/lancedb", "/tmp/y"]) {
+      expect(resolveDbPath(cfg(p)).startsWith("/")).toBe(true);
+    }
+  });
+
+  it("puts the sidecar data dir directly beside the database", () => {
+    expect(resolveDataDir(cfg("~/.recallnest/data/lancedb"))).toBe(
+      resolve(homedir(), ".recallnest/data")
+    );
+    expect(resolveDataDir(cfg("./data/lancedb"))).toBe(resolve(REPO_ROOT, "data"));
+  });
+});
+
+describe("scripts resolve the database through runtime-config", () => {
+  it("no script hardcodes a lancedb path", () => {
+    const dir = resolve(REPO_ROOT, "scripts");
+    const offenders: string[] = [];
+
+    // Two shapes of the same mistake. The second was missed by the first
+    // revision of this guard: health-check.ts built its path with
+    // path.join(dir, "..", "data", "lancedb"), so no single string literal
+    // ever contained "data/lancedb".
+    const LITERAL_PATH = /["'`][^"'`]*data\/lancedb[^"'`]*["'`]/;
+    const JOINED_PATH = /\b(join|resolve)\s*\([^)]*["'`][^"'`]*lancedb[^"'`]*["'`]/i;
+
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".ts")) continue;
+      const src = readFileSync(resolve(dir, name), "utf-8");
+      for (const [i, line] of src.split("\n").entries()) {
+        const code = line.split("//")[0];
+        if (/^\s*\*/.test(line)) continue; // block-comment body
+        if (/@lancedb\/lancedb/.test(code)) continue; // the package import itself
+        if (LITERAL_PATH.test(code) || JOINED_PATH.test(code)) {
+          offenders.push(`${name}:${i + 1}`);
+        }
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("no src file re-implements dbPath resolution instead of calling resolveDbPath", () => {
+    // cli.ts once duplicated the resolve() expression for its destructive
+    // "clear index" path, and doctor.ts resolved against process.cwd() — so the
+    // health check could report on a different directory than the server used.
+    const dir = resolve(REPO_ROOT, "src");
+    const offenders: string[] = [];
+
+    const walk = (d: string): void => {
+      for (const entry of readdirSync(d, { withFileTypes: true })) {
+        if (entry.name === "__tests__" || entry.name === "node_modules") continue;
+        const full = resolve(d, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+          continue;
+        }
+        if (!entry.name.endsWith(".ts") || entry.name === "runtime-config.ts") continue;
+        const src = readFileSync(full, "utf-8");
+        for (const [i, line] of src.split("\n").entries()) {
+          if (/expandHome\(\s*\w+\.dbPath\s*\)/.test(line)) {
+            offenders.push(`${entry.name}:${i + 1}`);
+          }
+        }
+      }
+    };
+    walk(dir);
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("no script reads the non-existent config.database key", () => {
+    const dir = resolve(REPO_ROOT, "scripts");
+    const offenders: string[] = [];
+
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".ts")) continue;
+      const src = readFileSync(resolve(dir, name), "utf-8");
+      for (const [i, line] of src.split("\n").entries()) {
+        // Skip comments — documenting the retired key must not fail the guard.
+        if (/^\s*(\/\/|\*|\/\*)/.test(line)) continue;
+        const code = line.split("//")[0];
+        if (/config\.database\b/.test(code)) offenders.push(`${name}:${i + 1}`);
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/__tests__/resolve-tier.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "bun:test";
+
+import { isDecayExempt, resolveTier } from "../decay-engine.js";
+
+/**
+ * importance 是 MemoryEntry 的列字段，metadata 里没有它——顶层住着的是
+ * accessCount / lastAccessedAt / tier（access-tracker 写的）。所以 heuristic
+ * 分支必须由调用方把 entry.importance 传进来。
+ * 2026-07 实测：全库 115688 行里 3214 行走这个分支，其中 metadata 顶层有
+ * importance 的是 0 行——也就是这些条目当时全部被压成了 peripheral。
+ */
+function meta(extra: Record<string, unknown> = {}): string {
+  return JSON.stringify({ source: "cc", evolution: { status: "active" }, ...extra });
+}
+
+describe("resolveTier", () => {
+  it("拿到 entry.importance 时，高 importance 条目升到对应档位", () => {
+    // 真实样本形状：importance 0.9 的 patterns，此前一直被判 peripheral
+    expect(resolveTier(meta(), 0.9)).toBe("working");
+    expect(resolveTier(meta(), 0.96)).toBe("core");
+    expect(resolveTier(meta(), 0.5)).toBe("peripheral");
+  });
+
+  it("不传 entry.importance 时退回 0——这正是修复前的行为", () => {
+    // 保持向后兼容：老调用方不传就还是老结果，不会炸
+    expect(resolveTier(meta(), undefined)).toBe("peripheral");
+    expect(resolveTier(meta())).toBe("peripheral");
+  });
+
+  it("显式 tier 优先，entry.importance 不能覆盖它", () => {
+    // access-tracker 算过一次就会把 tier 写进顶层，那是权威值
+    expect(resolveTier(meta({ tier: "peripheral" }), 0.99)).toBe("peripheral");
+    expect(resolveTier(meta({ tier: "core" }), 0.1)).toBe("core");
+  });
+
+  it("metadata 顶层真有 importance 时以它为准", () => {
+    // 顺序：meta.importance > entryImportance > 0
+    expect(resolveTier(meta({ importance: 0.85 }), 0.1)).toBe("working");
+  });
+
+  it("accessCount 仍走 metadata 顶层——那是 access-tracker 实际写入的位置", () => {
+    expect(resolveTier(meta({ accessCount: 10 }), 0.1)).toBe("core");
+    expect(resolveTier(meta({ accessCount: 3 }), 0.1)).toBe("working");
+  });
+
+  it("没有 metadata 或解析失败时给 peripheral", () => {
+    expect(resolveTier(undefined, 0.99)).toBe("peripheral");
+    expect(resolveTier("{ 坏掉的 json", 0.99)).toBe("peripheral");
+  });
+});
+
+describe("isDecayExempt", () => {
+  it("core + 高 importance 免衰减——importance 来自入参而非 metadata", () => {
+    // 修复前：resolveTierFromMeta 读不到 importance，tier 恒为 peripheral，
+    // 于是这条规则对没有显式 tier 的条目从来没生效过。
+    const noExplicitTier = JSON.stringify({ source: "cc", lastAccessedAt: 0 });
+    expect(isDecayExempt(noExplicitTier, 0.96)).toBe(true);
+  });
+
+  it("importance 不够高时不豁免", () => {
+    const noExplicitTier = JSON.stringify({ source: "cc", lastAccessedAt: 0 });
+    expect(isDecayExempt(noExplicitTier, 0.9)).toBe(false);
+  });
+});

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