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..41cbda22c5 100644
--- a/README.md
+++ b/README.md
@@ -1671,7 +1671,7 @@ Create `~/.agentmemory/.env`:
-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
@@ -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"}'
+```
+
---
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/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-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 68e78117dc..cf551727c7 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(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 {
+ 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")
+ .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(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,
@@ -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.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/src/functions/temporal-graph.ts b/src/functions/temporal-graph.ts
index 18d13c1fe5..d79dd04f20 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.ts
index 1025bf9d11..9087ac95f9 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -543,7 +543,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 f60e61faf7..c10868aab6 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 => {
+ const authErr = checkAuth(req, secret);
+ 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 (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 => {
const authErr = checkAuth(req, secret);
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 @@