@desplega.ai/agent-swarm 1.110.0 → 1.111.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.110.0",
+  "version": "1.111.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/be/memory/constants.ts

@@ -65,6 +65,13 @@ export function isHybridSearchEnabled(): boolean {
   return val === "1" || val.toLowerCase() === "true";
 }
 
+// Feature flag: expand search candidates with 1-hop memory_link graph neighbors
+// (DES-639a). Off by default; set MEMORY_GRAPH_EXPANSION=1 to enable.
+export function isGraphExpansionEnabled(): boolean {
+  const val = process.env.MEMORY_GRAPH_EXPANSION ?? "0";
+  return val === "1" || val.toLowerCase() === "true";
+}
+
 // Embedding defaults
 export const EMBEDDING_DIMENSIONS = numEnv("EMBEDDING_DIMENSIONS", 512);
 export const DEFAULT_EMBEDDING_DIMENSIONS = EMBEDDING_DIMENSIONS;

package/src/be/memory/graph-expansion.ts

@@ -0,0 +1,167 @@
+/**
+ * Graph candidate expansion (DES-639a) — the first READER of `memory_link`.
+ *
+ * Expands a search candidate set with 1-hop outgoing `memory_link` neighbors
+ * (`targetKind='memory'` rows whose targetId resolves to a real, non-expired
+ * memory), so a memory linked from a strong hit can surface in results it
+ * would never reach by similarity alone.
+ *
+ * Runs at the seam between `store.search()` and `rerank()` at both call sites
+ * (`POST /api/memory/search` and the `memory-search` MCP tool), so:
+ * - all four retrieval arms (vec/fts/hybrid/fallback) get expansion,
+ * - `rerank()` stays pure (no DB access),
+ * - `recordRetrievals` downstream picks up `retrievalSource: "graph"` for free.
+ *
+ * Flag-gated: `MEMORY_GRAPH_EXPANSION=1|true` (default off — same rollout
+ * pattern as MEMORY_HYBRID_SEARCH). With the flag off the input array is
+ * returned unchanged (same reference), keeping results byte-identical.
+ *
+ * Plan: thoughts/taras/plans/2026-07-02-memory-retrieval-v2-graph-and-measurement.md Phase 4
+ */
+import { getDb } from "@/be/db";
+import type { AgentMemorySource } from "@/types";
+import { isGraphExpansionEnabled } from "./constants";
+import { type AgentMemoryRow, rowToCandidate } from "./providers/sqlite-store";
+import { computeScore } from "./reranker";
+import type { MemoryCandidate } from "./types";
+
+export interface GraphExpansionOptions {
+  /** Max NEW candidates added (replacing an existing candidate doesn't count). Default 5. */
+  cap?: number;
+  /** Per-hop score damping: neighborSim = parentSim × link.strength × damping. Default 0.7. */
+  damping?: number;
+  /** Scope the search ran with — neighbor visibility mirrors the search ACL. Default "all". */
+  scope?: "agent" | "swarm" | "all";
+  /** Source filter the search ran with — expansion must not add off-filter rows. */
+  source?: AgentMemorySource;
+  isLead?: boolean;
+}
+
+type NeighborRow = AgentMemoryRow & { fromMemoryId: string; linkStrength: number | null };
+
+/**
+ * Mirrors `SqliteMemoryStore.addScopeConditions` (private) for the `m` alias:
+ * non-lead callers see own-agent rows + swarm-scoped rows; leads see all.
+ */
+function addNeighborScopeConditions(
+  conditions: string[],
+  params: (string | number)[],
+  agentId: string,
+  scope: "agent" | "swarm" | "all",
+  isLead: boolean,
+): void {
+  if (!isLead) {
+    if (scope === "agent") {
+      conditions.push("m.agentId = ? AND m.scope = 'agent'");
+      params.push(agentId);
+    } else if (scope === "swarm") {
+      conditions.push("m.scope = 'swarm'");
+    } else {
+      conditions.push("(m.agentId = ? OR m.scope = 'swarm')");
+      params.push(agentId);
+    }
+  } else {
+    if (scope === "agent") {
+      conditions.push("m.scope = 'agent'");
+    } else if (scope === "swarm") {
+      conditions.push("m.scope = 'swarm'");
+    }
+  }
+}
+
+export function expandCandidatesWithGraph(
+  candidates: MemoryCandidate[],
+  agentId: string,
+  options: GraphExpansionOptions = {},
+): MemoryCandidate[] {
+  if (!isGraphExpansionEnabled()) return candidates;
+  const { cap = 5, damping = 0.7, scope = "all", source, isLead = false } = options;
+  if (candidates.length === 0 || cap <= 0) return candidates;
+
+  const parentById = new Map(candidates.map((c) => [c.id, c]));
+  const parentIds = [...parentById.keys()];
+
+  // Outgoing memory→memory links whose targetId JOINs to a live agent_memory
+  // row. Unresolved wikilinks keep the raw `[[Name]]` text as targetId
+  // (link-resolver.ts) and therefore never match an id — the JOIN skips them.
+  const conditions: string[] = [
+    `ml.from_memory_id IN (${parentIds.map(() => "?").join(", ")})`,
+    "ml.targetKind = 'memory'",
+    "(m.expiresAt IS NULL OR m.expiresAt > datetime('now'))",
+  ];
+  const params: (string | number)[] = [...parentIds];
+  addNeighborScopeConditions(conditions, params, agentId, scope, isLead);
+  if (source) {
+    conditions.push("m.source = ?");
+    params.push(source);
+  }
+
+  let rows: NeighborRow[];
+  try {
+    rows = getDb()
+      .prepare<NeighborRow, (string | number)[]>(
+        `SELECT m.*, ml.from_memory_id AS fromMemoryId, ml.strength AS linkStrength
+         FROM memory_link ml
+         JOIN agent_memory m ON m.id = ml.targetId
+         WHERE ${conditions.join(" AND ")}`,
+      )
+      .all(...params);
+  } catch (err) {
+    // Best-effort: a graph-expansion failure must never poison search.
+    console.warn("[memory-graph] expansion query failed:", (err as Error).message);
+    return candidates;
+  }
+  if (rows.length === 0) return candidates;
+
+  // Best derived score per neighbor (a neighbor may be linked from several parents).
+  const neighbors = new Map<string, MemoryCandidate>();
+  for (const row of rows) {
+    const parent = parentById.get(row.fromMemoryId);
+    if (!parent) continue;
+    const strength = typeof row.linkStrength === "number" ? row.linkStrength : 1.0;
+    // Derive from the parent's RAW (pre-decay) similarity — fts/hybrid arms
+    // ship `similarity` with the parent's recency decay already applied, and
+    // rerank() will apply the NEIGHBOR's own decay to this candidate. Using
+    // the decayed value would stack two decay factors on one score.
+    const parentBase = parent.rawSimilarity ?? parent.similarity;
+    const similarity = parentBase * strength * damping;
+    const existing = neighbors.get(row.id);
+    if (existing && existing.similarity >= similarity) continue;
+    neighbors.set(row.id, {
+      ...rowToCandidate(row, similarity),
+      retrievalSource: "graph",
+      // The neighbor's own decay is applied exactly once by rerank().
+      recencyDecayApplied: false,
+    });
+  }
+  if (neighbors.size === 0) return candidates;
+
+  const result = [...candidates];
+  const indexById = new Map(result.map((c, i) => [c.id, i] as const));
+  let added = 0;
+  // Rank and compare via the reranker's composite score (recency decay,
+  // source quality, access, usefulness), NOT the raw similarity: cap selection
+  // by raw score would let stale low-value links crowd out neighbors the
+  // reranker would place higher, and organic fts/hybrid duplicates carry an
+  // already-decayed similarity that a raw comparison would mis-rank against
+  // the graph entry's deliberately pre-decay score.
+  const now = new Date();
+  const ranked = [...neighbors.values()].sort(
+    (a, b) => computeScore(b, now) - computeScore(a, now),
+  );
+  for (const neighbor of ranked) {
+    const existingIndex = indexById.get(neighbor.id);
+    if (existingIndex !== undefined) {
+      // Dedupe against organic candidates: keep whichever entry the reranker
+      // will score higher (same memory, so all non-similarity factors match).
+      if (computeScore(neighbor, now) > computeScore(result[existingIndex]!, now)) {
+        result[existingIndex] = neighbor;
+      }
+      continue;
+    }
+    if (added >= cap) continue;
+    result.push(neighbor);
+    added += 1;
+  }
+  return result;
+}

package/src/be/memory/link-resolver.ts

@@ -183,6 +183,30 @@ export function resolveWikilinksToMemoryIds(
   });
 }
 
+const INSERT_LINK_SQL = `INSERT OR IGNORE INTO memory_link
+   (id, from_memory_id, linkType, targetKind, targetId, strength, resolver, sourceText, metadata, createdAt, updatedAt)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+
+function insertLinkArgs(
+  memoryId: string,
+  link: ResolvedLink,
+  now: string,
+): [string, string, string, string, string, number, string, string, string | null, string, string] {
+  return [
+    crypto.randomUUID(),
+    memoryId,
+    link.linkType,
+    link.targetKind,
+    link.targetId,
+    link.strength,
+    link.resolver,
+    link.sourceText,
+    link.metadata ? JSON.stringify(link.metadata) : null,
+    now,
+    now,
+  ];
+}
+
 export function storeLinks(memoryId: string, agentId: string, content: string): void {
   const links = resolveLinks(content);
   if (links.length === 0) return;
@@ -190,27 +214,67 @@ export function storeLinks(memoryId: string, agentId: string, content: string):
   const resolved = resolveWikilinksToMemoryIds(agentId, links);
   const db = getDb();
   const now = new Date().toISOString();
-  const insert = db.prepare(
-    `INSERT OR IGNORE INTO memory_link
-       (id, from_memory_id, linkType, targetKind, targetId, strength, resolver, sourceText, metadata, createdAt, updatedAt)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  const insert = db.prepare(INSERT_LINK_SQL);
+
+  db.transaction(() => {
+    for (const link of resolved) {
+      insert.run(...insertLinkArgs(memoryId, link, now));
+    }
+  })();
+}
+
+/** The `memory_link` UNIQUE-constraint identity — the natural diff key for pruning. */
+function linkIdentity(link: {
+  linkType: string;
+  targetKind: string;
+  targetId: string;
+  sourceText: string | null;
+}): string {
+  return JSON.stringify([link.linkType, link.targetKind, link.targetId, link.sourceText ?? null]);
+}
+
+/**
+ * Re-derive content links on the EDIT/RE-INDEX paths (DES-639b).
+ *
+ * Unlike the additive `storeLinks`, this prunes: in one transaction it
+ * deletes content-derived rows (`linkType != 'sequel'`) whose UNIQUE identity
+ * (linkType, targetKind, targetId, sourceText) is absent from the new
+ * content's resolved set, then INSERT OR IGNOREs the new set. `sequel` links
+ * are preserved — they are created by `storeSequelLink` (resolver
+ * 'sequel-auto') and are not derivable from content. Fresh-store paths keep
+ * plain `storeLinks`.
+ */
+export function refreshLinks(memoryId: string, agentId: string, content: string): void {
+  const resolved = resolveWikilinksToMemoryIds(agentId, resolveLinks(content));
+  const nextIdentities = new Set(resolved.map((link) => linkIdentity(link)));
+
+  const db = getDb();
+  const now = new Date().toISOString();
+  const selectExisting = db.prepare<
+    {
+      id: string;
+      linkType: string;
+      targetKind: string;
+      targetId: string;
+      sourceText: string | null;
+    },
+    [string]
+  >(
+    `SELECT id, linkType, targetKind, targetId, sourceText
+       FROM memory_link
+      WHERE from_memory_id = ? AND linkType != 'sequel'`,
   );
+  const deleteById = db.prepare("DELETE FROM memory_link WHERE id = ?");
+  const insert = db.prepare(INSERT_LINK_SQL);
 
   db.transaction(() => {
+    for (const row of selectExisting.all(memoryId)) {
+      if (!nextIdentities.has(linkIdentity(row))) {
+        deleteById.run(row.id);
+      }
+    }
     for (const link of resolved) {
-      insert.run(
-        crypto.randomUUID(),
-        memoryId,
-        link.linkType,
-        link.targetKind,
-        link.targetId,
-        link.strength,
-        link.resolver,
-        link.sourceText,
-        link.metadata ? JSON.stringify(link.metadata) : null,
-        now,
-        now,
-      );
+      insert.run(...insertLinkArgs(memoryId, link, now));
     }
   })();
 }

package/src/be/memory/links-store.ts

@@ -0,0 +1,208 @@
+/**
+ * Read-side query helpers for the `memory_link` table (DES-639b).
+ *
+ * The write path lives in `src/be/memory/link-resolver.ts` (`storeLinks` /
+ * `refreshLinks` / `storeSequelLink`). This module surfaces traversal reads
+ * to the memory-get surfaces (`GET /api/memory/{id}` and the `memory-get`
+ * MCP tool): outgoing links plus inbound `targetKind='memory'` rows as a
+ * `backlinks` array (same table, cheap).
+ *
+ * Visibility mirrors the search ACL (see `graph-expansion.ts`): non-lead
+ * viewers see own-agent + swarm-scoped linked memories; leads see all.
+ * `memory_link.targetId` has no FK — dangling rows (target deleted, or a
+ * wikilink that never resolved past its raw name text) come back with
+ * `resolved: false` and no target metadata, indistinguishable from targets
+ * the viewer may not see, so nothing leaks. Server-side only.
+ */
+import { getDb } from "@/be/db";
+import type { LinkType, TargetKind } from "./link-resolver";
+
+/** Minimal metadata about a linked/backlinking memory — enough to memory-get it. */
+export interface LinkedMemoryRef {
+  id: string;
+  name: string;
+  scope: string;
+}
+
+export interface MemoryLinkView {
+  id: string;
+  linkType: LinkType;
+  targetKind: TargetKind;
+  targetId: string;
+  strength: number;
+  resolver: string;
+  sourceText: string | null;
+  createdAt: string;
+  /**
+   * For `targetKind='memory'`: true when targetId points at a live memory the
+   * viewer may see. Non-memory kinds (pr, agent-fs-file, …) are always true —
+   * their targetId is already the resolved external identity.
+   */
+  resolved: boolean;
+  /** Present only when `resolved` and `targetKind='memory'`. */
+  target?: LinkedMemoryRef;
+}
+
+export interface MemoryBacklinkView {
+  id: string;
+  linkType: LinkType;
+  strength: number;
+  sourceText: string | null;
+  createdAt: string;
+  /** The memory whose content links here. Always visible to the viewer (ACL-filtered). */
+  from: LinkedMemoryRef;
+}
+
+export interface MemoryLinksResult {
+  links: MemoryLinkView[];
+  backlinks: MemoryBacklinkView[];
+}
+
+export interface GetLinksOptions {
+  /** The requesting agent; undefined = anonymous (swarm-scoped visibility only). */
+  viewerAgentId?: string;
+  /** Leads see all linked-memory metadata regardless of scope. Default false. */
+  isLead?: boolean;
+}
+
+type OutgoingRow = {
+  id: string;
+  linkType: LinkType;
+  targetKind: TargetKind;
+  targetId: string;
+  strength: number;
+  resolver: string;
+  sourceText: string | null;
+  createdAt: string;
+  targetMemoryId: string | null;
+  targetName: string | null;
+  targetScope: string | null;
+  targetAgentId: string | null;
+};
+
+type BacklinkRow = {
+  id: string;
+  linkType: LinkType;
+  strength: number;
+  sourceText: string | null;
+  createdAt: string;
+  fromId: string;
+  fromName: string;
+  fromScope: string;
+};
+
+/** Hidden-target redaction: `[[Name]]` sourceText → `Name` (the unresolved-row form); anything else → "". */
+function redactedTargetId(sourceText: string | null): string {
+  const wikilink = /^\[\[(.+)\]\]$/.exec(sourceText ?? "");
+  return wikilink?.[1] ?? "";
+}
+
+export function getLinksForMemory(
+  memoryId: string,
+  options: GetLinksOptions = {},
+): MemoryLinksResult {
+  const { viewerAgentId, isLead = false } = options;
+  const db = getDb();
+
+  // Outgoing links. The LEFT JOIN resolves memory-kind targets to a live
+  // agent_memory row; dangling/unresolved/expired targets join to NULL.
+  const outgoing = db
+    .prepare<OutgoingRow, [string]>(
+      `SELECT ml.id, ml.linkType, ml.targetKind, ml.targetId, ml.strength,
+              ml.resolver, ml.sourceText, ml.createdAt,
+              m.id AS targetMemoryId, m.name AS targetName,
+              m.scope AS targetScope, m.agentId AS targetAgentId
+         FROM memory_link ml
+         LEFT JOIN agent_memory m
+           ON ml.targetKind = 'memory'
+          AND m.id = ml.targetId
+          AND (m.expiresAt IS NULL OR m.expiresAt > datetime('now'))
+        WHERE ml.from_memory_id = ?
+        ORDER BY ml.createdAt ASC, ml.id ASC`,
+    )
+    .all(memoryId);
+
+  const links: MemoryLinkView[] = outgoing.map((row) => {
+    if (row.targetKind !== "memory") {
+      return {
+        id: row.id,
+        linkType: row.linkType,
+        targetKind: row.targetKind,
+        targetId: row.targetId,
+        strength: row.strength,
+        resolver: row.resolver,
+        sourceText: row.sourceText,
+        createdAt: row.createdAt,
+        resolved: true,
+      };
+    }
+    const live = row.targetMemoryId !== null;
+    const visible =
+      live &&
+      (isLead || row.targetScope === "swarm" || (row.targetAgentId ?? "") === viewerAgentId);
+    // Redact targetId for every memory-kind row the viewer can't see: exposing
+    // a stored UUID would leak private memory ids (live-but-hidden AND
+    // expired/deleted targets, which store the once-resolved UUID) and let a
+    // viewer tell those apart from a genuinely unresolved wikilink. Redact to
+    // the wikilink NAME (derived from sourceText, verbatim content of the
+    // from-memory the viewer already reads) — the exact form an unresolved row
+    // stores in targetId, so all non-visible variants look identical.
+    const base: MemoryLinkView = {
+      id: row.id,
+      linkType: row.linkType,
+      targetKind: row.targetKind,
+      targetId: visible ? row.targetId : redactedTargetId(row.sourceText),
+      strength: row.strength,
+      resolver: row.resolver,
+      sourceText: row.sourceText,
+      createdAt: row.createdAt,
+      resolved: false,
+    };
+    if (!visible) return base;
+    return {
+      ...base,
+      resolved: true,
+      target: {
+        id: row.targetMemoryId as string,
+        name: row.targetName ?? "",
+        scope: row.targetScope ?? "",
+      },
+    };
+  });
+
+  // Inbound links (backlinks): rows in the same table pointing at this memory.
+  // INNER JOIN drops rows whose source memory no longer exists; the scope
+  // condition keeps cross-agent agent-scoped sources invisible to non-leads.
+  const conditions = [
+    "ml.targetKind = 'memory'",
+    "ml.targetId = ?",
+    "(m.expiresAt IS NULL OR m.expiresAt > datetime('now'))",
+  ];
+  const params: (string | null)[] = [memoryId];
+  if (!isLead) {
+    conditions.push("(m.agentId = ? OR m.scope = 'swarm')");
+    params.push(viewerAgentId ?? null);
+  }
+
+  const inbound = db
+    .prepare<BacklinkRow, (string | null)[]>(
+      `SELECT ml.id, ml.linkType, ml.strength, ml.sourceText, ml.createdAt,
+              m.id AS fromId, m.name AS fromName, m.scope AS fromScope
+         FROM memory_link ml
+         JOIN agent_memory m ON m.id = ml.from_memory_id
+        WHERE ${conditions.join(" AND ")}
+        ORDER BY ml.createdAt ASC, ml.id ASC`,
+    )
+    .all(...params);
+
+  const backlinks: MemoryBacklinkView[] = inbound.map((row) => ({
+    id: row.id,
+    linkType: row.linkType,
+    strength: row.strength,
+    sourceText: row.sourceText,
+    createdAt: row.createdAt,
+    from: { id: row.fromId, name: row.fromName, scope: row.fromScope },
+  }));
+
+  return { links, backlinks };
+}

package/src/be/memory/providers/sqlite-store.ts

@@ -26,7 +26,7 @@ import type {
 
 const VECTOR_BYTES = EMBEDDING_DIMENSIONS * Float32Array.BYTES_PER_ELEMENT;
 
-type AgentMemoryRow = {
+export type AgentMemoryRow = {
   id: string;
   agentId: string | null;
   scope: string;
@@ -79,7 +79,7 @@ function rowToAgentMemory(row: AgentMemoryRow): AgentMemory {
   };
 }
 
-function rowToCandidate(row: AgentMemoryRow, similarity: number): MemoryCandidate {
+export function rowToCandidate(row: AgentMemoryRow, similarity: number): MemoryCandidate {
   return {
     ...rowToAgentMemory(row),
     similarity,

package/src/be/memory/raters/retrieval.ts

@@ -1,5 +1,6 @@
 import { ensure } from "@desplega.ai/business-use";
 import { getDb } from "@/be/db";
+import type { MemoryRetrievalSource } from "@/be/memory/types";
 
 /**
  * Retrieval-bridge helper — appends `memory_retrieval` audit rows so
@@ -22,7 +23,7 @@ import { getDb } from "@/be/db";
 export type RetrievalRecord = {
   memoryId: string;
   similarity: number;
-  retrievalSource?: "vec" | "fts" | "hybrid" | "fallback";
+  retrievalSource?: MemoryRetrievalSource;
 };
 
 export type RetrievalExtras = {

package/src/be/memory/types.ts

@@ -76,7 +76,7 @@ export interface MemoryCandidate extends AgentMemory {
   beta: number;
 }
 
-export type MemoryRetrievalSource = "vec" | "fts" | "hybrid" | "fallback";
+export type MemoryRetrievalSource = "vec" | "fts" | "hybrid" | "fallback" | "graph";
 
 export interface MemorySearchOptions {
   scope?: "agent" | "swarm" | "all";