From 6715febcdc2770e6bc77336c62a20a5908937244 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Fri, 25 Sep 2026 00:25:38 -0400 Subject: [PATCH 01/14] fix(graph): bound and attribute node and edge provenance Each merge in persistGraphDelta added every observation id in the batch to every node and edge it touched, with no limit. Hot nodes grew without bound. On one store, 98% of the graph's bytes were these ids: 426 per node and 362 per edge on average. Nodes took 323 MB and edges 398 MB. Every kv.list traversal of the graph carried them. - A merge now adds the incoming record's own sourceObservationIds, not the whole batch. Heuristic extraction knows the exact source, so that attribution is now kept. - Each record keeps its newest 32 ids (MAX_GRAPH_SOURCE_OBSERVATIONS). A re-seen id moves to the newest end. New records are trimmed on first write. Retrieval returns at most 20 results, so 32 covers it. - The temporal-graph node merge uses the same rule. - New mem::graph-compact and POST /agentmemory/graph/compact trim records written before the cap. They walk the name and edge-key indexes and read and write one key at a time, so they never list the nodes or edges scope. An optional scope, offset and limit runs one slice per call, so each call finishes between worker reconnects. Re-running a slice is safe. - Compaction takes the graph:persist lock per record, so a trim cannot overwrite a merge that lands during it. persistGraphDelta no longer takes the batch id list. Measured on a live store: compaction trimmed 18,324 nodes and 32,654 edges and removed 18.9 million ids in 45 s with no retries. Nodes went from 323 to 30 MB and edges from 398 to 42 MB. Fixes #1374 Signed-off-by: David Waltermire --- AGENTS.md | 2 +- README.md | 2 +- .../skills/agentmemory-rest-api/REFERENCE.md | 3 +- src/functions/graph-import.ts | 1 - src/functions/graph.ts | 191 ++++++- src/functions/temporal-graph.ts | 12 +- src/index.ts | 2 +- src/triggers/api.ts | 28 ++ test/graph-compact.test.ts | 469 ++++++++++++++++++ test/graph-provenance-cap.test.ts | 288 +++++++++++ 10 files changed, 968 insertions(+), 30 deletions(-) create mode 100644 test/graph-compact.test.ts create mode 100644 test/graph-provenance-cap.test.ts diff --git a/AGENTS.md b/AGENTS.md index 9145dfa2ca..e65ccef47d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,7 +119,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Current Stats (v0.9.29) - 54 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all) -- 134 REST endpoints +- 135 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 17 skills - 260+ iii functions diff --git a/README.md b/README.md index 120ac49fa0..60f98155d7 100644 --- a/README.md +++ b/README.md @@ -1671,7 +1671,7 @@ Create `~/.agentmemory/.env`:

API

-134 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers. +135 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
Key endpoints diff --git a/plugin/skills/agentmemory-rest-api/REFERENCE.md b/plugin/skills/agentmemory-rest-api/REFERENCE.md index 75671c946e..7de5301098 100644 --- a/plugin/skills/agentmemory-rest-api/REFERENCE.md +++ b/plugin/skills/agentmemory-rest-api/REFERENCE.md @@ -5,7 +5,7 @@ Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run ` The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). When `AGENTMEMORY_SECRET` is set, send `Authorization: Bearer $AGENTMEMORY_SECRET`; localhost is otherwise open. -134 registered endpoints: +135 registered endpoints: | Method | Path | | --- | --- | @@ -55,6 +55,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111` | POST | `/agentmemory/governance/bulk-delete` | | DELETE | `/agentmemory/governance/memories` | | POST | `/agentmemory/graph/build` | +| POST | `/agentmemory/graph/compact` | | POST | `/agentmemory/graph/extract` | | POST | `/agentmemory/graph/import-graphify` | | GET | `/agentmemory/graph/node` | diff --git a/src/functions/graph-import.ts b/src/functions/graph-import.ts index 502526e8ba..bc595c9db7 100644 --- a/src/functions/graph-import.ts +++ b/src/functions/graph-import.ts @@ -224,7 +224,6 @@ export function registerGraphImportFunction(sdk: IIIClient, kv: StateKV): void { kv, parsed.nodes, parsed.edges, - [], ); await recordAudit(kv, "import", "mem::graph::import-graphify", [], { diff --git a/src/functions/graph.ts b/src/functions/graph.ts index 38add02bd4..0bd365838b 100644 --- a/src/functions/graph.ts +++ b/src/functions/graph.ts @@ -279,35 +279,47 @@ function snapshotPushEdgeIfBothInTop( } } +// Provenance is bounded. Every merge used to union the whole batch's +// observation ids into every node and edge it touched, which grew hot +// nodes without limit: on one store 98% of the graph's bytes were these +// ids, and every kv.list traversal carried them. Retrieval reads at most +// 20 results, so a record never needs more than its newest sources. +export const MAX_GRAPH_SOURCE_OBSERVATIONS = 32; + +// Union in arrival order, with a re-seen id moved to the newest end, then +// keep the newest MAX_GRAPH_SOURCE_OBSERVATIONS. +export function boundSources(existing: string[], incoming: string[]): string[] { + const merged = new Set(existing); + for (const id of incoming) { + merged.delete(id); + merged.add(id); + } + return [...merged].slice(-MAX_GRAPH_SOURCE_OBSERVATIONS); +} + function mergeNode( existing: GraphNode, incoming: GraphNode, - obsIds: string[], capturedAt: string, ): GraphNode { return { ...existing, - sourceObservationIds: [ - ...new Set([ - ...existing.sourceObservationIds, - ...incoming.sourceObservationIds, - ...obsIds, - ]), - ], + sourceObservationIds: boundSources( + existing.sourceObservationIds ?? [], + incoming.sourceObservationIds ?? [], + ), properties: { ...existing.properties, ...incoming.properties }, updatedAt: capturedAt, }; } -function mergeEdge( - existing: GraphEdge, - obsIds: string[], -): GraphEdge { +function mergeEdge(existing: GraphEdge, incoming: GraphEdge): GraphEdge { return { ...existing, - sourceObservationIds: [ - ...new Set([...existing.sourceObservationIds, ...obsIds]), - ], + sourceObservationIds: boundSources( + existing.sourceObservationIds ?? [], + incoming.sourceObservationIds ?? [], + ), }; } @@ -559,7 +571,6 @@ export async function persistGraphDelta( kv: StateKV, nodes: GraphNode[], edges: GraphEdge[], - obsIds: string[], ): Promise<{ newNodeCount: number; newEdgeCount: number }> { return withKeyedLock("graph:persist", async () => { const snap = (await readSnapshot(kv)) ?? emptySnapshot(); @@ -600,7 +611,7 @@ export async function persistGraphDelta( if (existing) { idRemap.set(node.id, existing.id); - const merged = mergeNode(existing, node, obsIds, capturedAt); + const merged = mergeNode(existing, node, capturedAt); await kv.set(KV.graphNodes, existing.id, merged); // Update topNodes entry if present so a stale clone isn't // returned from the snapshot fast path. @@ -610,6 +621,7 @@ export async function persistGraphDelta( snapMutated = true; } } else { + node.sourceObservationIds = boundSources([], node.sourceObservationIds ?? []); await kv.set(KV.graphNodes, node.id, node); await kv.set(KV.graphNameIndex, indexKey, node.id); await kv.set(KV.graphNodeDegree, node.id, 0); @@ -650,7 +662,7 @@ export async function persistGraphDelta( } if (existing) { - const merged = mergeEdge(existing, obsIds); + const merged = mergeEdge(existing, edge); 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); @@ -659,6 +671,7 @@ export async function persistGraphDelta( snapMutated = true; } } else { + edge.sourceObservationIds = boundSources([], edge.sourceObservationIds ?? []); await kv.set(KV.graphEdges, edge.id, edge); await kv.set(KV.graphEdgeKey, eKey, edge.id); snap.stats.totalEdges += 1; @@ -688,6 +701,133 @@ export async function persistGraphDelta( }); } +export interface GraphCompactResult { + nodesScanned: number; + nodesTrimmed: number; + edgesScanned: number; + edgesTrimmed: number; + idsRemoved: number; + snapshotTrimmed: boolean; + // Records in the sliced index, and where the next slice starts; null + // when this call reached the end. A full run always ends with null. + total?: number; + nextOffset: number | null; +} + +export type GraphCompactScope = "nodes" | "edges" | "snapshot"; + +export interface GraphCompactOptions { + scope?: GraphCompactScope; + offset?: number; + limit?: number; +} + +const COMPACT_SCOPES: readonly GraphCompactScope[] = ["nodes", "edges", "snapshot"]; + +// Trims provenance written before the cap existed. Records are reached +// through the name and edge-key indexes, whose values are short ids, and +// then read and written one key at a time. The nodes and edges scopes are +// never listed: that payload is what drops the worker on a large store. +// A record missing from both indexes is not reached; it is also never +// merged again, so it cannot grow. +// +// With no options it does everything in one call. With a scope it does one +// slice, so each invocation stays short enough to finish between worker +// reconnects; the caller walks nextOffset until it is null. Re-running any +// slice is safe because trimmed records are skipped. +export async function compactGraphProvenance( + kv: StateKV, + opts: GraphCompactOptions = {}, +): Promise { + const { scope } = opts; + if (scope !== undefined && !COMPACT_SCOPES.includes(scope)) { + throw new Error(`unknown compact scope: ${String(scope)}`); + } + const offset = opts.offset ?? 0; + const limit = opts.limit ?? Number.POSITIVE_INFINITY; + if (!Number.isInteger(offset) || offset < 0) { + throw new Error(`compact offset must be a non-negative integer: ${String(opts.offset)}`); + } + if (!(limit === Number.POSITIVE_INFINITY || (Number.isInteger(limit) && limit > 0))) { + throw new Error(`compact limit must be a positive integer: ${String(opts.limit)}`); + } + + const result: GraphCompactResult = { + nodesScanned: 0, + nodesTrimmed: 0, + edgesScanned: 0, + edgesTrimmed: 0, + idsRemoved: 0, + snapshotTrimmed: false, + nextOffset: null, + }; + + const trimScope = async ( + indexScope: string, + recordScope: string, + ): Promise<{ scanned: number; trimmed: number }> => { + const allIds = [...new Set(await kv.list(indexScope))].filter( + (id): id is string => typeof id === "string", + ); + const end = Math.min(allIds.length, offset + limit); + result.total = allIds.length; + result.nextOffset = end < allIds.length ? end : null; + let scanned = 0; + let trimmed = 0; + for (const id of allIds.slice(offset, end)) { + await withKeyedLock("graph:persist", async () => { + const record = await kv.get(recordScope, id); + if (!record) return; + scanned += 1; + const sources = record.sourceObservationIds ?? []; + if (sources.length <= MAX_GRAPH_SOURCE_OBSERVATIONS) return; + const bounded = boundSources([], sources); + result.idsRemoved += sources.length - bounded.length; + await kv.set(recordScope, id, { ...record, sourceObservationIds: bounded }); + trimmed += 1; + }); + } + return { scanned, trimmed }; + }; + + const trimSnapshot = () => + withKeyedLock("graph:persist", async () => { + const snap = await readSnapshot(kv); + if (!snap) return; + const trimList = (list: R[]) => + list.map((r) => { + const sources = r.sourceObservationIds ?? []; + if (sources.length <= MAX_GRAPH_SOURCE_OBSERVATIONS) return r; + result.snapshotTrimmed = true; + return { ...r, sourceObservationIds: boundSources([], sources) }; + }); + const topNodes = trimList(snap.topNodes); + const topEdges = trimList(snap.topEdges); + if (result.snapshotTrimmed) { + await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, { ...snap, topNodes, topEdges }); + } + }); + + if (scope === undefined || scope === "nodes") { + const n = await trimScope(KV.graphNameIndex, KV.graphNodes); + result.nodesScanned = n.scanned; + result.nodesTrimmed = n.trimmed; + } + if (scope === undefined || scope === "edges") { + const e = await trimScope(KV.graphEdgeKey, KV.graphEdges); + result.edgesScanned = e.scanned; + result.edgesTrimmed = e.trimmed; + } + if (scope === undefined || scope === "snapshot") { + await trimSnapshot(); + } + if (scope === undefined) { + delete result.total; + result.nextOffset = null; + } + return result; +} + export function registerGraphFunction( sdk: IIIClient, kv: StateKV, @@ -751,7 +891,6 @@ export function registerGraphFunction( kv, nodes, edges, - obsIds, ); await recordAudit(kv, "observe", "mem::graph-extract", obsIds, { @@ -1135,6 +1274,20 @@ export function registerGraphFunction( // read by any post-#816 code path. Cleanup is deferred to a future // chunked-vacuum job; #816's broken vacuum-via-list strategy is // what we are leaving behind here. + sdk.registerFunction("mem::graph-compact", async (data?: GraphCompactOptions) => { + const started = Date.now(); + try { + const result = await compactGraphProvenance(kv, data ?? {}); + const tookMs = Date.now() - started; + logger.info("Graph provenance compacted", { ...result, tookMs }); + return { success: true, ...result, tookMs }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logger.error("Graph provenance compaction failed", { error: msg }); + return { success: false, error: msg }; + } + }); + sdk.registerFunction("mem::graph-reset", async () => { const started = Date.now(); // Stamp resetAt=now on the empty snapshot. Future diff --git a/src/functions/temporal-graph.ts b/src/functions/temporal-graph.ts index 18d13c1fe5..4ee0c4c1be 100644 --- a/src/functions/temporal-graph.ts +++ b/src/functions/temporal-graph.ts @@ -8,6 +8,7 @@ import type { MemoryProvider, } from "../types.js"; import { KV, generateId } from "../state/schema.js"; +import { boundSources } from "./graph.js"; import type { StateKV } from "../state/kv.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import { logger } from "../logger.js"; @@ -201,12 +202,10 @@ export function registerTemporalGraphFunctions( const oldId = node.id; const merged = { ...existing, - sourceObservationIds: [ - ...new Set([ - ...existing.sourceObservationIds, - ...obsIds, - ]), - ], + sourceObservationIds: boundSources( + existing.sourceObservationIds ?? [], + node.sourceObservationIds ?? [], + ), properties: { ...existing.properties, ...node.properties }, updatedAt: new Date().toISOString(), aliases: [ @@ -221,6 +220,7 @@ export function registerTemporalGraphFunctions( node.id = existing.id; idRemap.set(oldId, existing.id); } else { + node.sourceObservationIds = boundSources([], node.sourceObservationIds ?? []); await kv.set(KV.graphNodes, node.id, node); existingNodes.push(node); } diff --git a/src/index.ts b/src/index.ts index e85f16217f..914a72a567 100644 --- a/src/index.ts +++ b/src/index.ts @@ -536,7 +536,7 @@ async function main() { `Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`, ); bootLog( - `REST API: 134 endpoints at http://localhost:${config.restPort}/agentmemory/*`, + `REST API: 135 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/triggers/api.ts b/src/triggers/api.ts index 8ae72d43c5..5a229dfef2 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -2017,6 +2017,34 @@ export function registerApiTriggers( config: { api_path: "/agentmemory/graph/reset", http_method: "POST" }, }); + // Trims graph provenance written before the per-record cap, walking the + // small name and edge-key indexes instead of listing the graph. + sdk.registerFunction("api::graph-compact", + async (req: HttpRequest): Promise => { + const authErr = checkAuth(req, secret); + if (authErr) return authErr; + try { + const body = (req.body ?? {}) as Record; + const result = await sdk.trigger({ + function_id: "mem::graph-compact", + payload: { + scope: body.scope, + offset: body.offset, + limit: body.limit, + }, + }); + return { status_code: 200, body: result }; + } catch { + return graphDisabledResponse(); + } + }, + ); + sdk.registerTrigger({ + type: "http", + function_id: "api::graph-compact", + config: { api_path: "/agentmemory/graph/compact", http_method: "POST" }, + }); + sdk.registerFunction("api::graph-extract", async (req: HttpRequest<{ observations: unknown[] }>): Promise => { const authErr = checkAuth(req, secret); diff --git a/test/graph-compact.test.ts b/test/graph-compact.test.ts new file mode 100644 index 0000000000..6b32a910c2 --- /dev/null +++ b/test/graph-compact.test.ts @@ -0,0 +1,469 @@ +import { describe, it, expect, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { + compactGraphProvenance, + persistGraphDelta, + registerGraphFunction, + MAX_GRAPH_SOURCE_OBSERVATIONS, +} from "../src/functions/graph.js"; +import type { GraphEdge, GraphNode } from "../src/types.js"; + +// Compaction trims provenance written before the cap existed. It must +// reach records through the small name and edge-key indexes only: listing +// the nodes or edges scope is the payload that drops the worker. + +// slowFirstNodeRead delays only the FIRST read of a node record, after the +// value is captured. That forces the interleaving that loses a merge when +// writers are not serialized: compaction reads, a merge writes, then +// compaction writes back its stale copy. +function mockKV(slowFirstNodeReadMs = 0) { + const store = new Map>(); + const calls = { list: [] as string[], set: [] as string[] }; + let nodeReads = 0; + return { + calls, + get: async (scope: string, key: string): Promise => { + const v = store.get(scope)?.get(key); + if ( + scope === "mem:graph:nodes" && + nodeReads++ === 0 && + slowFirstNodeReadMs + ) { + await new Promise((r) => setTimeout(r, slowFirstNodeReadMs)); + } + return (v === undefined ? null : structuredClone(v)) as T | null; + }, + set: async (scope: string, key: string, data: T): Promise => { + calls.set.push(`${scope}/${key}`); + if (!store.has(scope)) store.set(scope, new Map()); + store.get(scope)!.set(key, structuredClone(data)); + return data; + }, + delete: async (scope: string, key: string): Promise => { + store.get(scope)?.delete(key); + }, + list: async (scope: string): Promise => { + calls.list.push(scope); + const entries = store.get(scope); + return entries + ? (Array.from(entries.values()).map((v) => structuredClone(v)) as T[]) + : []; + }, + }; +} +type KV = ReturnType; + +const ids = (prefix: string, n: number) => + Array.from({ length: n }, (_, i) => `${prefix}_${i}`); + +async function seedNode(kv: KV, id: string, name: string, sources: string[]) { + const n: GraphNode = { + id, + type: "concept", + name, + properties: { keep: "me" }, + sourceObservationIds: sources, + createdAt: "2026-09-01T00:00:00.000Z", + aliases: ["alias"], + }; + await kv.set("mem:graph:nodes", id, n); + await kv.set("mem:graph:name-index", `concept|${name}`, id); + return n; +} + +async function seedEdge( + kv: KV, + id: string, + src: string, + tgt: string, + sources: string[], +) { + const e: GraphEdge = { + id, + type: "related_to", + sourceNodeId: src, + targetNodeId: tgt, + weight: 0.7, + sourceObservationIds: sources, + createdAt: "2026-09-01T00:00:00.000Z", + }; + await kv.set("mem:graph:edges", id, e); + await kv.set("mem:graph:edge-key", `${src}|${tgt}|related_to`, id); + return e; +} + +const node = (kv: KV, id: string) => kv.get("mem:graph:nodes", id); +const edge = (kv: KV, id: string) => kv.get("mem:graph:edges", id); + +describe("compactGraphProvenance", () => { + it("trims an oversized node to the newest ids and keeps every other field", async () => { + const kv = mockKV(); + const many = ids("obs", 500); + const before = await seedNode(kv, "gn_1", "hub", many); + await compactGraphProvenance(kv as never); + const after = (await node(kv, "gn_1"))!; + expect(after.sourceObservationIds).toEqual( + many.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS), + ); + expect({ ...after, sourceObservationIds: [] }).toEqual({ + ...before, + sourceObservationIds: [], + }); + }); + + it("trims an oversized edge the same way", async () => { + const kv = mockKV(); + const many = ids("obs", 300); + const before = await seedEdge(kv, "ge_1", "gn_a", "gn_b", many); + await compactGraphProvenance(kv as never); + const after = (await edge(kv, "ge_1"))!; + expect(after.sourceObservationIds).toEqual( + many.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS), + ); + expect({ ...after, sourceObservationIds: [] }).toEqual({ + ...before, + sourceObservationIds: [], + }); + }); + + it("does not rewrite records already within the cap", async () => { + const kv = mockKV(); + await seedNode( + kv, + "gn_small", + "small", + ids("obs", MAX_GRAPH_SOURCE_OBSERVATIONS), + ); + await seedEdge(kv, "ge_small", "gn_a", "gn_b", ["obs_1"]); + kv.calls.set.length = 0; + await compactGraphProvenance(kv as never); + expect( + kv.calls.set.filter( + (c) => + c.startsWith("mem:graph:nodes/") || c.startsWith("mem:graph:edges/"), + ), + ).toEqual([]); + }); + + it("never lists the nodes or edges scope", async () => { + const kv = mockKV(); + await seedNode(kv, "gn_1", "hub", ids("obs", 100)); + await seedEdge(kv, "ge_1", "gn_1", "gn_2", ids("obs", 100)); + await compactGraphProvenance(kv as never); + expect(kv.calls.list).not.toContain("mem:graph:nodes"); + expect(kv.calls.list).not.toContain("mem:graph:edges"); + }); + + it("reports what it scanned and trimmed", async () => { + const kv = mockKV(); + await seedNode(kv, "gn_1", "big", ids("obs", 100)); + await seedNode(kv, "gn_2", "small", ["obs_1"]); + await seedEdge(kv, "ge_1", "gn_1", "gn_2", ids("obs", 40)); + const r = await compactGraphProvenance(kv as never); + expect(r).toMatchObject({ + nodesScanned: 2, + nodesTrimmed: 1, + edgesScanned: 1, + edgesTrimmed: 1, + idsRemoved: + 100 - + MAX_GRAPH_SOURCE_OBSERVATIONS + + (40 - MAX_GRAPH_SOURCE_OBSERVATIONS), + }); + }); + + it("skips an index entry whose record is missing", async () => { + const kv = mockKV(); + await kv.set("mem:graph:name-index", "concept|ghost", "gn_missing"); + await kv.set("mem:graph:edge-key", "a|b|related_to", "ge_missing"); + const r = await compactGraphProvenance(kv as never); + expect(r).toMatchObject({ + nodesScanned: 0, + edgesScanned: 0, + nodesTrimmed: 0, + edgesTrimmed: 0, + }); + }); + + it("visits a record once when two index keys point at it", async () => { + const kv = mockKV(); + await seedNode(kv, "gn_1", "hub", ids("obs", 100)); + await kv.set("mem:graph:name-index", "concept|hub-alias", "gn_1"); + const r = await compactGraphProvenance(kv as never); + expect(r.nodesScanned).toBe(1); + expect(r.nodesTrimmed).toBe(1); + }); + + it("trims the cached snapshot's top nodes and edges", async () => { + const kv = mockKV(); + const n = await seedNode(kv, "gn_1", "hub", ids("obs", 100)); + const e = await seedEdge(kv, "ge_1", "gn_1", "gn_2", ids("obs", 80)); + await kv.set("mem:graph:snapshot", "current", { + version: 1, + dirty: false, + topNodes: [n], + topEdges: [e], + topDegrees: { gn_1: 1 }, + stats: { totalNodes: 1, totalEdges: 1, nodesByType: {}, edgesByType: {} }, + updatedAt: "2026-09-01T00:00:00.000Z", + }); + const r = await compactGraphProvenance(kv as never); + const snap = (await kv.get<{ + topNodes: GraphNode[]; + topEdges: GraphEdge[]; + }>("mem:graph:snapshot", "current"))!; + expect(snap.topNodes[0]!.sourceObservationIds.length).toBe( + MAX_GRAPH_SOURCE_OBSERVATIONS, + ); + expect(snap.topEdges[0]!.sourceObservationIds.length).toBe( + MAX_GRAPH_SOURCE_OBSERVATIONS, + ); + expect(r.snapshotTrimmed).toBe(true); + }); + + it("an empty graph is a no-op", async () => { + const kv = mockKV(); + const r = await compactGraphProvenance(kv as never); + expect(r).toMatchObject({ + nodesScanned: 0, + edgesScanned: 0, + idsRemoved: 0, + snapshotTrimmed: false, + }); + }); + + it("a merge running during compaction is not lost", async () => { + const kv = mockKV(20); + await seedNode(kv, "gn_1", "hub", ids("obs", 100)); + const incoming: GraphNode = { + id: "gn_fresh", + type: "concept", + name: "hub", + properties: { added: "during-compaction" }, + sourceObservationIds: ["obs_during"], + createdAt: "2026-09-24T00:00:00.000Z", + }; + await Promise.all([ + compactGraphProvenance(kv as never), + persistGraphDelta(kv as never, [incoming], []), + ]); + const after = (await node(kv, "gn_1"))!; + expect(after.sourceObservationIds).toContain("obs_during"); + expect(after.properties).toMatchObject({ + keep: "me", + added: "during-compaction", + }); + expect(after.sourceObservationIds.length).toBeLessThanOrEqual( + MAX_GRAPH_SOURCE_OBSERVATIONS, + ); + }); + + it("is registered as mem::graph-compact", async () => { + const kv = mockKV(); + await seedNode(kv, "gn_1", "hub", ids("obs", 50)); + const functions = new Map(); + const sdk = { + registerFunction: ( + idOrOpts: string | { id: string }, + handler: Function, + ) => + functions.set( + typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id, + handler, + ), + registerTrigger: () => {}, + }; + registerGraphFunction( + sdk as never, + kv as never, + { name: "noop", compress: vi.fn(), summarize: vi.fn() } as never, + ); + const fn = functions.get("mem::graph-compact"); + expect(fn).toBeDefined(); + const r = await fn!({}); + expect(r).toMatchObject({ success: true, nodesTrimmed: 1 }); + }); +}); + +describe("api::graph-compact endpoint", () => { + it("is an authenticated POST at /agentmemory/graph/compact that runs mem::graph-compact", async () => { + const { readFileSync } = await import("node:fs"); + const api = readFileSync("src/triggers/api.ts", "utf-8"); + expect(api).toMatch( + /registerFunction\("api::graph-compact",[\s\S]*?checkAuth\(req, secret\)[\s\S]*?function_id: "mem::graph-compact"/, + ); + expect(api).toMatch( + /function_id: "api::graph-compact",\s*config: \{ api_path: "\/agentmemory\/graph\/compact", http_method: "POST" \}/, + ); + }); +}); + +describe("chunked compaction", () => { + it("processes one slice of a scope and returns where the next slice starts", async () => { + const kv = mockKV(); + for (let i = 0; i < 5; i++) + await seedNode(kv, `gn_${i}`, `n${i}`, ids(`obs${i}`, 50)); + const first = await compactGraphProvenance(kv as never, { + scope: "nodes", + offset: 0, + limit: 2, + }); + expect(first).toMatchObject({ + nodesScanned: 2, + nodesTrimmed: 2, + total: 5, + nextOffset: 2, + }); + const trimmed = []; + for (let i = 0; i < 5; i++) + trimmed.push((await node(kv, `gn_${i}`))!.sourceObservationIds.length); + expect(trimmed).toEqual([ + MAX_GRAPH_SOURCE_OBSERVATIONS, + MAX_GRAPH_SOURCE_OBSERVATIONS, + 50, + 50, + 50, + ]); + }); + + it("walking every slice trims everything and ends with nextOffset null", async () => { + const kv = mockKV(); + for (let i = 0; i < 5; i++) + await seedNode(kv, `gn_${i}`, `n${i}`, ids(`obs${i}`, 50)); + let offset: number | null = 0; + let calls = 0; + while (offset !== null && calls < 10) { + const r = await compactGraphProvenance(kv as never, { + scope: "nodes", + offset, + limit: 2, + }); + offset = r.nextOffset === undefined ? -1 : r.nextOffset; + calls += 1; + } + expect(calls).toBe(3); + for (let i = 0; i < 5; i++) { + expect((await node(kv, `gn_${i}`))!.sourceObservationIds.length).toBe( + MAX_GRAPH_SOURCE_OBSERVATIONS, + ); + } + }); + + it("an edges slice touches edges only", async () => { + const kv = mockKV(); + const n = await seedNode(kv, "gn_1", "hub", ids("obs", 50)); + await seedEdge(kv, "ge_1", "gn_1", "gn_2", ids("obs", 50)); + await kv.set("mem:graph:snapshot", "current", { + version: 1, + dirty: false, + topNodes: [n], + topEdges: [], + topDegrees: {}, + stats: { totalNodes: 1, totalEdges: 1, nodesByType: {}, edgesByType: {} }, + updatedAt: "2026-09-01T00:00:00.000Z", + }); + const r = await compactGraphProvenance(kv as never, { + scope: "edges", + offset: 0, + limit: 10, + }); + expect(r).toMatchObject({ + edgesTrimmed: 1, + nodesScanned: 0, + nextOffset: null, + snapshotTrimmed: false, + }); + expect((await node(kv, "gn_1"))!.sourceObservationIds.length).toBe(50); + const snap = (await kv.get<{ topNodes: GraphNode[] }>( + "mem:graph:snapshot", + "current", + ))!; + expect(snap.topNodes[0]!.sourceObservationIds.length).toBe(50); + }); + + it("the snapshot scope trims only the snapshot", async () => { + const kv = mockKV(); + const n = await seedNode(kv, "gn_1", "hub", ids("obs", 50)); + await kv.set("mem:graph:snapshot", "current", { + version: 1, + dirty: false, + topNodes: [n], + topEdges: [], + topDegrees: {}, + stats: { totalNodes: 1, totalEdges: 0, nodesByType: {}, edgesByType: {} }, + updatedAt: "2026-09-01T00:00:00.000Z", + }); + const r = await compactGraphProvenance(kv as never, { scope: "snapshot" }); + expect(r).toMatchObject({ + snapshotTrimmed: true, + nodesScanned: 0, + nextOffset: null, + }); + expect((await node(kv, "gn_1"))!.sourceObservationIds.length).toBe(50); + }); + + it("an offset past the end scans nothing and ends", async () => { + const kv = mockKV(); + await seedNode(kv, "gn_1", "hub", ids("obs", 50)); + const r = await compactGraphProvenance(kv as never, { + scope: "nodes", + offset: 10, + limit: 5, + }); + expect(r).toMatchObject({ nodesScanned: 0, total: 1, nextOffset: null }); + }); + + it("rejects an unknown scope or a bad offset or limit", async () => { + const kv = mockKV(); + await expect( + compactGraphProvenance(kv as never, { scope: "bogus" as never }), + ).rejects.toThrow(/scope/); + await expect( + compactGraphProvenance(kv as never, { + scope: "nodes", + offset: -1, + limit: 5, + }), + ).rejects.toThrow(/offset/); + await expect( + compactGraphProvenance(kv as never, { + scope: "nodes", + offset: 0, + limit: 0, + }), + ).rejects.toThrow(/limit/); + }); + + it("mem::graph-compact passes the slice through", async () => { + const kv = mockKV(); + for (let i = 0; i < 3; i++) + await seedNode(kv, `gn_${i}`, `n${i}`, ids(`obs${i}`, 50)); + const functions = new Map(); + const sdk = { + registerFunction: ( + idOrOpts: string | { id: string }, + handler: Function, + ) => + functions.set( + typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id, + handler, + ), + registerTrigger: () => {}, + }; + registerGraphFunction( + sdk as never, + kv as never, + { name: "noop", compress: vi.fn(), summarize: vi.fn() } as never, + ); + const r = await functions.get("mem::graph-compact")!({ + scope: "nodes", + offset: 0, + limit: 1, + }); + expect(r).toMatchObject({ success: true, nodesScanned: 1, nextOffset: 1 }); + }); +}); diff --git a/test/graph-provenance-cap.test.ts b/test/graph-provenance-cap.test.ts new file mode 100644 index 0000000000..44f436df76 --- /dev/null +++ b/test/graph-provenance-cap.test.ts @@ -0,0 +1,288 @@ +import { describe, it, expect, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { + persistGraphDelta, + MAX_GRAPH_SOURCE_OBSERVATIONS, +} from "../src/functions/graph.js"; +import type { GraphEdge, GraphNode } from "../src/types.js"; + +// Each merge used to union every observation id in the batch into every +// node and edge it touched, with no bound. On one store that made 98% of +// the graph's bytes provenance ids (426 per node on average), and every +// traversal carried them. + +function mockKV() { + const store = new Map>(); + return { + get: async (scope: string, key: string): Promise => + (store.get(scope)?.get(key) as T) ?? null, + set: async (scope: string, key: string, data: T): Promise => { + if (!store.has(scope)) store.set(scope, new Map()); + store.get(scope)!.set(key, data); + return data; + }, + delete: async (scope: string, key: string): Promise => { + store.get(scope)?.delete(key); + }, + list: async (scope: string): Promise => { + const entries = store.get(scope); + return entries ? (Array.from(entries.values()) as T[]) : []; + }, + }; +} + +let seq = 0; +function node(name: string, sources: string[]): GraphNode { + seq += 1; + return { + id: `gn_${seq}`, + type: "concept", + name, + properties: {}, + sourceObservationIds: sources, + createdAt: "2026-09-24T00:00:00.000Z", + }; +} + +function edge(src: string, tgt: string, sources: string[]): GraphEdge { + seq += 1; + return { + id: `ge_${seq}`, + type: "related_to", + sourceNodeId: src, + targetNodeId: tgt, + weight: 0.5, + sourceObservationIds: sources, + createdAt: "2026-09-24T00:00:00.000Z", + }; +} + +const ids = (prefix: string, n: number) => + Array.from({ length: n }, (_, i) => `${prefix}_${i}`); + +async function onlyNode(kv: ReturnType, name: string) { + const all = await kv.list("mem:graph:nodes"); + const hits = all.filter((n) => n.name === name); + expect(hits.length).toBe(1); + return hits[0]!; +} + +async function onlyEdge(kv: ReturnType) { + const all = await kv.list("mem:graph:edges"); + expect(all.length).toBe(1); + return all[0]!; +} + +describe("graph provenance is bounded and attributed", () => { + it("the cap is at least the largest retrieval result size", () => { + expect(MAX_GRAPH_SOURCE_OBSERVATIONS).toBeGreaterThanOrEqual(20); + }); + + it("a node merged many times never exceeds the cap", async () => { + const kv = mockKV(); + for (let batch = 0; batch < 20; batch++) { + const batchIds = ids(`obs_b${batch}`, 10); + await persistGraphDelta(kv as never, [node("CLAUDE.md", batchIds)], []); + } + const n = await onlyNode(kv, "CLAUDE.md"); + expect(n.sourceObservationIds.length).toBe(MAX_GRAPH_SOURCE_OBSERVATIONS); + }); + + it("the cap keeps the NEWEST ids, in arrival order", async () => { + const kv = mockKV(); + const all: string[] = []; + for (let batch = 0; batch < 10; batch++) { + const batchIds = ids(`obs_b${batch}`, 10); + all.push(...batchIds); + await persistGraphDelta(kv as never, [node("hub", batchIds)], []); + } + const n = await onlyNode(kv, "hub"); + expect(n.sourceObservationIds).toEqual( + all.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS), + ); + }); + + it("a re-seen id moves to the newest end and survives trimming", async () => { + const kv = mockKV(); + await persistGraphDelta(kv as never, [node("hub", ["obs_old"])], []); + const filler = ids("obs_fill", MAX_GRAPH_SOURCE_OBSERVATIONS - 1); + await persistGraphDelta(kv as never, [node("hub", filler)], []); + await persistGraphDelta(kv as never, [node("hub", ["obs_old"])], []); + await persistGraphDelta(kv as never, [node("hub", ["obs_new"])], []); + const n = await onlyNode(kv, "hub"); + expect(n.sourceObservationIds).toContain("obs_old"); + expect(n.sourceObservationIds.at(-1)).toBe("obs_new"); + expect(n.sourceObservationIds.at(-2)).toBe("obs_old"); + expect(n.sourceObservationIds).not.toContain("obs_fill_0"); + }); + + it("ids are never duplicated", async () => { + const kv = mockKV(); + for (let i = 0; i < 3; i++) { + await persistGraphDelta( + kv as never, + [node("hub", ["obs_a", "obs_b"])], + [], + ); + } + const n = await onlyNode(kv, "hub"); + expect(n.sourceObservationIds).toEqual(["obs_a", "obs_b"]); + }); + + it("a brand-new node carrying more than the cap is trimmed on first write", async () => { + const kv = mockKV(); + const many = ids("obs", MAX_GRAPH_SOURCE_OBSERVATIONS + 15); + await persistGraphDelta(kv as never, [node("fresh", many)], []); + const n = await onlyNode(kv, "fresh"); + expect(n.sourceObservationIds).toEqual( + many.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS), + ); + }); + + it("a merged node gains ITS OWN sources, not every id in the batch", async () => { + const kv = mockKV(); + await persistGraphDelta(kv as never, [node("a.ts", ["obs_1"])], []); + // A batch of obs_2..obs_4 in which only obs_3 mentioned a.ts. + await persistGraphDelta( + kv as never, + [node("a.ts", ["obs_3"]), node("b.ts", ["obs_2", "obs_4"])], + [], + ); + const a = await onlyNode(kv, "a.ts"); + expect(a.sourceObservationIds).toEqual(["obs_1", "obs_3"]); + }); + + it("a merged edge gains its own sources, bounded, not the batch", async () => { + const kv = mockKV(); + const a = node("a", ["obs_0"]); + const b = node("b", ["obs_0"]); + await persistGraphDelta(kv as never, [a, b], [edge(a.id, b.id, ["obs_0"])]); + for (let batch = 1; batch <= 10; batch++) { + // A batch of ten observations; only the first one links a and b. + const batchIds = ids(`obs_b${batch}`, 10); + const a2 = node("a", batchIds); + const b2 = node("b", batchIds); + await persistGraphDelta( + kv as never, + [a2, b2], + [edge(a2.id, b2.id, [batchIds[0]!])], + ); + } + const e = await onlyEdge(kv); + expect(e.sourceObservationIds).toEqual([ + "obs_0", + ...Array.from({ length: 10 }, (_, i) => `obs_b${i + 1}_0`), + ]); + }); + + it("a merged edge is capped", async () => { + const kv = mockKV(); + const a = node("a", ["obs_0"]); + const b = node("b", ["obs_0"]); + await persistGraphDelta(kv as never, [a, b], [edge(a.id, b.id, ["obs_0"])]); + const many = ids("obs_e", MAX_GRAPH_SOURCE_OBSERVATIONS * 2); + const a2 = node("a", ["obs_x"]); + const b2 = node("b", ["obs_x"]); + await persistGraphDelta(kv as never, [a2, b2], [edge(a2.id, b2.id, many)]); + const e = await onlyEdge(kv); + expect(e.sourceObservationIds).toEqual( + many.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS), + ); + }); + + it("a brand-new edge carrying more than the cap is trimmed on first write", async () => { + const kv = mockKV(); + const a = node("a", ["obs_0"]); + const b = node("b", ["obs_0"]); + const many = ids("obs", MAX_GRAPH_SOURCE_OBSERVATIONS + 5); + await persistGraphDelta(kv as never, [a, b], [edge(a.id, b.id, many)]); + const e = await onlyEdge(kv); + expect(e.sourceObservationIds).toEqual( + many.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS), + ); + }); + + it("a record written before this change with an oversized list is trimmed on its next merge", async () => { + const kv = mockKV(); + const legacy = node("legacy", ids("obs_legacy", 500)); + await kv.set("mem:graph:nodes", legacy.id, legacy); + await kv.set("mem:graph:name-index", "concept|legacy", legacy.id); + await persistGraphDelta(kv as never, [node("legacy", ["obs_now"])], []); + const n = await onlyNode(kv, "legacy"); + expect(n.sourceObservationIds.length).toBe(MAX_GRAPH_SOURCE_OBSERVATIONS); + expect(n.sourceObservationIds.at(-1)).toBe("obs_now"); + }); +}); + +describe("temporal graph provenance is bounded", () => { + function mockSdk() { + const functions = new Map(); + return { + registerFunction: ( + idOrOpts: string | { id: string }, + handler: Function, + ) => { + functions.set( + typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id, + handler, + ); + }, + registerTrigger: () => {}, + trigger: async (id: string, data: unknown) => functions.get(id)!(data), + }; + } + + it("a temporal node merged many times keeps only the newest ids", async () => { + const { registerTemporalGraphFunctions } = await import( + "../src/functions/temporal-graph.js" + ); + const response = ` + + engineer + + +`; + const provider = { + name: "test", + compress: vi.fn().mockResolvedValue(response), + summarize: vi.fn().mockResolvedValue(response), + }; + const sdk = mockSdk(); + const kv = mockKV(); + registerTemporalGraphFunctions( + sdk as never, + kv as never, + provider as never, + ); + + const all: string[] = []; + for (let batch = 0; batch < 10; batch++) { + const observations = ids(`obs_t${batch}`, 10).map((id) => { + all.push(id); + return { + id, + title: "t", + narrative: "Alice works at Acme", + concepts: [], + files: [], + type: "conversation", + timestamp: "2026-09-24T00:00:00Z", + }; + }); + const r = (await sdk.trigger("mem::temporal-graph-extract", { + observations, + })) as { + success: boolean; + }; + expect(r.success).toBe(true); + } + const n = await onlyNode(kv, "Alice"); + expect(n.sourceObservationIds).toEqual( + all.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS), + ); + }); +}); From 82b9e48bee3fd06926ae92b03809b34d6ca186be Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Tue, 29 Sep 2026 22:39:21 -0400 Subject: [PATCH 02/14] fix(api): validate graph/compact input and report its real failures Review found two defects in POST /agentmemory/graph/compact. Invalid input returned HTTP 200. mem::graph-compact reports a bad scope, offset or limit as { success: false }, so the route passed that through with 200. The route now rejects an unknown scope, a negative or non-integer offset, and a non-positive or non-integer limit with 400, before invoking compaction. It accepts JSON numbers only, so "5" is rejected. Other success:false results still return 200, because that envelope also carries operational failures. Every failure was reported as "graph disabled". The catch returned graphDisabledResponse(), a 503 with GRAPH_EXTRACTION_ENABLED advice, but compaction is registered whether or not graph extraction is enabled. A timeout, such as an unsliced run on a large graph, now returns 504 and says to run in slices. Any other failure returns 500. Signed-off-by: David Waltermire --- src/triggers/api.ts | 34 ++++++++++++----- test/graph-compact.test.ts | 75 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 9 deletions(-) diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 5a229dfef2..22a806bb62 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -1,4 +1,4 @@ -import { TriggerAction, type IIIClient } from "iii-sdk"; +import { InvocationError, TriggerAction, type IIIClient } from "iii-sdk"; import type { HttpRequest } from "@iii-dev/helpers/http"; import { randomBytes } from "node:crypto"; import type { Session, CompressedObservation, HookPayload, CommitLink, SessionSummary, HealthSnapshot, AuditQueryResult, AuditMigrationState } from "../types.js"; @@ -2023,19 +2023,35 @@ export function registerApiTriggers( async (req: HttpRequest): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; + // Validate here: mem::graph-compact reports bad input as success:false, + // which would reach the caller as HTTP 200. JSON numbers only. + const body = (req.body ?? {}) as Record; + const { scope, offset, limit } = body; + if (scope !== undefined && scope !== "nodes" && scope !== "edges" && scope !== "snapshot") { + return { status_code: 400, body: { error: "scope must be nodes, edges or snapshot" } }; + } + if (offset !== undefined && !(Number.isInteger(offset) && (offset as number) >= 0)) { + return { status_code: 400, body: { error: "offset must be a non-negative integer" } }; + } + if (limit !== undefined && !(Number.isInteger(limit) && (limit as number) >= 1)) { + return { status_code: 400, body: { error: "limit must be a positive integer" } }; + } try { - const body = (req.body ?? {}) as Record; const result = await sdk.trigger({ function_id: "mem::graph-compact", - payload: { - scope: body.scope, - offset: body.offset, - limit: body.limit, - }, + payload: { scope, offset, limit }, }); return { status_code: 200, body: result }; - } catch { - return graphDisabledResponse(); + } catch (err) { + // Compaction is registered whether or not graph extraction is on, so + // a failure here is never the graph-disabled case. + if (err instanceof InvocationError && err.code === "TIMEOUT") { + return { + status_code: 504, + body: { error: "Graph compaction timed out; pass scope, offset and limit to run it in slices" }, + }; + } + return { status_code: 500, body: { error: "Graph compaction failed" } }; } }, ); diff --git a/test/graph-compact.test.ts b/test/graph-compact.test.ts index 6b32a910c2..9cc4ac2335 100644 --- a/test/graph-compact.test.ts +++ b/test/graph-compact.test.ts @@ -467,3 +467,78 @@ describe("chunked compaction", () => { expect(r).toMatchObject({ success: true, nodesScanned: 1, nextOffset: 1 }); }); }); + +describe("api::graph-compact responses", () => { + async function route( + trigger: (req: { + function_id: string; + payload?: unknown; + }) => Promise, + ) { + const { registerApiTriggers } = await import("../src/triggers/api.js"); + const fns = new Map(); + const sdk = { + registerFunction: (id: string, h: Function) => fns.set(id, h), + registerTrigger: () => {}, + trigger, + }; + registerApiTriggers(sdk as never, mockKV() as never); + return (body: unknown) => + fns.get("api::graph-compact")!({ headers: {}, body }) as Promise<{ + status_code: number; + body: Record; + }>; + } + + const ok = async () => ({ success: true, nodesTrimmed: 0 }); + + it("rejects invalid slice parameters with 400 before invoking compaction", async () => { + let calls = 0; + const post = await route(async () => { + calls += 1; + return ok(); + }); + for (const body of [ + { scope: "bogus" }, + { scope: "nodes", offset: -1 }, + { scope: "nodes", offset: 1.5 }, + { scope: "nodes", offset: "5" }, + { scope: "nodes", limit: 0 }, + { scope: "nodes", limit: "5" }, + ]) { + const r = await post(body); + expect(r.status_code, JSON.stringify(body)).toBe(400); + } + expect(calls).toBe(0); + }); + + it("passes valid parameters through and returns 200", async () => { + let seen: unknown; + const post = await route(async (req) => { + seen = req.payload; + return ok(); + }); + const r = await post({ scope: "edges", offset: 0, limit: 1000 }); + expect(r.status_code).toBe(200); + expect(seen).toEqual({ scope: "edges", offset: 0, limit: 1000 }); + expect((await post({})).status_code).toBe(200); + }); + + it("returns 504 when the invocation times out", async () => { + const { InvocationError } = await import("iii-sdk"); + const post = await route(async () => { + throw new InvocationError({ code: "TIMEOUT", message: "timed out" }); + }); + const r = await post({}); + expect(r.status_code).toBe(504); + }); + + it("returns 500 for other failures, not the graph-disabled advice", async () => { + const post = await route(async () => { + throw new Error("worker gone"); + }); + const r = await post({}); + expect(r.status_code).toBe(500); + expect(JSON.stringify(r.body)).not.toMatch(/GRAPH_EXTRACTION_ENABLED/); + }); +}); From b00eaed19c28c063c7c0a3a05f6c256e6f9fc37f Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Wed, 30 Sep 2026 01:08:00 -0400 Subject: [PATCH 03/14] fix(api): return 500 when graph compaction reports a failure mem::graph-compact catches a storage error and returns { success: false, error } instead of throwing. sdk.trigger therefore resolves, and POST /agentmemory/graph/compact answered 200. The route validates its input first, so a success:false result reaching this point is an operational failure. It now returns 500 with the generic "Graph compaction failed" message. The detailed error stays in the server-side log, which mem::graph-compact already writes. Signed-off-by: David Waltermire --- src/triggers/api.ts | 5 +++++ test/graph-compact.test.ts | 12 ++++++++++++ 2 files changed, 17 insertions(+) diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 22a806bb62..72882d0b80 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -2041,6 +2041,11 @@ export function registerApiTriggers( function_id: "mem::graph-compact", payload: { scope, offset, limit }, }); + // Input was validated above, so success:false here is an operational + // failure (mem::graph-compact logs the detail). Do not answer 200. + if ((result as { success?: boolean } | null)?.success === false) { + return { status_code: 500, body: { error: "Graph compaction failed" } }; + } return { status_code: 200, body: result }; } catch (err) { // Compaction is registered whether or not graph extraction is on, so diff --git a/test/graph-compact.test.ts b/test/graph-compact.test.ts index 9cc4ac2335..67b3044367 100644 --- a/test/graph-compact.test.ts +++ b/test/graph-compact.test.ts @@ -524,6 +524,18 @@ describe("api::graph-compact responses", () => { expect((await post({})).status_code).toBe(200); }); + it("returns 500 when compaction reports its own failure, without leaking the error", async () => { + // mem::graph-compact catches a storage error and returns success:false, + // so sdk.trigger resolves; the route must not answer 200. + const post = await route(async () => ({ + success: false, + error: "kv write failed: disk full", + })); + const r = await post({ scope: "nodes", offset: 0, limit: 10 }); + expect(r.status_code).toBe(500); + expect(r.body).toEqual({ error: "Graph compaction failed" }); + }); + it("returns 504 when the invocation times out", async () => { const { InvocationError } = await import("iii-sdk"); const post = await route(async () => { From 93143edb5ed7cc1b1b60d83f054922f3b81c1de1 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Wed, 30 Sep 2026 21:00:24 -0400 Subject: [PATCH 04/14] docs: add doc comments to the provenance and compaction helpers The explanations above boundSources and compactGraphProvenance are now doc comments, word for word. mergeNode, mergeEdge and the two compaction inner helpers get one-line doc comments, and so do the test helpers. This answers the docstring-coverage pre-merge check. No behavior changes. Signed-off-by: David Waltermire --- src/functions/graph.ts | 34 +++++++++++++++++++------------ test/graph-compact.test.ts | 7 +++++++ test/graph-provenance-cap.test.ts | 7 +++++++ 3 files changed, 35 insertions(+), 13 deletions(-) diff --git a/src/functions/graph.ts b/src/functions/graph.ts index 0bd365838b..68b3263618 100644 --- a/src/functions/graph.ts +++ b/src/functions/graph.ts @@ -286,8 +286,10 @@ function snapshotPushEdgeIfBothInTop( // 20 results, so a record never needs more than its newest sources. export const MAX_GRAPH_SOURCE_OBSERVATIONS = 32; -// Union in arrival order, with a re-seen id moved to the newest end, then -// keep the newest MAX_GRAPH_SOURCE_OBSERVATIONS. +/** + * Union in arrival order, with a re-seen id moved to the newest end, then + * keep the newest MAX_GRAPH_SOURCE_OBSERVATIONS. + */ export function boundSources(existing: string[], incoming: string[]): string[] { const merged = new Set(existing); for (const id of incoming) { @@ -297,6 +299,7 @@ export function boundSources(existing: string[], incoming: string[]): string[] { return [...merged].slice(-MAX_GRAPH_SOURCE_OBSERVATIONS); } +/** Merges an extracted node into the stored one: bounded own sources, newer properties. */ function mergeNode( existing: GraphNode, incoming: GraphNode, @@ -313,6 +316,7 @@ function mergeNode( }; } +/** Merges an extracted edge into the stored one, keeping its bounded own sources. */ function mergeEdge(existing: GraphEdge, incoming: GraphEdge): GraphEdge { return { ...existing, @@ -724,17 +728,19 @@ export interface GraphCompactOptions { const COMPACT_SCOPES: readonly GraphCompactScope[] = ["nodes", "edges", "snapshot"]; -// Trims provenance written before the cap existed. Records are reached -// through the name and edge-key indexes, whose values are short ids, and -// then read and written one key at a time. The nodes and edges scopes are -// never listed: that payload is what drops the worker on a large store. -// A record missing from both indexes is not reached; it is also never -// merged again, so it cannot grow. -// -// With no options it does everything in one call. With a scope it does one -// slice, so each invocation stays short enough to finish between worker -// reconnects; the caller walks nextOffset until it is null. Re-running any -// slice is safe because trimmed records are skipped. +/** + * Trims provenance written before the cap existed. Records are reached + * through the name and edge-key indexes, whose values are short ids, and + * then read and written one key at a time. The nodes and edges scopes are + * never listed: that payload is what drops the worker on a large store. + * A record missing from both indexes is not reached; it is also never + * merged again, so it cannot grow. + * + * With no options it does everything in one call. With a scope it does one + * slice, so each invocation stays short enough to finish between worker + * reconnects; the caller walks nextOffset until it is null. Re-running any + * slice is safe because trimmed records are skipped. + */ export async function compactGraphProvenance( kv: StateKV, opts: GraphCompactOptions = {}, @@ -762,6 +768,7 @@ export async function compactGraphProvenance( nextOffset: null, }; + /** Trims one slice of records reached through an index scope, one locked key at a time. */ const trimScope = async ( indexScope: string, recordScope: string, @@ -790,6 +797,7 @@ export async function compactGraphProvenance( return { scanned, trimmed }; }; + /** Trims the cached snapshot's top nodes and edges under the same lock. */ const trimSnapshot = () => withKeyedLock("graph:persist", async () => { const snap = await readSnapshot(kv); diff --git a/test/graph-compact.test.ts b/test/graph-compact.test.ts index 67b3044367..0f2ed1de66 100644 --- a/test/graph-compact.test.ts +++ b/test/graph-compact.test.ts @@ -20,6 +20,7 @@ import type { GraphEdge, GraphNode } from "../src/types.js"; // value is captured. That forces the interleaving that loses a merge when // writers are not serialized: compaction reads, a merge writes, then // compaction writes back its stale copy. +/** In-memory StateKV that records list and set calls; can delay the first node read to force a race. */ function mockKV(slowFirstNodeReadMs = 0) { const store = new Map>(); const calls = { list: [] as string[], set: [] as string[] }; @@ -57,9 +58,11 @@ function mockKV(slowFirstNodeReadMs = 0) { } type KV = ReturnType; +/** `n` distinct observation ids with a prefix. */ const ids = (prefix: string, n: number) => Array.from({ length: n }, (_, i) => `${prefix}_${i}`); +/** Stores a node and its name-index entry. */ async function seedNode(kv: KV, id: string, name: string, sources: string[]) { const n: GraphNode = { id, @@ -75,6 +78,7 @@ async function seedNode(kv: KV, id: string, name: string, sources: string[]) { return n; } +/** Stores an edge and its edge-key entry. */ async function seedEdge( kv: KV, id: string, @@ -96,7 +100,9 @@ async function seedEdge( return e; } +/** Reads a stored node by id. */ const node = (kv: KV, id: string) => kv.get("mem:graph:nodes", id); +/** Reads a stored edge by id. */ const edge = (kv: KV, id: string) => kv.get("mem:graph:edges", id); describe("compactGraphProvenance", () => { @@ -469,6 +475,7 @@ describe("chunked compaction", () => { }); describe("api::graph-compact responses", () => { + /** Registers the API handlers with a stub trigger and returns a caller for api::graph-compact. */ async function route( trigger: (req: { function_id: string; diff --git a/test/graph-provenance-cap.test.ts b/test/graph-provenance-cap.test.ts index 44f436df76..29b0afae2d 100644 --- a/test/graph-provenance-cap.test.ts +++ b/test/graph-provenance-cap.test.ts @@ -15,6 +15,7 @@ import type { GraphEdge, GraphNode } from "../src/types.js"; // the graph's bytes provenance ids (426 per node on average), and every // traversal carried them. +/** In-memory StateKV: one Map per scope. */ function mockKV() { const store = new Map>(); return { @@ -36,6 +37,7 @@ function mockKV() { } let seq = 0; +/** A concept node with the given name and sources. */ function node(name: string, sources: string[]): GraphNode { seq += 1; return { @@ -48,6 +50,7 @@ function node(name: string, sources: string[]): GraphNode { }; } +/** A related_to edge between two node ids with the given sources. */ function edge(src: string, tgt: string, sources: string[]): GraphEdge { seq += 1; return { @@ -61,9 +64,11 @@ function edge(src: string, tgt: string, sources: string[]): GraphEdge { }; } +/** `n` distinct observation ids with a prefix. */ const ids = (prefix: string, n: number) => Array.from({ length: n }, (_, i) => `${prefix}_${i}`); +/** The single stored node with this name; fails if there is not exactly one. */ async function onlyNode(kv: ReturnType, name: string) { const all = await kv.list("mem:graph:nodes"); const hits = all.filter((n) => n.name === name); @@ -71,6 +76,7 @@ async function onlyNode(kv: ReturnType, name: string) { return hits[0]!; } +/** The single stored edge; fails if there is not exactly one. */ async function onlyEdge(kv: ReturnType) { const all = await kv.list("mem:graph:edges"); expect(all.length).toBe(1); @@ -219,6 +225,7 @@ describe("graph provenance is bounded and attributed", () => { }); describe("temporal graph provenance is bounded", () => { + /** SDK stub that records registered functions so they can be triggered directly. */ function mockSdk() { const functions = new Map(); return { From 477dd0dfa9f60685f30524f2bfc31960a7cd4fe0 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Wed, 30 Sep 2026 21:16:37 -0400 Subject: [PATCH 05/14] docs: add doc comments to the graph function registrars Each comment names the functions its registrar exposes. Signed-off-by: David Waltermire --- src/functions/graph.ts | 4 ++++ src/functions/temporal-graph.ts | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/src/functions/graph.ts b/src/functions/graph.ts index 68b3263618..eda6fba6ad 100644 --- a/src/functions/graph.ts +++ b/src/functions/graph.ts @@ -836,6 +836,10 @@ export async function compactGraphProvenance( return result; } +/** + * Registers the knowledge-graph functions: mem::graph-extract, mem::graph-query, + * mem::graph-stats, mem::graph-compact and mem::graph-reset. + */ export function registerGraphFunction( sdk: IIIClient, kv: StateKV, diff --git a/src/functions/temporal-graph.ts b/src/functions/temporal-graph.ts index 4ee0c4c1be..e40be10ddc 100644 --- a/src/functions/temporal-graph.ts +++ b/src/functions/temporal-graph.ts @@ -151,6 +151,10 @@ function parseTemporalGraphXml( return { nodes, edges }; } +/** + * Registers the temporal-graph functions: mem::temporal-graph-extract, + * mem::temporal-query and mem::differential-state. + */ export function registerTemporalGraphFunctions( sdk: IIIClient, kv: StateKV, From a909039ab751afebf6dd147f38195a7267af7ad0 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Wed, 30 Sep 2026 21:41:39 -0400 Subject: [PATCH 06/14] fix(graph): bound temporal edge provenance before it is written The temporal parser gives every edge the whole batch's observation ids, and the edge write stored them without the cap that nodes already had. A batch of more than 32 observations wrote an edge over the cap. Signed-off-by: David Waltermire --- src/functions/temporal-graph.ts | 1 + test/graph-provenance-cap.test.ts | 50 +++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/src/functions/temporal-graph.ts b/src/functions/temporal-graph.ts index e40be10ddc..111c726368 100644 --- a/src/functions/temporal-graph.ts +++ b/src/functions/temporal-graph.ts @@ -259,6 +259,7 @@ export function registerTemporalGraphFunctions( edge.version = (existingEdge.version || 1) + 1; } + edge.sourceObservationIds = boundSources([], edge.sourceObservationIds ?? []); await kv.set(KV.graphEdges, edge.id, edge); existingEdges.push(edge); } diff --git a/test/graph-provenance-cap.test.ts b/test/graph-provenance-cap.test.ts index 29b0afae2d..f8bf16df78 100644 --- a/test/graph-provenance-cap.test.ts +++ b/test/graph-provenance-cap.test.ts @@ -292,4 +292,54 @@ describe("temporal graph provenance is bounded", () => { all.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS), ); }); + + it("a temporal edge from a batch larger than the cap keeps only the newest ids", async () => { + const { registerTemporalGraphFunctions } = await import( + "../src/functions/temporal-graph.js" + ); + const response = ` + + + + + + + +`; + const provider = { + name: "test", + compress: vi.fn().mockResolvedValue(response), + summarize: vi.fn().mockResolvedValue(response), + }; + const sdk = mockSdk(); + const kv = mockKV(); + registerTemporalGraphFunctions( + sdk as never, + kv as never, + provider as never, + ); + + const batch = ids("obs_e", MAX_GRAPH_SOURCE_OBSERVATIONS + 8); + for (let round = 0; round < 2; round++) { + const r = (await sdk.trigger("mem::temporal-graph-extract", { + observations: batch.map((id) => ({ + id, + title: "t", + narrative: "Alice works on Acme", + concepts: [], + files: [], + type: "conversation", + timestamp: "2026-09-24T00:00:00Z", + })), + })) as { success: boolean }; + expect(r.success).toBe(true); + } + const edges = await kv.list("mem:graph:edges"); + expect(edges).toHaveLength(2); + for (const e of edges) { + expect(e.sourceObservationIds).toEqual( + batch.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS), + ); + } + }); }); From 05138d31162573515ee34a476227ac8eb2b9ec85 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Thu, 1 Oct 2026 13:22:54 +0530 Subject: [PATCH 07/14] chore(graph): drop code comments added with provenance compaction The repo keeps code free of comments; the behaviour is covered by tests and the endpoint is documented in the README and REST reference. --- src/functions/graph.ts | 32 ------------------------------- src/functions/temporal-graph.ts | 4 ---- src/triggers/api.ts | 8 -------- test/graph-compact.test.ts | 17 ---------------- test/graph-provenance-cap.test.ts | 14 -------------- 5 files changed, 75 deletions(-) diff --git a/src/functions/graph.ts b/src/functions/graph.ts index 662af70edf..16559500af 100644 --- a/src/functions/graph.ts +++ b/src/functions/graph.ts @@ -301,17 +301,8 @@ function snapshotPushEdgeIfBothInTop( } } -// Provenance is bounded. Every merge used to union the whole batch's -// observation ids into every node and edge it touched, which grew hot -// nodes without limit: on one store 98% of the graph's bytes were these -// ids, and every kv.list traversal carried them. Retrieval reads at most -// 20 results, so a record never needs more than its newest sources. export const MAX_GRAPH_SOURCE_OBSERVATIONS = 32; -/** - * Union in arrival order, with a re-seen id moved to the newest end, then - * keep the newest MAX_GRAPH_SOURCE_OBSERVATIONS. - */ export function boundSources(existing: string[], incoming: string[]): string[] { const merged = new Set(existing); for (const id of incoming) { @@ -321,7 +312,6 @@ export function boundSources(existing: string[], incoming: string[]): string[] { return [...merged].slice(-MAX_GRAPH_SOURCE_OBSERVATIONS); } -/** Merges an extracted node into the stored one: bounded own sources, newer properties. */ function mergeNode( existing: GraphNode, incoming: GraphNode, @@ -338,7 +328,6 @@ function mergeNode( }; } -/** Merges an extracted edge into the stored one, keeping its bounded own sources. */ function mergeEdge(existing: GraphEdge, incoming: GraphEdge): GraphEdge { return { ...existing, @@ -733,8 +722,6 @@ export interface GraphCompactResult { edgesTrimmed: number; idsRemoved: number; snapshotTrimmed: boolean; - // Records in the sliced index, and where the next slice starts; null - // when this call reached the end. A full run always ends with null. total?: number; nextOffset: number | null; } @@ -749,19 +736,6 @@ export interface GraphCompactOptions { const COMPACT_SCOPES: readonly GraphCompactScope[] = ["nodes", "edges", "snapshot"]; -/** - * Trims provenance written before the cap existed. Records are reached - * through the name and edge-key indexes, whose values are short ids, and - * then read and written one key at a time. The nodes and edges scopes are - * never listed: that payload is what drops the worker on a large store. - * A record missing from both indexes is not reached; it is also never - * merged again, so it cannot grow. - * - * With no options it does everything in one call. With a scope it does one - * slice, so each invocation stays short enough to finish between worker - * reconnects; the caller walks nextOffset until it is null. Re-running any - * slice is safe because trimmed records are skipped. - */ export async function compactGraphProvenance( kv: StateKV, opts: GraphCompactOptions = {}, @@ -789,7 +763,6 @@ export async function compactGraphProvenance( nextOffset: null, }; - /** Trims one slice of records reached through an index scope, one locked key at a time. */ const trimScope = async ( indexScope: string, recordScope: string, @@ -818,7 +791,6 @@ export async function compactGraphProvenance( return { scanned, trimmed }; }; - /** Trims the cached snapshot's top nodes and edges under the same lock. */ const trimSnapshot = () => withKeyedLock("graph:persist", async () => { const snap = await readSnapshot(kv); @@ -857,10 +829,6 @@ export async function compactGraphProvenance( return result; } -/** - * Registers the knowledge-graph functions: mem::graph-extract, mem::graph-query, - * mem::graph-stats, mem::graph-compact and mem::graph-reset. - */ export function registerGraphFunction( sdk: IIIClient, kv: StateKV, diff --git a/src/functions/temporal-graph.ts b/src/functions/temporal-graph.ts index 111c726368..d79dd04f20 100644 --- a/src/functions/temporal-graph.ts +++ b/src/functions/temporal-graph.ts @@ -151,10 +151,6 @@ function parseTemporalGraphXml( return { nodes, edges }; } -/** - * Registers the temporal-graph functions: mem::temporal-graph-extract, - * mem::temporal-query and mem::differential-state. - */ export function registerTemporalGraphFunctions( sdk: IIIClient, kv: StateKV, diff --git a/src/triggers/api.ts b/src/triggers/api.ts index d01d991d51..c10868aab6 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -2027,14 +2027,10 @@ export function registerApiTriggers( config: { api_path: "/agentmemory/graph/reset", http_method: "POST" }, }); - // Trims graph provenance written before the per-record cap, walking the - // small name and edge-key indexes instead of listing the graph. sdk.registerFunction("api::graph-compact", async (req: HttpRequest): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; - // Validate here: mem::graph-compact reports bad input as success:false, - // which would reach the caller as HTTP 200. JSON numbers only. const body = (req.body ?? {}) as Record; const { scope, offset, limit } = body; if (scope !== undefined && scope !== "nodes" && scope !== "edges" && scope !== "snapshot") { @@ -2051,15 +2047,11 @@ export function registerApiTriggers( function_id: "mem::graph-compact", payload: { scope, offset, limit }, }); - // Input was validated above, so success:false here is an operational - // failure (mem::graph-compact logs the detail). Do not answer 200. if ((result as { success?: boolean } | null)?.success === false) { return { status_code: 500, body: { error: "Graph compaction failed" } }; } return { status_code: 200, body: result }; } catch (err) { - // Compaction is registered whether or not graph extraction is on, so - // a failure here is never the graph-disabled case. if (err instanceof InvocationError && err.code === "TIMEOUT") { return { status_code: 504, diff --git a/test/graph-compact.test.ts b/test/graph-compact.test.ts index 0f2ed1de66..4cd175276a 100644 --- a/test/graph-compact.test.ts +++ b/test/graph-compact.test.ts @@ -12,15 +12,6 @@ import { } from "../src/functions/graph.js"; import type { GraphEdge, GraphNode } from "../src/types.js"; -// Compaction trims provenance written before the cap existed. It must -// reach records through the small name and edge-key indexes only: listing -// the nodes or edges scope is the payload that drops the worker. - -// slowFirstNodeRead delays only the FIRST read of a node record, after the -// value is captured. That forces the interleaving that loses a merge when -// writers are not serialized: compaction reads, a merge writes, then -// compaction writes back its stale copy. -/** In-memory StateKV that records list and set calls; can delay the first node read to force a race. */ function mockKV(slowFirstNodeReadMs = 0) { const store = new Map>(); const calls = { list: [] as string[], set: [] as string[] }; @@ -58,11 +49,9 @@ function mockKV(slowFirstNodeReadMs = 0) { } type KV = ReturnType; -/** `n` distinct observation ids with a prefix. */ const ids = (prefix: string, n: number) => Array.from({ length: n }, (_, i) => `${prefix}_${i}`); -/** Stores a node and its name-index entry. */ async function seedNode(kv: KV, id: string, name: string, sources: string[]) { const n: GraphNode = { id, @@ -78,7 +67,6 @@ async function seedNode(kv: KV, id: string, name: string, sources: string[]) { return n; } -/** Stores an edge and its edge-key entry. */ async function seedEdge( kv: KV, id: string, @@ -100,9 +88,7 @@ async function seedEdge( return e; } -/** Reads a stored node by id. */ const node = (kv: KV, id: string) => kv.get("mem:graph:nodes", id); -/** Reads a stored edge by id. */ const edge = (kv: KV, id: string) => kv.get("mem:graph:edges", id); describe("compactGraphProvenance", () => { @@ -475,7 +461,6 @@ describe("chunked compaction", () => { }); describe("api::graph-compact responses", () => { - /** Registers the API handlers with a stub trigger and returns a caller for api::graph-compact. */ async function route( trigger: (req: { function_id: string; @@ -532,8 +517,6 @@ describe("api::graph-compact responses", () => { }); it("returns 500 when compaction reports its own failure, without leaking the error", async () => { - // mem::graph-compact catches a storage error and returns success:false, - // so sdk.trigger resolves; the route must not answer 200. const post = await route(async () => ({ success: false, error: "kv write failed: disk full", diff --git a/test/graph-provenance-cap.test.ts b/test/graph-provenance-cap.test.ts index f8bf16df78..8def25bf72 100644 --- a/test/graph-provenance-cap.test.ts +++ b/test/graph-provenance-cap.test.ts @@ -10,12 +10,6 @@ import { } from "../src/functions/graph.js"; import type { GraphEdge, GraphNode } from "../src/types.js"; -// Each merge used to union every observation id in the batch into every -// node and edge it touched, with no bound. On one store that made 98% of -// the graph's bytes provenance ids (426 per node on average), and every -// traversal carried them. - -/** In-memory StateKV: one Map per scope. */ function mockKV() { const store = new Map>(); return { @@ -37,7 +31,6 @@ function mockKV() { } let seq = 0; -/** A concept node with the given name and sources. */ function node(name: string, sources: string[]): GraphNode { seq += 1; return { @@ -50,7 +43,6 @@ function node(name: string, sources: string[]): GraphNode { }; } -/** A related_to edge between two node ids with the given sources. */ function edge(src: string, tgt: string, sources: string[]): GraphEdge { seq += 1; return { @@ -64,11 +56,9 @@ function edge(src: string, tgt: string, sources: string[]): GraphEdge { }; } -/** `n` distinct observation ids with a prefix. */ const ids = (prefix: string, n: number) => Array.from({ length: n }, (_, i) => `${prefix}_${i}`); -/** The single stored node with this name; fails if there is not exactly one. */ async function onlyNode(kv: ReturnType, name: string) { const all = await kv.list("mem:graph:nodes"); const hits = all.filter((n) => n.name === name); @@ -76,7 +66,6 @@ async function onlyNode(kv: ReturnType, name: string) { return hits[0]!; } -/** The single stored edge; fails if there is not exactly one. */ async function onlyEdge(kv: ReturnType) { const all = await kv.list("mem:graph:edges"); expect(all.length).toBe(1); @@ -152,7 +141,6 @@ describe("graph provenance is bounded and attributed", () => { it("a merged node gains ITS OWN sources, not every id in the batch", async () => { const kv = mockKV(); await persistGraphDelta(kv as never, [node("a.ts", ["obs_1"])], []); - // A batch of obs_2..obs_4 in which only obs_3 mentioned a.ts. await persistGraphDelta( kv as never, [node("a.ts", ["obs_3"]), node("b.ts", ["obs_2", "obs_4"])], @@ -168,7 +156,6 @@ describe("graph provenance is bounded and attributed", () => { const b = node("b", ["obs_0"]); await persistGraphDelta(kv as never, [a, b], [edge(a.id, b.id, ["obs_0"])]); for (let batch = 1; batch <= 10; batch++) { - // A batch of ten observations; only the first one links a and b. const batchIds = ids(`obs_b${batch}`, 10); const a2 = node("a", batchIds); const b2 = node("b", batchIds); @@ -225,7 +212,6 @@ describe("graph provenance is bounded and attributed", () => { }); describe("temporal graph provenance is bounded", () => { - /** SDK stub that records registered functions so they can be triggered directly. */ function mockSdk() { const functions = new Map(); return { From d84e5da80ba55b1ed723df9d36908edf0c9e979a Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Thu, 1 Oct 2026 13:26:37 +0530 Subject: [PATCH 08/14] fix(graph): walk compaction slices in a stable order and audit the run Sliced compaction paged over kv.list(index) by offset across calls. The Redis backend returns list entries in a different order on each call, so a full walk could end with nextOffset null while records were never visited. Sort the ids before slicing; ids carry a base36 timestamp, so records inserted during a walk sort to the end. mem::graph-compact now records a graph_compact audit entry with the counts whenever it removes ids, and its registration sits above the graph-reset notes it was splitting. --- src/functions/graph.ts | 47 ++++++++++------- src/types.ts | 1 + src/viewer/index.html | 3 +- test/graph-compact.test.ts | 101 +++++++++++++++++++++++++++++++++++++ 4 files changed, 133 insertions(+), 19 deletions(-) diff --git a/src/functions/graph.ts b/src/functions/graph.ts index 16559500af..5caafdcc1c 100644 --- a/src/functions/graph.ts +++ b/src/functions/graph.ts @@ -15,7 +15,7 @@ import { buildGraphExtractionPrompt, } from "../prompts/graph-extraction.js"; import { isGraphExtractionEnabled } from "../config.js"; -import { recordAudit } from "./audit.js"; +import { recordAudit, safeAudit } from "./audit.js"; import { logger } from "../logger.js"; // #753: keep the response payload below the iii state channel ceiling. @@ -767,9 +767,9 @@ export async function compactGraphProvenance( indexScope: string, recordScope: string, ): Promise<{ scanned: number; trimmed: number }> => { - const allIds = [...new Set(await kv.list(indexScope))].filter( - (id): id is string => typeof id === "string", - ); + const allIds = [...new Set(await kv.list(indexScope))] + .filter((id): id is string => typeof id === "string") + .sort(); const end = Math.min(allIds.length, offset + limit); result.total = allIds.length; result.nextOffset = end < allIds.length ? end : null; @@ -1254,6 +1254,31 @@ export function registerGraphFunction( } }); + sdk.registerFunction("mem::graph-compact", async (data?: GraphCompactOptions) => { + const started = Date.now(); + try { + const result = await compactGraphProvenance(kv, data ?? {}); + const tookMs = Date.now() - started; + logger.info("Graph provenance compacted", { ...result, tookMs }); + if (result.idsRemoved > 0) { + await safeAudit(kv, "graph_compact", "mem::graph-compact", [], { + scope: data?.scope ?? "all", + offset: data?.offset, + limit: data?.limit, + nodesTrimmed: result.nodesTrimmed, + edgesTrimmed: result.edgesTrimmed, + idsRemoved: result.idsRemoved, + snapshotTrimmed: result.snapshotTrimmed, + }); + } + return { success: true, ...result, tookMs }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logger.error("Graph provenance compaction failed", { error: msg }); + return { success: false, error: msg }; + } + }); + // #814 v2 + #825: clean-restart escape hatch for corpora of any // size, including the legacy 75K+ case that crashes kv.list. // @@ -1275,20 +1300,6 @@ export function registerGraphFunction( // read by any post-#816 code path. Cleanup is deferred to a future // chunked-vacuum job; #816's broken vacuum-via-list strategy is // what we are leaving behind here. - sdk.registerFunction("mem::graph-compact", async (data?: GraphCompactOptions) => { - const started = Date.now(); - try { - const result = await compactGraphProvenance(kv, data ?? {}); - const tookMs = Date.now() - started; - logger.info("Graph provenance compacted", { ...result, tookMs }); - return { success: true, ...result, tookMs }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logger.error("Graph provenance compaction failed", { error: msg }); - return { success: false, error: msg }; - } - }); - sdk.registerFunction("mem::graph-reset", async () => { const started = Date.now(); // Stamp resetAt=now on the empty snapshot. Future diff --git a/src/types.ts b/src/types.ts index a8674e2f36..d2f5c3ba03 100644 --- a/src/types.ts +++ b/src/types.ts @@ -655,6 +655,7 @@ export interface AuditEntry { | "slot_create" | "slot_delete" | "slot_reflect" + | "graph_compact" | "audit_migrate"; userId?: string; functionId: string; diff --git a/src/viewer/index.html b/src/viewer/index.html index 7a2e071932..0484361059 100644 --- a/src/viewer/index.html +++ b/src/viewer/index.html @@ -6714,7 +6714,8 @@

agentmemory

skill_extract: 'Extracted a skill', core_add: 'Added core memory', core_remove: 'Removed core memory', auto_page: 'Paged memory out', vision_embed: 'Embedded an image', slot_append: 'Appended to a slot', slot_replace: 'Replaced a slot', slot_create: 'Created a slot', - slot_delete: 'Deleted a slot', slot_reflect: 'Reflected into a slot' + slot_delete: 'Deleted a slot', slot_reflect: 'Reflected into a slot', + graph_compact: 'Compacted graph provenance' }; function auditVerb(op) { diff --git a/test/graph-compact.test.ts b/test/graph-compact.test.ts index 4cd175276a..b330376af4 100644 --- a/test/graph-compact.test.ts +++ b/test/graph-compact.test.ts @@ -460,6 +460,107 @@ describe("chunked compaction", () => { }); }); +function shuffledListKV() { + const kv = mockKV(); + let seed = 7; + const rand = () => { + seed = (seed * 1103515245 + 12345) % 2147483648; + return seed / 2147483648; + }; + const list = kv.list; + return { + ...kv, + list: async (scope: string): Promise => { + const items = await list(scope); + for (let i = items.length - 1; i > 0; i--) { + const j = Math.floor(rand() * (i + 1)); + [items[i], items[j]] = [items[j], items[i]]; + } + return items; + }, + }; +} + +function registerCompact(kv: KV) { + const functions = new Map(); + const sdk = { + registerFunction: (idOrOpts: string | { id: string }, handler: Function) => + functions.set(typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id, handler), + registerTrigger: () => {}, + }; + registerGraphFunction( + sdk as never, + kv as never, + { name: "noop", compress: vi.fn(), summarize: vi.fn() } as never, + ); + return functions.get("mem::graph-compact")!; +} + +describe("compaction with an unstable list order", () => { + it("a full sliced walk leaves no node or edge over the cap", async () => { + const kv = shuffledListKV(); + const nid = (i: number) => `gn_${String(i).padStart(2, "0")}`; + for (let i = 0; i < 40; i++) await seedNode(kv, nid(i), `n${i}`, ids(`obs${i}`, 50)); + for (let i = 0; i < 39; i++) + await seedEdge(kv, `ge_${String(i).padStart(2, "0")}`, nid(i), nid(i + 1), ids(`eobs${i}`, 50)); + for (const scope of ["nodes", "edges"] as const) { + let offset: number | null = 0; + let calls = 0; + while (offset !== null && calls < 100) { + const r = await compactGraphProvenance(kv as never, { scope, offset, limit: 3 }); + offset = r.nextOffset; + calls += 1; + } + expect(offset).toBeNull(); + } + const nodes = await kv.list("mem:graph:nodes"); + const edges = await kv.list("mem:graph:edges"); + expect(nodes).toHaveLength(40); + expect(edges).toHaveLength(39); + const over = (r: { sourceObservationIds: string[] }) => + r.sourceObservationIds.length > MAX_GRAPH_SOURCE_OBSERVATIONS; + expect(nodes.filter(over)).toEqual([]); + expect(edges.filter(over)).toEqual([]); + }); +}); + +describe("mem::graph-compact audit", () => { + const auditEntries = async (kv: KV) => { + const scopes = [...new Set(kv.calls.set.map((k) => k.slice(0, k.lastIndexOf("/"))))].filter( + (s) => /^mem:audit:\d{4}-\d{2}$/.test(s), + ); + const rows = await Promise.all( + scopes.map((s) => + kv.list<{ operation: string; functionId: string; details: Record }>(s), + ), + ); + return rows.flat(); + }; + + it("records an audit entry with the counts when ids are removed", async () => { + const kv = mockKV(); + await seedNode(kv, "gn_1", "hub", ids("obs", 50)); + await seedEdge(kv, "ge_1", "gn_1", "gn_2", ids("eobs", 40)); + const r = await registerCompact(kv)({}); + expect(r).toMatchObject({ success: true, idsRemoved: 26 }); + const entries = await auditEntries(kv); + expect(entries).toHaveLength(1); + expect(entries[0]).toMatchObject({ + operation: "graph_compact", + functionId: "mem::graph-compact", + details: { scope: "all", nodesTrimmed: 1, edgesTrimmed: 1, idsRemoved: 26 }, + }); + }); + + it("records nothing when there is nothing to trim", async () => { + const kv = mockKV(); + await seedNode(kv, "gn_1", "hub", ids("obs", 5)); + const r = await registerCompact(kv)({}); + expect(r).toMatchObject({ success: true, idsRemoved: 0 }); + expect(await auditEntries(kv)).toEqual([]); + }); +}); + describe("api::graph-compact responses", () => { async function route( trigger: (req: { From fdfbf5d79d78271f4066a9400fac9db7d80dfa6b Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Thu, 1 Oct 2026 13:28:01 +0530 Subject: [PATCH 09/14] fix(graph): bound provenance on import, mesh sync and snapshot restore mem::import, mem::mesh-receive / mesh pull and mem::snapshot-restore wrote graph nodes and edges as received. They do not write the name or edge-key index, so compaction cannot reach those rows, and a pre-fix export or peer brought the bloat straight back. Each path now keeps the newest 32 source observation ids, the same bound extraction uses. --- src/functions/export-import.ts | 5 +-- src/functions/graph.ts | 6 ++++ src/functions/mesh.ts | 9 +++--- src/functions/snapshot.ts | 3 +- test/export-import.test.ts | 59 ++++++++++++++++++++++++++++++++++ test/mesh.test.ts | 42 ++++++++++++++++++++++++ test/snapshot.test.ts | 35 ++++++++++++++++++++ 7 files changed, 152 insertions(+), 7 deletions(-) diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 1758a94c58..2a14ea2737 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -40,6 +40,7 @@ import { indexRecords } from "./search.js"; import { resetLessonIndex } from "./lessons.js"; import { logger } from "../logger.js"; import { budgetImportedObservationSources } from "./observation-source-budget.js"; +import { boundRecordSources } from "./graph.js"; // Bounded-concurrency chunk size for the import delete/write loops. A // "replace" or "merge" of a large export (up to MAX_TOTAL_OBSERVATIONS, @@ -516,7 +517,7 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void const existing = await kv.get(KV.graphNodes, node.id).catch(() => null); if (existing) { stats.skipped++; return; } } - await kv.set(KV.graphNodes, node.id, node); + await kv.set(KV.graphNodes, node.id, boundRecordSources(node)); }), ); } @@ -527,7 +528,7 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void const existing = await kv.get(KV.graphEdges, edge.id).catch(() => null); if (existing) { stats.skipped++; return; } } - await kv.set(KV.graphEdges, edge.id, edge); + await kv.set(KV.graphEdges, edge.id, boundRecordSources(edge)); }), ); } diff --git a/src/functions/graph.ts b/src/functions/graph.ts index 5caafdcc1c..0f5b494905 100644 --- a/src/functions/graph.ts +++ b/src/functions/graph.ts @@ -312,6 +312,12 @@ export function boundSources(existing: string[], incoming: string[]): string[] { return [...merged].slice(-MAX_GRAPH_SOURCE_OBSERVATIONS); } +export function boundRecordSources(record: R): R { + const sources = record?.sourceObservationIds; + if (!Array.isArray(sources) || sources.length <= MAX_GRAPH_SOURCE_OBSERVATIONS) return record; + return { ...record, sourceObservationIds: boundSources([], sources as string[]) }; +} + function mergeNode( existing: GraphNode, incoming: GraphNode, diff --git a/src/functions/mesh.ts b/src/functions/mesh.ts index 0dd7e95753..444e5105a3 100644 --- a/src/functions/mesh.ts +++ b/src/functions/mesh.ts @@ -3,6 +3,7 @@ import type { StateKV } from "../state/kv.js"; import { KV, generateId } from "../state/schema.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import { recordAudit } from "./audit.js"; +import { boundRecordSources } from "./graph.js"; import type { MeshPeer, Memory, @@ -122,11 +123,11 @@ async function lwwMergeGraphNodes( const wrote = await withKeyedLock("graph:persist", async () => { const existing = await kv.get(KV.graphNodes, item.id); if (!existing) { - await kv.set(KV.graphNodes, item.id, item); + await kv.set(KV.graphNodes, item.id, boundRecordSources(item)); return true; } if (new Date(ts) > new Date(graphNodeTs(existing))) { - await kv.set(KV.graphNodes, item.id, item); + await kv.set(KV.graphNodes, item.id, boundRecordSources(item)); return true; } return false; @@ -149,11 +150,11 @@ async function lwwMergeGraphEdges( const wrote = await withKeyedLock("graph:persist", async () => { const existing = await kv.get(KV.graphEdges, item.id); if (!existing) { - await kv.set(KV.graphEdges, item.id, item); + await kv.set(KV.graphEdges, item.id, boundRecordSources(item)); return true; } if (new Date(ts) > new Date(existing.createdAt)) { - await kv.set(KV.graphEdges, item.id, item); + await kv.set(KV.graphEdges, item.id, boundRecordSources(item)); return true; } return false; diff --git a/src/functions/snapshot.ts b/src/functions/snapshot.ts index 532c448a0c..d43b60f429 100644 --- a/src/functions/snapshot.ts +++ b/src/functions/snapshot.ts @@ -15,6 +15,7 @@ import type { StateKV } from "../state/kv.js"; import { addSessionToProjectIndex } from "../state/session-index.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import { recordAudit } from "./audit.js"; +import { boundRecordSources } from "./graph.js"; import { VERSION } from "../version.js"; import { logger } from "../logger.js"; @@ -220,7 +221,7 @@ export function registerSnapshotFunction( if (state.graphNodes) { for (const node of state.graphNodes) { await withKeyedLock("graph:persist", () => - kv.set(KV.graphNodes, node.id, node), + kv.set(KV.graphNodes, node.id, boundRecordSources(node)), ); } } diff --git a/test/export-import.test.ts b/test/export-import.test.ts index d33aacb1e6..8dfe5fbb40 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -309,3 +309,62 @@ describe("Export/Import Functions", () => { expect(result.error).toContain("Unsupported export version"); }); }); + +const bloatedIds = (prefix: string, n: number) => + Array.from({ length: n }, (_, i) => `${prefix}_${String(i).padStart(3, "0")}`); + +describe("import bounds graph provenance", () => { + it("caps sourceObservationIds on imported graph nodes and edges", async () => { + const sdk = mockSdk(); + const kv = mockKV(); + registerExportImportFunction(sdk as never, kv as never); + const exportData = { + version: "0.9.28", + exportedAt: new Date().toISOString(), + sessions: [], + observations: {}, + memories: [], + summaries: [], + graphNodes: [ + { + id: "gn_bloat", + type: "file", + name: "src/hot.ts", + properties: {}, + sourceObservationIds: bloatedIds("obs", 400), + createdAt: "2026-03-01T00:00:00Z", + }, + { + id: "gn_small", + type: "file", + name: "src/cold.ts", + properties: {}, + sourceObservationIds: ["obs_x"], + createdAt: "2026-03-01T00:00:00Z", + }, + ], + graphEdges: [ + { + id: "ge_bloat", + type: "related_to", + sourceNodeId: "gn_bloat", + targetNodeId: "gn_small", + weight: 0.5, + sourceObservationIds: bloatedIds("eobs", 100), + createdAt: "2026-03-01T00:00:00Z", + }, + ], + } as unknown as ExportData; + const result = (await sdk.trigger("mem::import", { + exportData, + strategy: "merge", + })) as { success: boolean }; + expect(result.success).toBe(true); + const n = await kv.get<{ sourceObservationIds: string[] }>("mem:graph:nodes", "gn_bloat"); + const s = await kv.get<{ sourceObservationIds: string[] }>("mem:graph:nodes", "gn_small"); + const e = await kv.get<{ sourceObservationIds: string[] }>("mem:graph:edges", "ge_bloat"); + expect(n!.sourceObservationIds).toEqual(bloatedIds("obs", 400).slice(-32)); + expect(s!.sourceObservationIds).toEqual(["obs_x"]); + expect(e!.sourceObservationIds).toEqual(bloatedIds("eobs", 100).slice(-32)); + }); +}); diff --git a/test/mesh.test.ts b/test/mesh.test.ts index e08db07840..5c5ecfd629 100644 --- a/test/mesh.test.ts +++ b/test/mesh.test.ts @@ -753,3 +753,45 @@ describe("Mesh Functions", () => { }); }); }); + +const bloatedIds = (prefix: string, n: number) => + Array.from({ length: n }, (_, i) => `${prefix}_${String(i).padStart(3, "0")}`); + +describe("mesh-receive bounds graph provenance", () => { + it("caps sourceObservationIds on received nodes and edges", async () => { + const sdk = mockSdk(); + const kv = mockKV(); + registerMeshFunction(sdk as never, kv as never); + const node: GraphNode = { + id: "gn_peer", + type: "file", + name: "src/hot.ts", + properties: {}, + sourceObservationIds: bloatedIds("obs", 500), + createdAt: "2026-03-01T00:00:00Z", + }; + const small: GraphNode = { ...node, id: "gn_small", sourceObservationIds: ["obs_a", "obs_b"] }; + const edge: GraphEdge = { + id: "ge_peer", + type: "related_to", + sourceNodeId: "gn_peer", + targetNodeId: "gn_small", + weight: 0.5, + sourceObservationIds: bloatedIds("eobs", 300), + createdAt: "2026-03-01T00:00:00Z", + }; + const result = (await sdk.trigger("mem::mesh-receive", { + graphNodes: [node, small], + graphEdges: [edge], + })) as { success: boolean; accepted: number }; + expect(result.success).toBe(true); + expect(result.accepted).toBe(3); + const storedNode = await kv.get("mem:graph:nodes", "gn_peer"); + const storedSmall = await kv.get("mem:graph:nodes", "gn_small"); + const storedEdge = await kv.get("mem:graph:edges", "ge_peer"); + expect(storedNode!.sourceObservationIds).toEqual(bloatedIds("obs", 500).slice(-32)); + expect(storedNode!.name).toBe("src/hot.ts"); + expect(storedSmall!.sourceObservationIds).toEqual(["obs_a", "obs_b"]); + expect(storedEdge!.sourceObservationIds).toEqual(bloatedIds("eobs", 300).slice(-32)); + }); +}); diff --git a/test/snapshot.test.ts b/test/snapshot.test.ts index 5fc51feab3..70969cfa62 100644 --- a/test/snapshot.test.ts +++ b/test/snapshot.test.ts @@ -258,3 +258,38 @@ describe("snapshot-create reentrancy guard", () => { expect(r3.snapshot).toBeDefined(); }); }); + +const bloatedIds = (prefix: string, n: number) => + Array.from({ length: n }, (_, i) => `${prefix}_${String(i).padStart(3, "0")}`); + +describe("snapshot-restore bounds graph provenance", () => { + it("caps sourceObservationIds on restored graph nodes", async () => { + const sdk = mockSdk(); + const kv = mockKV(); + registerSnapshotFunction(sdk as never, kv as never, "/tmp/agentmemory-snapshots"); + vi.mocked(readFileSync).mockReturnValueOnce( + JSON.stringify({ + version: "0.4.0", + sessions: [], + memories: [], + graphNodes: [ + { + id: "gn_bloat", + type: "file", + name: "src/hot.ts", + properties: {}, + sourceObservationIds: bloatedIds("obs", 250), + createdAt: "2026-03-01T00:00:00Z", + }, + ], + }), + ); + const result = (await sdk.trigger("mem::snapshot-restore", { + commitHash: "abc1234", + })) as { success: boolean }; + expect(result.success).toBe(true); + const n = await kv.get<{ name: string; sourceObservationIds: string[] }>("mem:graph:nodes", "gn_bloat"); + expect(n!.name).toBe("src/hot.ts"); + expect(n!.sourceObservationIds).toEqual(bloatedIds("obs", 250).slice(-32)); + }); +}); From 683ce83da484b1acc05f65091ee0b382f6ba0419 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Thu, 1 Oct 2026 13:29:38 +0530 Subject: [PATCH 10/14] fix(graph): accept loosely typed records in boundRecordSources snapshot-restore passes parsed JSON records typed as { id } & Record, which tsc rejected against the narrower generic bound. --- src/functions/graph.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/functions/graph.ts b/src/functions/graph.ts index 0f5b494905..cf551727c7 100644 --- a/src/functions/graph.ts +++ b/src/functions/graph.ts @@ -312,8 +312,8 @@ export function boundSources(existing: string[], incoming: string[]): string[] { return [...merged].slice(-MAX_GRAPH_SOURCE_OBSERVATIONS); } -export function boundRecordSources(record: R): R { - const sources = record?.sourceObservationIds; +export function boundRecordSources(record: R): R { + const sources = (record as { sourceObservationIds?: unknown } | null)?.sourceObservationIds; if (!Array.isArray(sources) || sources.length <= MAX_GRAPH_SOURCE_OBSERVATIONS) return record; return { ...record, sourceObservationIds: boundSources([], sources as string[]) }; } From ebe12f9acea27516c7610fe289351ca3b1f80f14 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Thu, 1 Oct 2026 13:29:38 +0530 Subject: [PATCH 11/14] docs: explain POST /agentmemory/graph/compact Add the endpoint to the key endpoints table and describe when to run it, the scope/offset/limit slicing loop, and the final scope "snapshot" call a sliced run needs. --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 60f98155d7..41cbda22c5 100644 --- a/README.md +++ b/README.md @@ -1691,6 +1691,7 @@ Create `~/.agentmemory/.env`: | `GET` | `/agentmemory/export` | Export all data | | `POST` | `/agentmemory/import` | Import from JSON | | `POST` | `/agentmemory/graph/query` | Knowledge graph query | +| `POST` | `/agentmemory/graph/compact` | Trim oversized graph provenance | | `POST` | `/agentmemory/team/share` | Share with team | | `GET` | `/agentmemory/audit` | Audit trail | @@ -1698,6 +1699,19 @@ Full endpoint list: [`src/triggers/api.ts`](src/triggers/api.ts)
+**Compacting graph provenance.** Each knowledge graph node and edge keeps the ids of the newest 32 observations it came from. Stores written before that cap can hold thousands of ids per hot node, which makes graph search and the viewer slow or drops the worker. Run `POST /agentmemory/graph/compact` once after upgrading if graph queries are slow or time out. It trims every node, edge and the cached snapshot to the cap, never lists the full graph, and is safe to re-run. When it trims ids it writes a `graph_compact` audit entry. + +```bash +curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}' +``` + +On a large store, or when the call returns 504, run it in slices. Send `scope` (`nodes` or `edges`), `offset` and `limit`, then call again with the returned `nextOffset` until it is `null`. Do this for `nodes` and for `edges`, and finish with one `{"scope":"snapshot"}` call, because a sliced run does not touch the cached snapshot. + +```bash +curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}' +curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}' +``` + ---

Development

From 71891b6e4226fbee91e7e561ffb039fbfbf852cc Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Thu, 1 Oct 2026 14:36:43 +0530 Subject: [PATCH 12/14] feat(graph): compact bloated graph provenance once at boot Stores hit by the unbounded sourceObservationIds bug (#1124) crash-loop or time out on graph search, and most of them will never call POST /agentmemory/graph/compact. After the worker is ready and the viewer is up, a background pass now walks nodes, edges and the temporal edge history in sorted slices of 100 with a 200 ms pause, then trims the cached snapshot. It reuses compactGraphProvenance, so each record takes graph:persist once and nothing nests the lock. Progress and the completion marker live in mem:config under graph-compact-on-boot:v1 with the cap, so a restart resumes from the saved offset, a finished store never runs it again, and a future cap change runs it once more. A failing slice is retried three times, then reported in the boot log, /agentmemory/status and the viewer Health page with the manual command; the worker keeps running. AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false turns it off. The manual endpoint gains a history scope for superseded temporal edges. --- README.md | 6 +- plugin/skills/agentmemory-config/REFERENCE.md | 3 +- src/config.ts | 4 + src/functions/graph-compact-boot.ts | 266 +++++++++++++ src/functions/graph.ts | 25 +- src/functions/status.ts | 26 ++ src/index.ts | 13 +- src/triggers/api.ts | 7 +- src/viewer/index.html | 13 + test/graph-compact-boot.test.ts | 359 ++++++++++++++++++ 10 files changed, 710 insertions(+), 12 deletions(-) create mode 100644 src/functions/graph-compact-boot.ts create mode 100644 test/graph-compact-boot.test.ts diff --git a/README.md b/README.md index 41cbda22c5..4fa80f5eeb 100644 --- a/README.md +++ b/README.md @@ -1699,13 +1699,15 @@ Full endpoint list: [`src/triggers/api.ts`](src/triggers/api.ts) -**Compacting graph provenance.** Each knowledge graph node and edge keeps the ids of the newest 32 observations it came from. Stores written before that cap can hold thousands of ids per hot node, which makes graph search and the viewer slow or drops the worker. Run `POST /agentmemory/graph/compact` once after upgrading if graph queries are slow or time out. It trims every node, edge and the cached snapshot to the cap, never lists the full graph, and is safe to re-run. When it trims ids it writes a `graph_compact` audit entry. +**Compacting graph provenance.** Each knowledge graph node and edge keeps the ids of the newest 32 observations it came from. Stores written before that cap can hold thousands of ids per hot node, which makes graph search and the viewer slow or drops the worker. agentmemory fixes this by itself: on the first start after upgrading it trims every node, edge, superseded edge (the temporal graph history) and the cached snapshot to the cap in the background, in small slices with a pause between them, so search, capture and the viewer keep working. It saves its progress, resumes after a restart and never runs again once it has finished. `/agentmemory/status` and the viewer Health page show it as pending, running (with the current scope and position), done or failed. Set `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` to turn it off. + +To run it by hand, call `POST /agentmemory/graph/compact`. It walks the name and edge-key indexes instead of listing every node and edge, and is safe to re-run. When it trims ids it writes a `graph_compact` audit entry. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}' ``` -On a large store, or when the call returns 504, run it in slices. Send `scope` (`nodes` or `edges`), `offset` and `limit`, then call again with the returned `nextOffset` until it is `null`. Do this for `nodes` and for `edges`, and finish with one `{"scope":"snapshot"}` call, because a sliced run does not touch the cached snapshot. +On a large store, or when the call returns 504, run it in slices. Send `scope` (`nodes`, `edges` or `history`), `offset` and `limit`, then call again with the returned `nextOffset` until it is `null`. Do this for `nodes`, `edges` and `history`, and finish with one `{"scope":"snapshot"}` call, because a sliced run does not touch the cached snapshot. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}' diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md index 158b1f1ec8..5cc5cbfd28 100644 --- a/plugin/skills/agentmemory-config/REFERENCE.md +++ b/plugin/skills/agentmemory-config/REFERENCE.md @@ -3,7 +3,7 @@ Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. -Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 58 recognized variables: +Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 59 recognized variables: - `AGENTMEMORY_AGENT_SCOPE` - `AGENTMEMORY_ALLOW_AGENT_SDK` @@ -27,6 +27,7 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e - `AGENTMEMORY_EXPORT_ROOT` - `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS` - `AGENTMEMORY_FORCE_PROXY` +- `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT` - `AGENTMEMORY_GRAPH_WEIGHT` - `AGENTMEMORY_III_CONFIG` - `AGENTMEMORY_III_VERSION` diff --git a/src/config.ts b/src/config.ts index ef0597cc8a..359e7a765d 100644 --- a/src/config.ts +++ b/src/config.ts @@ -249,6 +249,10 @@ export function getSessionSweepStaleHours(): number { return parsed > 0 ? parsed : 24; } +export function isGraphCompactOnBootEnabled(): boolean { + return getMergedEnv()["AGENTMEMORY_GRAPH_COMPACT_ON_BOOT"] !== "false"; +} + export function isDropStaleIndexEnabled(): boolean { return getMergedEnv()["AGENTMEMORY_DROP_STALE_INDEX"] === "true"; } diff --git a/src/functions/graph-compact-boot.ts b/src/functions/graph-compact-boot.ts new file mode 100644 index 0000000000..2ba09f9ab7 --- /dev/null +++ b/src/functions/graph-compact-boot.ts @@ -0,0 +1,266 @@ +import type { StateKV } from "../state/kv.js"; +import { KV } from "../state/schema.js"; +import { + MAX_GRAPH_SOURCE_OBSERVATIONS, + compactGraphProvenance, + type GraphCompactResult, + type GraphCompactScope, +} from "./graph.js"; +import { safeAudit } from "./audit.js"; + +export const GRAPH_COMPACT_BOOT_VERSION = 1; +export const GRAPH_COMPACT_BOOT_KEY = `graph-compact-on-boot:v${GRAPH_COMPACT_BOOT_VERSION}`; +export const GRAPH_COMPACT_BOOT_FUNCTION_ID = "mem::graph-compact-on-boot"; +export const GRAPH_COMPACT_BOOT_DELAY_MS = 3000; + +const SLICED_SCOPES = ["nodes", "edges", "history"] as const; +type SlicedScope = (typeof SLICED_SCOPES)[number]; +type BootPhase = SlicedScope | "snapshot"; + +export interface GraphCompactBootProgress { + version: number; + cap: number; + status: "running" | "done" | "failed"; + phase: BootPhase; + offset: number; + phaseTotal: number | null; + scanned: number; + trimmed: number; + idsRemoved: number; + startedAt: string; + updatedAt: string; + completedAt?: string; + error?: string; +} + +export type GraphCompactBootState = "off" | "pending" | "running" | "done" | "failed"; + +export interface GraphCompactBootStatus { + state: GraphCompactBootState; + phase?: BootPhase; + processed?: number; + total?: number | null; + scanned?: number; + trimmed?: number; + idsRemoved?: number; + startedAt?: string; + completedAt?: string; + error?: string; +} + +export interface GraphCompactBootOptions { + sliceSize?: number; + pauseMs?: number; + maxAttempts?: number; + retryDelayMs?: number; + log?: (msg: string) => void; + warn?: (msg: string) => void; + sleep?: (ms: number) => Promise; + now?: () => Date; +} + +const DEFAULT_SLICE_SIZE = 100; +const DEFAULT_PAUSE_MS = 200; +const DEFAULT_MAX_ATTEMPTS = 3; +const DEFAULT_RETRY_DELAY_MS = 2000; + +let current: GraphCompactBootStatus = { state: "pending" }; +let running: Promise | null = null; + +export function getGraphCompactBootStatus(): GraphCompactBootStatus { + return { ...current }; +} + +export function setGraphCompactBootDisabled(): void { + current = { state: "off" }; +} + +export function resetGraphCompactBootStatus(): void { + current = { state: "pending" }; + running = null; +} + +function statusFrom(p: GraphCompactBootProgress): GraphCompactBootStatus { + return { + state: p.status, + phase: p.phase, + processed: p.offset, + total: p.phaseTotal, + scanned: p.scanned, + trimmed: p.trimmed, + idsRemoved: p.idsRemoved, + startedAt: p.startedAt, + completedAt: p.completedAt, + error: p.error, + }; +} + +function isResumable(p: GraphCompactBootProgress | null): p is GraphCompactBootProgress { + return ( + !!p && + p.version === GRAPH_COMPACT_BOOT_VERSION && + p.cap === MAX_GRAPH_SOURCE_OBSERVATIONS && + (p.phase === "snapshot" || (SLICED_SCOPES as readonly string[]).includes(p.phase)) && + Number.isInteger(p.offset) && + p.offset >= 0 + ); +} + +function scannedOf(scope: SlicedScope, r: GraphCompactResult): [number, number] { + if (scope === "nodes") return [r.nodesScanned, r.nodesTrimmed]; + if (scope === "edges") return [r.edgesScanned, r.edgesTrimmed]; + return [r.historyScanned, r.historyTrimmed]; +} + +export function describeGraphCompactBoot(s: GraphCompactBootStatus): string { + if (s.state === "off") return "off (AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false)"; + if (s.state === "pending") return "pending"; + const where = + s.phase === "snapshot" || s.total === null || s.total === undefined + ? `${s.phase ?? "nodes"}` + : `${s.phase} ${s.processed ?? 0} of ${s.total}`; + if (s.state === "running") return `running, ${where}`; + if (s.state === "failed") return `failed at ${where}: ${s.error ?? "unknown error"}`; + return `done, ${s.trimmed ?? 0} records trimmed, ${s.idsRemoved ?? 0} ids removed`; +} + +export function runGraphCompactOnBoot( + kv: StateKV, + opts: GraphCompactBootOptions = {}, +): Promise { + if (running) return running; + running = runOnce(kv, opts).finally(() => { + running = null; + }); + return running; +} + +async function runOnce(kv: StateKV, opts: GraphCompactBootOptions): Promise { + const sliceSize = opts.sliceSize ?? DEFAULT_SLICE_SIZE; + const pauseMs = opts.pauseMs ?? DEFAULT_PAUSE_MS; + const maxAttempts = Math.max(1, opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS); + const retryDelayMs = opts.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS; + const log = opts.log ?? (() => {}); + const warn = opts.warn ?? log; + const sleep = opts.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms))); + const now = opts.now ?? (() => new Date()); + + const attempt = async (fn: () => Promise): Promise => { + let lastErr: unknown; + for (let i = 1; i <= maxAttempts; i++) { + try { + return await fn(); + } catch (err) { + lastErr = err; + if (i < maxAttempts) await sleep(retryDelayMs * i); + } + } + throw lastErr; + }; + + let progress: GraphCompactBootProgress | null = null; + const save = async () => { + if (!progress) return; + progress.updatedAt = now().toISOString(); + current = statusFrom(progress); + await attempt(() => kv.set(KV.config, GRAPH_COMPACT_BOOT_KEY, progress)); + }; + + try { + const stored = await attempt(() => kv.get(KV.config, GRAPH_COMPACT_BOOT_KEY)); + if (isResumable(stored) && stored.status === "done") { + current = statusFrom(stored); + return getGraphCompactBootStatus(); + } + const startedAt = now().toISOString(); + if (isResumable(stored)) { + progress = { ...stored, status: "running", error: undefined }; + log(`Graph provenance compaction: resuming in the background at ${progress.phase} ${progress.offset}`); + } else { + progress = { + version: GRAPH_COMPACT_BOOT_VERSION, + cap: MAX_GRAPH_SOURCE_OBSERVATIONS, + status: "running", + phase: "nodes", + offset: 0, + phaseTotal: null, + scanned: 0, + trimmed: 0, + idsRemoved: 0, + startedAt, + updatedAt: startedAt, + }; + log(`Graph provenance compaction: started in the background (cap ${MAX_GRAPH_SOURCE_OBSERVATIONS} ids per record)`); + } + await save(); + + const p = progress; + for (const scope of SLICED_SCOPES) { + if (p.phase === "snapshot") break; + if (SLICED_SCOPES.indexOf(p.phase) > SLICED_SCOPES.indexOf(scope)) continue; + p.phase = scope; + let phaseTrimmed = 0; + let phaseScanned = 0; + for (;;) { + const r = await attempt(() => + compactGraphProvenance(kv, { scope: scope as GraphCompactScope, offset: p.offset, limit: sliceSize }), + ); + const [scanned, trimmed] = scannedOf(scope, r); + phaseScanned += scanned; + phaseTrimmed += trimmed; + p.scanned += scanned; + p.trimmed += trimmed; + p.idsRemoved += r.idsRemoved; + p.phaseTotal = r.total ?? null; + if (r.nextOffset === null) { + p.offset = p.phaseTotal ?? p.offset; + await save(); + break; + } + p.offset = r.nextOffset; + await save(); + if (pauseMs > 0) await sleep(pauseMs); + } + log(`Graph provenance compaction: ${scope} done (${phaseScanned} checked, ${phaseTrimmed} trimmed)`); + const next = SLICED_SCOPES[SLICED_SCOPES.indexOf(scope) + 1]; + p.phase = next ?? "snapshot"; + p.offset = 0; + p.phaseTotal = null; + await save(); + } + + const snap = await attempt(() => compactGraphProvenance(kv, { scope: "snapshot" })); + if (snap.snapshotTrimmed) p.trimmed += 1; + p.status = "done"; + p.completedAt = now().toISOString(); + await save(); + if (p.idsRemoved > 0) { + await safeAudit(kv, "graph_compact", GRAPH_COMPACT_BOOT_FUNCTION_ID, [], { + trigger: "boot", + recordsTrimmed: p.trimmed, + idsRemoved: p.idsRemoved, + snapshotTrimmed: snap.snapshotTrimmed, + }); + } + log( + `Graph provenance compaction: done (${p.scanned} records checked, ${p.trimmed} trimmed, ${p.idsRemoved} ids removed)`, + ); + return getGraphCompactBootStatus(); + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + if (progress) { + progress.status = "failed"; + progress.error = msg; + current = statusFrom(progress); + try { + await kv.set(KV.config, GRAPH_COMPACT_BOOT_KEY, { ...progress, updatedAt: now().toISOString() }); + } catch {} + } else { + current = { state: "failed", error: msg }; + } + warn( + `Graph provenance compaction failed (${describeGraphCompactBoot(current)}). It resumes on the next start; to run it now, POST /agentmemory/graph/compact.`, + ); + return getGraphCompactBootStatus(); + } +} diff --git a/src/functions/graph.ts b/src/functions/graph.ts index cf551727c7..84eeff6678 100644 --- a/src/functions/graph.ts +++ b/src/functions/graph.ts @@ -726,13 +726,15 @@ export interface GraphCompactResult { nodesTrimmed: number; edgesScanned: number; edgesTrimmed: number; + historyScanned: number; + historyTrimmed: number; idsRemoved: number; snapshotTrimmed: boolean; total?: number; nextOffset: number | null; } -export type GraphCompactScope = "nodes" | "edges" | "snapshot"; +export type GraphCompactScope = "nodes" | "edges" | "history" | "snapshot"; export interface GraphCompactOptions { scope?: GraphCompactScope; @@ -740,7 +742,7 @@ export interface GraphCompactOptions { limit?: number; } -const COMPACT_SCOPES: readonly GraphCompactScope[] = ["nodes", "edges", "snapshot"]; +export const COMPACT_SCOPES: readonly GraphCompactScope[] = ["nodes", "edges", "history", "snapshot"]; export async function compactGraphProvenance( kv: StateKV, @@ -764,16 +766,18 @@ export async function compactGraphProvenance( nodesTrimmed: 0, edgesScanned: 0, edgesTrimmed: 0, + historyScanned: 0, + historyTrimmed: 0, idsRemoved: 0, snapshotTrimmed: false, nextOffset: null, }; const trimScope = async ( - indexScope: string, + listIds: () => Promise, recordScope: string, ): Promise<{ scanned: number; trimmed: number }> => { - const allIds = [...new Set(await kv.list(indexScope))] + const allIds = [...new Set(await listIds())] .filter((id): id is string => typeof id === "string") .sort(); const end = Math.min(allIds.length, offset + limit); @@ -816,15 +820,23 @@ export async function compactGraphProvenance( }); if (scope === undefined || scope === "nodes") { - const n = await trimScope(KV.graphNameIndex, KV.graphNodes); + const n = await trimScope(() => kv.list(KV.graphNameIndex), KV.graphNodes); result.nodesScanned = n.scanned; result.nodesTrimmed = n.trimmed; } if (scope === undefined || scope === "edges") { - const e = await trimScope(KV.graphEdgeKey, KV.graphEdges); + const e = await trimScope(() => kv.list(KV.graphEdgeKey), KV.graphEdges); result.edgesScanned = e.scanned; result.edgesTrimmed = e.trimmed; } + if (scope === undefined || scope === "history") { + const h = await trimScope( + async () => (await kv.list(KV.graphEdgeHistory)).map((r) => r?.id), + KV.graphEdgeHistory, + ); + result.historyScanned = h.scanned; + result.historyTrimmed = h.trimmed; + } if (scope === undefined || scope === "snapshot") { await trimSnapshot(); } @@ -1273,6 +1285,7 @@ export function registerGraphFunction( limit: data?.limit, nodesTrimmed: result.nodesTrimmed, edgesTrimmed: result.edgesTrimmed, + historyTrimmed: result.historyTrimmed, idsRemoved: result.idsRemoved, snapshotTrimmed: result.snapshotTrimmed, }); diff --git a/src/functions/status.ts b/src/functions/status.ts index 3e4d8af60e..5e0b3537ca 100644 --- a/src/functions/status.ts +++ b/src/functions/status.ts @@ -1,5 +1,6 @@ import type { IndexLegStatus, IndexPersistenceStatus } from "../state/index-persistence.js"; import type { VectorBackfillState } from "./search.js"; +import { describeGraphCompactBoot, type GraphCompactBootStatus } from "./graph-compact-boot.js"; export type StatusLevel = "ok" | "info" | "warn" | "error"; @@ -71,6 +72,7 @@ export interface StatusInputs { }; graph: GraphStatsInput | null; graphExtractionEnabled: boolean; + graphCompaction?: GraphCompactBootStatus | null; auditLegacy: { status: string; sizeBytes?: number } | null; indexPersistence?: IndexPersistenceStatus | null; stateStore?: { ok: boolean; latencyMs?: number } | null; @@ -104,6 +106,7 @@ export interface StatusReport { index: StatusInputs["index"] & { breakdown: IndexBreakdown | null }; indexPersistence: IndexPersistenceStatus | null; graph: (GraphStatsInput & { ageSeconds: number | null; extractionEnabled: boolean }) | null; + graphCompaction: GraphCompactBootStatus | null; functions: Array; flags: Array; problems: StatusProblem[]; @@ -385,6 +388,23 @@ export function evaluateStatus(input: StatusInputs): StatusReport { } } + const compaction = input.graphCompaction ?? null; + if (compaction?.state === "running") { + problems.push({ + level: "info", + code: "graph-compaction-running", + message: `Oversized graph provenance is being trimmed in the background (${describeGraphCompactBoot(compaction)}). Search and capture keep working.`, + fix: "No action needed. It runs once, resumes after a restart and stops by itself. AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false turns it off.", + }); + } else if (compaction?.state === "failed") { + problems.push({ + level: "warn", + code: "graph-compaction-failed", + message: `The one-time graph provenance compaction stopped: ${compaction.error ?? "unknown error"}. Graph search can stay slow until it finishes.`, + fix: `It resumes on the next start. To run it now: ${graphCompactCommand(input.ports.rest)}`, + }); + } + if (input.auditLegacy?.status === "too-large" || input.auditLegacy?.status === "unreadable") { const size = input.auditLegacy.sizeBytes; const sizeText = typeof size === "number" ? ` (${Math.round(size / (1024 * 1024))} MiB)` : ""; @@ -441,6 +461,7 @@ export function evaluateStatus(input: StatusInputs): StatusReport { index: { ...input.index, breakdown: indexBreakdown(input.index) }, indexPersistence: persistence, graph, + graphCompaction: compaction, functions, flags: input.flags.map((flag) => flag.enabled && flag.needsLlm && noLlm @@ -686,6 +707,7 @@ ${graph row("Nodes / edges", escapeHtml(`${graph.totalNodes ?? 0} / ${graph.totalEdges ?? 0}`)) + row("Snapshot age", escapeHtml(graph.fromSnapshot ? formatDuration(graph.ageSeconds) : "no snapshot")) : row("Graph", "unavailable")} +${report.graphCompaction ? row("Provenance compaction", escapeHtml(describeGraphCompactBoot(report.graphCompaction))) : ""}

Features

${flags}
FeatureSettingStateHow to change

Process

@@ -696,6 +718,10 @@ ${processRows(report)} `; } +export function graphCompactCommand(restPort: number | null): string { + return `curl -X POST http://localhost:${restPort ?? 3111}/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'`; +} + export const UNINDEXED_SCAN_REUSE_MS = 30_000; export function singleFlight( diff --git a/src/index.ts b/src/index.ts index 5786de4c36..7d3726c6d8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -17,6 +17,7 @@ import { getAuditRetentionMonths, getStateBackend, isSessionSweepEnabled, + isGraphCompactOnBootEnabled, getSessionSweepStaleHours, } from "./config.js"; import { @@ -72,6 +73,7 @@ import { registerExportImportFunction } from "./functions/export-import.js"; import { registerEnrichFunction } from "./functions/enrich.js"; import { registerClaudeBridgeFunction } from "./functions/claude-bridge.js"; import { registerGraphFunction } from "./functions/graph.js"; +import { GRAPH_COMPACT_BOOT_DELAY_MS, runGraphCompactOnBoot, setGraphCompactBootDisabled } from "./functions/graph-compact-boot.js"; import { registerGraphImportFunction } from "./functions/graph-import.js"; import { registerConsolidationPipelineFunction } from "./functions/consolidation-pipeline.js"; import { registerTeamFunction } from "./functions/team.js"; @@ -117,7 +119,7 @@ import { registerHealthMonitor } from "./health/monitor.js"; import { createStreamRelayProbe } from "./health/stream-relay-probe.js"; import { initMetrics, OTEL_CONFIG } from "./telemetry/setup.js"; import { VERSION } from "./version.js"; -import { bootLog } from "./logger.js"; +import { bootLog, bootWarn } from "./logger.js"; import { runtimeMetadataPath } from "./runtime-paths.js"; import { mkdirSync, writeFileSync, unlinkSync } from "node:fs"; import { dirname } from "node:path"; @@ -561,6 +563,15 @@ async function main() { config.restPort, ); + if (isGraphCompactOnBootEnabled()) { + const graphCompactTimer = setTimeout(() => { + void runGraphCompactOnBoot(kv, { log: bootLog, warn: bootWarn }).catch(() => {}); + }, GRAPH_COMPACT_BOOT_DELAY_MS); + graphCompactTimer.unref(); + } else { + setGraphCompactBootDisabled(); + } + const autoForgetIntervalMs = parseInt(process.env.AUTO_FORGET_INTERVAL_MS || "3600000", 10); const consolidationIntervalMs = getConsolidationIntervalMs(); diff --git a/src/triggers/api.ts b/src/triggers/api.ts index c10868aab6..ff8261bdc9 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -42,6 +42,8 @@ import { renderViewerDocument } from "../viewer/document.js"; import { getBoundViewerPort, getViewerSkipped } from "../viewer/server.js"; import { MAX_FILES_UPPER_BOUND } from "../functions/replay.js"; import { describeGraphNode } from "../functions/graph-node.js"; +import { COMPACT_SCOPES, type GraphCompactScope } from "../functions/graph.js"; +import { getGraphCompactBootStatus } from "../functions/graph-compact-boot.js"; import { LESSON_SOURCE_IDS_MAX, normalizeLessonSourceIds } from "../functions/lessons.js"; import { logger } from "../logger.js"; import { withoutObservationSource } from "../functions/observation-source.js"; @@ -402,6 +404,7 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusRe vectorBackfillState: getVectorBackfillState(), }, graph, + graphCompaction: getGraphCompactBootStatus(), graphExtractionEnabled: isGraphExtractionEnabled(), auditLegacy: auditMigrationState ? { status: auditMigrationState.status, sizeBytes: auditMigrationState.legacySizeBytes } @@ -2033,8 +2036,8 @@ export function registerApiTriggers( if (authErr) return authErr; const body = (req.body ?? {}) as Record; const { scope, offset, limit } = body; - if (scope !== undefined && scope !== "nodes" && scope !== "edges" && scope !== "snapshot") { - return { status_code: 400, body: { error: "scope must be nodes, edges or snapshot" } }; + if (scope !== undefined && !COMPACT_SCOPES.includes(scope as GraphCompactScope)) { + return { status_code: 400, body: { error: "scope must be nodes, edges, history or snapshot" } }; } if (offset !== undefined && !(Number.isInteger(offset) && (offset as number) >= 0)) { return { status_code: 400, body: { error: "offset must be a non-negative integer" } }; diff --git a/src/viewer/index.html b/src/viewer/index.html index dd8c0949e7..fe6484fc91 100644 --- a/src/viewer/index.html +++ b/src/viewer/index.html @@ -7168,9 +7168,22 @@

agentmemory

html += hrow('Vector save', esc(legText(p.vector)), null, 'Saved at most every ' + esc(durationText(p.saveIntervalMs || 600000)) + ' (AGENTMEMORY_INDEX_SAVE_INTERVAL_MS). ' + esc(fmtNum(p.buckets) + ' bucket' + (p.buckets === 1 ? '' : 's') + ', ' + fmtNum(p.pendingChanges) + ' unsaved change' + (p.pendingChanges === 1 ? '' : 's') + (p.saving ? ', saving now' : '') + '.')); } html += hrow('Graph', esc(fmtNum(c.graphNodes) + ' nodes · ' + fmtNum(c.graphEdges) + ' edges'), 'graph', store.graph && store.graph.updatedAt ? 'Snapshot rebuilt ' + esc(timeAgo(store.graph.updatedAt)) + '.' : ''); + if (r && r.graphCompaction) html += graphCompactionRowHtml(r.graphCompaction); return html + ''; } + function graphCompactionRowHtml(g) { + var where = g.phase === 'snapshot' || g.total === null || g.total === undefined ? (g.phase || 'nodes') : g.phase + ' ' + fmtNum(g.processed || 0) + ' of ' + fmtNum(g.total); + var text = g.state === 'off' ? 'off' : g.state === 'pending' ? 'pending' : g.state === 'running' ? 'running, ' + where : g.state === 'failed' ? 'failed at ' + where : 'done'; + var note = 'A one-time pass that trims each graph node and edge to its newest 32 source observations, so stores from older versions stop slowing graph search.'; + if (g.state === 'done') note = fmtNum(g.trimmed || 0) + ' records trimmed, ' + fmtNum(g.idsRemoved || 0) + ' ids removed' + (g.completedAt ? ', finished ' + timeAgo(g.completedAt) : '') + '. It does not run again.'; + else if (g.state === 'running') note += ' It runs in the background, resumes after a restart and stops by itself.'; + else if (g.state === 'off') note = 'Turned off with AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false. Run it by hand if graph search is slow:'; + else if (g.state === 'failed') note = esc(g.error || 'unknown error') + '. It resumes on the next start. To run it now:'; + var cmd = g.state === 'off' || g.state === 'failed' ? cmdBlock(curlPost('graph/compact', {})) : ''; + return hrow('Provenance compaction', esc(text), null, (g.state === 'failed' ? note : esc(note)) + cmd); + } + function llmCardHtml(r) { var cb = store.circuitBreaker; var noLlm = store.provider === 'noop' || (r && r.provider.llm === 'noop'); diff --git a/test/graph-compact-boot.test.ts b/test/graph-compact-boot.test.ts new file mode 100644 index 0000000000..ca56fc78e2 --- /dev/null +++ b/test/graph-compact-boot.test.ts @@ -0,0 +1,359 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"; +import { readFileSync } from "node:fs"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { + GRAPH_COMPACT_BOOT_KEY, + GRAPH_COMPACT_BOOT_VERSION, + describeGraphCompactBoot, + getGraphCompactBootStatus, + resetGraphCompactBootStatus, + runGraphCompactOnBoot, + setGraphCompactBootDisabled, + type GraphCompactBootProgress, +} from "../src/functions/graph-compact-boot.js"; +import { MAX_GRAPH_SOURCE_OBSERVATIONS, compactGraphProvenance } from "../src/functions/graph.js"; +import { isGraphCompactOnBootEnabled } from "../src/config.js"; +import { evaluateStatus, renderStatusHtml, type StatusInputs } from "../src/functions/status.js"; +import type { GraphEdge, GraphNode } from "../src/types.js"; + +const NODES = "mem:graph:nodes"; +const EDGES = "mem:graph:edges"; +const HISTORY = "mem:graph:edge-history"; +const CONFIG = "mem:config"; + +function mockKV(opts: { shuffle?: boolean } = {}) { + const store = new Map>(); + const calls = { list: [] as string[], get: [] as string[], set: [] as string[] }; + const kv = { + calls, + failGet: null as ((scope: string, key: string) => boolean) | null, + get: async (scope: string, key: string): Promise => { + calls.get.push(`${scope}/${key}`); + if (kv.failGet?.(scope, key)) throw new Error("state::get timed out"); + const v = store.get(scope)?.get(key); + return (v === undefined ? null : structuredClone(v)) as T | null; + }, + set: async (scope: string, key: string, data: T): Promise => { + calls.set.push(`${scope}/${key}`); + if (!store.has(scope)) store.set(scope, new Map()); + store.get(scope)!.set(key, structuredClone(data)); + return data; + }, + delete: async (scope: string, key: string): Promise => { + store.get(scope)?.delete(key); + }, + list: async (scope: string): Promise => { + calls.list.push(scope); + const values = Array.from(store.get(scope)?.values() ?? []).map((v) => structuredClone(v)); + if (opts.shuffle) { + for (let i = values.length - 1; i > 0; i--) { + const j = Math.floor(Math.random() * (i + 1)); + [values[i], values[j]] = [values[j], values[i]]; + } + } + return values as T[]; + }, + }; + return kv; +} +type KV = ReturnType; + +const ids = (prefix: string, n: number) => Array.from({ length: n }, (_, i) => `${prefix}_${i}`); + +async function seed(kv: KV, nodes: number, edges: number, history: number, bloat = 100) { + for (let i = 0; i < nodes; i++) { + const id = `gn_${String(i).padStart(4, "0")}`; + const n: GraphNode = { + id, + type: "concept", + name: `n${i}`, + properties: {}, + sourceObservationIds: ids(`obs${i}`, i % 2 === 0 ? bloat : 3), + createdAt: "2026-09-01T00:00:00.000Z", + }; + await kv.set(NODES, id, n); + await kv.set("mem:graph:name-index", `concept|n${i}`, id); + } + for (let i = 0; i < edges; i++) { + const id = `ge_${String(i).padStart(4, "0")}`; + const e: GraphEdge = { + id, + type: "related_to", + sourceNodeId: "gn_0000", + targetNodeId: `gn_${i}`, + weight: 0.5, + sourceObservationIds: ids(`eobs${i}`, bloat), + createdAt: "2026-09-01T00:00:00.000Z", + }; + await kv.set(EDGES, id, e); + await kv.set("mem:graph:edge-key", `gn_0000|gn_${i}|related_to`, id); + } + for (let i = 0; i < history; i++) { + const id = `ge_h${String(i).padStart(4, "0")}`; + await kv.set(HISTORY, id, { + id, + type: "uses", + sourceNodeId: "gn_0000", + targetNodeId: "gn_0001", + weight: 0.5, + sourceObservationIds: ids(`hobs${i}`, bloat), + createdAt: "2026-09-01T00:00:00.000Z", + isLatest: false, + }); + } + await kv.set("mem:graph:snapshot", "current", { + version: 1, + dirty: false, + topNodes: [await kv.get(NODES, "gn_0000")], + topEdges: [], + topDegrees: {}, + stats: { totalNodes: nodes, totalEdges: edges, nodesByType: {}, edgesByType: {} }, + updatedAt: "2026-09-01T00:00:00.000Z", + }); +} + +async function maxIds(kv: KV): Promise { + let max = 0; + for (const scope of [NODES, EDGES, HISTORY]) { + for (const r of await kv.list<{ sourceObservationIds: string[] }>(scope)) { + max = Math.max(max, r.sourceObservationIds.length); + } + } + const snap = (await kv.get<{ topNodes: GraphNode[] }>("mem:graph:snapshot", "current"))!; + for (const n of snap.topNodes) max = Math.max(max, n.sourceObservationIds.length); + return max; +} + +const fast = { sliceSize: 3, pauseMs: 0, retryDelayMs: 0, sleep: async () => {} }; +const marker = (kv: KV) => kv.get(CONFIG, GRAPH_COMPACT_BOOT_KEY); + +beforeEach(() => resetGraphCompactBootStatus()); +afterEach(() => vi.unstubAllEnvs()); + +describe("graph compaction on boot", () => { + it("trims nodes, edges, edge history and the snapshot to the cap and marks it done", async () => { + const kv = mockKV(); + await seed(kv, 10, 7, 5); + const log = vi.fn(); + const s = await runGraphCompactOnBoot(kv as never, { ...fast, log }); + const listed = [...kv.calls.list]; + expect(s.state).toBe("done"); + expect(await maxIds(kv)).toBe(MAX_GRAPH_SOURCE_OBSERVATIONS); + expect(s.trimmed).toBe(5 + 7 + 5 + 1); + expect(s.idsRemoved).toBe(17 * (100 - MAX_GRAPH_SOURCE_OBSERVATIONS)); + const m = (await marker(kv))!; + expect(m).toMatchObject({ status: "done", version: GRAPH_COMPACT_BOOT_VERSION, cap: MAX_GRAPH_SOURCE_OBSERVATIONS }); + expect(log.mock.calls.map((c) => c[0]).at(-1)).toMatch(/done \(22 records checked, 18 trimmed/); + expect(listed).not.toContain(NODES); + expect(listed).not.toContain(EDGES); + }); + + it("finishes fast on a store with nothing over the cap", async () => { + const kv = mockKV(); + await seed(kv, 4, 2, 1, 10); + kv.calls.set.length = 0; + const s = await runGraphCompactOnBoot(kv as never, fast); + expect(s).toMatchObject({ state: "done", trimmed: 0, idsRemoved: 0 }); + expect(kv.calls.set.filter((c) => !c.startsWith(CONFIG))).toEqual([]); + }); + + it("resumes from the saved offset after the process dies mid-run", async () => { + const kv = mockKV(); + await seed(kv, 12, 6, 0); + kv.calls.get.length = 0; + let pauses = 0; + const hang = new Promise(() => {}); + void runGraphCompactOnBoot(kv as never, { + ...fast, + pauseMs: 1, + sleep: async () => { + if (++pauses === 2) await hang; + }, + }); + await vi.waitFor(async () => expect((await marker(kv))?.offset).toBe(6)); + const saved = (await marker(kv))!; + expect(saved).toMatchObject({ status: "running", phase: "nodes", offset: 6 }); + const nodeReadsBefore = kv.calls.get.filter((c) => c.startsWith(`${NODES}/`)).length; + expect(nodeReadsBefore).toBe(6); + + resetGraphCompactBootStatus(); + kv.calls.get.length = 0; + const log = vi.fn(); + const s = await runGraphCompactOnBoot(kv as never, { ...fast, log }); + expect(log.mock.calls[0]![0]).toMatch(/resuming in the background at nodes 6/); + expect(kv.calls.get.filter((c) => c.startsWith(`${NODES}/`))).toHaveLength(6); + expect(s.state).toBe("done"); + expect(s.trimmed).toBe(6 + 6 + 1); + expect(await maxIds(kv)).toBe(MAX_GRAPH_SOURCE_OBSERVATIONS); + }); + + it("is idempotent: a second full pass trims nothing", async () => { + const kv = mockKV(); + await seed(kv, 6, 4, 3); + await runGraphCompactOnBoot(kv as never, fast); + const r = await compactGraphProvenance(kv as never); + expect(r).toMatchObject({ nodesTrimmed: 0, edgesTrimmed: 0, historyTrimmed: 0, idsRemoved: 0, snapshotTrimmed: false }); + }); + + it("never runs again once the completion marker is set", async () => { + const kv = mockKV(); + await seed(kv, 4, 2, 1); + await runGraphCompactOnBoot(kv as never, fast); + resetGraphCompactBootStatus(); + kv.calls.list.length = 0; + kv.calls.set.length = 0; + const log = vi.fn(); + const s = await runGraphCompactOnBoot(kv as never, { ...fast, log }); + expect(s.state).toBe("done"); + expect(kv.calls.list).toEqual([]); + expect(kv.calls.set).toEqual([]); + expect(log).not.toHaveBeenCalled(); + }); + + it("runs again when the marker was written for a different cap or version", async () => { + const kv = mockKV(); + await seed(kv, 4, 0, 0); + await kv.set(CONFIG, GRAPH_COMPACT_BOOT_KEY, { + version: GRAPH_COMPACT_BOOT_VERSION, + cap: MAX_GRAPH_SOURCE_OBSERVATIONS * 2, + status: "done", + phase: "snapshot", + offset: 0, + }); + const s = await runGraphCompactOnBoot(kv as never, fast); + expect(s.state).toBe("done"); + expect(s.trimmed).toBeGreaterThan(0); + expect((await marker(kv))!.cap).toBe(MAX_GRAPH_SOURCE_OBSERVATIONS); + }); + + it("covers every record when the store lists in a different order on every call", async () => { + const kv = mockKV({ shuffle: true }); + await seed(kv, 40, 30, 20); + const s = await runGraphCompactOnBoot(kv as never, { ...fast, sliceSize: 2 }); + expect(s.state).toBe("done"); + expect(await maxIds(kv)).toBe(MAX_GRAPH_SOURCE_OBSERVATIONS); + }); + + it("retries a failing slice a bounded number of times, then reports and keeps the worker alive", async () => { + const kv = mockKV(); + await seed(kv, 6, 0, 0); + kv.failGet = (scope, key) => scope === NODES && key === "gn_0004"; + const warn = vi.fn(); + const s = await runGraphCompactOnBoot(kv as never, { ...fast, maxAttempts: 2, warn }); + expect(s).toMatchObject({ state: "failed", phase: "nodes", processed: 3, error: "state::get timed out" }); + expect(kv.calls.get.filter((c) => c === `${NODES}/gn_0004`)).toHaveLength(2); + expect(warn).toHaveBeenCalledTimes(1); + expect(warn.mock.calls[0]![0]).toMatch(/failed at nodes 3 of 6: state::get timed out.*POST \/agentmemory\/graph\/compact/); + expect(await marker(kv)).toMatchObject({ status: "failed", offset: 3, error: "state::get timed out" }); + + kv.failGet = null; + resetGraphCompactBootStatus(); + const again = await runGraphCompactOnBoot(kv as never, fast); + expect(again.state).toBe("done"); + expect(await maxIds(kv)).toBe(MAX_GRAPH_SOURCE_OBSERVATIONS); + }); + + it("does not block the caller and runs at most once at a time", async () => { + const kv = mockKV(); + await seed(kv, 6, 0, 0); + let release!: () => void; + const gate = new Promise((r) => (release = r)); + const first = runGraphCompactOnBoot(kv as never, { ...fast, pauseMs: 1, sleep: () => gate }); + const second = runGraphCompactOnBoot(kv as never, fast); + expect(second).toBe(first); + await vi.waitFor(() => expect(getGraphCompactBootStatus().state).toBe("running")); + expect(describeGraphCompactBoot(getGraphCompactBootStatus())).toBe("running, nodes 3 of 6"); + release(); + expect((await first).state).toBe("done"); + }); + + it("is scheduled after the viewer starts and never awaited during boot", () => { + const src = readFileSync(new URL("../src/index.ts", import.meta.url), "utf8"); + const viewerAt = src.indexOf("startViewerServer(\n"); + const runAt = src.indexOf("void runGraphCompactOnBoot("); + expect(viewerAt).toBeGreaterThan(0); + expect(runAt).toBeGreaterThan(viewerAt); + expect(src).not.toMatch(/await runGraphCompactOnBoot/); + expect(src).toMatch(/if \(isGraphCompactOnBootEnabled\(\)\)[\s\S]*?setGraphCompactBootDisabled\(\)/); + }); +}); + +describe("AGENTMEMORY_GRAPH_COMPACT_ON_BOOT", () => { + it("is on by default and off only for false", () => { + vi.stubEnv("AGENTMEMORY_GRAPH_COMPACT_ON_BOOT", ""); + expect(isGraphCompactOnBootEnabled()).toBe(true); + vi.stubEnv("AGENTMEMORY_GRAPH_COMPACT_ON_BOOT", "true"); + expect(isGraphCompactOnBootEnabled()).toBe(true); + vi.stubEnv("AGENTMEMORY_GRAPH_COMPACT_ON_BOOT", "false"); + expect(isGraphCompactOnBootEnabled()).toBe(false); + }); + + it("reports off when disabled", () => { + setGraphCompactBootDisabled(); + expect(getGraphCompactBootStatus()).toEqual({ state: "off" }); + expect(describeGraphCompactBoot(getGraphCompactBootStatus())).toMatch(/AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false/); + }); +}); + +describe("graph compaction in /agentmemory/status", () => { + const base: StatusInputs = { + now: new Date("2026-10-01T12:00:00.000Z"), + version: "0.10.0", + engineVersion: "0.22.1", + uptimeSeconds: 10, + stateBackend: "file", + ports: { rest: 4611, streams: 4612, viewer: 4613 }, + health: null, + circuitBreaker: null, + functionMetrics: [], + provider: "llm", + embeddingProvider: "none", + flags: [], + index: { + bm25Documents: 0, + vectorDocuments: null, + observationsIndexed: 0, + missingObservations: 0, + sessions: 0, + bm25Incomplete: false, + pendingVectorBackfill: 0, + }, + graph: null, + graphExtractionEnabled: false, + auditLegacy: null, + }; + + it("shows a running pass as info with its position", () => { + const r = evaluateStatus({ + ...base, + graphCompaction: { state: "running", phase: "edges", processed: 400, total: 909 }, + }); + expect(r.graphCompaction?.state).toBe("running"); + const p = r.problems.find((x) => x.code === "graph-compaction-running")!; + expect(p.level).toBe("info"); + expect(p.message).toMatch(/edges 400 of 909/); + expect(renderStatusHtml(r, "n")).toMatch(/Provenance compaction/); + }); + + it("shows a failed pass as a warning with the reason and the manual command", () => { + const r = evaluateStatus({ + ...base, + graphCompaction: { state: "failed", phase: "nodes", processed: 3, total: 6, error: "state::get timed out" }, + }); + const p = r.problems.find((x) => x.code === "graph-compaction-failed")!; + expect(p.level).toBe("warn"); + expect(p.message).toMatch(/state::get timed out/); + expect(p.fix).toContain("curl -X POST http://localhost:4611/agentmemory/graph/compact"); + }); + + it("adds no problem when done or off", () => { + for (const state of ["done", "off", "pending"] as const) { + const r = evaluateStatus({ ...base, graphCompaction: { state } }); + expect(r.problems.map((x) => x.code).filter((c) => c.startsWith("graph-compaction"))).toEqual([]); + } + }); +}); From 97ad9e2f6f798fbed503c0c615b60c34b0a5e91f Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Thu, 1 Oct 2026 15:34:40 +0530 Subject: [PATCH 13/14] fix(graph): keep boot compaction totals exact across crashes Each slice is now counted with a dry run first. When the slice has records to trim, the plan (scanned, trimmed, ids removed, next offset) is saved in the progress record before any record is written, then the slice is applied and the plan is folded into the totals in the same write that advances the offset. A restart that lost the last progress write finds the saved plan at its offset and reuses those counts, so a re-processed slice never adds to the totals twice and never drops the records it already trimmed. The snapshot step follows the same rule. compactGraphProvenance gains a dryRun option that counts without writing. Status, viewer and boot-log fields are unchanged. The new test captures the store before every progress write of a full run, restarts from each of those states, and checks that the final scanned, trimmed and ids-removed totals equal a clean single run. --- src/functions/graph-compact-boot.ts | 86 +++++++++++++++++++++++------ src/functions/graph.ts | 6 +- test/graph-compact-boot.test.ts | 42 ++++++++++++-- 3 files changed, 110 insertions(+), 24 deletions(-) diff --git a/src/functions/graph-compact-boot.ts b/src/functions/graph-compact-boot.ts index 2ba09f9ab7..7b5391b227 100644 --- a/src/functions/graph-compact-boot.ts +++ b/src/functions/graph-compact-boot.ts @@ -27,12 +27,23 @@ export interface GraphCompactBootProgress { scanned: number; trimmed: number; idsRemoved: number; + pending?: GraphCompactBootSlicePlan; startedAt: string; updatedAt: string; completedAt?: string; error?: string; } +export interface GraphCompactBootSlicePlan { + phase: BootPhase; + offset: number; + scanned: number; + trimmed: number; + idsRemoved: number; + nextOffset: number | null; + total: number | null; +} + export type GraphCompactBootState = "off" | "pending" | "running" | "done" | "failed"; export interface GraphCompactBootStatus { @@ -106,6 +117,13 @@ function isResumable(p: GraphCompactBootProgress | null): p is GraphCompactBootP ); } +function storedPlan(p: GraphCompactBootProgress, phase: BootPhase): GraphCompactBootSlicePlan | null { + const plan = p.pending; + if (!plan || plan.phase !== phase || plan.offset !== p.offset) return null; + const counts = [plan.scanned, plan.trimmed, plan.idsRemoved]; + return counts.every((n) => Number.isInteger(n) && n >= 0) ? plan : null; +} + function scannedOf(scope: SlicedScope, r: GraphCompactResult): [number, number] { if (scope === "nodes") return [r.nodesScanned, r.nodesTrimmed]; if (scope === "edges") return [r.edgesScanned, r.edgesTrimmed]; @@ -202,23 +220,36 @@ async function runOnce(kv: StateKV, opts: GraphCompactBootOptions): Promise - compactGraphProvenance(kv, { scope: scope as GraphCompactScope, offset: p.offset, limit: sliceSize }), - ); - const [scanned, trimmed] = scannedOf(scope, r); - phaseScanned += scanned; - phaseTrimmed += trimmed; - p.scanned += scanned; - p.trimmed += trimmed; - p.idsRemoved += r.idsRemoved; - p.phaseTotal = r.total ?? null; - if (r.nextOffset === null) { - p.offset = p.phaseTotal ?? p.offset; - await save(); - break; + const slice = { scope: scope as GraphCompactScope, offset: p.offset, limit: sliceSize }; + let plan = storedPlan(p, scope); + if (!plan) { + const r = await attempt(() => compactGraphProvenance(kv, { ...slice, dryRun: true })); + const [scanned, trimmed] = scannedOf(scope, r); + plan = { + phase: scope, + offset: p.offset, + scanned, + trimmed, + idsRemoved: r.idsRemoved, + nextOffset: r.nextOffset, + total: r.total ?? null, + }; + if (plan.trimmed > 0) { + p.pending = plan; + await save(); + } } - p.offset = r.nextOffset; + if (plan.trimmed > 0) await attempt(() => compactGraphProvenance(kv, slice)); + phaseScanned += plan.scanned; + phaseTrimmed += plan.trimmed; + p.scanned += plan.scanned; + p.trimmed += plan.trimmed; + p.idsRemoved += plan.idsRemoved; + p.pending = undefined; + p.phaseTotal = plan.total; + p.offset = plan.nextOffset ?? p.phaseTotal ?? p.offset; await save(); + if (plan.nextOffset === null) break; if (pauseMs > 0) await sleep(pauseMs); } log(`Graph provenance compaction: ${scope} done (${phaseScanned} checked, ${phaseTrimmed} trimmed)`); @@ -229,8 +260,27 @@ async function runOnce(kv: StateKV, opts: GraphCompactBootOptions): Promise compactGraphProvenance(kv, { scope: "snapshot" })); - if (snap.snapshotTrimmed) p.trimmed += 1; + let snapPlan = storedPlan(p, "snapshot"); + if (!snapPlan) { + const dry = await attempt(() => compactGraphProvenance(kv, { scope: "snapshot", dryRun: true })); + snapPlan = { + phase: "snapshot", + offset: p.offset, + scanned: 0, + trimmed: dry.snapshotTrimmed ? 1 : 0, + idsRemoved: 0, + nextOffset: null, + total: null, + }; + if (snapPlan.trimmed > 0) { + p.pending = snapPlan; + await save(); + } + } + if (snapPlan.trimmed > 0) await attempt(() => compactGraphProvenance(kv, { scope: "snapshot" })); + const snapshotTrimmed = snapPlan.trimmed > 0; + p.trimmed += snapPlan.trimmed; + p.pending = undefined; p.status = "done"; p.completedAt = now().toISOString(); await save(); @@ -239,7 +289,7 @@ async function runOnce(kv: StateKV, opts: GraphCompactBootOptions): Promise>(); +function mockKV(opts: { shuffle?: boolean; store?: Map> } = {}) { + const store = opts.store ?? new Map>(); const calls = { list: [] as string[], get: [] as string[], set: [] as string[] }; const kv = { calls, + store, failGet: null as ((scope: string, key: string) => boolean) | null, get: async (scope: string, key: string): Promise => { calls.get.push(`${scope}/${key}`); @@ -178,19 +179,52 @@ describe("graph compaction on boot", () => { const saved = (await marker(kv))!; expect(saved).toMatchObject({ status: "running", phase: "nodes", offset: 6 }); const nodeReadsBefore = kv.calls.get.filter((c) => c.startsWith(`${NODES}/`)).length; - expect(nodeReadsBefore).toBe(6); + expect(nodeReadsBefore).toBe(12); resetGraphCompactBootStatus(); kv.calls.get.length = 0; const log = vi.fn(); const s = await runGraphCompactOnBoot(kv as never, { ...fast, log }); expect(log.mock.calls[0]![0]).toMatch(/resuming in the background at nodes 6/); - expect(kv.calls.get.filter((c) => c.startsWith(`${NODES}/`))).toHaveLength(6); + expect(kv.calls.get.filter((c) => c.startsWith(`${NODES}/`))).toHaveLength(12); expect(s.state).toBe("done"); expect(s.trimmed).toBe(6 + 6 + 1); expect(await maxIds(kv)).toBe(MAX_GRAPH_SOURCE_OBSERVATIONS); }); + it("reports the same totals as a clean run when the last progress write is lost at any point", async () => { + const clean = mockKV(); + await seed(clean, 10, 7, 5); + const want = await runGraphCompactOnBoot(clean as never, fast); + const totals = (s: { scanned?: number; trimmed?: number; idsRemoved?: number }) => ({ + scanned: s.scanned, + trimmed: s.trimmed, + idsRemoved: s.idsRemoved, + }); + expect(totals(want)).toEqual({ scanned: 22, trimmed: 18, idsRemoved: 17 * (100 - MAX_GRAPH_SOURCE_OBSERVATIONS) }); + + const probe = mockKV(); + await seed(probe, 10, 7, 5); + const cuts: Map>[] = []; + const set = probe.set; + probe.set = async (scope: string, key: string, data: T): Promise => { + if (scope === CONFIG && key === GRAPH_COMPACT_BOOT_KEY) cuts.push(structuredClone(probe.store)); + return set(scope, key, data); + }; + resetGraphCompactBootStatus(); + await runGraphCompactOnBoot(probe as never, fast); + expect(cuts.length).toBeGreaterThan(20); + + for (const store of cuts) { + const kv = mockKV({ store }); + resetGraphCompactBootStatus(); + const s = await runGraphCompactOnBoot(kv as never, fast); + expect(s.state).toBe("done"); + expect(totals(s)).toEqual(totals(want)); + expect(await maxIds(kv)).toBe(MAX_GRAPH_SOURCE_OBSERVATIONS); + } + }); + it("is idempotent: a second full pass trims nothing", async () => { const kv = mockKV(); await seed(kv, 6, 4, 3); From bbab447ee582e85595d2bf4aa119a14fbe7907f8 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Thu, 1 Oct 2026 16:34:23 +0530 Subject: [PATCH 14/14] docs(env): document the boot-time graph compaction setting --- .env.example | 1 + 1 file changed, 1 insertion(+) diff --git a/.env.example b/.env.example index 607e326f8a..4e4e344542 100644 --- a/.env.example +++ b/.env.example @@ -108,6 +108,7 @@ # BM25_WEIGHT=0.4 # Hybrid search weight for BM25 leg # VECTOR_WEIGHT=0.6 # Hybrid search weight for vector leg # AGENTMEMORY_GRAPH_WEIGHT=0.2 # Graph traversal bonus on smart-search ranking +# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false # Skip the one-time background trim of oversized graph provenance at startup # TOKEN_BUDGET=2000 # Max tokens injected via mem::context per session # MAX_OBS_PER_SESSION=500 # Per-session observation cap before consolidation kicks in # SUMMARIZE_CHUNK_SIZE=400 # When mem::summarize sees a session larger than this, it chunks observations and map-reduces (chunk-summarize → reduce-merge) to stay within the LLM's context window. Default 400 ≈ 50k tokens per chunk at ~110 tok/obs. Native sessions are capped by MAX_OBS_PER_SESSION; chunking primarily matters for bulk-imported jsonl sessions, which bypass that cap.