@agentmemory/agentmemory 0.9.21 → 0.9.22

package/dist/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { TriggerAction, registerWorker } from "iii-sdk";
-import { constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { constants, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import Anthropic from "@anthropic-ai/sdk";
@@ -40,6 +40,7 @@ function safeParseInt(value, fallback) {
 }
 const DATA_DIR = join(homedir(), ".agentmemory");
 const ENV_FILE = join(DATA_DIR, ".env");
+let warnPremiumModelShown = false;
 function loadEnvFile() {
 	if (!existsSync(ENV_FILE)) return {};
 	const content = readFileSync(ENV_FILE, "utf-8");
@@ -93,11 +94,18 @@ function detectProvider(env) {
 			maxTokens
 		};
 	}
-	if (hasRealValue(env["OPENROUTER_API_KEY"])) return {
-		provider: "openrouter",
-		model: env["OPENROUTER_MODEL"] || "anthropic/claude-sonnet-4-20250514",
-		maxTokens
-	};
+	if (hasRealValue(env["OPENROUTER_API_KEY"])) {
+		const model = env["OPENROUTER_MODEL"] || "anthropic/claude-sonnet-4-20250514";
+		if (!warnPremiumModelShown && /sonnet|opus|gpt-4o(?!.*mini)|gpt-4-turbo/i.test(model) && env["AGENTMEMORY_SUPPRESS_COST_WARNING"] !== "1" && env["AGENTMEMORY_SUPPRESS_COST_WARNING"] !== "true") {
+			warnPremiumModelShown = true;
+			process.stderr.write(`[agentmemory] OPENROUTER_MODEL=${model} is in the premium tier. Background compression on this model can cost $5+/day under active use. Cheaper alternatives with comparable quality for memory compression: deepseek/deepseek-v4-pro, deepseek/deepseek-chat, qwen/qwen3-coder. See README "Cost-aware model selection" for the full table. Set AGENTMEMORY_SUPPRESS_COST_WARNING=1 to silence.\n`);
+		}
+		return {
+			provider: "openrouter",
+			model,
+			maxTokens
+		};
+	}
 	if (!(env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true")) {
 		process.stderr.write("[agentmemory] No LLM provider key found (ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, MINIMAX_API_KEY, OPENAI_API_KEY). LLM-backed compression and summarization are DISABLED — using no-op provider. This is the safe default: the agent-sdk fallback used to spawn Claude Agent SDK child sessions which inherit Claude Code's plugin hooks and cause infinite Stop-hook recursion (#149 follow-up). To opt in to the agent-sdk fallback anyway, set both AGENTMEMORY_AUTO_COMPRESS=true AND AGENTMEMORY_ALLOW_AGENT_SDK=true — but be aware it will burn your Claude Pro allocation and may still recurse if you use it from inside Claude Code itself.\n");
 		return {
@@ -175,8 +183,8 @@ function loadClaudeBridgeConfig() {
 	const lineBudget = safeParseInt(env["CLAUDE_MEMORY_LINE_BUDGET"], 200);
 	let memoryFilePath = "";
 	if (enabled && projectPath) {
-		const safePath = projectPath.replace(/[/\\]/g, "-").replace(/^-/, "");
-		memoryFilePath = join(homedir(), ".claude", "projects", safePath, "memory", "MEMORY.md");
+		const safePath = projectPath.replace(/[/\\]/g, "-");
+		memoryFilePath = join(homedir(), ".claude", "projects", safePath, "MEMORY.md");
 	}
 	return {
 		enabled,
@@ -196,6 +204,23 @@ function loadTeamConfig() {
 		mode: env["TEAM_MODE"] === "shared" ? "shared" : "private"
 	};
 }
+function loadAgentScope() {
+	const env = getMergedEnv();
+	const raw = env["AGENT_ID"];
+	if (!raw) return null;
+	const agentId = raw.trim().slice(0, 128);
+	if (!agentId) return null;
+	return {
+		agentId,
+		mode: env["AGENTMEMORY_AGENT_SCOPE"] === "isolated" ? "isolated" : "shared"
+	};
+}
+function getAgentId() {
+	return loadAgentScope()?.agentId;
+}
+function isAgentScopeIsolated() {
+	return loadAgentScope()?.mode === "isolated";
+}
 function loadSnapshotConfig() {
 	const env = getMergedEnv();
 	return {
@@ -453,13 +478,25 @@ function v1AzureUrl(baseUrl, path) {
 	url.pathname = `${url.pathname.replace(/\/?openai(?:\/v1)?\/?$/, "").replace(/\/+$/, "")}/openai/v1/${route}`;
 	return url.toString();
 }
+function appendOpenAIRoute(baseUrl, route) {
+	const trimmedBase = baseUrl.replace(/\/+$/, "");
+	const cleanRoute = route.startsWith("/") ? route : `/${route}`;
+	let pathname;
+	try {
+		pathname = new URL(trimmedBase).pathname.replace(/\/+$/, "");
+	} catch {
+		return `${trimmedBase}/v1${cleanRoute}`;
+	}
+	if (pathname === "" || pathname === "/") return `${trimmedBase}/v1${cleanRoute}`;
+	return `${trimmedBase}${cleanRoute}`;
+}
 function buildChatUrl(baseUrl, isAzure, azureApiVersion) {
 	if (isAzure) return azureStyleOf(baseUrl) === "legacy" ? legacyAzureUrl(baseUrl, "/chat/completions", azureApiVersion) : v1AzureUrl(baseUrl, "/chat/completions");
-	return `${baseUrl}/v1/chat/completions`;
+	return appendOpenAIRoute(baseUrl, "/chat/completions");
 }
 function buildEmbeddingUrl(baseUrl, isAzure, azureApiVersion) {
 	if (isAzure) return azureStyleOf(baseUrl) === "legacy" ? legacyAzureUrl(baseUrl, "/embeddings", azureApiVersion) : v1AzureUrl(baseUrl, "/embeddings");
-	return `${baseUrl}/v1/embeddings`;
+	return appendOpenAIRoute(baseUrl, "/embeddings");
 }
 function buildAuthHeaders(apiKey, isAzure) {
 	if (isAzure) return {
@@ -541,6 +578,7 @@ var OpenAIProvider = class {
 		const body = {
 			model: this.model,
 			max_tokens: this.maxTokens,
+			stream: false,
 			messages: [{
 				role: "system",
 				content: systemPrompt
@@ -569,7 +607,7 @@ var OpenAIProvider = class {
 		const message = data.choices?.[0]?.message;
 		const content = message?.content;
 		if (content) return content;
-		const reasoning = message?.reasoning;
+		const reasoning = message?.reasoning ?? message?.reasoning_content;
 		if (reasoning) return reasoning;
 		throw new Error(`OpenAI returned unexpected response: ${JSON.stringify(data).slice(0, 200)}`);
 	}
@@ -2514,6 +2552,24 @@ var SearchIndex = class SearchIndex {
 	has(id) {
 		return this.entries.has(id);
 	}
+	remove(id) {
+		const entry = this.entries.get(id);
+		if (!entry) return;
+		const termFreq = this.docTermCounts.get(id);
+		if (termFreq) {
+			for (const term of termFreq.keys()) {
+				const postingList = this.invertedIndex.get(term);
+				if (postingList) {
+					postingList.delete(id);
+					if (postingList.size === 0) this.invertedIndex.delete(term);
+				}
+			}
+			this.docTermCounts.delete(id);
+		}
+		this.totalDocLength = Math.max(0, this.totalDocLength - entry.termCount);
+		this.entries.delete(id);
+		this.sortedTerms = null;
+	}
 	search(query, limit = 20) {
 		const rawTerms = this.tokenize(query.toLowerCase());
 		if (rawTerms.length === 0) return [];
@@ -2866,6 +2922,7 @@ function buildSyntheticCompression(raw) {
 	};
 	if (raw.modality) result.modality = raw.modality;
 	if (raw.imageData) result.imageData = raw.imageData;
+	if (raw.agentId) result.agentId = raw.agentId;
 	return result;
 }
 
@@ -2955,6 +3012,16 @@ function setVectorIndex(idx) {
 function setEmbeddingProvider(provider) {
 	currentEmbeddingProvider = provider;
 }
+function vectorIndexRemove(id) {
+	vectorIndex?.remove(id);
+}
+let indexPersistence = null;
+function setIndexPersistence(p) {
+	indexPersistence = p;
+}
+async function flushIndexSave() {
+	await indexPersistence?.save();
+}
 const EMBED_MAX_CHARS = 16e3;
 function clipEmbedInput(text) {
 	if (text.length <= EMBED_MAX_CHARS) return text;
@@ -3349,6 +3416,9 @@ function registerObserveFunction(sdk, kv, dedupMap, maxObservationsPerSession) {
 					error: `Session observation limit reached (${maxObservationsPerSession})`
 				};
 			}
+			const existingSession = await kv.get(KV.sessions, payload.sessionId);
+			const inheritedAgentId = existingSession ? existingSession.agentId : getAgentId();
+			if (inheritedAgentId) raw.agentId = inheritedAgentId;
 			if (pendingImageData && (pendingImageData.startsWith("data:image/") || pendingImageData.startsWith("iVBORw0KGgo") || pendingImageData.startsWith("/9j/"))) {
 				const { saveImageToDisk } = await Promise.resolve().then(() => image_store_exports);
 				const { filePath, bytesWritten } = await saveImageToDisk(pendingImageData);
@@ -3400,7 +3470,7 @@ function registerObserveFunction(sdk, kv, dedupMap, maxObservationsPerSession) {
 				},
 				action: TriggerAction.Void()
 			});
-			const session = await kv.get(KV.sessions, payload.sessionId);
+			const session = existingSession;
 			if (session) {
 				const updates = [{
 					type: "set",
@@ -3420,6 +3490,20 @@ function registerObserveFunction(sdk, kv, dedupMap, maxObservationsPerSession) {
 					});
 				}
 				await kv.update(KV.sessions, payload.sessionId, updates);
+			} else if (typeof payload.project === "string" && payload.project.trim().length > 0 && typeof payload.cwd === "string" && payload.cwd.trim().length > 0) {
+				const trimmedPrompt = typeof raw.userPrompt === "string" ? raw.userPrompt.replace(/\s+/g, " ").trim().slice(0, 200) : void 0;
+				const ts = (/* @__PURE__ */ new Date()).toISOString();
+				await kv.set(KV.sessions, payload.sessionId, {
+					id: payload.sessionId,
+					project: payload.project,
+					cwd: payload.cwd,
+					startedAt: payload.timestamp ?? ts,
+					updatedAt: ts,
+					status: "active",
+					observationCount: 1,
+					...inheritedAgentId ? { agentId: inheritedAgentId } : {},
+					...trimmedPrompt && trimmedPrompt.length > 0 ? { firstPrompt: trimmedPrompt } : {}
+				});
 			}
 			if (isAutoCompressEnabled()) await sdk.trigger({
 				function_id: "mem::compress",
@@ -4679,7 +4763,8 @@ function registerCompressFunction(sdk, kv, provider, metricsStore) {
 				confidence: qualityScore / 100,
 				...hasImage ? { modality: data.raw.modality } : {},
 				...imageDescription ? { imageDescription } : {},
-				...data.raw.imageData ? { imageRef: data.raw.imageData } : {}
+				...data.raw.imageData ? { imageRef: data.raw.imageData } : {},
+				...data.raw.agentId ? { agentId: data.raw.agentId } : {}
 			};
 			await kv.set(KV.observations(data.sessionId), data.observationId, compressed);
 			try {
@@ -5650,6 +5735,7 @@ function registerRememberFunction(sdk, kv) {
 					break;
 				}
 			}
+			const callAgentId = typeof data.agentId === "string" && data.agentId.trim().length > 0 ? data.agentId.trim().slice(0, 128) : getAgentId();
 			const memory = {
 				id: generateId("mem"),
 				createdAt: now,
@@ -5665,7 +5751,8 @@ function registerRememberFunction(sdk, kv) {
 				parentId: supersededId,
 				supersedes: supersededId ? [supersededId] : [],
 				sourceObservationIds: (data.sourceObservationIds || []).filter((id) => typeof id === "string" && id.length > 0),
-				isLatest: true
+				isLatest: true,
+				...callAgentId ? { agentId: callAgentId } : {}
 			};
 			if (data.ttlDays && typeof data.ttlDays === "number" && data.ttlDays > 0) memory.forgetAfter = new Date(Date.now() + data.ttlDays * 864e5).toISOString();
 			if (supersededMemory) {
@@ -5711,6 +5798,8 @@ function registerRememberFunction(sdk, kv) {
 			await kv.delete(KV.memories, data.memoryId);
 			if (mem?.imageRef) await decrementImageRef(kv, sdk, mem.imageRef);
 			await deleteAccessLog(kv, data.memoryId);
+			getSearchIndex().remove(data.memoryId);
+			vectorIndexRemove(data.memoryId);
 			deletedMemoryIds.push(data.memoryId);
 			deleted++;
 		}
@@ -5719,6 +5808,8 @@ function registerRememberFunction(sdk, kv) {
 			await kv.delete(KV.observations(data.sessionId), obsId);
 			if (obs?.imageData) await decrementImageRef(kv, sdk, obs.imageData);
 			if (obs?.imageRef && obs.imageRef !== obs.imageData) await decrementImageRef(kv, sdk, obs.imageRef);
+			getSearchIndex().remove(obsId);
+			vectorIndexRemove(obsId);
 			deletedObservationIds.push(obsId);
 			deleted++;
 		}
@@ -5728,6 +5819,8 @@ function registerRememberFunction(sdk, kv) {
 				await kv.delete(KV.observations(data.sessionId), obs.id);
 				if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData);
 				if (obs.imageRef && obs.imageRef !== obs.imageData) await decrementImageRef(kv, sdk, obs.imageRef);
+				getSearchIndex().remove(obs.id);
+				vectorIndexRemove(obs.id);
 				deletedObservationIds.push(obs.id);
 				deleted++;
 			}
@@ -5736,14 +5829,17 @@ function registerRememberFunction(sdk, kv) {
 			deletedSession = true;
 			deleted += 2;
 		}
-		if (deleted > 0) await recordAudit(kv, "forget", "mem::forget", [...deletedMemoryIds, ...deletedObservationIds], {
-			sessionId: data.sessionId,
-			deleted,
-			memoriesDeleted: deletedMemoryIds.length,
-			observationsDeleted: deletedObservationIds.length,
-			sessionDeleted: deletedSession,
-			reason: "user-initiated forget"
-		});
+		if (deleted > 0) {
+			await flushIndexSave();
+			await recordAudit(kv, "forget", "mem::forget", [...deletedMemoryIds, ...deletedObservationIds], {
+				sessionId: data.sessionId,
+				deleted,
+				memoriesDeleted: deletedMemoryIds.length,
+				observationsDeleted: deletedObservationIds.length,
+				sessionDeleted: deletedSession,
+				reason: "user-initiated forget"
+			});
+		}
 		logger.info("Memory forgotten", { deleted });
 		return {
 			success: true,
@@ -6258,6 +6354,9 @@ async function findByKeyword(kv, keyword, project) {
 const LESSON_CONTENT_PREVIEW_CHARS = 240;
 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);
 		if (data.expandIds && data.expandIds.length > 0) {
 			const raw = data.expandIds.slice(0, 20);
 			const items = raw.map((entry) => {
@@ -6278,17 +6377,19 @@ function registerSmartSearchFunction(sdk, kv, searchFn) {
 				observation: obs
 			} : null)));
 			for (const r of results) if (r) expanded.push(r);
-			recordAccessBatch(kv, expanded.map((e) => e.observation.id));
+			const scoped = filterAgentId ? expanded.filter((e) => e.observation.agentId === filterAgentId) : expanded;
+			recordAccessBatch(kv, scoped.map((e) => e.observation.id));
 			const truncated = data.expandIds.length > raw.length;
 			logger.info("Smart search expanded", {
 				requested: data.expandIds.length,
 				attempted: raw.length,
-				returned: expanded.length,
+				returned: scoped.length,
+				filteredOutOfScope: expanded.length - scoped.length,
 				truncated
 			});
 			return {
 				mode: "expanded",
-				results: expanded,
+				results: scoped,
 				truncated
 			};
 		}
@@ -6300,8 +6401,9 @@ function registerSmartSearchFunction(sdk, kv, searchFn) {
 		const limit = Math.max(1, Math.min(data.limit ?? 20, 100));
 		const lessonLimit = Math.min(limit, 10);
 		const includeLessons = data.includeLessons !== false;
-		const [hybridResults, lessons] = await Promise.all([searchFn(data.query, limit), includeLessons ? recallLessons(sdk, data.query, lessonLimit, data.project) : Promise.resolve([])]);
-		const compact = hybridResults.map((r) => ({
+		const overFetchLimit = filterAgentId ? Math.min(limit * 3, 300) : limit;
+		const [hybridResults, lessons] = await Promise.all([searchFn(data.query, overFetchLimit), includeLessons ? recallLessons(sdk, data.query, lessonLimit, data.project) : Promise.resolve([])]);
+		const compact = (filterAgentId ? hybridResults.filter((r) => r.observation.agentId === filterAgentId).slice(0, limit) : hybridResults.slice(0, limit)).map((r) => ({
 			obsId: r.observation.id,
 			sessionId: r.sessionId,
 			title: r.observation.title,
@@ -6480,6 +6582,8 @@ function registerAutoForgetFunction(sdk, kv) {
 						timestamp: mem.forgetAfter
 					});
 					await deleteAccessLog(kv, mem.id);
+					getSearchIndex().remove(mem.id);
+					vectorIndexRemove(mem.id);
 				}
 			}
 		}
@@ -6557,10 +6661,13 @@ function registerAutoForgetFunction(sdk, kv) {
 							sessionId: sessions[i].id,
 							timestamp: obs.timestamp
 						});
+						getSearchIndex().remove(obs.id);
+						vectorIndexRemove(obs.id);
 					}
 				}
 			}
 		}
+		if (!dryRun && (result.ttlExpired.length > 0 || result.lowValueObs.length > 0)) await flushIndexSave();
 		logger.info("Auto-forget complete", {
 			ttlExpired: result.ttlExpired.length,
 			contradictions: result.contradictions.length,
@@ -6573,7 +6680,7 @@ function registerAutoForgetFunction(sdk, kv) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.9.21";
+const VERSION = "0.9.22";
 
 //#endregion
 //#region src/functions/export-import.ts
@@ -6712,7 +6819,8 @@ function registerExportImportFunction(sdk, kv) {
 			"0.9.18",
 			"0.9.19",
 			"0.9.20",
-			"0.9.21"
+			"0.9.21",
+			"0.9.22"
 		]).has(importData.version)) return {
 			success: false,
 			error: `Unsupported export version: ${importData.version}`
@@ -7238,12 +7346,12 @@ function parseGraphXml(xml, observationIds) {
 	const nodes = [];
 	const edges = [];
 	const now = (/* @__PURE__ */ new Date()).toISOString();
-	const entityRegex = /<entity\s+type="([^"]+)"\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/entity>/g;
+	const entityRegex = /<entity\s+type="([^"]+)"\s+name="([^"]+)"[^>]*?(?:\/>|>([\s\S]*?)<\/entity>)/g;
 	let match;
 	while ((match = entityRegex.exec(xml)) !== null) {
 		const type = match[1];
 		const name = match[2];
-		const propsBlock = match[3];
+		const propsBlock = match[3] ?? "";
 		const properties = {};
 		const propRegex = /<property\s+key="([^"]+)">([^<]*)<\/property>/g;
 		let propMatch;
@@ -7771,8 +7879,11 @@ function registerGovernanceFunction(sdk, kv) {
 		for (const id of data.memoryIds) if (await kv.get(KV.memories, id)) {
 			await kv.delete(KV.memories, id);
 			await deleteAccessLog(kv, id);
+			getSearchIndex().remove(id);
+			vectorIndexRemove(id);
 			deleted++;
 		}
+		if (deleted > 0) await flushIndexSave();
 		await recordAudit(kv, "delete", "mem::governance-delete", data.memoryIds, {
 			reason: data.reason || "manual deletion",
 			deleted
@@ -7825,6 +7936,8 @@ function registerGovernanceFunction(sdk, kv) {
 			(await Promise.allSettled(batch.map(async (mem) => {
 				await kv.delete(KV.memories, mem.id);
 				await deleteAccessLog(kv, mem.id);
+				getSearchIndex().remove(mem.id);
+				vectorIndexRemove(mem.id);
 			}))).forEach((result, j) => {
 				const mem = batch[j];
 				if (result.status === "fulfilled") successfulIds.push(mem.id);
@@ -7840,6 +7953,7 @@ function registerGovernanceFunction(sdk, kv) {
 				}
 			});
 		}
+		if (successfulIds.length > 0) await flushIndexSave();
 		await safeAudit(kv, "delete", "mem::governance-bulk", successfulIds, {
 			filter: data,
 			deleted: successfulIds.length,
@@ -13239,6 +13353,8 @@ function registerRetentionFunctions(sdk, kv) {
 			await kv.delete(scope, candidate.memoryId);
 			await kv.delete(KV.retentionScores, candidate.memoryId);
 			await deleteAccessLog(kv, candidate.memoryId);
+			getSearchIndex().remove(candidate.memoryId);
+			vectorIndexRemove(candidate.memoryId);
 			evicted++;
 			evictedIds.push(candidate.memoryId);
 			if (resolvedSource === "semantic") evictedSemantic++;
@@ -13246,13 +13362,16 @@ function registerRetentionFunctions(sdk, kv) {
 		} catch {
 			continue;
 		}
-		if (evicted > 0) await recordAudit(kv, "delete", "mem::retention-evict", evictedIds, {
-			threshold,
-			evicted,
-			evictedEpisodic,
-			evictedSemantic,
-			reason: "retention score below threshold"
-		});
+		if (evicted > 0) {
+			await flushIndexSave();
+			await recordAudit(kv, "delete", "mem::retention-evict", evictedIds, {
+				threshold,
+				evicted,
+				evictedEpisodic,
+				evictedSemantic,
+				reason: "retention score below threshold"
+			});
+		}
 		logger.info("Retention-based eviction complete", {
 			evicted,
 			evictedEpisodic,
@@ -14156,6 +14275,221 @@ function renderViewerDocument() {
 	};
 }
 
+//#endregion
+//#region src/viewer/server.ts
+function loadViewerFavicon() {
+	const base = dirname(fileURLToPath(import.meta.url));
+	const candidates = [
+		join(base, "..", "src", "viewer", "favicon.svg"),
+		join(base, "..", "viewer", "favicon.svg"),
+		join(base, "viewer", "favicon.svg")
+	];
+	for (const path of candidates) try {
+		return readFileSync(path);
+	} catch {}
+	return null;
+}
+const ALLOWED_ORIGINS = (process.env.VIEWER_ALLOWED_ORIGINS || "http://localhost:3111,http://localhost:3113,http://127.0.0.1:3111,http://127.0.0.1:3113").split(",").map((o) => o.trim());
+const ALLOWED_HOSTS_OVERRIDE = (process.env.VIEWER_ALLOWED_HOSTS || "").split(",").map((h) => h.trim().toLowerCase()).filter(Boolean);
+function buildAllowedHosts(origins, listenPort) {
+	const hosts = /* @__PURE__ */ new Set();
+	for (const o of origins) try {
+		const parsed = new URL(o);
+		if (parsed.host) hosts.add(parsed.host.toLowerCase());
+	} catch {}
+	hosts.add(`localhost:${listenPort}`);
+	hosts.add(`127.0.0.1:${listenPort}`);
+	hosts.add(`[::1]:${listenPort}`);
+	for (const h of ALLOWED_HOSTS_OVERRIDE) hosts.add(h);
+	return hosts;
+}
+function isHostAllowed(headerHost, allowed) {
+	if (typeof headerHost !== "string") return false;
+	const lower = headerHost.toLowerCase().trim();
+	if (!lower) return false;
+	return allowed.has(lower);
+}
+function corsHeaders(req) {
+	const origin = req.headers.origin || "";
+	const allowed = ALLOWED_ORIGINS.includes(origin) ? origin : ALLOWED_ORIGINS[0];
+	return {
+		"Access-Control-Allow-Origin": allowed,
+		"Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+		"Access-Control-Allow-Headers": "Content-Type, Authorization",
+		Vary: "Origin"
+	};
+}
+function json(res, status, data, req) {
+	const body = JSON.stringify(data);
+	const cors = req ? corsHeaders(req) : {
+		"Access-Control-Allow-Origin": ALLOWED_ORIGINS[0],
+		Vary: "Origin"
+	};
+	res.writeHead(status, {
+		...cors,
+		"Content-Type": "application/json"
+	});
+	res.end(body);
+}
+function readBody(req) {
+	return new Promise((resolve, reject) => {
+		let data = "";
+		let size = 0;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > 1e6) {
+				req.destroy();
+				reject(/* @__PURE__ */ new Error("too large"));
+				return;
+			}
+			data += chunk.toString();
+		});
+		req.on("end", () => resolve(data));
+		req.on("error", reject);
+	});
+}
+const MAX_VIEWER_PORT_RETRIES = 10;
+let boundViewerPort = null;
+let viewerSkipped = false;
+function getBoundViewerPort() {
+	return boundViewerPort;
+}
+function getViewerSkipped() {
+	return viewerSkipped;
+}
+function startViewerServer(port, _kv, _sdk, secret, restPort) {
+	boundViewerPort = null;
+	viewerSkipped = false;
+	const resolvedRestPort = restPort ?? port - 2;
+	const requestedPort = port;
+	let allowedHosts = null;
+	const server = createServer(async (req, res) => {
+		if (!allowedHosts) {
+			const addr = server.address();
+			allowedHosts = buildAllowedHosts(ALLOWED_ORIGINS, addr && typeof addr === "object" && "port" in addr ? addr.port : port);
+		}
+		if (!isHostAllowed(req.headers.host, allowedHosts)) {
+			res.writeHead(403, { "Content-Type": "text/plain" });
+			res.end("forbidden host");
+			return;
+		}
+		const raw = req.url || "/";
+		const qIdx = raw.indexOf("?");
+		const pathname = qIdx >= 0 ? raw.slice(0, qIdx) : raw;
+		const qs = qIdx >= 0 ? raw.slice(qIdx + 1) : "";
+		const method = req.method || "GET";
+		if (method === "OPTIONS") {
+			res.writeHead(204, {
+				...corsHeaders(req),
+				"Access-Control-Max-Age": "86400"
+			});
+			res.end();
+			return;
+		}
+		if (method === "GET" && (pathname === "/" || pathname === "/viewer" || pathname === "/agentmemory/viewer")) {
+			const rendered = renderViewerDocument();
+			if (rendered.found) {
+				res.writeHead(200, {
+					"Content-Type": "text/html; charset=utf-8",
+					"Content-Security-Policy": rendered.csp,
+					"Cache-Control": "no-cache"
+				});
+				res.end(rendered.html);
+				return;
+			}
+			res.writeHead(404, { "Content-Type": "text/plain" });
+			res.end("viewer not found");
+			return;
+		}
+		if (method === "GET" && pathname === "/favicon.svg") {
+			const favicon = loadViewerFavicon();
+			if (favicon) {
+				res.writeHead(200, {
+					"Content-Type": "image/svg+xml",
+					"Cache-Control": "public, max-age=3600"
+				});
+				res.end(favicon);
+				return;
+			}
+			res.writeHead(404, { "Content-Type": "text/plain" });
+			res.end("favicon not found");
+			return;
+		}
+		try {
+			await proxyToRestApi(resolvedRestPort, pathname, qs, method, req, res, secret);
+		} catch (err) {
+			console.error(`[viewer] proxy error on ${method} ${pathname}:`, err);
+			json(res, 502, { error: "upstream error" }, req);
+		}
+	});
+	let attempt = 0;
+	let currentPort = requestedPort;
+	const tryListen = () => {
+		server.listen(currentPort, "127.0.0.1");
+	};
+	server.on("listening", () => {
+		const addr = server.address();
+		boundViewerPort = addr && typeof addr === "object" && "port" in addr ? addr.port : currentPort;
+		viewerSkipped = false;
+		if (currentPort === requestedPort) console.log(`[agentmemory] Viewer: http://localhost:${currentPort}`);
+		else console.log(`[agentmemory] Viewer started on http://localhost:${currentPort} (fallback from ${requestedPort})`);
+	});
+	server.on("error", (err) => {
+		if (err.code === "EADDRINUSE" && attempt < MAX_VIEWER_PORT_RETRIES) {
+			attempt++;
+			currentPort = requestedPort + attempt;
+			setImmediate(tryListen);
+			return;
+		}
+		if (err.code === "EADDRINUSE") {
+			boundViewerPort = null;
+			viewerSkipped = true;
+			console.warn(`[agentmemory] Viewer ports ${requestedPort}-${requestedPort + MAX_VIEWER_PORT_RETRIES} all in use, skipping viewer.`);
+		} else {
+			boundViewerPort = null;
+			viewerSkipped = true;
+			console.error(`[agentmemory] Viewer error:`, err.message);
+		}
+	});
+	tryListen();
+	return server;
+}
+async function proxyToRestApi(restPort, pathname, qs, method, req, res, secret) {
+	const upstreamUrl = `http://127.0.0.1:${restPort}${pathname.startsWith("/agentmemory/") ? pathname : `/agentmemory${pathname.startsWith("/") ? pathname : "/" + pathname}`}${qs ? "?" + qs : ""}`;
+	const headers = {};
+	if (secret) headers["Authorization"] = `Bearer ${secret}`;
+	const ct = req.headers["content-type"];
+	if (ct) headers["Content-Type"] = ct;
+	let body;
+	if (method === "POST" || method === "PUT" || method === "DELETE" || method === "PATCH") body = await readBody(req);
+	const controller = new AbortController();
+	const fetchTimeout = setTimeout(() => controller.abort(), 1e4);
+	let upstream;
+	try {
+		upstream = await fetch(upstreamUrl, {
+			method,
+			headers,
+			body: body || void 0,
+			signal: controller.signal
+		});
+		clearTimeout(fetchTimeout);
+	} catch (err) {
+		clearTimeout(fetchTimeout);
+		if (err instanceof Error && err.name === "AbortError") {
+			json(res, 504, { error: "upstream timeout" }, req);
+			return;
+		}
+		throw err;
+	}
+	const cors = corsHeaders(req);
+	const responseBody = await upstream.text();
+	const responseHeaders = { ...cors };
+	const upstreamCt = upstream.headers.get("content-type");
+	if (upstreamCt) responseHeaders["Content-Type"] = upstreamCt;
+	res.writeHead(upstream.status, responseHeaders);
+	res.end(responseBody);
+}
+
 //#endregion
 //#region src/triggers/api.ts
 function parseOptionalInt(raw) {
@@ -14241,7 +14575,9 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 		status_code: 200,
 		body: {
 			status: "ok",
-			service: "agentmemory"
+			service: "agentmemory",
+			viewerPort: getBoundViewerPort(),
+			viewerSkipped: getViewerSkipped()
 		}
 	}));
 	sdk.registerTrigger({
@@ -14336,7 +14672,9 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 				version: VERSION,
 				health: health || null,
 				functionMetrics,
-				circuitBreaker
+				circuitBreaker,
+				viewerPort: getBoundViewerPort(),
+				viewerSkipped: getViewerSkipped()
 			}
 		};
 	});
@@ -14590,6 +14928,7 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			body: { error: "sessionId, project, and cwd are required non-empty strings" }
 		};
 		const title = typeof body.title === "string" ? body.title.trim() : void 0;
+		const agentId = (typeof body.agentId === "string" && body.agentId.trim().length > 0 ? body.agentId.trim().slice(0, 128) : void 0) ?? getAgentId();
 		const session = {
 			id: sessionId,
 			project,
@@ -14598,7 +14937,8 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			status: "active",
 			observationCount: 0,
 			...title ? { summary: title.slice(0, 200) } : {},
-			...title ? { firstPrompt: title.slice(0, 200) } : {}
+			...title ? { firstPrompt: title.slice(0, 200) } : {},
+			...agentId ? { agentId } : {}
 		};
 		await kv.set(KV.sessions, sessionId, session);
 		return {
@@ -14785,9 +15125,13 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::sessions", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		const sessions = await kv.list(KV.sessions);
+		const normalizedAgentId = typeof req.query_params?.["agentId"] === "string" ? req.query_params["agentId"].trim() : void 0;
+		const wildcardAgent = normalizedAgentId === "*";
+		const filterAgentId = wildcardAgent ? void 0 : (normalizedAgentId && !wildcardAgent ? normalizedAgentId : void 0) ?? (isAgentScopeIsolated() ? getAgentId() : void 0);
 		return {
 			status_code: 200,
-			body: { sessions: await kv.list(KV.sessions) }
+			body: { sessions: filterAgentId ? sessions.filter((s) => s.agentId === filterAgentId) : sessions }
 		};
 	});
 	sdk.registerTrigger({
@@ -14806,9 +15150,13 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			status_code: 400,
 			body: { error: "sessionId required" }
 		};
+		const observations = await kv.list(KV.observations(sessionId));
+		const normalizedAgentId = typeof req.query_params?.["agentId"] === "string" ? req.query_params["agentId"].trim() : void 0;
+		const wildcardAgent = normalizedAgentId === "*";
+		const filterAgentId = wildcardAgent ? void 0 : (normalizedAgentId && !wildcardAgent ? normalizedAgentId : void 0) ?? (isAgentScopeIsolated() ? getAgentId() : void 0);
 		return {
 			status_code: 200,
-			body: { observations: await kv.list(KV.observations(sessionId)) }
+			body: { observations: filterAgentId ? observations.filter((o) => o.agentId === filterAgentId) : observations }
 		};
 	});
 	sdk.registerTrigger({
@@ -15084,11 +15432,22 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::export", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		const rawMax = req.query_params?.["maxSessions"];
+		const rawOffset = req.query_params?.["offset"];
+		const payload = {};
+		if (typeof rawMax === "string") {
+			const n = Number(rawMax);
+			if (Number.isInteger(n) && n > 0) payload.maxSessions = n;
+		}
+		if (typeof rawOffset === "string") {
+			const n = Number(rawOffset);
+			if (Number.isInteger(n) && n >= 0) payload.offset = n;
+		}
 		return {
 			status_code: 200,
 			body: await sdk.trigger({
 				function_id: "mem::export",
-				payload: {}
+				payload
 			})
 		};
 	});
@@ -15574,9 +15933,35 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
 		const memories = await kv.list(KV.memories);
+		const latest = req.query_params?.["latest"] === "true";
+		const normalizedAgentId = typeof req.query_params?.["agentId"] === "string" ? req.query_params["agentId"].trim() : void 0;
+		const wildcardAgent = normalizedAgentId === "*";
+		const explicitAgentId = normalizedAgentId && !wildcardAgent ? normalizedAgentId : void 0;
+		const includeOrphans = req.query_params?.["includeOrphans"] === "true";
+		const filterAgentId = wildcardAgent ? void 0 : explicitAgentId ?? (isAgentScopeIsolated() ? getAgentId() : void 0);
+		let filtered = latest ? memories.filter((m) => m.isLatest) : memories;
+		if (filterAgentId) filtered = filtered.filter((m) => m.agentId === filterAgentId || includeOrphans && m.agentId === void 0);
+		if (req.query_params?.["count"] === "true") return {
+			status_code: 200,
+			body: {
+				total: filtered.length,
+				latestCount: filtered.filter((m) => m.isLatest).length
+			}
+		};
+		const rawLimit = req.query_params?.["limit"];
+		const rawOffset = req.query_params?.["offset"];
+		const parsedLimit = typeof rawLimit === "string" ? Number(rawLimit) : NaN;
+		const parsedOffset = typeof rawOffset === "string" ? Number(rawOffset) : NaN;
+		const limit = Number.isInteger(parsedLimit) && parsedLimit > 0 ? Math.min(parsedLimit, 5e3) : void 0;
+		const offset = Number.isInteger(parsedOffset) && parsedOffset >= 0 ? parsedOffset : 0;
 		return {
 			status_code: 200,
-			body: { memories: req.query_params?.["latest"] === "true" ? memories.filter((m) => m.isLatest) : memories }
+			body: {
+				memories: limit !== void 0 ? filtered.slice(offset, offset + limit) : filtered,
+				total: filtered.length,
+				offset,
+				limit: limit ?? null
+			}
 		};
 	});
 	sdk.registerTrigger({
@@ -18656,8 +19041,8 @@ function getAllTools() {
 	];
 }
 function getVisibleTools() {
-	if ((process.env["AGENTMEMORY_TOOLS"] || "core") === "all") return getAllTools();
-	return getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name));
+	if ((process.env["AGENTMEMORY_TOOLS"] || "all") === "core") return getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name));
+	return getAllTools();
 }
 
 //#endregion
@@ -20295,201 +20680,6 @@ function registerMcpEndpoints(sdk, kv, secret) {
 	});
 }
 
-//#endregion
-//#region src/viewer/server.ts
-function loadViewerFavicon() {
-	const base = dirname(fileURLToPath(import.meta.url));
-	const candidates = [
-		join(base, "..", "src", "viewer", "favicon.svg"),
-		join(base, "..", "viewer", "favicon.svg"),
-		join(base, "viewer", "favicon.svg")
-	];
-	for (const path of candidates) try {
-		return readFileSync(path);
-	} catch {}
-	return null;
-}
-const ALLOWED_ORIGINS = (process.env.VIEWER_ALLOWED_ORIGINS || "http://localhost:3111,http://localhost:3113,http://127.0.0.1:3111,http://127.0.0.1:3113").split(",").map((o) => o.trim());
-const ALLOWED_HOSTS_OVERRIDE = (process.env.VIEWER_ALLOWED_HOSTS || "").split(",").map((h) => h.trim().toLowerCase()).filter(Boolean);
-function buildAllowedHosts(origins, listenPort) {
-	const hosts = /* @__PURE__ */ new Set();
-	for (const o of origins) try {
-		const parsed = new URL(o);
-		if (parsed.host) hosts.add(parsed.host.toLowerCase());
-	} catch {}
-	hosts.add(`localhost:${listenPort}`);
-	hosts.add(`127.0.0.1:${listenPort}`);
-	hosts.add(`[::1]:${listenPort}`);
-	for (const h of ALLOWED_HOSTS_OVERRIDE) hosts.add(h);
-	return hosts;
-}
-function isHostAllowed(headerHost, allowed) {
-	if (typeof headerHost !== "string") return false;
-	const lower = headerHost.toLowerCase().trim();
-	if (!lower) return false;
-	return allowed.has(lower);
-}
-function corsHeaders(req) {
-	const origin = req.headers.origin || "";
-	const allowed = ALLOWED_ORIGINS.includes(origin) ? origin : ALLOWED_ORIGINS[0];
-	return {
-		"Access-Control-Allow-Origin": allowed,
-		"Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
-		"Access-Control-Allow-Headers": "Content-Type, Authorization",
-		Vary: "Origin"
-	};
-}
-function json(res, status, data, req) {
-	const body = JSON.stringify(data);
-	const cors = req ? corsHeaders(req) : {
-		"Access-Control-Allow-Origin": ALLOWED_ORIGINS[0],
-		Vary: "Origin"
-	};
-	res.writeHead(status, {
-		...cors,
-		"Content-Type": "application/json"
-	});
-	res.end(body);
-}
-function readBody(req) {
-	return new Promise((resolve, reject) => {
-		let data = "";
-		let size = 0;
-		req.on("data", (chunk) => {
-			size += chunk.length;
-			if (size > 1e6) {
-				req.destroy();
-				reject(/* @__PURE__ */ new Error("too large"));
-				return;
-			}
-			data += chunk.toString();
-		});
-		req.on("end", () => resolve(data));
-		req.on("error", reject);
-	});
-}
-const MAX_VIEWER_PORT_RETRIES = 10;
-function startViewerServer(port, _kv, _sdk, secret, restPort) {
-	const resolvedRestPort = restPort ?? port - 2;
-	const requestedPort = port;
-	let allowedHosts = null;
-	const server = createServer(async (req, res) => {
-		if (!allowedHosts) {
-			const addr = server.address();
-			allowedHosts = buildAllowedHosts(ALLOWED_ORIGINS, addr && typeof addr === "object" && "port" in addr ? addr.port : port);
-		}
-		if (!isHostAllowed(req.headers.host, allowedHosts)) {
-			res.writeHead(403, { "Content-Type": "text/plain" });
-			res.end("forbidden host");
-			return;
-		}
-		const raw = req.url || "/";
-		const qIdx = raw.indexOf("?");
-		const pathname = qIdx >= 0 ? raw.slice(0, qIdx) : raw;
-		const qs = qIdx >= 0 ? raw.slice(qIdx + 1) : "";
-		const method = req.method || "GET";
-		if (method === "OPTIONS") {
-			res.writeHead(204, {
-				...corsHeaders(req),
-				"Access-Control-Max-Age": "86400"
-			});
-			res.end();
-			return;
-		}
-		if (method === "GET" && (pathname === "/" || pathname === "/viewer" || pathname === "/agentmemory/viewer")) {
-			const rendered = renderViewerDocument();
-			if (rendered.found) {
-				res.writeHead(200, {
-					"Content-Type": "text/html; charset=utf-8",
-					"Content-Security-Policy": rendered.csp,
-					"Cache-Control": "no-cache"
-				});
-				res.end(rendered.html);
-				return;
-			}
-			res.writeHead(404, { "Content-Type": "text/plain" });
-			res.end("viewer not found");
-			return;
-		}
-		if (method === "GET" && pathname === "/favicon.svg") {
-			const favicon = loadViewerFavicon();
-			if (favicon) {
-				res.writeHead(200, {
-					"Content-Type": "image/svg+xml",
-					"Cache-Control": "public, max-age=3600"
-				});
-				res.end(favicon);
-				return;
-			}
-			res.writeHead(404, { "Content-Type": "text/plain" });
-			res.end("favicon not found");
-			return;
-		}
-		try {
-			await proxyToRestApi(resolvedRestPort, pathname, qs, method, req, res, secret);
-		} catch (err) {
-			console.error(`[viewer] proxy error on ${method} ${pathname}:`, err);
-			json(res, 502, { error: "upstream error" }, req);
-		}
-	});
-	let attempt = 0;
-	let currentPort = requestedPort;
-	const tryListen = () => {
-		server.listen(currentPort, "127.0.0.1");
-	};
-	server.on("listening", () => {
-		if (currentPort === requestedPort) console.log(`[agentmemory] Viewer: http://localhost:${currentPort}`);
-		else console.log(`[agentmemory] Viewer started on http://localhost:${currentPort} (fallback from ${requestedPort})`);
-	});
-	server.on("error", (err) => {
-		if (err.code === "EADDRINUSE" && attempt < MAX_VIEWER_PORT_RETRIES) {
-			attempt++;
-			currentPort = requestedPort + attempt;
-			setImmediate(tryListen);
-			return;
-		}
-		if (err.code === "EADDRINUSE") console.warn(`[agentmemory] Viewer ports ${requestedPort}-${requestedPort + MAX_VIEWER_PORT_RETRIES} all in use, skipping viewer.`);
-		else console.error(`[agentmemory] Viewer error:`, err.message);
-	});
-	tryListen();
-	return server;
-}
-async function proxyToRestApi(restPort, pathname, qs, method, req, res, secret) {
-	const upstreamUrl = `http://127.0.0.1:${restPort}${pathname.startsWith("/agentmemory/") ? pathname : `/agentmemory${pathname.startsWith("/") ? pathname : "/" + pathname}`}${qs ? "?" + qs : ""}`;
-	const headers = {};
-	if (secret) headers["Authorization"] = `Bearer ${secret}`;
-	const ct = req.headers["content-type"];
-	if (ct) headers["Content-Type"] = ct;
-	let body;
-	if (method === "POST" || method === "PUT" || method === "DELETE" || method === "PATCH") body = await readBody(req);
-	const controller = new AbortController();
-	const fetchTimeout = setTimeout(() => controller.abort(), 1e4);
-	let upstream;
-	try {
-		upstream = await fetch(upstreamUrl, {
-			method,
-			headers,
-			body: body || void 0,
-			signal: controller.signal
-		});
-		clearTimeout(fetchTimeout);
-	} catch (err) {
-		clearTimeout(fetchTimeout);
-		if (err instanceof Error && err.name === "AbortError") {
-			json(res, 504, { error: "upstream timeout" }, req);
-			return;
-		}
-		throw err;
-	}
-	const cors = corsHeaders(req);
-	const responseBody = await upstream.text();
-	const responseHeaders = { ...cors };
-	const upstreamCt = upstream.headers.get("content-type");
-	if (upstreamCt) responseHeaders["Content-Type"] = upstreamCt;
-	res.writeHead(upstream.status, responseHeaders);
-	res.end(responseBody);
-}
-
 //#endregion
 //#region src/eval/metrics-store.ts
 var MetricsStore = class {
@@ -20627,6 +20817,21 @@ function initMetrics(getMeter) {
 
 //#endregion
 //#region src/index.ts
+function workerPidfilePath() {
+	return join(homedir(), ".agentmemory", "worker.pid");
+}
+function writeWorkerPidfile() {
+	try {
+		const p = workerPidfilePath();
+		mkdirSync(dirname(p), { recursive: true });
+		writeFileSync(p, `${process.pid}\n`, { encoding: "utf-8" });
+	} catch {}
+}
+function clearWorkerPidfile() {
+	try {
+		unlinkSync(workerPidfilePath());
+	} catch {}
+}
 function hasGetMeter(sdk) {
 	return typeof sdk === "object" && sdk !== null && "getMeter" in sdk && typeof sdk.getMeter === "function";
 }
@@ -20667,6 +20872,7 @@ async function main() {
 			framework: "iii-sdk"
 		}
 	});
+	writeWorkerPidfile();
 	const kv = new StateKV(sdk);
 	const secret = getEnvVar("AGENTMEMORY_SECRET");
 	const metricsStore = new MetricsStore(kv);
@@ -20762,6 +20968,7 @@ async function main() {
 	registerMcpEndpoints(sdk, kv, secret);
 	const healthMonitor = registerHealthMonitor(sdk, kv);
 	const indexPersistence = new IndexPersistence(kv, bm25Index, vectorIndex);
+	setIndexPersistence(indexPersistence);
 	const loaded = await indexPersistence.load().catch((err) => {
 		console.warn(`[agentmemory] Failed to load persisted index:`, err);
 		return null;
@@ -20879,6 +21086,7 @@ async function main() {
 			console.warn(`[agentmemory] Failed to save index on shutdown:`, err);
 		});
 		await sdk.shutdown();
+		clearWorkerPidfile();
 		process.exit(0);
 	};
 	process.on("SIGINT", shutdown);