Skip to content

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

fix(viewer): graph tab blank on large graphs (graph/query pagination)

Rohit Ghumare436c86c86dbb
diff --git a/src/functions/graph.ts b/src/functions/graph.ts
index 09c23af0..74764cc5 100644
--- a/src/functions/graph.ts
+++ b/src/functions/graph.ts
@@ -15,6 +15,81 @@ import {
import { recordAudit } from "./audit.js";
import { logger } from "../logger.js";
+// #753: keep the response payload below the iii state channel ceiling.
+// 500 nodes + their incident edges hold well under the limit on the
+// reported 11k-node / 28k-edge corpus, and 5,000 is the upper bound a
+// caller can request explicitly. Tuned conservatively because edges
+// fan out faster than nodes.
+const DEFAULT_GRAPH_QUERY_LIMIT = 500;
+const MAX_GRAPH_QUERY_LIMIT = 5000;
+
+function resolvePagination(
+ rawLimit: number | undefined,
+ rawOffset: number | undefined,
+): { limit: number; offset: number } {
+ const requested = typeof rawLimit === "number" && Number.isFinite(rawLimit)
+ ? Math.floor(rawLimit)
+ : DEFAULT_GRAPH_QUERY_LIMIT;
+ const limit = Math.max(1, Math.min(requested, MAX_GRAPH_QUERY_LIMIT));
+ const offset = Math.max(
+ 0,
+ typeof rawOffset === "number" && Number.isFinite(rawOffset)
+ ? Math.floor(rawOffset)
+ : 0,
+ );
+ 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[],
+ depth: number,
+ limit: number,
+ offset: number,
+): GraphQueryResult {
+ const totalNodes = nodes.length;
+ const pageNodes = nodes.slice(offset, offset + limit);
+ const pageNodeIds = new Set(pageNodes.map((n) => n.id));
+ // Edges restricted to the page so the response payload scales with
+ // `limit`, not with the global edge count. An edge is included only
+ // when BOTH endpoints land in the page — half-edges to nodes outside
+ // the page would render as dangling links in the viewer.
+ const pageEdges = allEdges.filter(
+ (e) => pageNodeIds.has(e.sourceNodeId) && pageNodeIds.has(e.targetNodeId),
+ );
+ // Total edges (for the same node universe). Counted unbounded so the
+ // viewer can show "showing X of Y" without re-querying.
+ const universeIds = new Set(nodes.map((n) => n.id));
+ const totalEdges = allEdges.reduce(
+ (count, e) =>
+ universeIds.has(e.sourceNodeId) && universeIds.has(e.targetNodeId)
+ ? count + 1
+ : count,
+ 0,
+ );
+ return {
+ nodes: pageNodes,
+ edges: pageEdges,
+ depth,
+ totalNodes,
+ totalEdges,
+ truncated: totalNodes > pageNodes.length,
+ limit,
+ offset,
+ };
+}
+
// Parse all key="value" pairs from a tag's attribute string, in any
// order. The previous parser hard-coded attribute order
// (type before name on <entity>, type/source/target/weight on
@@ -198,16 +273,25 @@ export function registerGraphFunction(
},
);
- sdk.registerFunction("mem::graph-query",
+ // #753: every branch now applies a default cap and reports the
+ // unbounded `total*` counts. Before this change, an unfiltered POST
+ // /graph/query body (`{}`) on a corpus with ~10k+ nodes serialized
+ // to a payload large enough that the iii state response channel
+ // rejected it with HTTP 500 "Invocation stopped", leaving the viewer
+ // graph tab silently blank.
+ sdk.registerFunction("mem::graph-query",
async (data: {
startNodeId?: string;
nodeType?: string;
maxDepth?: number;
query?: string;
+ 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);
if (data.query) {
const lower = data.query.toLowerCase();
@@ -218,11 +302,7 @@ export function registerGraphFunction(
(v) => typeof v === "string" && v.toLowerCase().includes(lower),
),
);
- const nodeIds = new Set(matchingNodes.map((n) => n.id));
- const relatedEdges = allEdges.filter(
- (e) => nodeIds.has(e.sourceNodeId) || nodeIds.has(e.targetNodeId),
- );
- return { nodes: matchingNodes, edges: relatedEdges, depth: 0 };
+ return paginate(matchingNodes, allEdges, 0, limit, offset);
}
if (data.startNodeId) {
@@ -264,14 +344,18 @@ export function registerGraphFunction(
}
}
- return { nodes: resultNodes, edges: resultEdges, depth: maxDepth };
+ return paginate(resultNodes, resultEdges, maxDepth, limit, offset);
}
let filtered = allNodes;
if (data.nodeType) {
filtered = allNodes.filter((n) => n.type === data.nodeType);
}
- return { nodes: filtered, edges: allEdges, depth: 0 };
+ // 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);
},
);
diff --git a/src/triggers/api.ts b/src/triggers/api.ts
index ea817164..442209dc 100644
--- a/src/triggers/api.ts
+++ b/src/triggers/api.ts
@@ -1330,19 +1330,31 @@ export function registerApiTriggers(
},
});
- sdk.registerFunction("api::graph-query",
+ sdk.registerFunction("api::graph-query",
async (
req: ApiRequest<{
startNodeId?: string;
nodeType?: string;
maxDepth?: number;
query?: string;
+ limit?: number;
+ offset?: number;
}>,
): Promise<Response> => {
const authErr = checkAuth(req, secret);
if (authErr) return authErr;
+ // Whitelist payload fields explicitly; AGENTS.md security rule:
+ // REST endpoints never pass raw req.body through to sdk.trigger.
+ const payload = {
+ startNodeId: req.body?.startNodeId,
+ nodeType: req.body?.nodeType,
+ maxDepth: req.body?.maxDepth,
+ query: req.body?.query,
+ limit: req.body?.limit,
+ offset: req.body?.offset,
+ };
try {
- const result = await sdk.trigger({ function_id: "mem::graph-query", payload: req.body || {} });
+ const result = await sdk.trigger({ function_id: "mem::graph-query", payload });
return { status_code: 200, body: result };
} catch {
return graphDisabledResponse();
diff --git a/src/types.ts b/src/types.ts
index b734a4d2..cabcdc4c 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -438,6 +438,18 @@ export interface GraphQueryResult {
nodes: GraphNode[];
edges: GraphEdge[];
depth: number;
+ // #753: pagination + truncation signals for large graphs. `total*`
+ // counts reflect the full unbounded result for the given filter so
+ // the viewer can show "showing N of M" without re-querying. `truncated`
+ // is true when the default cap kicked in (operator may have wanted
+ // the full set but didn't ask for one).
+ totalNodes?: number;
+ totalEdges?: number;
+ truncated?: boolean;
+ // Echoes back the cap that produced this page so a paged client can
+ // detect when the default was applied vs an explicit `limit`.
+ limit?: number;
+ offset?: number;
}
export type ConsolidationTier =
diff --git a/src/viewer/index.html b/src/viewer/index.html
index 8382235e..305397e9 100644
--- a/src/viewer/index.html
+++ b/src/viewer/index.html
@@ -1111,7 +1111,7 @@
var state = {
activeTab: 'dashboard',
dashboard: { loaded: false, health: null, sessions: [], memories: [], graphStats: null, recentAudit: [], lessons: [], crystals: [] },
- graph: { loaded: false, nodes: [], edges: [], stats: null, filters: {}, selectedNode: null },
+ graph: { loaded: false, nodes: [], edges: [], stats: null, filters: {}, selectedNode: null, queryError: null, truncated: false, totalNodes: 0, totalEdges: 0 },
memories: { loaded: false, items: [], search: '', typeFilter: '' },
timeline: { loaded: false, observations: [], sessionId: '', minImportance: 0, page: 0, pageSize: 50 },
sessions: { loaded: false, items: [], selectedId: null },
@@ -1668,31 +1668,61 @@
}
}
+ // #753: previously POST'd `{}` and let the engine return the full
+ // graph. On 10k+ nodes the payload exceeded the iii state channel
+ // limit and the engine returned HTTP 500, leaving the tab blank
+ // with no signal. Now we pass an explicit `limit`, distinguish
+ // server error from empty-corpus, and render an actionable banner
+ // when the request itself fails instead of falling silent.
+ var GRAPH_INITIAL_LIMIT = 500;
+
async function loadGraph() {
var el = document.getElementById('view-graph');
el.innerHTML = '<div class="graph-container"><div class="graph-canvas-wrap"><canvas id="graph-canvas"></canvas><div class="graph-controls"><button title="Zoom In" data-action="zoom-graph" data-dir="1">+</button><button title="Zoom Out" data-action="zoom-graph" data-dir="-1">&minus;</button><div class="ctrl-divider"></div><button title="Recenter" data-action="recenter-graph">⌖</button></div><div class="graph-tooltip" id="graph-tooltip"></div></div><div class="graph-sidebar" id="graph-sidebar"></div></div>';
var results = await Promise.all([
- apiPost('graph/query', {}),
+ apiPost('graph/query', { limit: GRAPH_INITIAL_LIMIT }),
apiGet('graph/stats')
]);
- var queryResult = results[0] || { nodes: [], edges: [] };
+ var queryResult = results[0];
+ if (queryResult === null) {
+ // api() returns null only on non-2xx or a transport error; an
+ // empty graph would come back as { nodes: [], edges: [] }.
+ // Surface as an error state so #753-class failures don't read
+ // as "no data yet" — and so "Rebuild Graph" stays available.
+ state.graph.queryError = 'graph/query failed (check server logs for HTTP error)';
+ state.graph.nodes = [];
+ state.graph.edges = [];
+ state.graph.stats = results[1] || {};
+ state.graph.loaded = true;
+ renderGraphSidebar();
+ return;
+ }
+ state.graph.queryError = null;
state.graph.nodes = queryResult.nodes || [];
state.graph.edges = queryResult.edges || [];
+ state.graph.truncated = queryResult.truncated === true;
+ state.graph.totalNodes = typeof queryResult.totalNodes === 'number' ? queryResult.totalNodes : state.graph.nodes.length;
+ state.graph.totalEdges = typeof queryResult.totalEdges === 'number' ? queryResult.totalEdges : state.graph.edges.length;
state.graph.stats = results[1] || {};
- if (state.graph.nodes.length === 0) {
+ if (state.graph.nodes.length === 0 && (state.graph.stats.totalNodes || state.graph.stats.nodes || 0) === 0) {
var sb = document.getElementById('graph-sidebar');
if (sb) sb.innerHTML = '<h3>Graph</h3><p style="font-size:12px;color:var(--ink-faint);margin:8px 0;font-style:italic;">No graph data yet. Building from observations and memories...</p>';
var buildResult = await apiPost('graph/build', {});
if (buildResult && buildResult.success && buildResult.nodes > 0) {
var freshResults = await Promise.all([
- apiPost('graph/query', {}),
+ apiPost('graph/query', { limit: GRAPH_INITIAL_LIMIT }),
apiGet('graph/stats')
]);
- var freshQuery = freshResults[0] || { nodes: [], edges: [] };
- state.graph.nodes = freshQuery.nodes || [];
- state.graph.edges = freshQuery.edges || [];
+ var freshQuery = freshResults[0];
+ if (freshQuery) {
+ state.graph.nodes = freshQuery.nodes || [];
+ state.graph.edges = freshQuery.edges || [];
+ state.graph.truncated = freshQuery.truncated === true;
+ state.graph.totalNodes = typeof freshQuery.totalNodes === 'number' ? freshQuery.totalNodes : state.graph.nodes.length;
+ state.graph.totalEdges = typeof freshQuery.totalEdges === 'number' ? freshQuery.totalEdges : state.graph.edges.length;
+ }
state.graph.stats = freshResults[1] || {};
}
}
@@ -1719,7 +1749,26 @@
var nodeCount = gs.totalNodes !== undefined ? gs.totalNodes : (gs.nodes !== undefined ? gs.nodes : (gs.nodeCount || state.graph.nodes.length));
var edgeCount = gs.totalEdges !== undefined ? gs.totalEdges : (gs.edges !== undefined ? gs.edges : (gs.edgeCount || state.graph.edges.length));
- var html = '<input type="text" class="graph-search" id="graph-search" placeholder="Search nodes...">';
+ var html = '';
+
+ // #753: error banner stays above the search box so a failed
+ // graph/query doesn't read as "0 nodes".
+ if (state.graph.queryError) {
+ html += '<div style="margin:8px 0;padding:10px 12px;border:1px solid var(--accent);background:var(--bg-alt);font-size:12px;color:var(--ink);line-height:1.4;">';
+ html += '<div style="font-weight:600;margin-bottom:4px;">Graph query failed</div>';
+ html += '<div style="font-size:11px;color:var(--ink-muted);">' + esc(state.graph.queryError) + '</div>';
+ html += '<button class="btn" data-action="rebuild-graph" style="margin-top:8px;font-size:11px;">Retry</button>';
+ html += '</div>';
+ } else if (state.graph.truncated) {
+ // #753: surface the cap so operators know they're not seeing
+ // the whole graph. Densest-first ranking on the server makes
+ // this the meaningful subset, not an arbitrary head.
+ html += '<div style="margin:8px 0;padding:10px 12px;border:1px solid var(--border);background:var(--bg-alt);font-size:11px;color:var(--ink-muted);line-height:1.4;">';
+ html += 'Showing ' + state.graph.nodes.length + ' of ' + state.graph.totalNodes + ' nodes (most-connected first). The full graph is too large to render at once.';
+ html += '</div>';
+ }
+
+ html += '<input type="text" class="graph-search" id="graph-search" placeholder="Search nodes...">';
html += '<h3 style="margin-top:16px;font-size:10px;text-transform:uppercase;letter-spacing:0.12em;color:var(--ink-muted);font-family:var(--font-ui);font-weight:700;">Graph Stats</h3>';
html += '<div style="display:flex;gap:20px;margin:10px 0 16px;padding:12px;background:var(--bg-alt);border:1px solid var(--border-light);border-radius:4px;">';
diff --git a/test/graph.test.ts b/test/graph.test.ts
index ca50264c..ef0ebb5c 100644
--- a/test/graph.test.ts
+++ b/test/graph.test.ts
@@ -214,4 +214,168 @@ describe("Graph Functions", () => {
expect(result.success).toBe(false);
expect(result.error).toContain("No observations");
});
+
+ // #753: an unbounded {} body used to materialize every node+edge in
+ // one payload, which exceeded the iii state response channel on
+ // large corpora (11k+ nodes) and returned HTTP 500 "Invocation
+ // stopped". The fix caps the page at DEFAULT_GRAPH_QUERY_LIMIT (500)
+ // and surfaces totalNodes / totalEdges so callers know it was
+ // truncated.
+ it("caps an unbounded graph-query body to a default page and reports totals", async () => {
+ // Seed a graph with more nodes than the default page size.
+ const NODE_COUNT = 1200;
+ for (let i = 0; i < NODE_COUNT; i++) {
+ const node: GraphNode = {
+ id: `n_${i.toString().padStart(4, "0")}`,
+ type: "concept",
+ name: `node-${i}`,
+ properties: {},
+ firstSeen: "2026-01-01T00:00:00Z",
+ lastSeen: "2026-01-01T00:00:00Z",
+ observationCount: 1,
+ } as GraphNode;
+ await kv.set("mem:graph:nodes", node.id, node);
+ }
+ // A few edges among the first 50 nodes so high-degree ranking has
+ // something to grade.
+ for (let i = 0; i < 50; i++) {
+ const edge: GraphEdge = {
+ id: `e_${i}`,
+ type: "related_to",
+ sourceNodeId: `n_${i.toString().padStart(4, "0")}`,
+ targetNodeId: `n_${((i + 1) % 50).toString().padStart(4, "0")}`,
+ weight: 1,
+ evidence: [],
+ firstSeen: "2026-01-01T00:00:00Z",
+ lastSeen: "2026-01-01T00:00:00Z",
+ } as GraphEdge;
+ await kv.set("mem:graph:edges", edge.id, edge);
+ }
+
+ const unbounded = (await sdk.trigger(
+ "mem::graph-query",
+ {},
+ )) as GraphQueryResult;
+
+ expect(unbounded.totalNodes).toBe(NODE_COUNT);
+ expect(unbounded.nodes.length).toBe(500);
+ expect(unbounded.truncated).toBe(true);
+ expect(unbounded.limit).toBe(500);
+ expect(unbounded.offset).toBe(0);
+ // The 50 connected nodes should be on the first page since the
+ // default ranks by degree.
+ const connectedOnPage = unbounded.nodes.filter((n) => /^n_00[0-4]\d$/.test(n.id));
+ expect(connectedOnPage.length).toBe(50);
+ });
+
+ it("honors limit and offset for paged graph-query traversal", async () => {
+ for (let i = 0; i < 50; i++) {
+ const node: GraphNode = {
+ id: `p_${i.toString().padStart(3, "0")}`,
+ type: "concept",
+ name: `node-${i}`,
+ properties: {},
+ firstSeen: "2026-01-01T00:00:00Z",
+ lastSeen: "2026-01-01T00:00:00Z",
+ observationCount: 1,
+ } as GraphNode;
+ await kv.set("mem:graph:nodes", node.id, node);
+ }
+
+ const page1 = (await sdk.trigger("mem::graph-query", {
+ limit: 10,
+ offset: 0,
+ })) as GraphQueryResult;
+ const page2 = (await sdk.trigger("mem::graph-query", {
+ limit: 10,
+ offset: 10,
+ })) as GraphQueryResult;
+
+ expect(page1.nodes.length).toBe(10);
+ expect(page2.nodes.length).toBe(10);
+ expect(page1.totalNodes).toBe(50);
+ expect(page2.totalNodes).toBe(50);
+ expect(page1.truncated).toBe(true);
+ // The two pages must not overlap.
+ const overlap = page1.nodes.filter((n) =>
+ page2.nodes.some((p) => p.id === n.id),
+ );
+ expect(overlap.length).toBe(0);
+ });
+
+ it("clamps an explicit limit above the cap to the cap value", async () => {
+ for (let i = 0; i < 10; i++) {
+ await kv.set("mem:graph:nodes", `c_${i}`, {
+ id: `c_${i}`,
+ type: "concept",
+ name: `n-${i}`,
+ properties: {},
+ firstSeen: "2026-01-01T00:00:00Z",
+ lastSeen: "2026-01-01T00:00:00Z",
+ observationCount: 1,
+ });
+ }
+
+ const huge = (await sdk.trigger("mem::graph-query", {
+ limit: 999999,
+ })) as GraphQueryResult;
+ expect(huge.limit).toBeLessThanOrEqual(5000);
+ expect(huge.nodes.length).toBe(10);
+ expect(huge.truncated).toBe(false);
+ });
+
+ it("paginate excludes edges whose endpoints fall outside the page", async () => {
+ for (let i = 0; i < 60; i++) {
+ await kv.set("mem:graph:nodes", `x_${i.toString().padStart(3, "0")}`, {
+ id: `x_${i.toString().padStart(3, "0")}`,
+ type: "concept",
+ name: `n-${i}`,
+ properties: {},
+ firstSeen: "2026-01-01T00:00:00Z",
+ lastSeen: "2026-01-01T00:00:00Z",
+ observationCount: 1,
+ });
+ }
+ // Make the first 10 nodes a tightly connected cluster so they
+ // rank highest by degree and land on the page deterministically.
+ for (let i = 0; i < 10; i++) {
+ const next = (i + 1) % 10;
+ await kv.set("mem:graph:edges", `cluster_${i}`, {
+ id: `cluster_${i}`,
+ type: "related_to",
+ sourceNodeId: `x_${i.toString().padStart(3, "0")}`,
+ targetNodeId: `x_${next.toString().padStart(3, "0")}`,
+ weight: 1,
+ evidence: [],
+ firstSeen: "2026-01-01T00:00:00Z",
+ lastSeen: "2026-01-01T00:00:00Z",
+ });
+ }
+ // Cross-page edge: source in the high-degree cluster (on page),
+ // target is an isolated node (degree 1; cluster nodes have
+ // degree 2 so the target ranks below the cap).
+ await kv.set("mem:graph:edges", "cross", {
+ id: "cross",
+ type: "related_to",
+ sourceNodeId: "x_005",
+ targetNodeId: "x_055",
+ weight: 1,
+ evidence: [],
+ firstSeen: "2026-01-01T00:00:00Z",
+ lastSeen: "2026-01-01T00:00:00Z",
+ });
+
+ const page = (await sdk.trigger("mem::graph-query", {
+ limit: 10,
+ offset: 0,
+ })) as GraphQueryResult;
+ // The cross-page edge should not appear in the page response —
+ // otherwise the viewer renders a dangling line to a node it
+ // doesn't have.
+ expect(page.edges.find((e) => e.id === "cross")).toBeUndefined();
+ // Cluster edges among page nodes ARE present.
+ expect(page.edges.filter((e) => e.id.startsWith("cluster_")).length).toBe(10);
+ // totalEdges counts every edge in the full result universe.
+ expect(page.totalEdges).toBe(11);
+ });
});