Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

perf(graph): swap BFS for Dijkstra over edge-weighted graph (#328) (#463)

Rohit Ghumare4db303b6b947
diff --git a/src/functions/graph-retrieval.ts b/src/functions/graph-retrieval.ts
index 245d2efb..10fd51a7 100644
--- a/src/functions/graph-retrieval.ts
+++ b/src/functions/graph-retrieval.ts
@@ -64,7 +64,7 @@ export class GraphRetrieval {
const visitedObs = new Set<string>();
for (const startNode of matchingNodes) {
- const paths = this.bfsTraversal(
+ const paths = this.dijkstraTraversal(
startNode,
allNodes,
allEdges,
@@ -130,7 +130,7 @@ export class GraphRetrieval {
const visitedObs = new Set<string>(obsIds);
for (const node of linkedNodes) {
- const paths = this.bfsTraversal(node, allNodes, allEdges, maxDepth);
+ const paths = this.dijkstraTraversal(node, allNodes, allEdges, maxDepth);
for (const path of paths) {
const lastNode = path[path.length - 1].node;
for (const obsId of lastNode.sourceObservationIds) {
@@ -227,51 +227,136 @@ export class GraphRetrieval {
return latest;
}
- private bfsTraversal(
+ // Weighted shortest-path traversal (#328). Replaces the prior BFS,
+ // which fell back to edge-count order and ignored the 0.1-1.0 weight
+ // attached to every graph edge. Dijkstra over `cost = 1/weight`
+ // (cheaper edges = stronger relationships) returns the
+ // highest-weighted path to each reachable node within maxDepth. Also
+ // tightens the perf profile:
+ // - Adjacency built once in O(V+E) (previous BFS re-filtered
+ // allEdges per visited node, O(V·E) overall).
+ // - Min-heap dequeue is O(log V) per pop (previous queue.shift()
+ // was O(n) — the dominant cost on graphs above ~200 nodes per
+ // the contributor's benchmark in #328).
+ private dijkstraTraversal(
startNode: GraphNode,
allNodes: GraphNode[],
allEdges: GraphEdge[],
maxDepth: number,
): Array<Array<{ node: GraphNode; edge?: GraphEdge }>> {
- const paths: Array<Array<{ node: GraphNode; edge?: GraphEdge }>> = [];
- const visited = new Set<string>();
- const queue: Array<{
- nodeId: string;
- depth: number;
- path: Array<{ node: GraphNode; edge?: GraphEdge }>;
- }> = [{ nodeId: startNode.id, depth: 0, path: [{ node: startNode }] }];
+ const nodeIndex = new Map<string, GraphNode>();
+ for (const n of allNodes) nodeIndex.set(n.id, n);
+
+ const adjacency = new Map<string, Array<{ neighborId: string; edge: GraphEdge }>>();
+ for (const edge of allEdges) {
+ const a = edge.sourceNodeId;
+ const b = edge.targetNodeId;
+ if (!adjacency.has(a)) adjacency.set(a, []);
+ if (!adjacency.has(b)) adjacency.set(b, []);
+ adjacency.get(a)!.push({ neighborId: b, edge });
+ adjacency.get(b)!.push({ neighborId: a, edge });
+ }
- visited.add(startNode.id);
+ const dist = new Map<string, number>();
+ const pathTo = new Map<string, Array<{ node: GraphNode; edge?: GraphEdge }>>();
+ dist.set(startNode.id, 0);
+ pathTo.set(startNode.id, [{ node: startNode }]);
- while (queue.length > 0) {
- const { nodeId, depth, path } = queue.shift()!;
- paths.push(path);
+ const heap = new MinHeap<{ nodeId: string; depth: number; cost: number }>(
+ (a, b) => a.cost - b.cost,
+ );
+ heap.push({ nodeId: startNode.id, depth: 0, cost: 0 });
+ while (heap.size() > 0) {
+ const { nodeId, depth, cost } = heap.pop()!;
+ // Skip stale heap entries (cost beaten by a later push).
+ if (cost > (dist.get(nodeId) ?? Infinity)) continue;
if (depth >= maxDepth) continue;
- const neighborEdges = allEdges.filter(
- (e) => e.sourceNodeId === nodeId || e.targetNodeId === nodeId,
- );
+ const neighbors = adjacency.get(nodeId) ?? [];
+ for (const { neighborId, edge } of neighbors) {
+ const nextNode = nodeIndex.get(neighborId);
+ if (!nextNode) continue;
+ // Clamp weight to avoid division-by-zero on malformed edges;
+ // 0.01 is below the documented 0.1 floor.
+ const edgeCost = 1 / Math.max(edge.weight, 0.01);
+ const newCost = cost + edgeCost;
+ if (newCost < (dist.get(neighborId) ?? Infinity)) {
+ dist.set(neighborId, newCost);
+ pathTo.set(neighborId, [
+ ...pathTo.get(nodeId)!,
+ { node: nextNode, edge },
+ ]);
+ heap.push({ nodeId: neighborId, depth: depth + 1, cost: newCost });
+ }
+ }
+ }
- for (const edge of neighborEdges) {
- const nextId =
- edge.sourceNodeId === nodeId
- ? edge.targetNodeId
- : edge.sourceNodeId;
- if (visited.has(nextId)) continue;
- visited.add(nextId);
+ // Drop the startNode's own entry before returning: callers
+ // (searchByEntities, expandFromChunks) score start-node
+ // observations via a dedicated fallback loop with score=1.0. If
+ // we leave it in here, the start-path (length 1, no edges) goes
+ // through the generic path-scoring loop first — pathLength=1 +
+ // empty edgeWeights makes avgWeight fall to 0.5, the obs get
+ // marked visited, and the score=1.0 fallback becomes dead code.
+ pathTo.delete(startNode.id);
+ return Array.from(pathTo.values());
+ }
+}
- const nextNode = allNodes.find((n) => n.id === nextId);
- if (!nextNode) continue;
+// Minimal binary min-heap. Pulled inline so graph-retrieval doesn't
+// take a new dependency for the perf-critical inner loop of #328.
+// Comparator returns negative when `a` should pop before `b`.
+class MinHeap<T> {
+ private heap: T[] = [];
- queue.push({
- nodeId: nextId,
- depth: depth + 1,
- path: [...path, { node: nextNode, edge }],
- });
- }
+ constructor(private compare: (a: T, b: T) => number) {}
+
+ size(): number {
+ return this.heap.length;
+ }
+
+ push(value: T): void {
+ this.heap.push(value);
+ this.bubbleUp(this.heap.length - 1);
+ }
+
+ pop(): T | undefined {
+ if (this.heap.length === 0) return undefined;
+ const top = this.heap[0];
+ const last = this.heap.pop()!;
+ if (this.heap.length > 0) {
+ this.heap[0] = last;
+ this.sinkDown(0);
+ }
+ return top;
+ }
+
+ private bubbleUp(i: number): void {
+ while (i > 0) {
+ const parent = (i - 1) >> 1;
+ if (this.compare(this.heap[i], this.heap[parent]) < 0) {
+ [this.heap[i], this.heap[parent]] = [this.heap[parent], this.heap[i]];
+ i = parent;
+ } else break;
}
+ }
- return paths;
+ private sinkDown(i: number): void {
+ const n = this.heap.length;
+ while (true) {
+ const left = 2 * i + 1;
+ const right = 2 * i + 2;
+ let smallest = i;
+ if (left < n && this.compare(this.heap[left], this.heap[smallest]) < 0) {
+ smallest = left;
+ }
+ if (right < n && this.compare(this.heap[right], this.heap[smallest]) < 0) {
+ smallest = right;
+ }
+ if (smallest === i) break;
+ [this.heap[i], this.heap[smallest]] = [this.heap[smallest], this.heap[i]];
+ i = smallest;
+ }
}
}
diff --git a/test/graph-retrieval.test.ts b/test/graph-retrieval.test.ts
index 57dcc7dc..2eb3f923 100644
--- a/test/graph-retrieval.test.ts
+++ b/test/graph-retrieval.test.ts
@@ -183,4 +183,116 @@ describe("GraphRetrieval", () => {
const indirectScore = results.find((r) => r.obsId === "obs_3")?.score ?? 0;
expect(directScore).toBeGreaterThan(indirectScore);
});
+
+ // Dijkstra path selection (#328). The BFS implementation this
+ // replaced visited a node via its first-discovered path regardless
+ // of edge weight. Dijkstra picks the highest-weight (lowest
+ // 1/weight cost) path, so a one-hop weak edge no longer beats a
+ // two-hop chain of strong edges to the same node.
+ it("picks the weight-optimal path under Dijkstra, not the edge-count-shortest one (#328)", async () => {
+ const nodes = [
+ makeNode("n1", "Start", "concept", ["obs_start"]),
+ makeNode("n2", "Mid", "concept", ["obs_mid"]),
+ makeNode("n3", "End", "concept", ["obs_end"]),
+ ];
+ const edges = [
+ // Direct n1 → n3 path with a weak edge. BFS would prefer this.
+ makeEdge("e_direct", "n1", "n3", "related_to", 0.15),
+ // Two-hop chain n1 → n2 → n3 with strong edges. Total cost
+ // (1/0.9) + (1/0.9) ≈ 2.22, vs direct 1/0.15 ≈ 6.67.
+ // Dijkstra picks the chain.
+ makeEdge("e_strong_a", "n1", "n2", "related_to", 0.9),
+ makeEdge("e_strong_b", "n2", "n3", "related_to", 0.9),
+ ];
+ const kv = mockKV(nodes, edges);
+ const retrieval = new GraphRetrieval(kv as never);
+
+ const results = await retrieval.searchByEntities(["Start"], 3);
+ const endResult = results.find((r) => r.obsId === "obs_end");
+ expect(endResult).toBeDefined();
+ // Path is [Start → Mid → End] (length 3) — Dijkstra picked the
+ // chain of two strong edges over the direct weak one.
+ expect(endResult!.pathLength).toBe(3);
+ expect(endResult!.graphContext).toContain("Mid");
+ });
+
+ it("handles disconnected nodes without crashing", async () => {
+ const nodes = [
+ makeNode("n1", "A", "concept", ["obs_a"]),
+ makeNode("n2", "B", "concept", ["obs_b"]),
+ // n3 is unreachable from the matched node.
+ makeNode("n3", "Lonely", "concept", ["obs_lonely"]),
+ ];
+ const edges = [makeEdge("e1", "n1", "n2", "related_to", 0.7)];
+ const kv = mockKV(nodes, edges);
+ const retrieval = new GraphRetrieval(kv as never);
+
+ const results = await retrieval.searchByEntities(["A"], 5);
+ expect(results.find((r) => r.obsId === "obs_a")).toBeDefined();
+ expect(results.find((r) => r.obsId === "obs_b")).toBeDefined();
+ expect(results.find((r) => r.obsId === "obs_lonely")).toBeUndefined();
+ });
+
+ it("clamps near-zero edge weights without dividing by zero", async () => {
+ const nodes = [
+ makeNode("n1", "Anchor", "concept", ["obs_anchor"]),
+ makeNode("n2", "Weak", "concept", ["obs_weak"]),
+ ];
+ // weight: 0 is malformed but we shouldn't crash on it; the clamp
+ // floor at 0.01 means traversal completes with a very high cost
+ // rather than throwing or producing Infinity.
+ const edges = [makeEdge("e1", "n1", "n2", "related_to", 0)];
+ const kv = mockKV(nodes, edges);
+ const retrieval = new GraphRetrieval(kv as never);
+
+ const results = await retrieval.searchByEntities(["Anchor"], 2);
+ const weak = results.find((r) => r.obsId === "obs_weak");
+ expect(weak).toBeDefined();
+ expect(Number.isFinite(weak!.score)).toBe(true);
+ });
+
+ it("scores startNode observations at 1.0 via the fallback path, not 0.5 via the path-scoring loop (#328 review)", async () => {
+ // Regression for a bug surfaced by inline review on #463: if the
+ // traversal includes a length-1 path for the startNode itself,
+ // the generic path-scoring loop in searchByEntities computes
+ // avgWeight=0.5 (empty edgeWeights → fallback) and pathLength=1,
+ // yielding score=0.5, then marks the obs as visited. The
+ // dedicated score=1.0 fallback loop for startNode obs is then
+ // skipped via the visitedObs guard — dead code.
+ const nodes = [
+ makeNode("n1", "React", "library", ["obs_root"]),
+ makeNode("n2", "Hook", "concept", ["obs_neighbor"]),
+ ];
+ const edges = [makeEdge("e1", "n1", "n2", "uses", 0.8)];
+ const kv = mockKV(nodes, edges);
+ const retrieval = new GraphRetrieval(kv as never);
+
+ const results = await retrieval.searchByEntities(["React"], 2);
+ const root = results.find((r) => r.obsId === "obs_root");
+ expect(root).toBeDefined();
+ expect(root!.score).toBe(1.0);
+ expect(root!.pathLength).toBe(0);
+ });
+
+ it("respects maxDepth bound (Dijkstra stops at edge-count depth)", async () => {
+ // Chain n1 -> n2 -> n3 -> n4. With maxDepth=2 we should reach n3
+ // but not n4 — edge-count semantics preserved from the old BFS.
+ const nodes = [
+ makeNode("n1", "Start", "concept", ["obs_1"]),
+ makeNode("n2", "Hop1", "concept", ["obs_2"]),
+ makeNode("n3", "Hop2", "concept", ["obs_3"]),
+ makeNode("n4", "Hop3", "concept", ["obs_4"]),
+ ];
+ const edges = [
+ makeEdge("e1", "n1", "n2", "related_to", 0.8),
+ makeEdge("e2", "n2", "n3", "related_to", 0.8),
+ makeEdge("e3", "n3", "n4", "related_to", 0.8),
+ ];
+ const kv = mockKV(nodes, edges);
+ const retrieval = new GraphRetrieval(kv as never);
+
+ const results = await retrieval.searchByEntities(["Start"], 2);
+ expect(results.find((r) => r.obsId === "obs_3")).toBeDefined();
+ expect(results.find((r) => r.obsId === "obs_4")).toBeUndefined();
+ });
});