@agentmemory/agentmemory 0.9.25 → 0.9.27

package/dist/index.mjs

@@ -119,10 +119,12 @@ function detectProvider(env) {
 function loadConfig() {
 	const env = getMergedEnv();
 	const provider = detectProvider(env);
+	const restPort = parseInt(env["III_REST_PORT"] || "3111", 10) || 3111;
+	const streamsPort = parseInt(env["III_STREAM_PORT"] || env["III_STREAMS_PORT"] || "", 10) || restPort + 1;
 	return {
-		engineUrl: env["III_ENGINE_URL"] || "ws://localhost:49134",
-		restPort: parseInt(env["III_REST_PORT"] || "3111", 10) || 3111,
-		streamsPort: parseInt(env["III_STREAMS_PORT"] || "3112", 10) || 3112,
+		engineUrl: env["III_ENGINE_URL"] || `ws://localhost:${parseInt(env["III_ENGINE_PORT"] || "", 10) || restPort + 46023}`,
+		restPort,
+		streamsPort,
 		provider,
 		tokenBudget: safeParseInt(env["TOKEN_BUDGET"], 2e3),
 		maxObservationsPerSession: safeParseInt(env["MAX_OBS_PER_SESSION"], 500),
@@ -1326,6 +1328,10 @@ const KV = {
 	claudeBridge: "mem:claude-bridge",
 	graphNodes: "mem:graph:nodes",
 	graphEdges: "mem:graph:edges",
+	graphSnapshot: "mem:graph:snapshot",
+	graphNameIndex: "mem:graph:name-index",
+	graphEdgeKey: "mem:graph:edge-key",
+	graphNodeDegree: "mem:graph:node-degree",
 	semantic: "mem:semantic",
 	procedural: "mem:procedural",
 	teamShared: (teamId) => `mem:team:${teamId}:shared`,
@@ -2988,7 +2994,7 @@ var IndexPersistence = class {
 	async loadShardedData(legacyKey, manifestKey, label) {
 		const manifest = await this.readIndexValue(KV.bm25Index, manifestKey, label, "manifest");
 		if (!manifest.ok) return null;
-		if (manifest.value !== null) return this.loadManifestData(manifest.value, label);
+		if (manifest.value != null && typeof manifest.value === "object") return this.loadManifestData(manifest.value, label);
 		const legacy = await this.readIndexValue(KV.bm25Index, legacyKey, label, "legacy");
 		if (!legacy.ok) return null;
 		if (legacy.value && typeof legacy.value === "string") return legacy.value;
@@ -3482,6 +3488,12 @@ function registerSearchFunction(sdk, kv) {
 		}
 		const projectFilter = typeof data.project === "string" && data.project.trim().length > 0 ? data.project.trim() : void 0;
 		const cwdFilter = typeof data.cwd === "string" && data.cwd.trim().length > 0 ? data.cwd.trim() : void 0;
+		const isolated = isAgentScopeIsolated();
+		const explicitAgentId = typeof data.agentId === "string" && data.agentId.trim().length > 0 ? data.agentId.trim() : void 0;
+		const wildcardAgent = explicitAgentId === "*";
+		const envAgentId = isolated ? getAgentId() : void 0;
+		const filterAgentId = wildcardAgent ? void 0 : explicitAgentId ?? envAgentId;
+		if (isolated && !wildcardAgent && !explicitAgentId && !envAgentId) throw new Error("mem::search: AGENTMEMORY_AGENT_SCOPE=isolated is set but no agent id is available (env AGENT_ID unset and no explicit agentId in the call). Refusing to read cross-agent rows. Pass agentId: \"*\" to opt in to a wildcard read.");
 		const format = typeof data.format === "string" ? data.format : "full";
 		if (![
 			"full",
@@ -3497,7 +3509,7 @@ function registerSearchFunction(sdk, kv) {
 			const count = await rebuildIndex(kv);
 			logger.info("Search index rebuilt", { entries: count });
 		}
-		const filtering = !!(projectFilter || cwdFilter);
+		const filtering = !!(projectFilter || cwdFilter || filterAgentId);
 		const fetchLimit = filtering ? Math.max(effectiveLimit * 10, 100) : effectiveLimit;
 		const results = idx.search(query, fetchLimit);
 		const sessionCache = /* @__PURE__ */ new Map();
@@ -3514,9 +3526,10 @@ function registerSearchFunction(sdk, kv) {
 			memoryProjectCache.set(obsId, proj);
 			return proj;
 		};
+		const earlyCap = filterAgentId ? fetchLimit : effectiveLimit;
 		const candidates = [];
 		for (const r of results) {
-			if (candidates.length >= effectiveLimit) break;
+			if (candidates.length >= earlyCap) break;
 			if (filtering) {
 				const s = await loadSession(r.sessionId);
 				if (s) {
@@ -3538,7 +3551,10 @@ function registerSearchFunction(sdk, kv) {
 		const enriched = [];
 		for (let i = 0; i < candidates.length; i++) {
 			const obs = obsResults[i];
-			if (obs) enriched.push({
+			if (!obs) continue;
+			if (filterAgentId !== void 0 && obs.agentId !== filterAgentId) continue;
+			if (enriched.length >= effectiveLimit) break;
+			enriched.push({
 				observation: obs,
 				score: candidates[i].score,
 				sessionId: candidates[i].sessionId
@@ -6688,7 +6704,7 @@ async function findByKeyword(kv, keyword, project) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.9.25";
+const VERSION = "0.9.27";
 //#endregion
 //#region src/telemetry/setup.ts
 const OTEL_CONFIG = {
@@ -6763,7 +6779,10 @@ function registerSmartSearchFunction(sdk, kv, searchFn) {
 	sdk.registerFunction("mem::smart-search", async (data) => {
 		const isolated = isAgentScopeIsolated();
 		const explicitAgentId = typeof data.agentId === "string" && data.agentId.trim().length > 0 ? data.agentId.trim() : void 0;
-		const filterAgentId = explicitAgentId === "*" ? void 0 : explicitAgentId ?? (isolated ? getAgentId() : void 0);
+		const wildcardAgent = explicitAgentId === "*";
+		const envAgentId = isolated ? getAgentId() : void 0;
+		const filterAgentId = wildcardAgent ? void 0 : explicitAgentId ?? envAgentId;
+		if (isolated && !wildcardAgent && !explicitAgentId && !envAgentId) throw new Error("mem::smart-search: AGENTMEMORY_AGENT_SCOPE=isolated is set but no agent id is available (env AGENT_ID unset and no explicit agentId in the call). Refusing to read cross-agent rows. Pass agentId: \"*\" to opt in to a wildcard read.");
 		if (data.expandIds && data.expandIds.length > 0) {
 			const raw = data.expandIds.slice(0, 20);
 			const items = raw.map((entry) => {
@@ -7313,7 +7332,9 @@ function registerExportImportFunction(sdk, kv) {
 			"0.9.22",
 			"0.9.23",
 			"0.9.24",
-			"0.9.25"
+			"0.9.25",
+			"0.9.26",
+			"0.9.27"
 		]).has(importData.version)) return {
 			success: false,
 			error: `Unsupported export version: ${importData.version}`
@@ -7837,19 +7858,167 @@ function buildGraphExtractionPrompt(observations) {
 //#region src/functions/graph.ts
 const DEFAULT_GRAPH_QUERY_LIMIT = 500;
 const MAX_GRAPH_QUERY_LIMIT = 5e3;
-function resolvePagination(rawLimit, rawOffset) {
+const SNAPSHOT_TOP_NODES = DEFAULT_GRAPH_QUERY_LIMIT;
+const SNAPSHOT_KEY = "current";
+const LIVE_ENUMERATION_BUDGET_MS = 6e3;
+function withTimeout(p, ms, label) {
+	return new Promise((resolve, reject) => {
+		const t = setTimeout(() => reject(/* @__PURE__ */ new Error(`${label}: exceeded ${ms}ms budget`)), ms);
+		p.then((v) => {
+			clearTimeout(t);
+			resolve(v);
+		}, (err) => {
+			clearTimeout(t);
+			reject(err);
+		});
+	});
+}
+function emptySnapshot() {
 	return {
-		limit: Math.max(1, Math.min(typeof rawLimit === "number" && Number.isFinite(rawLimit) ? Math.floor(rawLimit) : DEFAULT_GRAPH_QUERY_LIMIT, MAX_GRAPH_QUERY_LIMIT)),
-		offset: Math.max(0, typeof rawOffset === "number" && Number.isFinite(rawOffset) ? Math.floor(rawOffset) : 0)
+		version: 1,
+		topNodes: [],
+		topEdges: [],
+		topDegrees: {},
+		stats: {
+			totalNodes: 0,
+			totalEdges: 0,
+			nodesByType: {},
+			edgesByType: {}
+		},
+		updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+		dirty: true
 	};
 }
-function rankByDegree(nodes, edges) {
+async function readSnapshot(kv) {
+	try {
+		const snap = await kv.get(KV.graphSnapshot, SNAPSHOT_KEY);
+		if (snap && typeof snap === "object" && snap.version === 1) return snap;
+		return null;
+	} catch (err) {
+		logger.warn("Graph snapshot read failed", { error: err instanceof Error ? err.message : String(err) });
+		return null;
+	}
+}
+function buildSnapshotFromArrays(nodes, edges) {
+	const liveNodes = nodes.filter((n) => !n.stale);
+	const liveEdges = edges.filter((e) => !e.stale);
 	const degree = /* @__PURE__ */ new Map();
-	for (const edge of edges) {
-		degree.set(edge.sourceNodeId, (degree.get(edge.sourceNodeId) ?? 0) + 1);
-		degree.set(edge.targetNodeId, (degree.get(edge.targetNodeId) ?? 0) + 1);
+	for (const e of liveEdges) {
+		degree.set(e.sourceNodeId, (degree.get(e.sourceNodeId) ?? 0) + 1);
+		degree.set(e.targetNodeId, (degree.get(e.targetNodeId) ?? 0) + 1);
+	}
+	const ranked = [...liveNodes].sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0)).slice(0, SNAPSHOT_TOP_NODES);
+	const rankedIds = new Set(ranked.map((n) => n.id));
+	const topEdges = liveEdges.filter((e) => rankedIds.has(e.sourceNodeId) && rankedIds.has(e.targetNodeId));
+	const topDegrees = {};
+	for (const n of ranked) topDegrees[n.id] = degree.get(n.id) ?? 0;
+	const nodesByType = {};
+	for (const n of liveNodes) nodesByType[n.type] = (nodesByType[n.type] || 0) + 1;
+	const edgesByType = {};
+	for (const e of liveEdges) edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
+	return {
+		version: 1,
+		topNodes: ranked,
+		topEdges,
+		topDegrees,
+		stats: {
+			totalNodes: liveNodes.length,
+			totalEdges: liveEdges.length,
+			nodesByType,
+			edgesByType
+		},
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		dirty: false
+	};
+}
+function paginateFromSnapshot(snap, filterType, limit, offset) {
+	const filteredNodes = filterType ? snap.topNodes.filter((n) => n.type === filterType) : snap.topNodes;
+	const total = filterType ? snap.stats.nodesByType[filterType] ?? 0 : snap.stats.totalNodes;
+	const pageNodes = filteredNodes.slice(offset, offset + limit);
+	const pageIds = new Set(pageNodes.map((n) => n.id));
+	return {
+		nodes: pageNodes,
+		edges: snap.topEdges.filter((e) => pageIds.has(e.sourceNodeId) && pageIds.has(e.targetNodeId)),
+		depth: 0,
+		totalNodes: total,
+		totalEdges: snap.stats.totalEdges,
+		truncated: total > pageNodes.length,
+		limit,
+		offset,
+		fromSnapshot: true
+	};
+}
+const REBUILD_SAFE_NODE_CEILING = 25e3;
+function nameIndexKey(type, name) {
+	return `${type}|${name}`;
+}
+function edgeIndexKey(sourceNodeId, targetNodeId, type) {
+	return `${sourceNodeId}|${targetNodeId}|${type}`;
+}
+async function applyDegreeDelta(kv, snap, nodeId, delta) {
+	const prev = await kv.get(KV.graphNodeDegree, nodeId) ?? 0;
+	const next = Math.max(0, prev + delta);
+	await kv.set(KV.graphNodeDegree, nodeId, next);
+	if (snap.topNodes.findIndex((n) => n.id === nodeId) !== -1) {
+		snap.topDegrees[nodeId] = next;
+		snap.topNodes.sort((a, b) => (snap.topDegrees[b.id] ?? 0) - (snap.topDegrees[a.id] ?? 0));
+		return next;
+	}
+	if (snap.topNodes.length < SNAPSHOT_TOP_NODES) {
+		const node = await kv.get(KV.graphNodes, nodeId);
+		if (node && !node.stale) {
+			snap.topNodes.push(node);
+			snap.topDegrees[node.id] = next;
+			snap.topNodes.sort((a, b) => (snap.topDegrees[b.id] ?? 0) - (snap.topDegrees[a.id] ?? 0));
+		}
+		return next;
+	}
+	const tailEntry = snap.topNodes[snap.topNodes.length - 1];
+	if (!tailEntry) return next;
+	if (next > (snap.topDegrees[tailEntry.id] ?? 0)) {
+		const node = await kv.get(KV.graphNodes, nodeId);
+		if (node && !node.stale) {
+			const evicted = snap.topNodes.pop();
+			if (evicted) delete snap.topDegrees[evicted.id];
+			snap.topNodes.push(node);
+			snap.topDegrees[node.id] = next;
+			snap.topNodes.sort((a, b) => (snap.topDegrees[b.id] ?? 0) - (snap.topDegrees[a.id] ?? 0));
+		}
+	}
+	return next;
+}
+function snapshotPushEdgeIfBothInTop(snap, edge) {
+	const topIds = new Set(snap.topNodes.map((n) => n.id));
+	if (topIds.has(edge.sourceNodeId) && topIds.has(edge.targetNodeId)) {
+		if (!snap.topEdges.find((e) => e.id === edge.id)) snap.topEdges.push(edge);
 	}
-	return [...nodes].sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0));
+}
+function mergeNode(existing, incoming, obsIds, capturedAt) {
+	return {
+		...existing,
+		sourceObservationIds: [...new Set([
+			...existing.sourceObservationIds,
+			...incoming.sourceObservationIds,
+			...obsIds
+		])],
+		properties: {
+			...existing.properties,
+			...incoming.properties
+		},
+		updatedAt: capturedAt
+	};
+}
+function mergeEdge(existing, obsIds) {
+	return {
+		...existing,
+		sourceObservationIds: [...new Set([...existing.sourceObservationIds, ...obsIds])]
+	};
+}
+function resolvePagination(rawLimit, rawOffset) {
+	return {
+		limit: Math.max(1, Math.min(typeof rawLimit === "number" && Number.isFinite(rawLimit) ? Math.floor(rawLimit) : DEFAULT_GRAPH_QUERY_LIMIT, MAX_GRAPH_QUERY_LIMIT)),
+		offset: Math.max(0, typeof rawOffset === "number" && Number.isFinite(rawOffset) ? Math.floor(rawOffset) : 0)
+	};
 }
 function paginate(nodes, allEdges, depth, limit, offset) {
 	const totalNodes = nodes.length;
@@ -7946,45 +8115,76 @@ function registerGraphFunction(sdk, kv, provider) {
 			const response = await provider.compress(GRAPH_EXTRACTION_SYSTEM, prompt);
 			const obsIds = data.observations.map((o) => o.id);
 			const { nodes, edges } = parseGraphXml(response, obsIds);
-			const existingNodes = await kv.list(KV.graphNodes);
-			const existingEdges = await kv.list(KV.graphEdges);
+			const snap = await readSnapshot(kv) ?? emptySnapshot();
+			const capturedAt = (/* @__PURE__ */ new Date()).toISOString();
+			let newNodeCount = 0;
+			let newEdgeCount = 0;
+			const newEdgesForTopCheck = [];
 			for (const node of nodes) {
-				const existing = existingNodes.find((n) => n.name === node.name && n.type === node.type);
+				const indexKey = nameIndexKey(node.type, node.name);
+				const existingId = await kv.get(KV.graphNameIndex, indexKey);
+				let existing = null;
+				if (existingId) {
+					existing = await kv.get(KV.graphNodes, existingId);
+					if (existing && snap.resetAt && typeof existing.createdAt === "string" && existing.createdAt < snap.resetAt) existing = null;
+				}
 				if (existing) {
-					const merged = {
-						...existing,
-						sourceObservationIds: [...new Set([...existing.sourceObservationIds, ...obsIds])],
-						properties: {
-							...existing.properties,
-							...node.properties
-						}
-					};
+					const merged = mergeNode(existing, node, obsIds, capturedAt);
 					await kv.set(KV.graphNodes, existing.id, merged);
-					const idx = existingNodes.findIndex((n) => n.id === existing.id);
-					if (idx !== -1) existingNodes[idx] = merged;
+					const topIdx = snap.topNodes.findIndex((n) => n.id === existing.id);
+					if (topIdx !== -1) snap.topNodes[topIdx] = merged;
 				} else {
 					await kv.set(KV.graphNodes, node.id, node);
-					existingNodes.push(node);
+					await kv.set(KV.graphNameIndex, indexKey, node.id);
+					await kv.set(KV.graphNodeDegree, node.id, 0);
+					snap.stats.totalNodes += 1;
+					snap.stats.nodesByType[node.type] = (snap.stats.nodesByType[node.type] ?? 0) + 1;
+					newNodeCount += 1;
+					if (snap.topNodes.length < SNAPSHOT_TOP_NODES) {
+						snap.topNodes.push(node);
+						snap.topDegrees[node.id] = 0;
+					}
 				}
 			}
 			for (const edge of edges) {
-				const edgeKey = `${edge.sourceNodeId}|${edge.targetNodeId}|${edge.type}`;
-				const existingEdge = existingEdges.find((e) => `${e.sourceNodeId}|${e.targetNodeId}|${e.type}` === edgeKey);
-				if (existingEdge) {
-					existingEdge.sourceObservationIds = [...new Set([...existingEdge.sourceObservationIds, ...obsIds])];
-					await kv.set(KV.graphEdges, existingEdge.id, existingEdge);
+				const eKey = edgeIndexKey(edge.sourceNodeId, edge.targetNodeId, edge.type);
+				const existingId = await kv.get(KV.graphEdgeKey, eKey);
+				let existing = null;
+				if (existingId) {
+					existing = await kv.get(KV.graphEdges, existingId);
+					if (existing && snap.resetAt && typeof existing.createdAt === "string" && existing.createdAt < snap.resetAt) existing = null;
+				}
+				if (existing) {
+					const merged = mergeEdge(existing, obsIds);
+					await kv.set(KV.graphEdges, existing.id, merged);
+					const topIdx = snap.topEdges.findIndex((e) => e.id === existing.id);
+					if (topIdx !== -1) snap.topEdges[topIdx] = merged;
 				} else {
 					await kv.set(KV.graphEdges, edge.id, edge);
-					existingEdges.push(edge);
+					await kv.set(KV.graphEdgeKey, eKey, edge.id);
+					snap.stats.totalEdges += 1;
+					snap.stats.edgesByType[edge.type] = (snap.stats.edgesByType[edge.type] ?? 0) + 1;
+					newEdgeCount += 1;
+					await applyDegreeDelta(kv, snap, edge.sourceNodeId, 1);
+					await applyDegreeDelta(kv, snap, edge.targetNodeId, 1);
+					newEdgesForTopCheck.push(edge);
 				}
 			}
+			for (const edge of newEdgesForTopCheck) snapshotPushEdgeIfBothInTop(snap, edge);
+			if (newNodeCount > 0 || newEdgeCount > 0) {
+				snap.updatedAt = capturedAt;
+				snap.dirty = false;
+				await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, snap);
+			}
 			await recordAudit(kv, "observe", "mem::graph-extract", obsIds, {
 				nodesExtracted: nodes.length,
 				edgesExtracted: edges.length
 			});
 			logger.info("Graph extraction complete", {
 				nodes: nodes.length,
-				edges: edges.length
+				edges: edges.length,
+				newNodes: newNodeCount,
+				newEdges: newEdgeCount
 			});
 			return {
 				success: true,
@@ -8001,10 +8201,49 @@ function registerGraphFunction(sdk, kv, provider) {
 		}
 	});
 	sdk.registerFunction("mem::graph-query", async (data) => {
-		const allNodes = (await kv.list(KV.graphNodes)).filter((n) => !n.stale);
-		const allEdges = (await kv.list(KV.graphEdges)).filter((e) => !e.stale);
 		const maxDepth = Math.min(data.maxDepth || 3, 5);
 		const { limit, offset } = resolvePagination(data.limit, data.offset);
+		if (!data.query && !data.startNodeId) {
+			const snap = await readSnapshot(kv);
+			if (snap && snap.stats.totalNodes > 0) return paginateFromSnapshot(snap, data.nodeType, limit, offset);
+			return {
+				nodes: [],
+				edges: [],
+				depth: 0,
+				totalNodes: 0,
+				totalEdges: 0,
+				truncated: false,
+				limit,
+				offset,
+				warning: "No graph snapshot available. Either no graph has been extracted yet, or you are on a legacy corpus from a pre-#814 agentmemory build. Run POST /agentmemory/graph/snapshot-rebuild (safe up to ~25K nodes) or POST /agentmemory/graph/reset to wipe and let future extracts repopulate."
+			};
+		}
+		let allNodes;
+		let allEdges;
+		try {
+			const [rawNodes, rawEdges] = await withTimeout(Promise.all([kv.list(KV.graphNodes), kv.list(KV.graphEdges)]), LIVE_ENUMERATION_BUDGET_MS, "graph-query enumeration");
+			allNodes = rawNodes.filter((n) => !n.stale);
+			allEdges = rawEdges.filter((e) => !e.stale);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			logger.warn("Graph query enumeration timed out, using snapshot", { error: msg });
+			const snap = await readSnapshot(kv);
+			if (snap) return {
+				...paginateFromSnapshot(snap, data.nodeType, limit, offset),
+				warning: "Live graph enumeration exceeded budget. Query / startNodeId paths degrade on >25K-node corpora until a per-node edge index lands. Result reflects top-degree snapshot, not the requested walk."
+			};
+			return {
+				nodes: [],
+				edges: [],
+				depth: 0,
+				totalNodes: 0,
+				totalEdges: 0,
+				truncated: false,
+				limit,
+				offset,
+				warning: "Graph enumeration exceeded budget and no snapshot is available."
+			};
+		}
 		if (data.query) {
 			const lower = data.query.toLowerCase();
 			return paginate(allNodes.filter((n) => n.name.toLowerCase().includes(lower) || Object.values(n.properties).some((v) => typeof v === "string" && v.toLowerCase().includes(lower))), allEdges, 0, limit, offset);
@@ -8041,22 +8280,116 @@ function registerGraphFunction(sdk, kv, provider) {
 			}
 			return paginate(resultNodes, resultEdges, maxDepth, limit, offset);
 		}
-		let filtered = allNodes;
-		if (data.nodeType) filtered = allNodes.filter((n) => n.type === data.nodeType);
-		return paginate(rankByDegree(filtered, allEdges), allEdges, 0, limit, offset);
+		return paginate([], [], 0, limit, offset);
 	});
 	sdk.registerFunction("mem::graph-stats", async () => {
-		const nodes = await kv.list(KV.graphNodes);
-		const edges = await kv.list(KV.graphEdges);
-		const nodesByType = {};
-		for (const n of nodes) nodesByType[n.type] = (nodesByType[n.type] || 0) + 1;
-		const edgesByType = {};
-		for (const e of edges) edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
+		const snap = await readSnapshot(kv);
+		if (snap) return {
+			...snap.stats,
+			fromSnapshot: true,
+			updatedAt: snap.updatedAt,
+			...snap.dirty ? { warning: "Snapshot is marked dirty (write was in-flight when read). Counts are eventually consistent." } : {}
+		};
 		return {
-			totalNodes: nodes.length,
-			totalEdges: edges.length,
-			nodesByType,
-			edgesByType
+			totalNodes: 0,
+			totalEdges: 0,
+			nodesByType: {},
+			edgesByType: {},
+			fromSnapshot: false,
+			warning: "No graph snapshot available. Run POST /agentmemory/graph/snapshot-rebuild (safe up to ~25K nodes) or POST /agentmemory/graph/reset to wipe and let future extracts repopulate."
+		};
+	});
+	sdk.registerFunction("mem::graph-snapshot-rebuild", async (data) => {
+		const started = Date.now();
+		const forceRebuild = data?.force === true;
+		try {
+			if (!await readSnapshot(kv) && !forceRebuild) {
+				logger.warn("Graph snapshot rebuild refused: no prior snapshot", { hint: "legacy corpus or empty store" });
+				return {
+					success: false,
+					legacyCorpus: true,
+					error: "No prior snapshot found. Rebuild would call kv.list on KV.graphNodes/Edges, which heartbeat-crashes the worker on corpora past the iii state response budget (~25K nodes). Either (a) call POST /agentmemory/graph/reset to drop into incremental-only mode and rebuild from new extracts, or (b) re-send with `force: true` if you're certain the corpus is small."
+				};
+			}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			logger.warn("Graph snapshot pre-flight read failed", { error: msg });
+		}
+		try {
+			const [nodes, edges] = await withTimeout(Promise.all([kv.list(KV.graphNodes), kv.list(KV.graphEdges)]), LIVE_ENUMERATION_BUDGET_MS, "graph-snapshot-rebuild enumeration");
+			if (nodes.length > REBUILD_SAFE_NODE_CEILING) {
+				logger.warn("Graph snapshot rebuild aborted: corpus too large", {
+					totalNodes: nodes.length,
+					ceiling: REBUILD_SAFE_NODE_CEILING
+				});
+				return {
+					success: false,
+					tooLarge: true,
+					totalNodes: nodes.length,
+					ceiling: REBUILD_SAFE_NODE_CEILING,
+					error: `Corpus has ${nodes.length} graph nodes; safe-rebuild ceiling is ${REBUILD_SAFE_NODE_CEILING}. Run POST /agentmemory/graph/reset to wipe and let future extracts rebuild incrementally.`
+				};
+			}
+			const liveNodes = nodes.filter((n) => !n.stale);
+			const liveEdges = edges.filter((e) => !e.stale);
+			const degree = /* @__PURE__ */ new Map();
+			for (const e of liveEdges) {
+				degree.set(e.sourceNodeId, (degree.get(e.sourceNodeId) ?? 0) + 1);
+				degree.set(e.targetNodeId, (degree.get(e.targetNodeId) ?? 0) + 1);
+			}
+			const BATCH_SIZE = 100;
+			for (let i = 0; i < liveNodes.length; i += BATCH_SIZE) {
+				const batch = liveNodes.slice(i, i + BATCH_SIZE);
+				await Promise.all(batch.flatMap((n) => [kv.set(KV.graphNameIndex, nameIndexKey(n.type, n.name), n.id), kv.set(KV.graphNodeDegree, n.id, degree.get(n.id) ?? 0)]));
+			}
+			for (let i = 0; i < liveEdges.length; i += BATCH_SIZE) {
+				const batch = liveEdges.slice(i, i + BATCH_SIZE);
+				await Promise.all(batch.map((e) => kv.set(KV.graphEdgeKey, edgeIndexKey(e.sourceNodeId, e.targetNodeId, e.type), e.id)));
+			}
+			const snap = buildSnapshotFromArrays(nodes, edges);
+			await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, snap);
+			const tookMs = Date.now() - started;
+			logger.info("Graph snapshot rebuilt", {
+				totalNodes: snap.stats.totalNodes,
+				totalEdges: snap.stats.totalEdges,
+				topNodes: snap.topNodes.length,
+				topEdges: snap.topEdges.length,
+				tookMs
+			});
+			return {
+				success: true,
+				...snap.stats,
+				topNodes: snap.topNodes.length,
+				topEdges: snap.topEdges.length,
+				updatedAt: snap.updatedAt,
+				tookMs
+			};
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			logger.error("Graph snapshot rebuild failed", { error: msg });
+			return {
+				success: false,
+				error: msg
+			};
+		}
+	});
+	sdk.registerFunction("mem::graph-reset", async () => {
+		const started = Date.now();
+		const resetSnapshot = {
+			...emptySnapshot(),
+			resetAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await kv.set(KV.graphSnapshot, SNAPSHOT_KEY, resetSnapshot);
+		const counts = { [KV.graphSnapshot]: 1 };
+		const tookMs = Date.now() - started;
+		logger.info("Graph state reset", {
+			counts,
+			tookMs
+		});
+		return {
+			success: true,
+			cleared: counts,
+			tookMs
 		};
 	});
 }
@@ -15371,6 +15704,7 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	});
 	sdk.registerFunction("api::search", async (req) => {
 		const body = req.body ?? {};
+		const queryAgentId = typeof req.query_params?.["agentId"] === "string" ? req.query_params["agentId"] : void 0;
 		if (typeof body.query !== "string" || !body.query.trim()) return {
 			status_code: 400,
 			body: { error: "query is required and must be a non-empty string" }
@@ -15399,13 +15733,15 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			status_code: 400,
 			body: { error: "token_budget must be a positive integer" }
 		};
+		const bodyAgentId = typeof body.agentId === "string" && body.agentId.trim().length > 0 ? body.agentId.trim() : void 0;
 		const payload = {
 			query: body.query.trim(),
 			limit: body.limit,
 			project: body.project,
 			cwd: body.cwd,
 			format: typeof body.format === "string" ? body.format.trim().toLowerCase() : void 0,
-			token_budget: body.token_budget
+			token_budget: body.token_budget,
+			agentId: bodyAgentId ?? queryAgentId
 		};
 		return {
 			status_code: 200,
@@ -16341,6 +16677,52 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			http_method: "GET"
 		}
 	});
+	sdk.registerFunction("api::graph-snapshot-rebuild", async (req) => {
+		const authErr = checkAuth(req, secret);
+		if (authErr) return authErr;
+		try {
+			return {
+				status_code: 200,
+				body: await sdk.trigger({
+					function_id: "mem::graph-snapshot-rebuild",
+					payload: {}
+				})
+			};
+		} catch {
+			return graphDisabledResponse();
+		}
+	});
+	sdk.registerTrigger({
+		type: "http",
+		function_id: "api::graph-snapshot-rebuild",
+		config: {
+			api_path: "/agentmemory/graph/snapshot-rebuild",
+			http_method: "POST"
+		}
+	});
+	sdk.registerFunction("api::graph-reset", async (req) => {
+		const authErr = checkAuth(req, secret);
+		if (authErr) return authErr;
+		try {
+			return {
+				status_code: 200,
+				body: await sdk.trigger({
+					function_id: "mem::graph-reset",
+					payload: {}
+				})
+			};
+		} catch {
+			return graphDisabledResponse();
+		}
+	});
+	sdk.registerTrigger({
+		type: "http",
+		function_id: "api::graph-reset",
+		config: {
+			api_path: "/agentmemory/graph/reset",
+			http_method: "POST"
+		}
+	});
 	sdk.registerFunction("api::graph-extract", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
@@ -19884,13 +20266,15 @@ function registerMcpEndpoints(sdk, kv, secret) {
 						status_code: 400,
 						body: { error: "token_budget must be a positive integer" }
 					};
+					const recallAgentId = typeof args.agentId === "string" && args.agentId.trim().length > 0 ? args.agentId.trim() : void 0;
 					const result = await sdk.trigger({
 						function_id: "mem::search",
 						payload: {
 							query: args.query,
 							limit: typeof args.limit === "number" ? args.limit : 10,
 							format,
-							token_budget: tokenBudget
+							token_budget: tokenBudget,
+							agentId: recallAgentId
 						}
 					});
 					return {
@@ -21378,7 +21762,10 @@ function registerMcpEndpoints(sdk, kv, secret) {
 							limit: 10
 						}
 					}).catch(() => ({ results: [] }));
-					const relevant = (await kv.list(KV.memories)).filter((m) => m.isLatest).slice(0, 5);
+					const memories = await kv.list(KV.memories);
+					const isolated = isAgentScopeIsolated();
+					const activeAgentId = isolated ? getAgentId() : void 0;
+					const relevant = isolated && activeAgentId === void 0 ? [] : memories.filter((m) => m.isLatest).filter((m) => activeAgentId === void 0 || m.agentId === activeAgentId).slice(0, 5);
 					return {
 						status_code: 200,
 						body: { messages: [{
@@ -21749,7 +22136,7 @@ async function main() {
 		console.warn(`[agentmemory] Failed to backfill memories into BM25:`, err);
 	}
 	bootLog(`Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`);
-	bootLog(`REST API: 126 endpoints at http://localhost:${config.restPort}/agentmemory/*`);
+	bootLog(`REST API: 128 endpoints at http://localhost:${config.restPort}/agentmemory/*`);
 	bootLog(`MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`);
 	const viewerServer = startViewerServer(config.restPort + 2, kv, sdk, secret, config.restPort);
 	const autoForgetIntervalMs = parseInt(process.env.AUTO_FORGET_INTERVAL_MS || "3600000", 10);