@remnic/core 1.1.12 → 1.1.13

package/src/graph-dashboard-diff.ts

@@ -0,0 +1,35 @@
+import type { GraphEdge } from "./graph.js";
+import { graphEdgeKey } from "./graph-dashboard-key.js";
+import type { GraphSnapshot } from "./graph-dashboard-parser.js";
+
+export interface GraphPatch {
+  addedNodes: string[];
+  removedNodes: string[];
+  addedEdges: GraphEdge[];
+  removedEdges: GraphEdge[];
+}
+
+export function diffGraphSnapshots(previous: GraphSnapshot, next: GraphSnapshot): GraphPatch {
+  const prevNodeSet = new Set(previous.nodes.map((node) => node.id));
+  const nextNodeSet = new Set(next.nodes.map((node) => node.id));
+  const prevEdges = new Map(previous.edges.map((edge) => [graphEdgeKey(edge), edge]));
+  const nextEdges = new Map(next.edges.map((edge) => [graphEdgeKey(edge), edge]));
+
+  const addedNodes = [...nextNodeSet].filter((id) => !prevNodeSet.has(id)).sort((a, b) => a.localeCompare(b));
+  const removedNodes = [...prevNodeSet].filter((id) => !nextNodeSet.has(id)).sort((a, b) => a.localeCompare(b));
+  const addedEdges = [...nextEdges.entries()]
+    .filter(([key]) => !prevEdges.has(key))
+    .map(([, edge]) => edge)
+    .sort((a, b) => a.type.localeCompare(b.type) || a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+  const removedEdges = [...prevEdges.entries()]
+    .filter(([key]) => !nextEdges.has(key))
+    .map(([, edge]) => edge)
+    .sort((a, b) => a.type.localeCompare(b.type) || a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+
+  return {
+    addedNodes,
+    removedNodes,
+    addedEdges,
+    removedEdges,
+  };
+}

package/src/graph-dashboard-key.ts

@@ -0,0 +1,5 @@
+import type { GraphEdge } from "./graph.js";
+
+export function graphEdgeKey(edge: GraphEdge): string {
+  return `${edge.type}|${edge.from}|${edge.to}|${edge.label}|${edge.ts}`;
+}

package/src/graph-dashboard-parser.ts

@@ -0,0 +1,104 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import type { GraphEdge, GraphType } from "./graph.js";
+import { graphEdgeKey } from "./graph-dashboard-key.js";
+
+export interface GraphSnapshotNode {
+  id: string;
+}
+
+export interface GraphSnapshotStats {
+  nodes: number;
+  edges: number;
+  malformedLines: number;
+  filesMissing: GraphType[];
+}
+
+export interface GraphSnapshot {
+  generatedAt: string;
+  nodes: GraphSnapshotNode[];
+  edges: GraphEdge[];
+  stats: GraphSnapshotStats;
+}
+
+const GRAPH_TYPES: GraphType[] = ["entity", "time", "causal"];
+
+function graphFile(memoryDir: string, type: GraphType): string {
+  return path.join(memoryDir, "state", "graphs", `${type}.jsonl`);
+}
+
+function isGraphEdge(raw: unknown, expectedType: GraphType): raw is GraphEdge {
+  if (!raw || typeof raw !== "object") return false;
+  const edge = raw as Record<string, unknown>;
+  return (
+    edge.type === expectedType &&
+    typeof edge.from === "string" &&
+    edge.from.length > 0 &&
+    typeof edge.to === "string" &&
+    edge.to.length > 0 &&
+    typeof edge.weight === "number" &&
+    Number.isFinite(edge.weight) &&
+    typeof edge.label === "string" &&
+    typeof edge.ts === "string"
+  );
+}
+
+export async function graphSnapshotFromMemoryDir(memoryDir: string): Promise<GraphSnapshot> {
+  const nodes = new Set<string>();
+  const edges: GraphEdge[] = [];
+  const filesMissing: GraphType[] = [];
+  let malformedLines = 0;
+  const seenEdges = new Set<string>();
+
+  for (const type of GRAPH_TYPES) {
+    const filePath = graphFile(memoryDir, type);
+    let raw = "";
+    try {
+      raw = await readFile(filePath, "utf-8");
+    } catch {
+      filesMissing.push(type);
+      continue;
+    }
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        malformedLines += 1;
+        continue;
+      }
+      if (!isGraphEdge(parsed, type)) {
+        malformedLines += 1;
+        continue;
+      }
+      const key = graphEdgeKey(parsed);
+      if (seenEdges.has(key)) continue;
+      seenEdges.add(key);
+      edges.push(parsed);
+      nodes.add(parsed.from);
+      nodes.add(parsed.to);
+    }
+  }
+
+  const sortedEdges = edges.sort((a, b) =>
+    a.type.localeCompare(b.type) ||
+    a.from.localeCompare(b.from) ||
+    a.to.localeCompare(b.to) ||
+    a.ts.localeCompare(b.ts)
+  );
+  const sortedNodes = [...nodes].sort((a, b) => a.localeCompare(b)).map((id) => ({ id }));
+
+  return {
+    generatedAt: new Date().toISOString(),
+    nodes: sortedNodes,
+    edges: sortedEdges,
+    stats: {
+      nodes: sortedNodes.length,
+      edges: sortedEdges.length,
+      malformedLines,
+      filesMissing,
+    },
+  };
+}

package/src/graph-edge-reinforcement.ts

@@ -0,0 +1,192 @@
+/**
+ * Graph edge confidence + reinforcement primitives (issue #681, PR 1/3).
+ *
+ * Pure functions only — no I/O, no global state. The maintenance job (PR 2/3)
+ * and PageRank weighting (PR 3/3) compose these helpers.
+ *
+ * Schema:
+ *   - `confidence`   ∈ [0, 1]; missing on legacy edges, treated as 1.0.
+ *   - `lastReinforcedAt` — ISO timestamp of most recent reinforcement; missing
+ *     on legacy edges, treated as the original edge `ts`.
+ *
+ * Defaults documented here are the agreed-on starting points and may be
+ * tuned later via config. They live as named constants so call sites and
+ * tests share the same values.
+ */
+
+import type { GraphEdge } from "./graph.js";
+
+/** Default confidence bump per reinforcement event. */
+export const DEFAULT_REINFORCE_DELTA = 0.05;
+
+/** Maximum edge confidence — confidence is capped at this on reinforcement. */
+export const CONFIDENCE_CEILING = 1.0;
+
+/** Default decay window in milliseconds (90 days). */
+export const DEFAULT_DECAY_WINDOW_MS = 90 * 24 * 60 * 60 * 1000;
+
+/** Default decay floor — confidence will not drop below this purely from age. */
+export const DEFAULT_DECAY_FLOOR = 0.1;
+
+/** Default per-window decay amount (linear). */
+export const DEFAULT_DECAY_PER_WINDOW = 0.1;
+
+/**
+ * Treat a missing `confidence` on a legacy edge as 1.0.
+ * Clamps to `[0, CONFIDENCE_CEILING]` so downstream math is well-behaved.
+ */
+export function readEdgeConfidence(edge: Pick<GraphEdge, "confidence">): number {
+  const raw = edge.confidence;
+  if (raw === undefined || raw === null || !Number.isFinite(raw)) {
+    return CONFIDENCE_CEILING;
+  }
+  if (raw < 0) return 0;
+  if (raw > CONFIDENCE_CEILING) return CONFIDENCE_CEILING;
+  return raw;
+}
+
+/**
+ * Resolve the reference timestamp for decay calculations.
+ * Falls back to the edge's creation `ts` when `lastReinforcedAt` is absent
+ * (legacy edges have never been reinforced).
+ */
+export function readLastReinforcedAt(
+  edge: Pick<GraphEdge, "lastReinforcedAt" | "ts">,
+): string {
+  return edge.lastReinforcedAt ?? edge.ts;
+}
+
+/**
+ * Reinforce an edge: bump confidence by `delta` (capped at 1.0) and stamp
+ * `lastReinforcedAt = now`. Pure — returns a new edge, never mutates input.
+ *
+ * Idempotency note: calling reinforceEdge twice with the same `now` and a
+ * delta of 0 returns an edge equal to the input (modulo timestamp).
+ *
+ * @param edge  the edge to reinforce
+ * @param now   ISO timestamp of the reinforcement event
+ * @param delta confidence bump; defaults to DEFAULT_REINFORCE_DELTA
+ */
+export function reinforceEdge(
+  edge: GraphEdge,
+  now: string,
+  delta: number = DEFAULT_REINFORCE_DELTA,
+): GraphEdge {
+  const current = readEdgeConfidence(edge);
+  // Codex P2: reinforcement must never silently decrease confidence.
+  // A negative delta sneaking in through parsed config / CLI flags
+  // would push strong edges toward zero on every observation. Treat
+  // anything below zero as 0 (no-op besides the timestamp bump) so
+  // misconfiguration is harmless rather than corrupting.
+  const safeDelta =
+    Number.isFinite(delta) && delta >= 0 ? delta : 0;
+  const next = Math.min(CONFIDENCE_CEILING, Math.max(0, current + safeDelta));
+  return {
+    ...edge,
+    confidence: next,
+    lastReinforcedAt: now,
+  };
+}
+
+/** Options for {@link decayEdgeConfidence}. */
+export interface DecayOptions {
+  /** Decay window in milliseconds. Defaults to 90 days. */
+  windowMs?: number;
+  /** Per-window decay amount. Defaults to 0.1. */
+  perWindow?: number;
+  /** Floor confidence will not decay below. Defaults to 0.1. */
+  floor?: number;
+}
+
+/**
+ * Apply linear decay to an edge's confidence based on time since last
+ * reinforcement (or creation, for legacy edges). Pure — returns a new edge.
+ *
+ * Decay model:
+ *   age = now - lastReinforcedAt
+ *   if age <= windowMs:           confidence unchanged
+ *   else:                          confidence -= perWindow * floor((age - windowMs) / windowMs + 1)
+ *   confidence is clamped to [floor, 1.0]
+ *
+ * Boundary semantics: `age === windowMs` is INSIDE the no-decay grace period
+ * (`<=`). Decay only kicks in once age strictly exceeds the window. This
+ * keeps the boundary deterministic and easy to test.
+ *
+ * @param edge edge to decay (confidence and lastReinforcedAt may be absent)
+ * @param now  ISO timestamp representing "now"
+ * @param opts override window / per-window / floor; otherwise defaults are used
+ */
+export function decayEdgeConfidence(
+  edge: GraphEdge,
+  now: string,
+  opts: DecayOptions = {},
+): GraphEdge {
+  const windowMs = opts.windowMs ?? DEFAULT_DECAY_WINDOW_MS;
+  const perWindow = opts.perWindow ?? DEFAULT_DECAY_PER_WINDOW;
+  const floor = opts.floor ?? DEFAULT_DECAY_FLOOR;
+
+  // Codex P2: reject negative `perWindow` so a misconfigured value
+  // doesn't invert the decay equation and silently boost stale
+  // edges instead of decaying them. Negative `floor` would also let
+  // confidence drop below zero — clamp the floor to [0, 1] so the
+  // model stays well-defined.
+  if (
+    !(windowMs > 0) ||
+    !Number.isFinite(perWindow) ||
+    perWindow < 0 ||
+    !Number.isFinite(floor)
+  ) {
+    // Degenerate options — return a normalized copy without changing confidence.
+    return { ...edge, confidence: readEdgeConfidence(edge) };
+  }
+  const safeFloor = Math.min(CONFIDENCE_CEILING, Math.max(0, floor));
+
+  const nowMs = Date.parse(now);
+  const refMs = Date.parse(readLastReinforcedAt(edge));
+  if (!Number.isFinite(nowMs) || !Number.isFinite(refMs)) {
+    return { ...edge, confidence: readEdgeConfidence(edge) };
+  }
+
+  const age = nowMs - refMs;
+  const current = readEdgeConfidence(edge);
+
+  if (age <= windowMs) {
+    // Inside the grace period: no decay.
+    return { ...edge, confidence: current };
+  }
+
+  // Number of full windows past the grace window.
+  //
+  // Codex P2: the previous formula (`Math.floor((age - windowMs) / windowMs) + 1`)
+  // over-counted at exact multiples of the window. At `age === 2 * windowMs`,
+  // only ONE post-grace window has elapsed (we're sitting on the boundary
+  // of the second), but the old formula returned 2. Switch to a ceiling
+  // count: `ceil((age - windowMs) / windowMs)` correctly returns 1 for
+  // `windowMs < age <= 2*windowMs`, 2 for `2*windowMs < age <= 3*windowMs`,
+  // etc. With the outer `age > windowMs` guard, this always evaluates to
+  // a positive integer.
+  const windowsPast = Math.ceil((age - windowMs) / windowMs);
+  const decayed = current - perWindow * windowsPast;
+  // Codex P2: an edge that already sits below `safeFloor` (e.g. an
+  // explicit confidence: 0) must NOT be boosted up to the floor by a
+  // decay pass. Decay can lower confidence or leave it unchanged — it
+  // can never raise it. Cap the result at `current` and only apply
+  // the floor when the pre-existing value is still above it.
+  const lowerBound = Math.min(safeFloor, current);
+  const next = Math.max(lowerBound, Math.min(current, decayed));
+
+  // Cursor Medium round 2 + Codex P1: the anchor must advance by
+  // EXACTLY the windows we just charged for — not to `now`. Resetting
+  // to `now` makes every decay pass look like a fresh reinforcement
+  // and re-applies the grace window on every run, under-decaying
+  // stale edges when the maintenance job runs less frequently than
+  // `windowMs` (codex P1). Leaving the anchor unchanged compounds
+  // decay on frequent calls (cursor Medium). Advancing by
+  // `windowsPast * windowMs` from the prior anchor is the right
+  // middle ground: subsequent calls see a fresh grace window,
+  // decay accrues at most `perWindow` per real `windowMs` regardless
+  // of cadence, and historical anchor information is preserved.
+  const newRefMs = refMs + windowsPast * windowMs;
+  const newRef = new Date(newRefMs).toISOString();
+  return { ...edge, confidence: next, lastReinforcedAt: newRef };
+}

package/src/graph-events.ts

@@ -0,0 +1,151 @@
+/**
+ * In-process EventEmitter for graph mutation events (issue #691 PR 5/5).
+ *
+ * The singleton is keyed by memoryDir so multiple orchestrator instances in
+ * the same process get distinct event buses (CLAUDE.md rule 11: scope globals
+ * per service).  The SSE handler in access-http.ts subscribes to the bus for
+ * the resolved namespace and fans out to connected clients.
+ *
+ * Event types mirror the five mutations the graph layer can produce:
+ *   node-added    — a memory file was referenced for the first time
+ *   node-updated  — a memory file's metadata changed
+ *   edge-added    — a new edge was appended
+ *   edge-updated  — an existing edge's confidence/weight was modified
+ *   edge-removed  — an edge was pruned (e.g. by decay maintenance)
+ *
+ * The `GraphEventBus` interface is intentionally narrow so nothing outside
+ * this module needs to import Node.js EventEmitter directly.
+ */
+
+import { EventEmitter } from "node:events";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type GraphEventType =
+  | "node-added"
+  | "node-updated"
+  | "edge-added"
+  | "edge-updated"
+  | "edge-removed";
+
+export interface GraphEvent {
+  type: GraphEventType;
+  /** Memory dir that owns this event (absolute path). */
+  memoryDir: string;
+  /** ISO timestamp of the event. */
+  ts: string;
+  /** Payload depends on event type — always serialisable to JSON. */
+  payload: Record<string, unknown>;
+}
+
+export interface NodeAddedPayload {
+  nodeId: string;   // relative memory path
+  kind: string;
+  label: string;
+  lastUpdated: string;
+}
+
+export interface NodeUpdatedPayload {
+  nodeId: string;
+  kind: string;
+  label: string;
+  lastUpdated: string;
+}
+
+export interface EdgeAddedPayload {
+  source: string;
+  target: string;
+  kind: string;
+  weight: number;
+  label: string;
+  confidence: number;
+}
+
+export interface EdgeUpdatedPayload {
+  source: string;
+  target: string;
+  kind: string;
+  weight: number;
+  confidence: number;
+}
+
+export interface EdgeRemovedPayload {
+  source: string;
+  target: string;
+  kind: string;
+}
+
+// ---------------------------------------------------------------------------
+// Per-memoryDir singleton bus
+// ---------------------------------------------------------------------------
+
+const buses = new Map<string, EventEmitter>();
+
+/**
+ * Return (or lazily create) the event bus for the given memoryDir.
+ * The same bus is shared by the write side (graph.ts → appendEdge hooks) and
+ * the read side (EngramAccessHttpServer SSE handler).
+ */
+export function getGraphEventBus(memoryDir: string): EventEmitter {
+  let bus = buses.get(memoryDir);
+  if (!bus) {
+    bus = new EventEmitter();
+    // Remove the default listener-count warning — SSE clients may hold many
+    // concurrent connections. Each SSE client registers one "graph-event"
+    // listener; warn only when an unreasonably high count suggests a leak.
+    bus.setMaxListeners(200);
+    buses.set(memoryDir, bus);
+  }
+  return bus;
+}
+
+/**
+ * Emit a single graph event onto the bus for memoryDir.
+ * Fails open: any listener that throws is caught so one bad client can't
+ * crash the extraction pipeline.
+ */
+export function emitGraphEvent(
+  memoryDir: string,
+  type: GraphEventType,
+  payload: Record<string, unknown>,
+): void {
+  const event: GraphEvent = {
+    type,
+    memoryDir,
+    ts: new Date().toISOString(),
+    payload,
+  };
+  const bus = getGraphEventBus(memoryDir);
+  try {
+    bus.emit("graph-event", event);
+  } catch {
+    // fail-open: never propagate listener errors to the write path
+  }
+}
+
+/**
+ * Subscribe to graph events for a given memoryDir.
+ * Returns an unsubscribe function.
+ */
+export function subscribeGraphEvents(
+  memoryDir: string,
+  listener: (event: GraphEvent) => void,
+): () => void {
+  const bus = getGraphEventBus(memoryDir);
+  bus.on("graph-event", listener);
+  return () => bus.off("graph-event", listener);
+}
+
+/**
+ * Remove all listeners and the bus entry for a memoryDir.
+ * Useful for tests that spin up isolated memory dirs.
+ */
+export function destroyGraphEventBus(memoryDir: string): void {
+  const bus = buses.get(memoryDir);
+  if (bus) {
+    bus.removeAllListeners();
+    buses.delete(memoryDir);
+  }
+}

package/src/graph-recall.test.ts

@@ -0,0 +1,164 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  type GraphRecallConfig,
+  type GraphRecallOptions,
+  runGraphRecall,
+} from "./graph-recall.js";
+import type { MemoryEdgeSource } from "./graph-retrieval.js";
+
+const DEFAULT_CONFIG: GraphRecallConfig = {
+  recallGraphEnabled: true,
+  recallGraphDamping: 0.85,
+  recallGraphIterations: 20,
+  recallGraphTopK: 50,
+};
+
+function disabledConfig(): GraphRecallConfig {
+  return { ...DEFAULT_CONFIG, recallGraphEnabled: false };
+}
+
+function sampleMemories(): MemoryEdgeSource[] {
+  return [
+    { id: "m1", entityRef: "person:Jane" },
+    { id: "m2", entityRef: "person:Jane" },
+    { id: "m3", lineage: ["m1"], entityRefs: ["person:Jane", "org:Acme"] },
+    { id: "m4", supersedes: "m3" },
+    { id: "m5", entityRef: "org:Acme" },
+  ];
+}
+
+test("runGraphRecall short-circuits when recallGraphEnabled=false", () => {
+  const run = runGraphRecall(disabledConfig(), {
+    memories: sampleMemories(),
+    seedIds: ["m1"],
+  });
+  assert.equal(run.ran, false);
+  assert.equal(run.reason, "disabled");
+  assert.equal(run.results.length, 0);
+  assert.equal(run.graph, null);
+});
+
+test("runGraphRecall short-circuits when recallGraphTopK<=0", () => {
+  for (const topK of [0, -1]) {
+    const cfg: GraphRecallConfig = { ...DEFAULT_CONFIG, recallGraphTopK: topK };
+    const run = runGraphRecall(cfg, {
+      memories: sampleMemories(),
+      seedIds: ["m1"],
+    });
+    assert.equal(run.ran, false);
+    assert.equal(run.reason, "topk-zero");
+    assert.equal(run.results.length, 0);
+    assert.equal(run.graph, null);
+  }
+});
+
+test("runGraphRecall short-circuits when memory pool is empty", () => {
+  const run = runGraphRecall(DEFAULT_CONFIG, {
+    memories: [],
+    seedIds: ["m1"],
+  });
+  assert.equal(run.ran, false);
+  assert.equal(run.reason, "empty-input");
+});
+
+test("runGraphRecall returns memory-typed results only", () => {
+  const run = runGraphRecall(DEFAULT_CONFIG, {
+    memories: sampleMemories(),
+    seedIds: ["m1"],
+  });
+  assert.equal(run.ran, true);
+  assert.equal(run.reason, "ran");
+  assert.ok(run.graph !== null);
+  for (const r of run.results) {
+    assert.equal(run.graph!.nodes.get(r.id)?.type, "memory");
+  }
+  assert.ok(run.results.length > 0);
+  assert.equal(run.results[0]?.id, "m1");
+});
+
+test("runGraphRecall respects recallGraphTopK after projection", () => {
+  const chain: MemoryEdgeSource[] = [
+    { id: "m1" },
+    { id: "m2", supersedes: "m1" },
+    { id: "m3", supersedes: "m2" },
+    { id: "m4", supersedes: "m3" },
+  ];
+  const cfg: GraphRecallConfig = { ...DEFAULT_CONFIG, recallGraphTopK: 2 };
+  const run = runGraphRecall(cfg, {
+    memories: chain,
+    seedIds: ["m4"],
+  });
+  assert.equal(run.ran, true);
+  assert.equal(run.results.length, 2);
+});
+
+test("runGraphRecall threads damping + iteration cap through to PPR", () => {
+  const cfg: GraphRecallConfig = {
+    ...DEFAULT_CONFIG,
+    recallGraphDamping: 0.5,
+    recallGraphIterations: 5,
+  };
+  const run = runGraphRecall(cfg, {
+    memories: sampleMemories(),
+    seedIds: ["m1"],
+  });
+  assert.ok(run.iterations <= 5, `expected <= 5 iterations, got ${run.iterations}`);
+});
+
+test("runGraphRecall uniform-fallback when seed ids are empty", () => {
+  const run = runGraphRecall(DEFAULT_CONFIG, {
+    memories: sampleMemories(),
+    seedIds: [],
+  });
+  assert.equal(run.ran, true);
+  assert.ok(run.results.length > 0);
+  for (const r of run.results) {
+    assert.equal(run.graph!.nodes.get(r.id)?.type, "memory");
+  }
+});
+
+test("runGraphRecall accepts seedWeights and biases ranking accordingly", () => {
+  const weightedM1 = runGraphRecall(DEFAULT_CONFIG, {
+    memories: sampleMemories(),
+    seedIds: ["m1", "m2"],
+    seedWeights: { m1: 0.9, m2: 0.1 },
+  });
+  const weightedM2 = runGraphRecall(DEFAULT_CONFIG, {
+    memories: sampleMemories(),
+    seedIds: ["m1", "m2"],
+    seedWeights: { m1: 0.1, m2: 0.9 },
+  });
+
+  const m1_scoreA = weightedM1.results.find((r) => r.id === "m1")?.score ?? 0;
+  const m2_scoreA = weightedM1.results.find((r) => r.id === "m2")?.score ?? 0;
+  const m1_scoreB = weightedM2.results.find((r) => r.id === "m1")?.score ?? 0;
+  const m2_scoreB = weightedM2.results.find((r) => r.id === "m2")?.score ?? 0;
+
+  assert.ok(m1_scoreA > m1_scoreB, "m1 should rank higher when weighted on m1");
+  assert.ok(m2_scoreB > m2_scoreA, "m2 should rank higher when weighted on m2");
+});
+
+test("runGraphRecall is deterministic", () => {
+  const memories = sampleMemories();
+  const seedIds = ["m1"];
+  const r1 = runGraphRecall(DEFAULT_CONFIG, { memories, seedIds });
+  const r2 = runGraphRecall(DEFAULT_CONFIG, { memories, seedIds });
+  assert.deepEqual(r1.results, r2.results);
+});
+
+test("runGraphRecall default-off: disabled config with defaults does nothing", () => {
+  const defaults: GraphRecallConfig = {
+    recallGraphEnabled: false,
+    recallGraphDamping: 0.85,
+    recallGraphIterations: 20,
+    recallGraphTopK: 50,
+  };
+  const run = runGraphRecall(defaults, {
+    memories: sampleMemories(),
+    seedIds: ["m1"],
+  });
+  assert.equal(run.ran, false);
+  assert.equal(run.reason, "disabled");
+});