#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix(graph): bound and attribute node and edge provenance (carries #1445) (#1454)
Rohit Ghumare1abb2cb0a391
diff --git a/AGENTS.md b/AGENTS.mdindex 9145dfa2..e65ccef4 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 functionsdiff --git a/README.md b/README.mdindex 120ac49f..41cbda22 100644--- a/README.md+++ b/README.md@@ -1671,7 +1671,7 @@ Create `~/.agentmemory/.env`:<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-api.svg"><img src="assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>-134 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.+135 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.<details><summary>Key endpoints</summary>@@ -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)</details>+**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"}'+```+---<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-development.svg"><img src="assets/tags/section-development.svg" alt="Development" height="32" /></picture></h2>diff --git a/plugin/skills/agentmemory-rest-api/REFERENCE.md b/plugin/skills/agentmemory-rest-api/REFERENCE.mdindex 75671c94..7de53010 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 `<!-- AUTOGEN:rest START - generated by scripts/skills/generate.ts, do not edit by hand -->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/export-import.ts b/src/functions/export-import.tsindex 1758a94c..2a14ea27 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): voidconst 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): voidconst 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-import.ts b/src/functions/graph-import.tsindex 502526e8..bc595c9d 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.tsindex 68e78117..cf551727 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.@@ -301,35 +301,46 @@ function snapshotPushEdgeIfBothInTop(}}+export const MAX_GRAPH_SOURCE_OBSERVATIONS = 32;++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);+}++export function boundRecordSources<R extends object>(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[]) };+}+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 ?? [],+ ),};}@@ -580,7 +591,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 readSnapshotStrict(kv)) ?? emptySnapshot();@@ -621,7 +631,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.@@ -631,6 +641,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);@@ -671,7 +682,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);@@ -680,6 +691,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;@@ -709,6 +721,120 @@ export async function persistGraphDelta(});}+export interface GraphCompactResult {+ nodesScanned: number;+ nodesTrimmed: number;+ edgesScanned: number;+ edgesTrimmed: number;+ idsRemoved: number;+ snapshotTrimmed: boolean;+ 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"];++export async function compactGraphProvenance(+ kv: StateKV,+ opts: GraphCompactOptions = {},+): Promise<GraphCompactResult> {+ 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 <R extends { sourceObservationIds: string[] }>(+ indexScope: string,+ recordScope: string,+ ): Promise<{ scanned: number; trimmed: number }> => {+ const allIds = [...new Set(await kv.list<string>(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;+ let scanned = 0;+ let trimmed = 0;+ for (const id of allIds.slice(offset, end)) {+ await withKeyedLock("graph:persist", async () => {+ const record = await kv.get<R>(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 = <R extends { sourceObservationIds: string[] }>(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<GraphNode>(KV.graphNameIndex, KV.graphNodes);+ result.nodesScanned = n.scanned;+ result.nodesTrimmed = n.trimmed;+ }+ if (scope === undefined || scope === "edges") {+ const e = await trimScope<GraphEdge>(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,@@ -772,7 +898,6 @@ export function registerGraphFunction(kv,nodes,edges,- obsIds,);await recordAudit(kv, "observe", "mem::graph-extract", obsIds, {@@ -1135,6 +1260,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.//diff --git a/src/functions/mesh.ts b/src/functions/mesh.tsindex 0dd7e957..444e5105 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<GraphNode>(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<GraphEdge>(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.tsindex 532c448a..d43b60f4 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/src/functions/temporal-graph.ts b/src/functions/temporal-graph.tsindex 18d13c1f..d79dd04f 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);}@@ -255,6 +255,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/src/index.ts b/src/index.tsindex 7134677d..5786de4c 100644--- a/src/index.ts+++ b/src/index.ts@@ -547,7 +547,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.tsindex f60e61fa..c10868aa 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";@@ -2027,6 +2027,47 @@ export function registerApiTriggers(config: { api_path: "/agentmemory/graph/reset", http_method: "POST" },});+ sdk.registerFunction("api::graph-compact",+ async (req: HttpRequest): Promise<Response> => {+ const authErr = checkAuth(req, secret);+ if (authErr) return authErr;+ const body = (req.body ?? {}) as Record<string, unknown>;+ 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 result = await sdk.trigger({+ function_id: "mem::graph-compact",+ payload: { scope, offset, limit },+ });+ 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) {+ 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" } };+ }+ },+ );+ 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<Response> => {const authErr = checkAuth(req, secret);diff --git a/src/types.ts b/src/types.tsindex 727a6c23..2c46ec4e 100644--- a/src/types.ts+++ b/src/types.ts@@ -656,6 +656,7 @@ export interface AuditEntry {| "slot_create"| "slot_delete"| "slot_reflect"+ | "graph_compact"| "audit_migrate"| "session_sweep";userId?: string;diff --git a/src/viewer/index.html b/src/viewer/index.htmlindex 50cbf48d..dd8c0949 100644--- a/src/viewer/index.html+++ b/src/viewer/index.html@@ -6715,6 +6715,7 @@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',+ graph_compact: 'Compacted graph provenance',session_sweep: 'Marked stale sessions abandoned'};diff --git a/test/export-import.test.ts b/test/export-import.test.tsindex d33aacb1..8dfe5fbb 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/graph-compact.test.ts b/test/graph-compact.test.tsnew file mode 100644index 00000000..b330376a--- /dev/null+++ b/test/graph-compact.test.ts@@ -0,0 +1,647 @@+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";++function mockKV(slowFirstNodeReadMs = 0) {+ const store = new Map<string, Map<string, unknown>>();+ const calls = { list: [] as string[], set: [] as string[] };+ let nodeReads = 0;+ return {+ calls,+ get: async <T>(scope: string, key: string): Promise<T | null> => {+ 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 <T>(scope: string, key: string, data: T): Promise<T> => {+ 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<void> => {+ store.get(scope)?.delete(key);+ },+ list: async <T>(scope: string): Promise<T[]> => {+ calls.list.push(scope);+ const entries = store.get(scope);+ return entries+ ? (Array.from(entries.values()).map((v) => structuredClone(v)) as T[])+ : [];+ },+ };+}+type KV = ReturnType<typeof mockKV>;++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<GraphNode>("mem:graph:nodes", id);+const edge = (kv: KV, id: string) => kv.get<GraphEdge>("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<string, Function>();+ 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<string, Function>();+ 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 });+ });+});++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 <T>(scope: string): Promise<T[]> => {+ const items = await list<T>(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<string, Function>();+ 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<GraphNode>("mem:graph:nodes");+ const edges = await kv.list<GraphEdge>("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<string, unknown> }>(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: {+ function_id: string;+ payload?: unknown;+ }) => Promise<unknown>,+ ) {+ const { registerApiTriggers } = await import("../src/triggers/api.js");+ const fns = new Map<string, Function>();+ 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<string, unknown>;+ }>;+ }++ 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 500 when compaction reports its own failure, without leaking the error", async () => {+ 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 () => {+ 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/);+ });+});diff --git a/test/graph-provenance-cap.test.ts b/test/graph-provenance-cap.test.tsnew file mode 100644index 00000000..8def25bf--- /dev/null+++ b/test/graph-provenance-cap.test.ts@@ -0,0 +1,331 @@+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";++function mockKV() {+ const store = new Map<string, Map<string, unknown>>();+ return {+ get: async <T>(scope: string, key: string): Promise<T | null> =>+ (store.get(scope)?.get(key) as T) ?? null,+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {+ if (!store.has(scope)) store.set(scope, new Map());+ store.get(scope)!.set(key, data);+ return data;+ },+ delete: async (scope: string, key: string): Promise<void> => {+ store.get(scope)?.delete(key);+ },+ list: async <T>(scope: string): Promise<T[]> => {+ 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<typeof mockKV>, name: string) {+ const all = await kv.list<GraphNode>("mem:graph:nodes");+ const hits = all.filter((n) => n.name === name);+ expect(hits.length).toBe(1);+ return hits[0]!;+}++async function onlyEdge(kv: ReturnType<typeof mockKV>) {+ const all = await kv.list<GraphEdge>("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"])], []);+ 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++) {+ 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<string, Function>();+ 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 = `<temporal_graph>+ <entities>+ <entity type="person" name="Alice"><property key="role">engineer</property></entity>+ </entities>+ <relationships></relationships>+</temporal_graph>`;+ 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),+ );+ });++ 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 = `<temporal_graph>+ <entities>+ <entity type="person" name="Alice"></entity>+ <entity type="project" name="Acme"></entity>+ </entities>+ <relationships>+ <relationship type="works_on" source="Alice" target="Acme" weight="0.9"></relationship>+ </relationships>+</temporal_graph>`;+ 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<GraphEdge>("mem:graph:edges");+ expect(edges).toHaveLength(2);+ for (const e of edges) {+ expect(e.sourceObservationIds).toEqual(+ batch.slice(-MAX_GRAPH_SOURCE_OBSERVATIONS),+ );+ }+ });+});diff --git a/test/mesh.test.ts b/test/mesh.test.tsindex e08db078..5c5ecfd6 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<GraphNode>("mem:graph:nodes", "gn_peer");+ const storedSmall = await kv.get<GraphNode>("mem:graph:nodes", "gn_small");+ const storedEdge = await kv.get<GraphEdge>("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.tsindex 5fc51fea..70969cfa 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));+ });+});