Skip to content

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

fix(graph): top-degree snapshot cache for /graph/query + /graph/stats (#814) (#816)

Rohit Ghumare2a581408a7bf
diff --git a/AGENTS.md b/AGENTS.md
index ae0d577f..a5e3633a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -117,7 +117,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
## Current Stats (v0.9.16)
- 53 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
-- 126 REST endpoints
+- 128 REST endpoints
- 6 MCP resources, 3 MCP prompts
- 12 hooks, 4 skills
- 50+ iii functions
diff --git a/README.md b/README.md
index d5f4c414..af019002 100644
--- a/README.md
+++ b/README.md
@@ -1431,7 +1431,7 @@ Create `~/.agentmemory/.env`:
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-api.svg"><img src="assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-126 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
+128 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
<details>
<summary>Key endpoints</summary>
diff --git a/src/functions/graph.ts b/src/functions/graph.ts
index 74764cc5..9493674d 100644
--- a/src/functions/graph.ts
+++ b/src/functions/graph.ts
@@ -3,6 +3,7 @@ import type {
GraphNode,
GraphEdge,
GraphQueryResult,
+ GraphSnapshot,
CompressedObservation,
MemoryProvider,
} from "../types.js";
@@ -23,6 +24,285 @@ import { logger } from "../logger.js";
const DEFAULT_GRAPH_QUERY_LIMIT = 500;
const MAX_GRAPH_QUERY_LIMIT = 5000;
+// #814: the precomputed snapshot covers the top-degree subgraph used by
+// the empty-body / nodeType-only branch — the path the viewer hits on
+// tab load. Sized to match the default query limit so the snapshot can
+// service a default-cap request without falling back to live
+// enumeration. Aggregate stats (nodesByType / edgesByType) are computed
+// fresh during rebuild and stored alongside.
+const SNAPSHOT_TOP_NODES = DEFAULT_GRAPH_QUERY_LIMIT;
+const SNAPSHOT_KEY = "current";
+
+// `state::list` over a 75K-node scope can exceed the iii invocation
+// timeout. The query handler races the enumeration against this budget
+// and falls back to the snapshot (or a warning envelope) when the live
+// path is too slow. 6000ms leaves headroom under the default 8s engine
+// invocation deadline.
+const LIVE_ENUMERATION_BUDGET_MS = 6000;
+
+function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+ return new Promise<T>((resolve, reject) => {
+ const t = setTimeout(
+ () => reject(new Error(`${label}: exceeded ${ms}ms budget`)),
+ ms,
+ );
+ p.then(
+ (v) => {
+ clearTimeout(t);
+ resolve(v);
+ },
+ (err) => {
+ clearTimeout(t);
+ reject(err);
+ },
+ );
+ });
+}
+
+function emptySnapshot(): GraphSnapshot {
+ return {
+ version: 1,
+ topNodes: [],
+ topEdges: [],
+ topDegrees: {},
+ stats: {
+ totalNodes: 0,
+ totalEdges: 0,
+ nodesByType: {},
+ edgesByType: {},
+ },
+ updatedAt: new Date(0).toISOString(),
+ dirty: true,
+ };
+}
+
+async function readSnapshot(kv: StateKV): Promise<GraphSnapshot | null> {
+ try {
+ const snap = await kv.get<GraphSnapshot>(KV.graphSnapshot, SNAPSHOT_KEY);
+ if (snap && typeof snap === "object" && snap.version === 1) {
+ return snap;
+ }
+ return null;
+ } catch (err) {
+ logger.warn("Graph snapshot read failed", {
+ error: err instanceof Error ? err.message : String(err),
+ });
+ return null;
+ }
+}
+
+function buildSnapshotFromArrays(
+ nodes: GraphNode[],
+ edges: GraphEdge[],
+): GraphSnapshot {
+ const liveNodes = nodes.filter((n) => !n.stale);
+ const liveEdges = edges.filter((e) => !e.stale);
+ // Build the global degree map once so we can both rank by it AND
+ // snapshot the per-top-node values into topDegrees for synchronous
+ // re-sort after incremental edge writes.
+ const degree = new Map<string, number>();
+ for (const e of liveEdges) {
+ degree.set(e.sourceNodeId, (degree.get(e.sourceNodeId) ?? 0) + 1);
+ degree.set(e.targetNodeId, (degree.get(e.targetNodeId) ?? 0) + 1);
+ }
+ const ranked = [...liveNodes]
+ .sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0))
+ .slice(0, SNAPSHOT_TOP_NODES);
+ const rankedIds = new Set(ranked.map((n) => n.id));
+ const topEdges = liveEdges.filter(
+ (e) => rankedIds.has(e.sourceNodeId) && rankedIds.has(e.targetNodeId),
+ );
+ const topDegrees: Record<string, number> = {};
+ for (const n of ranked) {
+ topDegrees[n.id] = degree.get(n.id) ?? 0;
+ }
+ const nodesByType: Record<string, number> = {};
+ for (const n of liveNodes) {
+ nodesByType[n.type] = (nodesByType[n.type] || 0) + 1;
+ }
+ const edgesByType: Record<string, number> = {};
+ for (const e of liveEdges) {
+ edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
+ }
+ return {
+ version: 1,
+ topNodes: ranked,
+ topEdges,
+ topDegrees,
+ stats: {
+ totalNodes: liveNodes.length,
+ totalEdges: liveEdges.length,
+ nodesByType,
+ edgesByType,
+ },
+ updatedAt: new Date().toISOString(),
+ dirty: false,
+ };
+}
+
+function paginateFromSnapshot(
+ snap: GraphSnapshot,
+ filterType: string | undefined,
+ limit: number,
+ offset: number,
+): GraphQueryResult {
+ const filteredNodes = filterType
+ ? snap.topNodes.filter((n) => n.type === filterType)
+ : snap.topNodes;
+ const total = filterType
+ ? snap.stats.nodesByType[filterType] ?? 0
+ : snap.stats.totalNodes;
+ const pageNodes = filteredNodes.slice(offset, offset + limit);
+ const pageIds = new Set(pageNodes.map((n) => n.id));
+ const pageEdges = snap.topEdges.filter(
+ (e) => pageIds.has(e.sourceNodeId) && pageIds.has(e.targetNodeId),
+ );
+ return {
+ nodes: pageNodes,
+ edges: pageEdges,
+ depth: 0,
+ totalNodes: total,
+ totalEdges: snap.stats.totalEdges,
+ truncated: total > pageNodes.length,
+ limit,
+ offset,
+ fromSnapshot: true,
+ };
+}
+
+// #814 v2: the rebuild path won't terminate on corpora large enough
+// that kv.list returns a payload too big to JSON.parse without
+// starving the iii heartbeat. We don't actually know the corpus size
+// without enumerating, but we can refuse to start a rebuild if the
+// snapshot's recorded `totalNodes` already exceeds this threshold —
+// the rebuild path is unreliable above it, and an incremental
+// extract-driven snapshot is the right approach for those corpora.
+// Operators above the threshold should use mem::graph-reset and let
+// future extracts rebuild incrementally.
+const REBUILD_SAFE_NODE_CEILING = 25000;
+
+function nameIndexKey(type: string, name: string): string {
+ return `${type}|${name}`;
+}
+
+function edgeIndexKey(
+ sourceNodeId: string,
+ targetNodeId: string,
+ type: string,
+): string {
+ return `${sourceNodeId}|${targetNodeId}|${type}`;
+}
+
+// Mutates `snap` to apply a +1 (or -1) degree delta for nodeId,
+// maintaining the top-N ranking. Returns the new degree. Reads /
+// writes the per-node degree counter via targeted kv.get/set so we
+// never enumerate. Top-N membership flips when:
+// - node's new degree > current min in topNodes AND it's not in
+// topNodes (promote, evict tail if topNodes is full)
+// - node IS in topNodes and its position needs resorting (re-sort
+// topNodes in place)
+async function applyDegreeDelta(
+ kv: StateKV,
+ snap: GraphSnapshot,
+ nodeId: string,
+ delta: number,
+): Promise<number> {
+ const prev = (await kv.get<number>(KV.graphNodeDegree, nodeId)) ?? 0;
+ const next = Math.max(0, prev + delta);
+ await kv.set(KV.graphNodeDegree, nodeId, next);
+
+ const inTop = snap.topNodes.findIndex((n) => n.id === nodeId);
+ if (inTop !== -1) {
+ // Cache the new degree in topDegrees so the comparator runs
+ // synchronously over numbers, not async kv.get calls. Re-sort
+ // descending by degree.
+ snap.topDegrees[nodeId] = next;
+ snap.topNodes.sort(
+ (a, b) =>
+ (snap.topDegrees[b.id] ?? 0) - (snap.topDegrees[a.id] ?? 0),
+ );
+ return next;
+ }
+
+ if (snap.topNodes.length < SNAPSHOT_TOP_NODES) {
+ // Capacity available — fetch + promote.
+ const node = await kv.get<GraphNode>(KV.graphNodes, nodeId);
+ if (node && !node.stale) {
+ snap.topNodes.push(node);
+ snap.topDegrees[node.id] = next;
+ snap.topNodes.sort(
+ (a, b) =>
+ (snap.topDegrees[b.id] ?? 0) - (snap.topDegrees[a.id] ?? 0),
+ );
+ }
+ return next;
+ }
+
+ // topNodes is full; the cutoff is the tail's cached degree.
+ const tailEntry = snap.topNodes[snap.topNodes.length - 1];
+ if (!tailEntry) return next;
+ const tailDegree = snap.topDegrees[tailEntry.id] ?? 0;
+ if (next > tailDegree) {
+ const node = await kv.get<GraphNode>(KV.graphNodes, nodeId);
+ if (node && !node.stale) {
+ const evicted = snap.topNodes.pop();
+ if (evicted) delete snap.topDegrees[evicted.id];
+ snap.topNodes.push(node);
+ snap.topDegrees[node.id] = next;
+ snap.topNodes.sort(
+ (a, b) =>
+ (snap.topDegrees[b.id] ?? 0) - (snap.topDegrees[a.id] ?? 0),
+ );
+ }
+ }
+ return next;
+}
+
+function snapshotPushEdgeIfBothInTop(
+ snap: GraphSnapshot,
+ edge: GraphEdge,
+): void {
+ const topIds = new Set(snap.topNodes.map((n) => n.id));
+ if (topIds.has(edge.sourceNodeId) && topIds.has(edge.targetNodeId)) {
+ // Dedupe in case the same edge gets pushed twice.
+ if (!snap.topEdges.find((e) => e.id === edge.id)) {
+ snap.topEdges.push(edge);
+ }
+ }
+}
+
+function mergeNode(
+ existing: GraphNode,
+ incoming: GraphNode,
+ obsIds: string[],
+ capturedAt: string,
+): GraphNode {
+ return {
+ ...existing,
+ sourceObservationIds: [
+ ...new Set([
+ ...existing.sourceObservationIds,
+ ...incoming.sourceObservationIds,
+ ...obsIds,
+ ]),
+ ],
+ properties: { ...existing.properties, ...incoming.properties },
+ updatedAt: capturedAt,
+ };
+}
+
+function mergeEdge(
+ existing: GraphEdge,
+ obsIds: string[],
+): GraphEdge {
+ return {
+ ...existing,
+ sourceObservationIds: [
+ ...new Set([...existing.sourceObservationIds, ...obsIds]),
+ ],
+ };
+}
+
function resolvePagination(
rawLimit: number | undefined,
rawOffset: number | undefined,
@@ -40,17 +320,6 @@ function resolvePagination(
return { limit, offset };
}
-// Score nodes by incident-edge count so the default-cap page surfaces
-// the densest part of the graph rather than an arbitrary KV scan order.
-function rankByDegree(nodes: GraphNode[], edges: GraphEdge[]): GraphNode[] {
- const degree = new Map<string, number>();
- for (const edge of edges) {
- degree.set(edge.sourceNodeId, (degree.get(edge.sourceNodeId) ?? 0) + 1);
- degree.set(edge.targetNodeId, (degree.get(edge.targetNodeId) ?? 0) + 1);
- }
- return [...nodes].sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0));
-}
-
function paginate(
nodes: GraphNode[],
allEdges: GraphEdge[],
@@ -211,46 +480,102 @@ export function registerGraphFunction(
const obsIds = data.observations.map((o) => o.id);
const { nodes, edges } = parseGraphXml(response, obsIds);
- const existingNodes = await kv.list<GraphNode>(KV.graphNodes);
- const existingEdges = await kv.list<GraphEdge>(KV.graphEdges);
+ // #814 v2: targeted name-index lookups replace the O(n) scan
+ // over `kv.list<GraphNode>(KV.graphNodes)`. At 75K nodes the
+ // list payload exceeds the iii heartbeat budget and the worker
+ // dies before merge can complete. Each name-index entry is a
+ // single small kv.get/set pair.
+ const snap = (await readSnapshot(kv)) ?? emptySnapshot();
+ const capturedAt = new Date().toISOString();
+ let newNodeCount = 0;
+ let newEdgeCount = 0;
+ const newEdgesForTopCheck: GraphEdge[] = [];
for (const node of nodes) {
- const existing = existingNodes.find(
- (n) => n.name === node.name && n.type === node.type,
+ const indexKey = nameIndexKey(node.type, node.name);
+ const existingId = await kv.get<string>(
+ KV.graphNameIndex,
+ indexKey,
);
+
+ let existing: GraphNode | null = null;
+ if (existingId) {
+ existing = await kv.get<GraphNode>(KV.graphNodes, existingId);
+ }
+
if (existing) {
- const merged = {
- ...existing,
- sourceObservationIds: [
- ...new Set([...existing.sourceObservationIds, ...obsIds]),
- ],
- properties: { ...existing.properties, ...node.properties },
- };
+ const merged = mergeNode(existing, node, obsIds, capturedAt);
await kv.set(KV.graphNodes, existing.id, merged);
- const idx = existingNodes.findIndex((n) => n.id === existing.id);
- if (idx !== -1) existingNodes[idx] = merged;
+ // Update topNodes entry if present so a stale clone isn't
+ // returned from the snapshot fast path.
+ const topIdx = snap.topNodes.findIndex(
+ (n) => n.id === existing!.id,
+ );
+ if (topIdx !== -1) snap.topNodes[topIdx] = merged;
} else {
await kv.set(KV.graphNodes, node.id, node);
- existingNodes.push(node);
+ await kv.set(KV.graphNameIndex, indexKey, node.id);
+ await kv.set(KV.graphNodeDegree, node.id, 0);
+ snap.stats.totalNodes += 1;
+ snap.stats.nodesByType[node.type] =
+ (snap.stats.nodesByType[node.type] ?? 0) + 1;
+ newNodeCount += 1;
+ if (snap.topNodes.length < SNAPSHOT_TOP_NODES) {
+ // Degree 0 still beats an empty slot — sit at the tail
+ // until edges arrive and promote.
+ snap.topNodes.push(node);
+ snap.topDegrees[node.id] = 0;
+ }
}
}
for (const edge of edges) {
- const edgeKey = `${edge.sourceNodeId}|${edge.targetNodeId}|${edge.type}`;
- const existingEdge = existingEdges.find(
- (e) => `${e.sourceNodeId}|${e.targetNodeId}|${e.type}` === edgeKey,
+ const eKey = edgeIndexKey(
+ edge.sourceNodeId,
+ edge.targetNodeId,
+ edge.type,
);
- if (existingEdge) {
- existingEdge.sourceObservationIds = [
- ...new Set([...existingEdge.sourceObservationIds, ...obsIds]),
- ];
- await kv.set(KV.graphEdges, existingEdge.id, existingEdge);
+ const existingId = await kv.get<string>(KV.graphEdgeKey, eKey);
+
+ let existing: GraphEdge | null = null;
+ if (existingId) {
+ existing = await kv.get<GraphEdge>(KV.graphEdges, existingId);
+ }
+
+ if (existing) {
+ const merged = mergeEdge(existing, obsIds);
+ await kv.set(KV.graphEdges, existing.id, merged);
+ // Replace cached topEdges entry too if present.
+ const topIdx = snap.topEdges.findIndex(
+ (e) => e.id === existing!.id,
+ );
+ if (topIdx !== -1) snap.topEdges[topIdx] = merged;
} else {
await kv.set(KV.graphEdges, edge.id, edge);
- existingEdges.push(edge);
+ await kv.set(KV.graphEdgeKey, eKey, edge.id);
+ snap.stats.totalEdges += 1;
+ snap.stats.edgesByType[edge.type] =
+ (snap.stats.edgesByType[edge.type] ?? 0) + 1;
+ newEdgeCount += 1;
+ await applyDegreeDelta(kv, snap, edge.sourceNodeId, +1);
+ await applyDegreeDelta(kv, snap, edge.targetNodeId, +1);
+ newEdgesForTopCheck.push(edge);
}
}
+ // Push newly-added edges into snapshot.topEdges if both
+ // endpoints are in the top-N (post-degree-delta). Done after
+ // all degree updates so the topIds set is stable.
+ for (const edge of newEdgesForTopCheck) {
+ snapshotPushEdgeIfBothInTop(snap, edge);
+ }
+
+ if (newNodeCount > 0 || newEdgeCount > 0) {
+ snap.updatedAt = capturedAt;
+ snap.dirty = false;
+ await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, snap);
+ }
+
await recordAudit(kv, "observe", "mem::graph-extract", obsIds, {
nodesExtracted: nodes.length,
edgesExtracted: edges.length,
@@ -259,6 +584,8 @@ export function registerGraphFunction(
logger.info("Graph extraction complete", {
nodes: nodes.length,
edges: edges.length,
+ newNodes: newNodeCount,
+ newEdges: newEdgeCount,
});
return {
success: true,
@@ -288,11 +615,87 @@ export function registerGraphFunction(
limit?: number;
offset?: number;
}): Promise<GraphQueryResult> => {
- const allNodes = (await kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
- const allEdges = (await kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
const maxDepth = Math.min(data.maxDepth || 3, 5);
const { limit, offset } = resolvePagination(data.limit, data.offset);
+ // #814 v2: the empty-body / nodeType-only path NEVER enumerates.
+ // It reads the snapshot exclusively. The snapshot is updated
+ // inline by graph-extract, so for newly-built corpora it's
+ // always current. For legacy corpora missing a snapshot the
+ // operator must run mem::graph-snapshot-rebuild (safe under
+ // REBUILD_SAFE_NODE_CEILING) or mem::graph-reset to wipe and
+ // rebuild incrementally from new observations.
+ const noWalk = !data.query && !data.startNodeId;
+ if (noWalk) {
+ const snap = await readSnapshot(kv);
+ if (snap && snap.stats.totalNodes > 0) {
+ return paginateFromSnapshot(snap, data.nodeType, limit, offset);
+ }
+ return {
+ nodes: [],
+ edges: [],
+ depth: 0,
+ totalNodes: 0,
+ totalEdges: 0,
+ truncated: false,
+ limit,
+ offset,
+ warning:
+ "No graph snapshot available. Either no graph has been " +
+ "extracted yet, or you are on a legacy corpus from a pre-#814 " +
+ "agentmemory build. Run POST /agentmemory/graph/snapshot-rebuild " +
+ "(safe up to ~25K nodes) or POST /agentmemory/graph/reset to " +
+ "wipe and let future extracts repopulate.",
+ };
+ }
+
+ // Query / startNodeId paths still need broader access. Race the
+ // live enumeration against a wall-clock budget so a long
+ // kv.list doesn't block the worker indefinitely. On timeout the
+ // caller gets a snapshot-backed approximation instead of a 500.
+ let allNodes: GraphNode[];
+ let allEdges: GraphEdge[];
+ try {
+ const [rawNodes, rawEdges] = await withTimeout(
+ Promise.all([
+ kv.list<GraphNode>(KV.graphNodes),
+ kv.list<GraphEdge>(KV.graphEdges),
+ ]),
+ LIVE_ENUMERATION_BUDGET_MS,
+ "graph-query enumeration",
+ );
+ allNodes = rawNodes.filter((n) => !n.stale);
+ allEdges = rawEdges.filter((e) => !e.stale);
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ logger.warn("Graph query enumeration timed out, using snapshot", {
+ error: msg,
+ });
+ const snap = await readSnapshot(kv);
+ if (snap) {
+ return {
+ ...paginateFromSnapshot(snap, data.nodeType, limit, offset),
+ warning:
+ "Live graph enumeration exceeded budget. Query / " +
+ "startNodeId paths degrade on >25K-node corpora until a " +
+ "per-node edge index lands. Result reflects top-degree " +
+ "snapshot, not the requested walk.",
+ };
+ }
+ return {
+ nodes: [],
+ edges: [],
+ depth: 0,
+ totalNodes: 0,
+ totalEdges: 0,
+ truncated: false,
+ limit,
+ offset,
+ warning:
+ "Graph enumeration exceeded budget and no snapshot is available.",
+ };
+ }
+
if (data.query) {
const lower = data.query.toLowerCase();
const matchingNodes = allNodes.filter(
@@ -347,37 +750,244 @@ export function registerGraphFunction(
return paginate(resultNodes, resultEdges, maxDepth, limit, offset);
}
- let filtered = allNodes;
- if (data.nodeType) {
- filtered = allNodes.filter((n) => n.type === data.nodeType);
- }
- // Empty-body / nodeType-only branch is the path the viewer hits
- // on tab load. Page by the most-connected nodes first so the
- // truncated view conveys the densest part of the graph (#753).
- const ranked = rankByDegree(filtered, allEdges);
- return paginate(ranked, allEdges, 0, limit, offset);
+ // Unreachable — noWalk branch handles the rest.
+ return paginate([], [], 0, limit, offset);
},
);
- sdk.registerFunction("mem::graph-stats", async () => {
- const nodes = await kv.list<GraphNode>(KV.graphNodes);
- const edges = await kv.list<GraphEdge>(KV.graphEdges);
-
- const nodesByType: Record<string, number> = {};
- for (const n of nodes) {
- nodesByType[n.type] = (nodesByType[n.type] || 0) + 1;
+ // #814 v2: graph-stats reads the snapshot exclusively. The snapshot
+ // is maintained inline by mem::graph-extract, so for any corpus built
+ // on a post-#814 agentmemory the stats are always current without an
+ // enumeration. Legacy corpora without a snapshot get an empty
+ // envelope + a warning pointing at the snapshot-rebuild or graph-reset
+ // endpoints — never a 500.
+ sdk.registerFunction("mem::graph-stats", async () => {
+ const snap = await readSnapshot(kv);
+ if (snap) {
+ return {
+ ...snap.stats,
+ fromSnapshot: true,
+ updatedAt: snap.updatedAt,
+ ...(snap.dirty
+ ? {
+ warning:
+ "Snapshot is marked dirty (write was in-flight when read). " +
+ "Counts are eventually consistent.",
+ }
+ : {}),
+ };
}
+ return {
+ totalNodes: 0,
+ totalEdges: 0,
+ nodesByType: {},
+ edgesByType: {},
+ fromSnapshot: false,
+ warning:
+ "No graph snapshot available. Run POST /agentmemory/graph/snapshot-rebuild " +
+ "(safe up to ~25K nodes) or POST /agentmemory/graph/reset to wipe " +
+ "and let future extracts repopulate.",
+ };
+ });
+
+ // #814 v2: explicit rebuild backfills the snapshot AND the name /
+ // edge-key / degree indexes from existing graphNodes/graphEdges
+ // scopes. This is the path operators run once after upgrading to a
+ // post-#814 build to bring legacy corpora online. It enumerates via
+ // kv.list — the same pair that breaks at 75K+ — so we refuse to
+ // run on corpora large enough that the response payload would
+ // block the worker heartbeat. Above the ceiling the only safe path
+ // is mem::graph-reset followed by incremental re-extraction.
+ sdk.registerFunction("mem::graph-snapshot-rebuild", async () => {
+ const started = Date.now();
+ try {
+ const [nodes, edges] = await withTimeout(
+ Promise.all([
+ kv.list<GraphNode>(KV.graphNodes),
+ kv.list<GraphEdge>(KV.graphEdges),
+ ]),
+ LIVE_ENUMERATION_BUDGET_MS,
+ "graph-snapshot-rebuild enumeration",
+ );
+
+ if (nodes.length > REBUILD_SAFE_NODE_CEILING) {
+ logger.warn("Graph snapshot rebuild aborted: corpus too large", {
+ totalNodes: nodes.length,
+ ceiling: REBUILD_SAFE_NODE_CEILING,
+ });
+ return {
+ success: false,
+ tooLarge: true,
+ totalNodes: nodes.length,
+ ceiling: REBUILD_SAFE_NODE_CEILING,
+ error:
+ `Corpus has ${nodes.length} graph nodes; safe-rebuild ceiling ` +
+ `is ${REBUILD_SAFE_NODE_CEILING}. Run POST /agentmemory/graph/reset ` +
+ `to wipe and let future extracts rebuild incrementally.`,
+ };
+ }
- const edgesByType: Record<string, number> = {};
- for (const e of edges) {
- edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
+ // Backfill the targeted-lookup indexes so post-rebuild
+ // graph-extract calls hit the O(1) path instead of falling
+ // through to the (already-removed) full-scope scan. Batch
+ // writes via Promise.all to avoid N sequential round-trips —
+ // BATCH_SIZE bounds in-flight writes so we don't open thousands
+ // of concurrent state channels on huge corpora.
+ const liveNodes = nodes.filter((n) => !n.stale);
+ const liveEdges = edges.filter((e) => !e.stale);
+ const degree = new Map<string, number>();
+ for (const e of liveEdges) {
+ degree.set(e.sourceNodeId, (degree.get(e.sourceNodeId) ?? 0) + 1);
+ degree.set(e.targetNodeId, (degree.get(e.targetNodeId) ?? 0) + 1);
+ }
+ const BATCH_SIZE = 100;
+ for (let i = 0; i < liveNodes.length; i += BATCH_SIZE) {
+ const batch = liveNodes.slice(i, i + BATCH_SIZE);
+ await Promise.all(
+ batch.flatMap((n) => [
+ kv.set(KV.graphNameIndex, nameIndexKey(n.type, n.name), n.id),
+ kv.set(KV.graphNodeDegree, n.id, degree.get(n.id) ?? 0),
+ ]),
+ );
+ }
+ for (let i = 0; i < liveEdges.length; i += BATCH_SIZE) {
+ const batch = liveEdges.slice(i, i + BATCH_SIZE);
+ await Promise.all(
+ batch.map((e) =>
+ kv.set(
+ KV.graphEdgeKey,
+ edgeIndexKey(e.sourceNodeId, e.targetNodeId, e.type),
+ e.id,
+ ),
+ ),
+ );
+ }
+
+ const snap = buildSnapshotFromArrays(nodes, edges);
+ await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, snap);
+ const tookMs = Date.now() - started;
+ logger.info("Graph snapshot rebuilt", {
+ totalNodes: snap.stats.totalNodes,
+ totalEdges: snap.stats.totalEdges,
+ topNodes: snap.topNodes.length,
+ topEdges: snap.topEdges.length,
+ tookMs,
+ });
+ return {
+ success: true,
+ ...snap.stats,
+ topNodes: snap.topNodes.length,
+ topEdges: snap.topEdges.length,
+ updatedAt: snap.updatedAt,
+ tookMs,
+ };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ logger.error("Graph snapshot rebuild failed", { error: msg });
+ return { success: false, error: msg };
}
+ });
- return {
- totalNodes: nodes.length,
- totalEdges: edges.length,
- nodesByType,
- edgesByType,
+ // #814 v2: clean-restart escape hatch for legacy corpora too large
+ // for safe rebuild. Wipes every graph KV scope and writes an empty
+ // snapshot. Observations are NOT touched, so recall + history stay
+ // intact; the graph rebuilds incrementally from future
+ // mem::graph-extract calls (or a one-shot api::graph-build replay
+ // from existing observations).
+ sdk.registerFunction("mem::graph-reset", async () => {
+ const started = Date.now();
+ const counts: Record<string, number> = {
+ [KV.graphNodes]: 0,
+ [KV.graphEdges]: 0,
+ [KV.graphNameIndex]: 0,
+ [KV.graphEdgeKey]: 0,
+ [KV.graphNodeDegree]: 0,
+ [KV.graphEdgeHistory]: 0,
+ [KV.graphSnapshot]: 0,
};
+
+ // Composite-key scopes (graphNameIndex / graphEdgeKey /
+ // graphNodeDegree) store primitives, not objects, so we can't
+ // recover their keys via kv.list (which returns values only). The
+ // only reliable wipe path is to walk the canonical object scopes
+ // (graphNodes / graphEdges) and reconstruct the composite keys
+ // from each node/edge's fields, deleting both the canonical row
+ // AND every derived index entry in lock-step.
+ try {
+ const nodes = await withTimeout(
+ kv.list<GraphNode>(KV.graphNodes),
+ LIVE_ENUMERATION_BUDGET_MS,
+ "graph-reset list graphNodes",
+ );
+ counts[KV.graphNodes] = nodes.length;
+ for (const node of nodes) {
+ if (!node?.id) continue;
+ await Promise.all([
+ kv.delete(KV.graphNodes, node.id).catch(() => undefined),
+ kv
+ .delete(KV.graphNameIndex, nameIndexKey(node.type, node.name))
+ .catch(() => undefined),
+ kv.delete(KV.graphNodeDegree, node.id).catch(() => undefined),
+ ]);
+ counts[KV.graphNameIndex] += 1;
+ counts[KV.graphNodeDegree] += 1;
+ }
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ logger.warn("graph-reset: graphNodes list failed", { error: msg });
+ counts[KV.graphNodes] = -1;
+ }
+
+ try {
+ const edges = await withTimeout(
+ kv.list<GraphEdge>(KV.graphEdges),
+ LIVE_ENUMERATION_BUDGET_MS,
+ "graph-reset list graphEdges",
+ );
+ counts[KV.graphEdges] = edges.length;
+ for (const edge of edges) {
+ if (!edge?.id) continue;
+ await Promise.all([
+ kv.delete(KV.graphEdges, edge.id).catch(() => undefined),
+ kv
+ .delete(
+ KV.graphEdgeKey,
+ edgeIndexKey(edge.sourceNodeId, edge.targetNodeId, edge.type),
+ )
+ .catch(() => undefined),
+ ]);
+ counts[KV.graphEdgeKey] += 1;
+ }
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ logger.warn("graph-reset: graphEdges list failed", { error: msg });
+ counts[KV.graphEdges] = -1;
+ }
+
+ // graphEdgeHistory entries also key by id (audit row shape). Best
+ // effort — failures here don't block the reset.
+ try {
+ const history = await withTimeout(
+ kv.list<{ id?: string }>(KV.graphEdgeHistory),
+ LIVE_ENUMERATION_BUDGET_MS,
+ "graph-reset list graphEdgeHistory",
+ );
+ counts[KV.graphEdgeHistory] = history.length;
+ for (const row of history) {
+ if (row?.id) {
+ await kv.delete(KV.graphEdgeHistory, row.id).catch(() => undefined);
+ }
+ }
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ logger.warn("graph-reset: graphEdgeHistory list failed", { error: msg });
+ counts[KV.graphEdgeHistory] = -1;
+ }
+
+ await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, emptySnapshot());
+ counts[KV.graphSnapshot] = 1;
+ const tookMs = Date.now() - started;
+ logger.info("Graph state reset", { counts, tookMs });
+ return { success: true, cleared: counts, tookMs };
});
}
diff --git a/src/index.ts b/src/index.ts
index cef06a24..4233e8a6 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -518,7 +518,7 @@ async function main() {
`Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`,
);
bootLog(
- `REST API: 126 endpoints at http://localhost:${config.restPort}/agentmemory/*`,
+ `REST API: 128 endpoints at http://localhost:${config.restPort}/agentmemory/*`,
);
bootLog(
`MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`,
diff --git a/src/state/schema.ts b/src/state/schema.ts
index 2000d52c..cb29d41a 100644
--- a/src/state/schema.ts
+++ b/src/state/schema.ts
@@ -15,6 +15,28 @@ export const KV = {
claudeBridge: "mem:claude-bridge",
graphNodes: "mem:graph:nodes",
graphEdges: "mem:graph:edges",
+ // #814: precomputed snapshot of the top-degree subgraph and aggregate
+ // type counts. Saves /graph/query and /graph/stats from a full
+ // kv.list enumeration over 75K+ node corpora, which exceeds the iii
+ // invocation timeout and surfaces as "Invocation stopped" 500s.
+ // Single fixed key ("current") so writes are read-modify-write under
+ // the same keyed mutex as graph-extract.
+ graphSnapshot: "mem:graph:snapshot",
+ // #814 v2: targeted-lookup indexes so graph-extract never enumerates
+ // the full nodes/edges scope. Each entry is a single small kv.get,
+ // bounded payload — works at 75K+ nodes where kv.list would block
+ // the worker event loop (37MB WS frame parse blocks heartbeat,
+ // worker is declared dead before any Promise.race timer can fire).
+ // - graphNameIndex: key `${type}|${name}` -> nodeId. Replaces the
+ // existingNodes.find() O(n) dedup scan inside mem::graph-extract.
+ // - graphEdgeKey: key `${src}|${tgt}|${type}` -> edgeId. Same for
+ // edge dedup.
+ // - graphNodeDegree: key nodeId -> incident-edge count. Read /
+ // incremented on edge writes to maintain the snapshot top-N
+ // ranking without scanning all edges.
+ graphNameIndex: "mem:graph:name-index",
+ graphEdgeKey: "mem:graph:edge-key",
+ graphNodeDegree: "mem:graph:node-degree",
semantic: "mem:semantic",
procedural: "mem:procedural",
teamShared: (teamId: string) => `mem:team:${teamId}:shared`,
diff --git a/src/triggers/api.ts b/src/triggers/api.ts
index 6bcf12a1..43468c02 100644
--- a/src/triggers/api.ts
+++ b/src/triggers/api.ts
@@ -1446,7 +1446,58 @@ export function registerApiTriggers(
config: { api_path: "/agentmemory/graph/stats", http_method: "GET" },
});
- sdk.registerFunction("api::graph-extract",
+ // #814: explicit snapshot rebuild endpoint. Pays the full graph
+ // enumeration once and persists a top-degree subgraph + aggregate
+ // counts so subsequent /graph/query and /graph/stats calls skip the
+ // unbounded kv.list. Operator-grade endpoint exposed for the viewer
+ // banner action and CLI repair.
+ sdk.registerFunction("api::graph-snapshot-rebuild",
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger({
+ function_id: "mem::graph-snapshot-rebuild",
+ payload: {},
+ });
+ return { status_code: 200, body: result };
+ } catch {
+ return graphDisabledResponse();
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::graph-snapshot-rebuild",
+ config: { api_path: "/agentmemory/graph/snapshot-rebuild", http_method: "POST" },
+ });
+
+ // #814 v2: clean-restart endpoint for legacy corpora too large for
+ // safe rebuild. Wipes graph state without touching observations, so
+ // recall + history stay intact while the graph rebuilds incrementally
+ // from new extracts (or a one-shot /graph/build replay).
+ sdk.registerFunction("api::graph-reset",
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ try {
+ const result = await sdk.trigger({
+ function_id: "mem::graph-reset",
+ payload: {},
+ });
+ return { status_code: 200, body: result };
+ } catch {
+ return graphDisabledResponse();
+ }
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::graph-reset",
+ config: { api_path: "/agentmemory/graph/reset", http_method: "POST" },
+ });
+
+ sdk.registerFunction("api::graph-extract",
async (req: ApiRequest<{ observations: unknown[] }>): Promise<Response> => {
const authErr = checkAuth(req, secret);
if (authErr) return authErr;
diff --git a/src/types.ts b/src/types.ts
index 1b53d1b6..2110aa82 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -450,6 +450,39 @@ export interface GraphQueryResult {
// detect when the default was applied vs an explicit `limit`.
limit?: number;
offset?: number;
+ // #814: indicates the response came from the precomputed top-degree
+ // snapshot rather than a live kv.list enumeration. Set only on the
+ // empty-body / nodeType-only branch on large corpora where the
+ // unbounded enumeration would exceed the iii invocation timeout.
+ fromSnapshot?: boolean;
+ // #814: when the snapshot is stale or absent and the live fallback
+ // also failed, expose an explanatory note so the viewer can surface
+ // an actionable banner instead of a blank graph.
+ warning?: string;
+}
+
+// #814: persisted top-degree subgraph + aggregate counts. Stored under
+// KV.graphSnapshot with a single key "current". `dirty` is set true by
+// mem::graph-extract after writes and flipped false when the snapshot
+// rebuild completes.
+export interface GraphSnapshot {
+ version: 1;
+ topNodes: GraphNode[];
+ topEdges: GraphEdge[];
+ // Synchronous degree lookup keyed by nodeId. Maintained alongside
+ // topNodes so re-ranking after an edge write doesn't require an
+ // async kv.get for every top-N entry inside the sort comparator.
+ // Keys are limited to the top-N set; non-top nodes track their
+ // degree in KV.graphNodeDegree only.
+ topDegrees: Record<string, number>;
+ stats: {
+ totalNodes: number;
+ totalEdges: number;
+ nodesByType: Record<string, number>;
+ edgesByType: Record<string, number>;
+ };
+ updatedAt: string;
+ dirty: boolean;
}
export type ConsolidationTier =
diff --git a/test/graph.test.ts b/test/graph.test.ts
index ef0ebb5c..3d0472af 100644
--- a/test/graph.test.ts
+++ b/test/graph.test.ts
@@ -252,6 +252,10 @@ describe("Graph Functions", () => {
await kv.set("mem:graph:edges", edge.id, edge);
}
+ // Post-#814 the empty-body path reads the snapshot exclusively.
+ // Backfill the snapshot from the seeded data first.
+ await sdk.trigger("mem::graph-snapshot-rebuild", {});
+
const unbounded = (await sdk.trigger(
"mem::graph-query",
{},
@@ -282,6 +286,8 @@ describe("Graph Functions", () => {
await kv.set("mem:graph:nodes", node.id, node);
}
+ await sdk.trigger("mem::graph-snapshot-rebuild", {});
+
const page1 = (await sdk.trigger("mem::graph-query", {
limit: 10,
offset: 0,
@@ -316,6 +322,8 @@ describe("Graph Functions", () => {
});
}
+ await sdk.trigger("mem::graph-snapshot-rebuild", {});
+
const huge = (await sdk.trigger("mem::graph-query", {
limit: 999999,
})) as GraphQueryResult;
@@ -365,6 +373,8 @@ describe("Graph Functions", () => {
lastSeen: "2026-01-01T00:00:00Z",
});
+ await sdk.trigger("mem::graph-snapshot-rebuild", {});
+
const page = (await sdk.trigger("mem::graph-query", {
limit: 10,
offset: 0,
@@ -378,4 +388,302 @@ describe("Graph Functions", () => {
// totalEdges counts every edge in the full result universe.
expect(page.totalEdges).toBe(11);
});
+
+ // #814: precomputed snapshot path. The viewer-tab default-cap query
+ // and graph-stats both have to work at 75K-node scale where the
+ // full kv.list enumeration exceeds the iii invocation budget.
+ describe("snapshot cache (#814)", () => {
+ async function seed(nodeCount: number, edgeCount: number) {
+ for (let i = 0; i < nodeCount; i++) {
+ await kv.set("mem:graph:nodes", `n_${i}`, {
+ id: `n_${i}`,
+ type: i % 3 === 0 ? "file" : "function",
+ name: `node-${i}`,
+ properties: {},
+ sourceObservationIds: [`obs_${i}`],
+ firstSeen: "2026-01-01T00:00:00Z",
+ lastSeen: "2026-01-01T00:00:00Z",
+ observationCount: 1,
+ stale: false,
+ });
+ }
+ for (let i = 0; i < edgeCount; i++) {
+ const src = `n_${i % nodeCount}`;
+ const dst = `n_${(i + 1) % nodeCount}`;
+ await kv.set("mem:graph:edges", `e_${i}`, {
+ id: `e_${i}`,
+ type: i % 2 === 0 ? "uses" : "imports",
+ sourceNodeId: src,
+ targetNodeId: dst,
+ weight: 1,
+ evidence: [],
+ sourceObservationIds: [`obs_${i}`],
+ firstSeen: "2026-01-01T00:00:00Z",
+ lastSeen: "2026-01-01T00:00:00Z",
+ stale: false,
+ });
+ }
+ }
+
+ it("snapshot-rebuild persists top-degree subgraph + aggregate stats", async () => {
+ await seed(50, 100);
+ const result = (await sdk.trigger("mem::graph-snapshot-rebuild", {})) as {
+ success: boolean;
+ totalNodes: number;
+ totalEdges: number;
+ topNodes: number;
+ topEdges: number;
+ };
+ expect(result.success).toBe(true);
+ expect(result.totalNodes).toBe(50);
+ expect(result.totalEdges).toBe(100);
+ // 50 nodes is below the SNAPSHOT_TOP_NODES cap, so every node
+ // lands in the snapshot.
+ expect(result.topNodes).toBe(50);
+
+ const snap = await kv.get<{
+ version: number;
+ topNodes: unknown[];
+ stats: { totalNodes: number; nodesByType: Record<string, number> };
+ }>("mem:graph:snapshot", "current");
+ expect(snap).not.toBeNull();
+ expect(snap!.version).toBe(1);
+ expect(snap!.stats.totalNodes).toBe(50);
+ // nodesByType reflects every type seen.
+ expect(snap!.stats.nodesByType["file"]).toBeGreaterThan(0);
+ expect(snap!.stats.nodesByType["function"]).toBeGreaterThan(0);
+ });
+
+ it("graph-query empty-body branch serves from snapshot once it exists", async () => {
+ await seed(20, 30);
+ await sdk.trigger("mem::graph-snapshot-rebuild", {});
+
+ const result = (await sdk.trigger("mem::graph-query", {})) as GraphQueryResult;
+ expect(result.fromSnapshot).toBe(true);
+ expect(result.totalNodes).toBe(20);
+ expect(result.totalEdges).toBe(30);
+ });
+
+ it("graph-query nodeType filter respects snapshot type counts", async () => {
+ await seed(30, 0);
+ await sdk.trigger("mem::graph-snapshot-rebuild", {});
+
+ const fileQuery = (await sdk.trigger("mem::graph-query", {
+ nodeType: "file",
+ })) as GraphQueryResult;
+ expect(fileQuery.fromSnapshot).toBe(true);
+ // 30 nodes, every 3rd is "file" → 10 files.
+ expect(fileQuery.totalNodes).toBe(10);
+ for (const n of fileQuery.nodes) {
+ expect(n.type).toBe("file");
+ }
+ });
+
+ it("graph-stats returns from snapshot when not dirty", async () => {
+ await seed(15, 25);
+ await sdk.trigger("mem::graph-snapshot-rebuild", {});
+
+ const stats = (await sdk.trigger("mem::graph-stats", {})) as {
+ totalNodes: number;
+ totalEdges: number;
+ fromSnapshot: boolean;
+ };
+ expect(stats.fromSnapshot).toBe(true);
+ expect(stats.totalNodes).toBe(15);
+ expect(stats.totalEdges).toBe(25);
+ });
+
+ it("graph-extract updates snapshot inline (no kv.list, dirty stays false)", async () => {
+ // Post-#814 v2 the snapshot is updated incrementally on every
+ // extract — no dirty flag bounces. Test asserts that after an
+ // extract the snapshot reflects the new nodes/edges.
+ await sdk.trigger("mem::graph-extract", { observations: [testObs] });
+
+ const snap = await kv.get<{
+ dirty: boolean;
+ stats: { totalNodes: number };
+ }>("mem:graph:snapshot", "current");
+ expect(snap?.dirty).toBe(false);
+ // testObs produces 2 nodes (src/index.ts, main) + 1 edge.
+ expect(snap?.stats.totalNodes).toBeGreaterThanOrEqual(1);
+ });
+
+ it("graph-extract maintains name-index for O(1) dedup on re-extract", async () => {
+ // First extract creates nodes.
+ await sdk.trigger("mem::graph-extract", { observations: [testObs] });
+ const nameIndex = await kv.get<string>(
+ "mem:graph:name-index",
+ "file|src/index.ts",
+ );
+ expect(typeof nameIndex).toBe("string");
+
+ // Re-extract the same observation. With name-index lookup the
+ // existing node merges; no duplicates.
+ await sdk.trigger("mem::graph-extract", { observations: [testObs] });
+ const nodes = await kv.list<{ name: string; type: string }>(
+ "mem:graph:nodes",
+ );
+ const fileNodes = nodes.filter(
+ (n) => n.name === "src/index.ts" && n.type === "file",
+ );
+ expect(fileNodes.length).toBe(1);
+ });
+
+ it("graph-stats returns empty envelope + warning when no snapshot exists", async () => {
+ // Seed nodes but never rebuild the snapshot — simulates a legacy
+ // corpus on a post-#814 upgrade.
+ await seed(5, 5);
+
+ const stats = (await sdk.trigger("mem::graph-stats", {})) as {
+ totalNodes: number;
+ totalEdges: number;
+ fromSnapshot: boolean;
+ warning?: string;
+ };
+ expect(stats.fromSnapshot).toBe(false);
+ expect(stats.totalNodes).toBe(0);
+ expect(stats.warning).toMatch(/snapshot-rebuild|graph\/reset/);
+ });
+
+ it("graph-reset clears state and writes empty snapshot", async () => {
+ await sdk.trigger("mem::graph-extract", { observations: [testObs] });
+ const result = (await sdk.trigger("mem::graph-reset", {})) as {
+ success: boolean;
+ cleared: Record<string, number>;
+ };
+ expect(result.success).toBe(true);
+
+ const snap = await kv.get<{
+ stats: { totalNodes: number };
+ }>("mem:graph:snapshot", "current");
+ expect(snap?.stats.totalNodes).toBe(0);
+ });
+
+ it("graph-reset also wipes composite-key index scopes", async () => {
+ await sdk.trigger("mem::graph-extract", { observations: [testObs] });
+ // Index entries exist after the extract — name-index keyed by
+ // type|name; degree keyed by nodeId; edge-key by composite
+ // src|tgt|type.
+ const nameBefore = await kv.get(
+ "mem:graph:name-index",
+ "file|src/index.ts",
+ );
+ expect(nameBefore).not.toBeNull();
+ const edgeKeyBefore = await kv.list("mem:graph:edge-key");
+ expect(edgeKeyBefore.length).toBeGreaterThan(0);
+
+ await sdk.trigger("mem::graph-reset", {});
+
+ const nameAfter = await kv.get(
+ "mem:graph:name-index",
+ "file|src/index.ts",
+ );
+ expect(nameAfter).toBeNull();
+ const edgeKeyAfter = await kv.list("mem:graph:edge-key");
+ expect(edgeKeyAfter.length).toBe(0);
+ // Same for the per-node degree counter.
+ const degree = await kv.list("mem:graph:node-degree");
+ expect(degree.length).toBe(0);
+ });
+ });
+
+ // CodeRabbit feedback: cover the timeout-budget fallback path and
+ // the oversized-corpus rebuild refusal. The hot path never enumerates
+ // any more, but the rebuild endpoint AND the BFS / query branches
+ // still call kv.list — both need explicit failure-mode tests.
+ describe("budget + tooLarge guards (#814 v2)", () => {
+ function slowKV(delayMs: number) {
+ const base = mockKV();
+ return {
+ ...base,
+ list: async <T>(scope: string): Promise<T[]> => {
+ await new Promise((r) => setTimeout(r, delayMs));
+ return base.list<T>(scope);
+ },
+ };
+ }
+
+ it("graph-query startNodeId returns warning envelope when enumeration exceeds budget", async () => {
+ const slow = slowKV(7000); // > LIVE_ENUMERATION_BUDGET_MS (6000ms)
+ const localSdk = mockSdk();
+ registerGraphFunction(localSdk as never, slow as never, mockProvider as never);
+
+ const result = (await localSdk.trigger("mem::graph-query", {
+ startNodeId: "n_missing",
+ })) as GraphQueryResult;
+
+ expect(result.warning).toBeTruthy();
+ expect(result.warning).toMatch(/budget|enumeration/i);
+ }, 10000);
+
+ // CodeRabbit raised that slowKV(setTimeout) doesn't simulate a
+ // blocked event loop. The real production failure is iii rejecting
+ // the trigger with "Invocation stopped" after the worker dies
+ // (heartbeat starvation). A rejecting kv.list mock covers that
+ // catch-path directly without introducing a busy-wait that would
+ // also starve the budget timer and produce a flaky test.
+ function rejectingKV() {
+ const base = mockKV();
+ return {
+ ...base,
+ list: async <T>(_scope: string): Promise<T[]> => {
+ throw new Error("Invocation stopped");
+ },
+ };
+ }
+
+ it("graph-query rejects-from-engine path returns warning envelope (worker-death simulation)", async () => {
+ const rejector = rejectingKV();
+ const localSdk = mockSdk();
+ registerGraphFunction(
+ localSdk as never,
+ rejector as never,
+ mockProvider as never,
+ );
+
+ const result = (await localSdk.trigger("mem::graph-query", {
+ startNodeId: "n_missing",
+ })) as GraphQueryResult;
+
+ expect(result.warning).toBeTruthy();
+ expect(result.nodes).toEqual([]);
+ });
+
+ it("graph-snapshot-rebuild refuses corpora past REBUILD_SAFE_NODE_CEILING", async () => {
+ // Direct-poke the mock store with > 25K node values so kv.list
+ // returns them without paying the per-set cost. Each node only
+ // needs id/type/name/stale=false for the rebuild path.
+ const localKv = mockKV();
+ // Walk the implementation detail: mockKV stores entries in a
+ // Map under the scope key. Push directly to that map via the
+ // public `set` API in a tight loop.
+ const COUNT = 25001;
+ const sets: Array<Promise<unknown>> = [];
+ for (let i = 0; i < COUNT; i++) {
+ sets.push(
+ localKv.set("mem:graph:nodes", `bn_${i}`, {
+ id: `bn_${i}`,
+ type: "concept",
+ name: `bulk-${i}`,
+ properties: {},
+ sourceObservationIds: [],
+ createdAt: "2026-01-01T00:00:00Z",
+ stale: false,
+ }),
+ );
+ }
+ await Promise.all(sets);
+
+ const localSdk = mockSdk();
+ registerGraphFunction(localSdk as never, localKv as never, mockProvider as never);
+
+ const result = (await localSdk.trigger(
+ "mem::graph-snapshot-rebuild",
+ {},
+ )) as { success: boolean; tooLarge?: boolean; totalNodes?: number };
+ expect(result.success).toBe(false);
+ expect(result.tooLarge).toBe(true);
+ expect(result.totalNodes).toBeGreaterThanOrEqual(25001);
+ });
+ });
});