@desplega.ai/agent-swarm 1.157.0 → 1.158.0

package/src/tests/memory-hybrid.test.ts

@@ -1,7 +1,14 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { unlink } from "node:fs/promises";
 import { closeDb, createAgent, getDbClient, initDb } from "../be/db";
-import { computeRrfScore, SqliteMemoryStore } from "../be/memory/providers/sqlite-store";
+import { expandCandidatesWithGraph } from "../be/memory/graph-expansion";
+import {
+  computeRrfScore,
+  fusedSimilarity,
+  SqliteMemoryStore,
+} from "../be/memory/providers/sqlite-store";
+import { rerank } from "../be/memory/reranker";
+import { memoryRelevance, renderMemoriesPrompt, SIMILARITY_THRESHOLD } from "../prompts/memories";
 
 const TEST_DB_PATH = "./test-memory-hybrid.sqlite";
 const agentId = "aaaa0000-0000-4000-8000-000000000101";
@@ -213,3 +220,156 @@ describe("memory hybrid search", () => {
     expect(freshIndex).toBeLessThan(staleIndex);
   });
 });
+
+describe("fusedSimilarity", () => {
+  test("keeps the vec arm's [0,1] cosine scale", () => {
+    const both = computeRrfScore(0, 1.0) * 2;
+    expect(fusedSimilarity(0.8, both)).toBeCloseTo(0.8, 6);
+    expect(fusedSimilarity(0.8, computeRrfScore(0, 1.0))).toBeCloseTo(0.6, 6);
+    expect(fusedSimilarity(0.8, computeRrfScore(99, 1.0))).toBeGreaterThan(0.4);
+    expect(fusedSimilarity(1, both)).toBeLessThanOrEqual(1);
+  });
+});
+
+// Score-scale regression: every arm must land on one [0,1] scale before
+// rerank, and the injection gate must read that scale, not the boosted
+// composite. Before the fix a hybrid hit scored ~0.033 (raw RRF) while a graph
+// neighbour scored parentCosine × 0.7, so neighbours outranked the hit that
+// surfaced them and an unrelated vec-only query cleared the 0.4 composite gate.
+describe("memory search score scale", () => {
+  const scaleAgentId = "aaaa0000-0000-4000-8000-000000000102";
+  let store: SqliteMemoryStore;
+  let prevHybridFlag: string | undefined;
+  let exactId: string;
+  let siblingId: string;
+  let neighborId: string;
+
+  /** Unit vector: `cos` on axis 2 (the query axis), the remainder on `axis`. */
+  function mix(cos: number, axis: number): Float32Array {
+    const embedding = new Float32Array(512);
+    embedding[2] = cos;
+    embedding[axis] = Math.sqrt(1 - cos * cos);
+    return embedding;
+  }
+
+  const queryAxis = mix(1, 3);
+
+  async function searchRanked(queryEmbedding: Float32Array, queryText: string) {
+    const candidates = await store.search(queryEmbedding, scaleAgentId, {
+      scope: "agent",
+      limit: 15,
+      queryText,
+    });
+    const expanded = await expandCandidatesWithGraph(candidates, scaleAgentId, { scope: "agent" });
+    return rerank(expanded, { limit: 5 });
+  }
+
+  beforeAll(async () => {
+    prevHybridFlag = process.env.MEMORY_HYBRID_SEARCH;
+    process.env.MEMORY_HYBRID_SEARCH = "1";
+    await createAgent({
+      id: scaleAgentId,
+      name: "Scale Test Agent",
+      isLead: false,
+      status: "idle",
+    });
+    store = new SqliteMemoryStore();
+
+    const exact = await store.store({
+      agentId: scaleAgentId,
+      scope: "agent",
+      name: "blockerdigestexactname",
+      content: "Daily blocker digest for one specific day.",
+      source: "manual",
+    });
+    const sibling = await store.store({
+      agentId: scaleAgentId,
+      scope: "agent",
+      name: "digest for another day",
+      content: "Daily blocker digest for a different day.",
+      source: "manual",
+    });
+    const neighbor = await store.store({
+      agentId: scaleAgentId,
+      scope: "agent",
+      name: "linked follow-up",
+      content: "Follow-up linked from the digest.",
+      source: "manual",
+    });
+    exactId = exact.id;
+    siblingId = sibling.id;
+    neighborId = neighbor.id;
+    // The sibling is semantically CLOSER than the exact hit (as dated siblings
+    // are in production); only the keyword arm can put the exact name first.
+    await store.updateEmbedding(exactId, mix(0.7, 4), "test");
+    await store.updateEmbedding(siblingId, mix(0.72, 5), "test");
+    await store.updateEmbedding(neighborId, mix(0.2, 6), "test");
+    const now = new Date().toISOString();
+    await getDbClient().run(
+      `INSERT INTO memory_link
+         (id, from_memory_id, linkType, targetKind, targetId, strength, resolver, sourceText, metadata, createdAt, updatedAt)
+       VALUES (?, ?, 'wikilink', 'memory', ?, 1.0, 'wikilink', 'follow-up', NULL, ?, ?)`,
+      [crypto.randomUUID(), exactId, neighborId, now, now],
+    );
+  });
+
+  afterAll(() => {
+    if (prevHybridFlag === undefined) delete process.env.MEMORY_HYBRID_SEARCH;
+    else process.env.MEMORY_HYBRID_SEARCH = prevHybridFlag;
+  });
+
+  test("hybrid arm emits a [0,1] score instead of raw RRF", async () => {
+    const candidates = await store.search(queryAxis, scaleAgentId, {
+      scope: "agent",
+      limit: 10,
+      queryText: "blockerdigestexactname",
+    });
+    const exact = candidates.find((c) => c.id === exactId);
+    expect(exact?.retrievalSource).toBe("hybrid");
+    expect(exact!.similarity).toBeGreaterThan(0.6);
+    expect(exact!.similarity).toBeLessThanOrEqual(0.7);
+    expect(exact!.rawSimilarity).toBe(exact!.similarity);
+    expect(exact!.recencyDecayApplied).toBe(false);
+  });
+
+  test("exact-name direct hit outranks its graph neighbour and the closer sibling", async () => {
+    const ranked = await searchRanked(queryAxis, "blockerdigestexactname");
+    const ids = ranked.map((r) => r.id);
+    expect(ids[0]).toBe(exactId);
+    const neighbor = ranked.find((r) => r.id === neighborId);
+    expect(neighbor?.retrievalSource).toBe("graph");
+    expect(ids.indexOf(exactId)).toBeLessThan(ids.indexOf(neighborId));
+    expect(ids.indexOf(exactId)).toBeLessThan(ids.indexOf(siblingId));
+  });
+
+  test("a hybrid direct hit clears the injection threshold; its graph neighbour does not", async () => {
+    const ranked = await searchRanked(queryAxis, "blockerdigestexactname");
+    const exact = ranked.find((r) => r.id === exactId)!;
+    const neighbor = ranked.find((r) => r.id === neighborId)!;
+    expect(memoryRelevance(exact)).toBeGreaterThan(SIMILARITY_THRESHOLD);
+    expect(memoryRelevance(neighbor)).toBeLessThan(SIMILARITY_THRESHOLD);
+    const prompt = renderMemoriesPrompt(ranked);
+    expect(prompt).toContain(exactId);
+    expect(prompt).not.toContain(neighborId);
+  });
+
+  test("a vec-only direct hit (no keyword match) clears the injection threshold", async () => {
+    const ranked = await searchRanked(mix(0.99, 5), "paraphrasednokeywordmatch");
+    const sibling = ranked.find((r) => r.id === siblingId)!;
+    expect(sibling.retrievalSource).toBe("vec");
+    expect(memoryRelevance(sibling)).toBeGreaterThan(SIMILARITY_THRESHOLD);
+  });
+
+  test("negative control: a nonexistent-name query injects nothing", async () => {
+    // Best cosine ~0.33, the production level for an unrelated query. The old
+    // path returned it raw and rerank's 1.5x manual boost lifted it to ~0.5,
+    // over the old 0.4 composite gate.
+    const unrelated = new Float32Array(512);
+    unrelated[2] = 0.46;
+    unrelated[7] = Math.sqrt(1 - 0.46 ** 2);
+    const ranked = await searchRanked(unrelated, "blockerdigest-2031-01-01-nonexistent");
+    expect(ranked.length).toBeGreaterThan(0);
+    for (const r of ranked) expect(memoryRelevance(r)).toBeLessThan(SIMILARITY_THRESHOLD);
+    expect(renderMemoriesPrompt(ranked)).toBeNull();
+  });
+});

package/src/tests/memory-prompt-recall-crowdout.test.ts

@@ -0,0 +1,297 @@
+import { afterAll, beforeAll, describe, expect, mock, test } from "bun:test";
+import { randomUUID } from "node:crypto";
+import { unlink } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Readable } from "node:stream";
+import { closeDb, createAgent, getDbClient, initDb } from "../be/db";
+import * as realMemoryModule from "../be/memory";
+import { expandCandidatesWithGraph } from "../be/memory/graph-expansion";
+import { SqliteMemoryStore } from "../be/memory/providers/sqlite-store";
+import { rerank } from "../be/memory/reranker";
+import { memoryRelevance, renderMemoriesPrompt, SIMILARITY_THRESHOLD } from "../prompts/memories";
+
+// Crowd-out regression (PR #1689 review): graph neighbours get their own
+// access and source boosts, so five boosted neighbours of one direct hit
+// out-scored it on the composite, filled all five slots of the runner's
+// `limit: 5` recall, and all failed the relevance gate. The rendered prompt
+// was null while an eligible direct hit existed. Everything below the query
+// embedding is real: SQLite store, hybrid fusion, graph expansion, reranker,
+// the HTTP handler's selection, and the runner's prompt renderer.
+
+// Capture the real exports BEFORE mock.module patches the registry entry.
+const realMemoryExports = {
+  getEmbeddingProvider: realMemoryModule.getEmbeddingProvider,
+  getMemoryStore: realMemoryModule.getMemoryStore,
+};
+
+const TEST_DB_PATH = "./test-memory-prompt-recall-crowdout.sqlite";
+const agentId = randomUUID();
+const sourceTaskId = randomUUID();
+const PARENT_NAME = "crowdoutparentexactname";
+const NEIGHBOR_COUNT = 5;
+
+/** Unit vector: `cos` on axis 2 (the query axis), the remainder on `axis`. */
+function mix(cos: number, axis: number): Float32Array {
+  const embedding = new Float32Array(512);
+  embedding[2] = cos;
+  embedding[axis] = Math.sqrt(1 - cos * cos);
+  return embedding;
+}
+
+const queryEmbedding = mix(1, 3);
+
+mock.module("../be/memory", () => ({
+  getEmbeddingProvider: () => ({
+    name: "test",
+    dimensions: 512,
+    embed: async () => queryEmbedding,
+    embedBatch: async (texts: string[]) => texts.map(() => queryEmbedding),
+  }),
+  getMemoryStore: () => new SqliteMemoryStore(),
+}));
+
+const { handleMemory } = await import("../http/memory");
+
+let parentId: string;
+const neighborIds: string[] = [];
+let prevHybridFlag: string | undefined;
+
+async function promptRecall(
+  callerAgentId: string = agentId,
+  query: string = PARENT_NAME,
+): Promise<{
+  results: Array<{
+    id: string;
+    name: string;
+    content: string;
+    similarity: number;
+    rawSimilarity?: number;
+    retrievalSource?: string;
+  }>;
+}> {
+  // Byte-for-byte the runner's pre-task recall request (fetchRelevantMemories).
+  const body = { query, limit: 5, intent: "pre-task memory recall" };
+  const req = Readable.from([Buffer.from(JSON.stringify(body))]) as IncomingMessage;
+  req.method = "POST";
+  req.url = "/api/memory/search";
+  req.headers = {
+    "x-source-task-id": sourceTaskId,
+    "x-context-key": "task:crowdout",
+    "x-memory-consumption": "prompt",
+  };
+  let payload: any = null;
+  const res = {
+    writeHead() {
+      return this;
+    },
+    end(chunk?: unknown) {
+      payload = typeof chunk === "string" ? JSON.parse(chunk) : chunk;
+      return this;
+    },
+  } as unknown as ServerResponse;
+  const handled = await handleMemory(req, res, ["api", "memory", "search"], callerAgentId);
+  expect(handled).toBe(true);
+  return payload;
+}
+
+beforeAll(async () => {
+  prevHybridFlag = process.env.MEMORY_HYBRID_SEARCH;
+  process.env.MEMORY_HYBRID_SEARCH = "1";
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(TEST_DB_PATH + suffix);
+    } catch {}
+  }
+  initDb(TEST_DB_PATH);
+  await createAgent({ id: agentId, name: "Crowd-out Agent", isLead: false, status: "idle" });
+  const nowIso = new Date().toISOString();
+  await getDbClient().run(
+    `INSERT INTO agent_tasks (id, agentId, task, status, source, createdAt, lastUpdatedAt)
+       VALUES (?, ?, ?, 'in_progress', 'mcp', ?, ?)`,
+    [sourceTaskId, agentId, "crowd-out recall task", nowIso, nowIso],
+  );
+
+  const store = new SqliteMemoryStore();
+  // Fresh manual parent, cosine 0.7, matched by both arms, never accessed.
+  const parent = await store.store({
+    agentId,
+    scope: "agent",
+    name: PARENT_NAME,
+    content: "The direct hit this recall is looking for.",
+    source: "manual",
+  });
+  parentId = parent.id;
+  await store.updateEmbedding(parentId, mix(0.7, 4), "test");
+
+  // Five fresh manual neighbours, each linked at strength 1 and independently
+  // boosted by five recent accesses. Their own cosine is low; only the graph
+  // arm can surface them.
+  for (let i = 0; i < NEIGHBOR_COUNT; i++) {
+    const neighbor = await store.store({
+      agentId,
+      scope: "agent",
+      name: `linked note ${i}`,
+      content: `Linked follow-up note number ${i}.`,
+      source: "manual",
+    });
+    neighborIds.push(neighbor.id);
+    await store.updateEmbedding(neighbor.id, mix(0.1, 10 + i), "test");
+    await getDbClient().run(
+      `INSERT INTO memory_link
+         (id, from_memory_id, linkType, targetKind, targetId, strength, resolver, sourceText, metadata, createdAt, updatedAt)
+       VALUES (?, ?, 'wikilink', 'memory', ?, 1.0, 'wikilink', ?, NULL, ?, ?)`,
+      [randomUUID(), parentId, neighbor.id, `note ${i}`, nowIso, nowIso],
+    );
+  }
+});
+
+afterAll(async () => {
+  // bun's mock.module is process-global and never auto-restored.
+  mock.module("../be/memory", () => realMemoryExports);
+  if (prevHybridFlag === undefined) delete process.env.MEMORY_HYBRID_SEARCH;
+  else process.env.MEMORY_HYBRID_SEARCH = prevHybridFlag;
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(TEST_DB_PATH + suffix);
+    } catch {}
+  }
+});
+
+describe("pre-task recall with independently boosted graph neighbours", () => {
+  // Set boosts before each test: prompt recall records accesses on the rows it
+  // injects, so a previous test would otherwise shift the fixture.
+  async function boostFixture(): Promise<void> {
+    const nowIso = new Date().toISOString();
+    await getDbClient().run(
+      "UPDATE agent_memory SET accessCount = 0, accessedAt = ? WHERE id = ?",
+      [nowIso, parentId],
+    );
+    for (const id of neighborIds) {
+      await getDbClient().run(
+        "UPDATE agent_memory SET accessCount = 5, accessedAt = ? WHERE id = ?",
+        [nowIso, id],
+      );
+    }
+  }
+
+  test("fixture reproduces the review: the neighbours alone out-score the eligible parent", async () => {
+    await boostFixture();
+    const candidates = await new SqliteMemoryStore().search(queryEmbedding, agentId, {
+      scope: "all",
+      limit: 15,
+      queryText: PARENT_NAME,
+    });
+    const expanded = await expandCandidatesWithGraph(candidates, agentId, { scope: "all" });
+    const scored = expanded.map((c) => ({ c, score: rerank([c], { limit: 1 })[0]! }));
+    const parent = scored.find((s) => s.c.id === parentId)!;
+    const neighbors = scored.filter((s) => neighborIds.includes(s.c.id));
+
+    expect(parent.c.retrievalSource).toBe("hybrid");
+    expect(memoryRelevance(parent.score)).toBeGreaterThan(SIMILARITY_THRESHOLD);
+    expect(neighbors).toHaveLength(NEIGHBOR_COUNT);
+    for (const n of neighbors) {
+      expect(n.c.retrievalSource).toBe("graph");
+      expect(memoryRelevance(n.score)).toBeLessThan(SIMILARITY_THRESHOLD);
+      // Scored in isolation, each neighbour's boosted composite beats the parent's.
+      expect(n.score.compositeScore!).toBeGreaterThan(parent.score.compositeScore!);
+    }
+  });
+
+  test("a parent outranks its own boosted graph neighbours in the reranked top five", async () => {
+    await boostFixture();
+    const candidates = await new SqliteMemoryStore().search(queryEmbedding, agentId, {
+      scope: "all",
+      limit: 15,
+      queryText: PARENT_NAME,
+    });
+    const expanded = await expandCandidatesWithGraph(candidates, agentId, { scope: "all" });
+    const ranked = rerank(expanded, { limit: 5 });
+    expect(ranked[0]!.id).toBe(parentId);
+    const parentScore = ranked[0]!.compositeScore!;
+    for (const r of ranked.slice(1)) {
+      if (neighborIds.includes(r.id)) expect(r.compositeScore!).toBeLessThanOrEqual(parentScore);
+    }
+  });
+
+  test("the runner's five-slot prompt recall injects the parent instead of rendering null", async () => {
+    await boostFixture();
+    const { results } = await promptRecall();
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.length).toBeLessThanOrEqual(5);
+    expect(results[0]!.id).toBe(parentId);
+
+    const prompt = renderMemoriesPrompt(results);
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain(parentId);
+    for (const id of neighborIds) expect(prompt).not.toContain(id);
+
+    const recorded = await getDbClient().query<{ memoryId: string; relevance: number | null }>(
+      "SELECT memoryId, relevance FROM memory_retrieval WHERE taskId = ?",
+      [sourceTaskId],
+    );
+    expect(recorded.map((r) => r.memoryId)).toContain(parentId);
+    const access = await getDbClient().get<{ accessCount: number }>(
+      "SELECT accessCount FROM agent_memory WHERE id = ?",
+      [parentId],
+    );
+    expect(access!.accessCount).toBe(1);
+  });
+
+  test("boosted low-relevance direct rows do not take the slots of an eligible hit", async () => {
+    // No graph here: an eligible task_completion hit (0.7x source quality)
+    // against five manual rows that match only on the vector arm and carry
+    // five recent accesses each. The composite puts all five above the hit;
+    // the prompt selection must still give the hit a slot.
+    const otherAgentId = randomUUID();
+    const hitName = "crowdoutsecondexactname";
+    await createAgent({
+      id: otherAgentId,
+      name: "Crowd-out Agent 2",
+      isLead: false,
+      status: "idle",
+    });
+    const store = new SqliteMemoryStore();
+    const hit = await store.store({
+      agentId: otherAgentId,
+      scope: "agent",
+      name: hitName,
+      content: "An eligible hit from a completed task.",
+      source: "task_completion",
+    });
+    await store.updateEmbedding(hit.id, mix(0.75, 4), "test");
+    const boostedIds: string[] = [];
+    const nowIso = new Date().toISOString();
+    for (let i = 0; i < NEIGHBOR_COUNT; i++) {
+      const row = await store.store({
+        agentId: otherAgentId,
+        scope: "agent",
+        name: `unrelated manual ${i}`,
+        content: `Loosely related manual note ${i}.`,
+        source: "manual",
+      });
+      boostedIds.push(row.id);
+      await store.updateEmbedding(row.id, mix(0.5, 20 + i), "test");
+      await getDbClient().run(
+        "UPDATE agent_memory SET accessCount = 5, accessedAt = ? WHERE id = ?",
+        [nowIso, row.id],
+      );
+    }
+
+    const candidates = await store.search(queryEmbedding, otherAgentId, {
+      scope: "all",
+      limit: 15,
+      queryText: hitName,
+    });
+    const byComposite = rerank(candidates, { limit: 5 });
+    expect(byComposite.map((r) => r.id)).not.toContain(hit.id);
+
+    const { results } = await promptRecall(otherAgentId, hitName);
+    expect(results).toHaveLength(5);
+    expect(results[0]!.id).toBe(hit.id);
+    expect(memoryRelevance(results[0]!)).toBeGreaterThan(SIMILARITY_THRESHOLD);
+    const prompt = renderMemoriesPrompt(results);
+    expect(prompt).toContain(hit.id);
+    for (const id of boostedIds) expect(prompt).not.toContain(id);
+  });
+});

package/src/tests/memory.test.ts

@@ -192,6 +192,28 @@ describe("Memory System", () => {
       }
     });
 
+    test("hard-splits a long unbroken run and terminates", () => {
+      // No separator (space, newline, ". ") in 2600 chars, as in base64 or minified JSON.
+      const run = Array.from({ length: 2600 }, (_, i) => String.fromCharCode(97 + (i % 26))).join(
+        "",
+      );
+      const chunks = chunkContent(run);
+      expect(chunks.length).toBe(2);
+      for (const chunk of chunks) {
+        expect(run).toContain(chunk.content);
+        expect(chunk.content.length).toBeLessThanOrEqual(2000);
+      }
+      expect(run.startsWith(chunks[0]!.content)).toBe(true);
+      expect(run.endsWith(chunks[1]!.content)).toBe(true);
+    });
+
+    test("terminates when an unbroken run follows normal text", () => {
+      const chunks = chunkContent(`${"word ".repeat(600)}\n\n${"x".repeat(2500)}`);
+      expect(chunks.length).toBeGreaterThan(1);
+      const xChars = chunks.reduce((n, c) => n + (c.content.match(/x/g)?.length ?? 0), 0);
+      expect(xChars).toBeGreaterThanOrEqual(2500);
+    });
+
     test("chunk indices are sequential", () => {
       const longText = "A ".repeat(3000);
       const chunks = chunkContent(longText);