@agentmemory/agentmemory 0.9.20 → 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 {
@@ -137,6 +145,9 @@ function getMergedEnv(overrides) {
 function getEnvVar(key) {
 	return getMergedEnv()[key];
 }
+function isDropStaleIndexEnabled() {
+	return getMergedEnv()["AGENTMEMORY_DROP_STALE_INDEX"] === "true";
+}
 function detectLlmProviderKind() {
 	const env = getMergedEnv();
 	if (hasRealValue(env["ANTHROPIC_API_KEY"]) || hasRealValue(env["GEMINI_API_KEY"]) || hasRealValue(env["GOOGLE_API_KEY"]) || hasRealValue(env["OPENROUTER_API_KEY"]) || hasRealValue(env["MINIMAX_API_KEY"]) || hasRealValue(env["OPENAI_API_KEY"]) && env["OPENAI_API_KEY_FOR_LLM"] !== "false") return "llm";
@@ -172,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,
@@ -193,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 {
@@ -450,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 {
@@ -538,6 +578,7 @@ var OpenAIProvider = class {
 		const body = {
 			model: this.model,
 			max_tokens: this.maxTokens,
+			stream: false,
 			messages: [{
 				role: "system",
 				content: systemPrompt
@@ -566,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)}`);
 	}
@@ -2511,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 [];
@@ -2863,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;
 }
 
@@ -2952,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;
@@ -2985,20 +3055,108 @@ async function vectorIndexAddGuarded(id, sessionId, text, context) {
 		return false;
 	}
 }
+async function vectorIndexAddBatchGuarded(items) {
+	const vi = vectorIndex;
+	const ep = currentEmbeddingProvider;
+	if (!vi || !ep || items.length === 0) return {
+		ok: 0,
+		fail: 0
+	};
+	let embeddings;
+	try {
+		embeddings = await ep.embedBatch(items.map((i) => clipEmbedInput(i.text)));
+	} catch (err) {
+		logger.warn("vector-index add batch: embed failed — skipping batch", {
+			batchSize: items.length,
+			provider: ep.name,
+			error: err instanceof Error ? err.message : String(err)
+		});
+		return {
+			ok: 0,
+			fail: items.length
+		};
+	}
+	if (embeddings.length !== items.length) {
+		logger.warn("vector-index add batch: provider returned wrong length — skipping batch", {
+			batchSize: items.length,
+			returned: embeddings.length,
+			provider: ep.name
+		});
+		return {
+			ok: 0,
+			fail: items.length
+		};
+	}
+	let ok = 0;
+	let fail = 0;
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i];
+		const embedding = embeddings[i];
+		if (embedding.length !== ep.dimensions) {
+			logger.warn("vector-index add batch: dimension mismatch — skipping item", {
+				kind: item.context.kind,
+				id: item.context.logId,
+				provider: ep.name,
+				expected: ep.dimensions,
+				received: embedding.length
+			});
+			fail++;
+			continue;
+		}
+		try {
+			vi.add(item.id, item.sessionId, embedding);
+			ok++;
+		} catch (err) {
+			logger.warn("vector-index add batch: index write failed — skipping item", {
+				kind: item.context.kind,
+				id: item.context.logId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+			fail++;
+		}
+	}
+	return {
+		ok,
+		fail
+	};
+}
+const DEFAULT_REBUILD_EMBED_BATCH = 32;
+function getRebuildEmbedBatchSize() {
+	const raw = process.env.REBUILD_EMBED_BATCH_SIZE;
+	if (!raw) return DEFAULT_REBUILD_EMBED_BATCH;
+	const n = parseInt(raw, 10);
+	return Number.isFinite(n) && n > 0 ? n : DEFAULT_REBUILD_EMBED_BATCH;
+}
 async function rebuildIndex(kv) {
 	const idx = getSearchIndex();
 	idx.clear();
 	vectorIndex?.clear();
+	const batchSize = getRebuildEmbedBatchSize();
+	const pending = [];
 	let count = 0;
+	const flush = async () => {
+		if (pending.length === 0) return;
+		await vectorIndexAddBatchGuarded(pending);
+		pending.length = 0;
+	};
+	const enqueue = async (job) => {
+		pending.push(job);
+		if (pending.length >= batchSize) await flush();
+	};
 	try {
 		const memories = await kv.list(KV.memories);
 		for (const memory of memories) {
 			if (memory.isLatest === false) continue;
 			if (!memory.title || !memory.content) continue;
 			idx.add(memoryToObservation(memory));
-			await vectorIndexAddGuarded(memory.id, memory.sessionIds[0] ?? "memory", memory.title + " " + memory.content, {
-				kind: "memory",
-				logId: memory.id
+			await enqueue({
+				id: memory.id,
+				sessionId: memory.sessionIds[0] ?? "memory",
+				text: memory.title + " " + memory.content,
+				context: {
+					kind: "memory",
+					logId: memory.id
+				}
 			});
 			count++;
 		}
@@ -3006,7 +3164,10 @@ async function rebuildIndex(kv) {
 		logger.warn("rebuildIndex: failed to load memories", { error: err instanceof Error ? err.message : String(err) });
 	}
 	const sessions = await kv.list(KV.sessions);
-	if (!sessions.length) return count;
+	if (!sessions.length) {
+		await flush();
+		return count;
+	}
 	const obsPerSession = [];
 	const failedSessions = [];
 	for (let batch = 0; batch < sessions.length; batch += 10) {
@@ -3024,12 +3185,18 @@ async function rebuildIndex(kv) {
 	if (failedSessions.length > 0) logger.warn("rebuildIndex: failed to load observations for sessions", { failedSessions });
 	for (const observations of obsPerSession) for (const obs of observations) if (obs.title && obs.narrative) {
 		idx.add(obs);
-		await vectorIndexAddGuarded(obs.id, obs.sessionId, obs.title + " " + obs.narrative, {
-			kind: "observation",
-			logId: obs.id
+		await enqueue({
+			id: obs.id,
+			sessionId: obs.sessionId,
+			text: obs.title + " " + obs.narrative,
+			context: {
+				kind: "observation",
+				logId: obs.id
+			}
 		});
 		count++;
 	}
+	await flush();
 	return count;
 }
 function registerSearchFunction(sdk, kv) {
@@ -3249,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);
@@ -3300,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",
@@ -3320,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",
@@ -4579,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 {
@@ -4814,9 +4999,134 @@ function buildSummaryPrompt(observations) {
 	});
 	return `Session observations (${observations.length} total):\n\n${lines.join("\n\n---\n\n")}`;
 }
+const REDUCE_SYSTEM = `You are merging multiple partial summaries of the SAME coding session into one final session summary. The partials are chronological chunks of one continuous session — not separate sessions.
+
+Output EXACTLY this XML format with no additional text:
+
+<summary>
+  <title>Short session title (max 100 chars)</title>
+  <narrative>3-5 sentence narrative covering the whole session</narrative>
+  <decisions>
+    <decision>Key technical decision made</decision>
+  </decisions>
+  <files>
+    <file>path/to/modified/file</file>
+  </files>
+  <concepts>
+    <concept>key concept from session</concept>
+  </concepts>
+</summary>
+
+Rules:
+- Synthesize a single narrative that reflects the whole arc, not a chunk-by-chunk recap
+- Preserve every distinct decision across chunks
+- Union (deduplicate) all files and concepts
+- Title should capture the session's overall outcome`;
+function buildReducePrompt(partials) {
+	const sections = partials.map((p, i) => {
+		const decisions = p.keyDecisions.map((d) => `  - ${d}`).join("\n");
+		const files = p.filesModified.map((f) => `  - ${f}`).join("\n");
+		const concepts = p.concepts.join(", ");
+		return `[Chunk ${i + 1} of ${partials.length} — obs ${p.obsRangeStart}-${p.obsRangeEnd}]
+Title: ${p.title}
+Narrative: ${p.narrative}
+Decisions:
+${decisions}
+Files:
+${files}
+Concepts: ${concepts}`;
+	});
+	return `Partial summaries (${partials.length} chunks of one session, chronological):\n\n${sections.join("\n\n---\n\n")}`;
+}
 
 //#endregion
 //#region src/functions/summarize.ts
+const CHUNK_SIZE_DEFAULT = 400;
+const CHUNK_CONCURRENCY_DEFAULT = 6;
+const MAX_SKIP_RATIO = .5;
+function getChunkSize() {
+	const raw = process.env.SUMMARIZE_CHUNK_SIZE;
+	if (!raw) return CHUNK_SIZE_DEFAULT;
+	const n = parseInt(raw, 10);
+	return Number.isFinite(n) && n > 0 ? n : CHUNK_SIZE_DEFAULT;
+}
+function getChunkConcurrency() {
+	const raw = process.env.SUMMARIZE_CHUNK_CONCURRENCY;
+	if (!raw) return CHUNK_CONCURRENCY_DEFAULT;
+	const n = parseInt(raw, 10);
+	return Number.isFinite(n) && n > 0 ? n : CHUNK_CONCURRENCY_DEFAULT;
+}
+async function summarizeChunkWithRetry(provider, chunk, sessionId, project, idx, total) {
+	for (let attempt = 1; attempt <= 2; attempt++) try {
+		const parsed = parseSummaryXml(await provider.summarize(SUMMARY_SYSTEM, buildSummaryPrompt(chunk)), sessionId, project, chunk.length);
+		if (parsed) return parsed;
+		logger.warn("Summarize chunk parse failed", {
+			sessionId,
+			chunk: `${idx + 1}/${total}`,
+			attempt
+		});
+	} catch (err) {
+		logger.warn("Summarize chunk LLM call failed", {
+			sessionId,
+			chunk: `${idx + 1}/${total}`,
+			attempt,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+	return null;
+}
+async function produceSummaryXml(provider, compressed, sessionId, project) {
+	const chunkSize = getChunkSize();
+	if (compressed.length <= chunkSize) return {
+		response: await provider.summarize(SUMMARY_SYSTEM, buildSummaryPrompt(compressed)),
+		mode: "single",
+		chunks: 1
+	};
+	const chunks = [];
+	for (let i = 0; i < compressed.length; i += chunkSize) chunks.push(compressed.slice(i, i + chunkSize));
+	const concurrency = getChunkConcurrency();
+	logger.info("Summarize chunking session", {
+		sessionId,
+		chunks: chunks.length,
+		chunkSize,
+		concurrency,
+		totalObservations: compressed.length
+	});
+	const partialByIdx = new Array(chunks.length).fill(null);
+	for (let batchStart = 0; batchStart < chunks.length; batchStart += concurrency) {
+		const batch = chunks.slice(batchStart, batchStart + concurrency);
+		await Promise.all(batch.map(async (chunk, j) => {
+			const idx = batchStart + j;
+			partialByIdx[idx] = await summarizeChunkWithRetry(provider, chunk, sessionId, project, idx, chunks.length);
+		}));
+	}
+	const skipped = partialByIdx.filter((p) => p === null).length;
+	const partials = partialByIdx.filter((p) => p !== null);
+	if (skipped > Math.floor(chunks.length * MAX_SKIP_RATIO)) throw new Error(`too_many_chunks_skipped: ${skipped}/${chunks.length} chunks failed to parse after retry`);
+	if (skipped > 0) logger.warn("Summarize chunks partially skipped", {
+		sessionId,
+		skipped,
+		total: chunks.length
+	});
+	const reduceInput = partials.map((p) => {
+		const originalIdx = partialByIdx.indexOf(p);
+		return {
+			title: p.title,
+			narrative: p.narrative,
+			keyDecisions: p.keyDecisions,
+			filesModified: p.filesModified,
+			concepts: p.concepts,
+			obsRangeStart: originalIdx * chunkSize + 1,
+			obsRangeEnd: Math.min((originalIdx + 1) * chunkSize, compressed.length)
+		};
+	});
+	return {
+		response: await provider.summarize(REDUCE_SYSTEM, buildReducePrompt(reduceInput)),
+		mode: "chunked",
+		chunks: chunks.length,
+		skipped
+	};
+}
 function parseSummaryXml(xml, sessionId, project, obsCount) {
 	const title = getXmlTag(xml, "title");
 	if (!title) return null;
@@ -4865,16 +5175,15 @@ function registerSummarizeFunction(sdk, kv, provider, metricsStore) {
 			};
 		}
 		try {
-			const prompt = buildSummaryPrompt(compressed);
-			const response = await provider.summarize(SUMMARY_SYSTEM, prompt);
+			const { response, mode, chunks } = await produceSummaryXml(provider, compressed, sessionId, session.project);
 			if (!response || !response.trim()) {
 				const latencyMs = Date.now() - startMs;
 				if (metricsStore) await metricsStore.record("mem::summarize", latencyMs, false);
 				logger.warn("Empty provider response on summarize", {
 					sessionId,
 					provider: provider.name,
-					promptBytes: prompt.length,
-					systemBytes: SUMMARY_SYSTEM.length,
+					mode,
+					chunks,
 					observationCount: compressed.length
 				});
 				return {
@@ -5426,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,
@@ -5441,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) {
@@ -5487,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++;
 		}
@@ -5495,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++;
 		}
@@ -5504,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++;
 			}
@@ -5512,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,
@@ -6031,8 +6351,12 @@ async function findByKeyword(kv, keyword, project) {
 
 //#endregion
 //#region src/functions/smart-search.ts
+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) => {
@@ -6053,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
 			};
 		}
@@ -6073,7 +6399,11 @@ function registerSmartSearchFunction(sdk, kv, searchFn) {
 			error: "query is required"
 		};
 		const limit = Math.max(1, Math.min(data.limit ?? 20, 100));
-		const compact = (await searchFn(data.query, limit)).map((r) => ({
+		const lessonLimit = Math.min(limit, 10);
+		const includeLessons = data.includeLessons !== false;
+		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,
@@ -6084,14 +6414,42 @@ function registerSmartSearchFunction(sdk, kv, searchFn) {
 		recordAccessBatch(kv, compact.map((r) => r.obsId));
 		logger.info("Smart search compact", {
 			query: data.query,
-			results: compact.length
+			results: compact.length,
+			lessons: lessons.length
 		});
-		return {
+		const response = {
 			mode: "compact",
 			results: compact
 		};
+		if (includeLessons) response.lessons = lessons;
+		return response;
 	});
 }
+async function recallLessons(sdk, query, limit, project) {
+	try {
+		const result = await sdk.trigger({
+			function_id: "mem::lesson-recall",
+			payload: {
+				query,
+				limit,
+				project
+			}
+		});
+		if (!result?.success || !Array.isArray(result.lessons)) return [];
+		return result.lessons.map((l) => ({
+			lessonId: l.id,
+			content: l.content.length > LESSON_CONTENT_PREVIEW_CHARS ? l.content.slice(0, LESSON_CONTENT_PREVIEW_CHARS) + "…" : l.content,
+			confidence: l.confidence,
+			score: l.score ?? l.confidence,
+			createdAt: l.createdAt,
+			project: l.project,
+			tags: l.tags ?? []
+		}));
+	} catch (err) {
+		logger.warn("Smart search: mem::lesson-recall failed; returning empty lesson list", { error: err instanceof Error ? err.message : String(err) });
+		return [];
+	}
+}
 async function findObservation$1(kv, obsId, sessionIdHint) {
 	if (sessionIdHint) {
 		const obs = await kv.get(KV.observations(sessionIdHint), obsId).catch(() => null);
@@ -6224,6 +6582,8 @@ function registerAutoForgetFunction(sdk, kv) {
 						timestamp: mem.forgetAfter
 					});
 					await deleteAccessLog(kv, mem.id);
+					getSearchIndex().remove(mem.id);
+					vectorIndexRemove(mem.id);
 				}
 			}
 		}
@@ -6301,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,
@@ -6317,7 +6680,7 @@ function registerAutoForgetFunction(sdk, kv) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.9.20";
+const VERSION = "0.9.22";
 
 //#endregion
 //#region src/functions/export-import.ts
@@ -6455,7 +6818,9 @@ function registerExportImportFunction(sdk, kv) {
 			"0.9.17",
 			"0.9.18",
 			"0.9.19",
-			"0.9.20"
+			"0.9.20",
+			"0.9.21",
+			"0.9.22"
 		]).has(importData.version)) return {
 			success: false,
 			error: `Unsupported export version: ${importData.version}`
@@ -6981,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;
@@ -7514,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
@@ -7568,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);
@@ -7583,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,
@@ -10157,6 +10528,12 @@ const ALL_CATEGORIES = [
 	"signals",
 	"sessions",
 	"memories",
+	"lessons",
+	"summaries",
+	"semantic",
+	"procedural",
+	"crystals",
+	"insights",
 	"mesh"
 ];
 const TWENTY_FOUR_HOURS_MS = 1440 * 60 * 1e3;
@@ -10389,6 +10766,133 @@ function registerDiagnosticsFunction(sdk, kv) {
 				fixable: false
 			});
 		}
+		if (categories.includes("lessons")) {
+			const lessons = await kv.list(KV.lessons);
+			const live = lessons.filter((l) => !l.deleted);
+			let lessonIssues = 0;
+			for (const l of live) if (!Number.isFinite(l.confidence) || l.confidence < 0 || l.confidence > 1) {
+				checks.push({
+					name: `lesson-bad-confidence:${l.id}`,
+					category: "lessons",
+					status: "warn",
+					message: `Lesson ${l.id} has confidence ${l.confidence} (expected finite number in 0..1)`,
+					fixable: false
+				});
+				lessonIssues++;
+			}
+			if (lessonIssues === 0) checks.push({
+				name: "lessons-ok",
+				category: "lessons",
+				status: "pass",
+				message: `All ${live.length} lessons are healthy (${lessons.length - live.length} tombstoned)`,
+				fixable: false
+			});
+		}
+		if (categories.includes("summaries")) {
+			const summaries = await kv.list(KV.summaries);
+			let summaryIssues = 0;
+			for (const s of summaries) if (typeof s.title !== "string" || s.title.trim().length === 0) {
+				checks.push({
+					name: `summary-missing-title:${s.sessionId}`,
+					category: "summaries",
+					status: "warn",
+					message: `Summary for session ${s.sessionId} has no title`,
+					fixable: false
+				});
+				summaryIssues++;
+			}
+			if (summaryIssues === 0) checks.push({
+				name: "summaries-ok",
+				category: "summaries",
+				status: "pass",
+				message: `All ${summaries.length} session summaries are consistent`,
+				fixable: false
+			});
+		}
+		if (categories.includes("semantic")) {
+			const semantic = await kv.list(KV.semantic);
+			let semanticIssues = 0;
+			for (const s of semantic) if (!Number.isFinite(s.confidence) || s.confidence < 0 || s.confidence > 1) {
+				checks.push({
+					name: `semantic-bad-confidence:${s.id}`,
+					category: "semantic",
+					status: "warn",
+					message: `Semantic fact ${s.id} has confidence ${s.confidence} (expected finite number in 0..1)`,
+					fixable: false
+				});
+				semanticIssues++;
+			}
+			if (semanticIssues === 0) checks.push({
+				name: "semantic-ok",
+				category: "semantic",
+				status: "pass",
+				message: `All ${semantic.length} semantic memories are consistent`,
+				fixable: false
+			});
+		}
+		if (categories.includes("procedural")) {
+			const procedural = await kv.list(KV.procedural);
+			let proceduralIssues = 0;
+			for (const p of procedural) if (!Array.isArray(p.steps) || p.steps.length === 0) {
+				checks.push({
+					name: `procedural-empty-steps:${p.id}`,
+					category: "procedural",
+					status: "warn",
+					message: `Procedural memory "${p.name}" (${p.id}) has no steps`,
+					fixable: false
+				});
+				proceduralIssues++;
+			}
+			if (proceduralIssues === 0) checks.push({
+				name: "procedural-ok",
+				category: "procedural",
+				status: "pass",
+				message: `All ${procedural.length} procedural memories are consistent`,
+				fixable: false
+			});
+		}
+		if (categories.includes("crystals")) {
+			const crystals = await kv.list(KV.crystals);
+			let crystalIssues = 0;
+			for (const c of crystals) if (typeof c.narrative !== "string" || c.narrative.trim().length === 0) {
+				checks.push({
+					name: `crystal-empty-narrative:${c.id}`,
+					category: "crystals",
+					status: "warn",
+					message: `Crystal ${c.id} has empty narrative`,
+					fixable: false
+				});
+				crystalIssues++;
+			}
+			if (crystalIssues === 0) checks.push({
+				name: "crystals-ok",
+				category: "crystals",
+				status: "pass",
+				message: `All ${crystals.length} crystals are consistent`,
+				fixable: false
+			});
+		}
+		if (categories.includes("insights")) {
+			const insights = await kv.list(KV.insights);
+			let insightIssues = 0;
+			for (const i of insights) if (!Number.isFinite(i.confidence) || i.confidence < 0 || i.confidence > 1) {
+				checks.push({
+					name: `insight-bad-confidence:${i.id}`,
+					category: "insights",
+					status: "warn",
+					message: `Insight ${i.id} has confidence ${i.confidence} (expected finite number in 0..1)`,
+					fixable: false
+				});
+				insightIssues++;
+			}
+			if (insightIssues === 0) checks.push({
+				name: "insights-ok",
+				category: "insights",
+				status: "pass",
+				message: `All ${insights.length} insights are consistent`,
+				fixable: false
+			});
+		}
 		if (categories.includes("mesh")) {
 			const peers = await kv.list(KV.mesh);
 			let meshIssues = 0;
@@ -12849,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++;
@@ -12856,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,
@@ -13767,31 +14276,246 @@ function renderViewerDocument() {
 }
 
 //#endregion
-//#region src/triggers/api.ts
-function parseOptionalInt(raw) {
-	if (raw === void 0 || raw === null || raw === "") return void 0;
-	const n = typeof raw === "number" ? raw : parseInt(String(raw), 10);
-	return Number.isFinite(n) ? n : void 0;
-}
-function checkAuth(req, secret) {
-	if (!secret) return null;
-	const auth = req.headers?.["authorization"] || req.headers?.["Authorization"];
-	if (typeof auth !== "string" || !timingSafeCompare(auth, `Bearer ${secret}`)) return {
-		status_code: 401,
-		body: { error: "unauthorized" }
-	};
+//#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;
 }
-function requireConfiguredSecret(secret, feature) {
-	if (secret) 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 {
-		status_code: 503,
-		body: { error: `${feature} requires AGENTMEMORY_SECRET` }
+		"Access-Control-Allow-Origin": allowed,
+		"Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+		"Access-Control-Allow-Headers": "Content-Type, Authorization",
+		Vary: "Origin"
 	};
 }
-function flagDisabledResponse(opts) {
-	return {
-		status_code: 503,
+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) {
+	if (raw === void 0 || raw === null || raw === "") return void 0;
+	const n = typeof raw === "number" ? raw : parseInt(String(raw), 10);
+	return Number.isFinite(n) ? n : void 0;
+}
+function checkAuth(req, secret) {
+	if (!secret) return null;
+	const auth = req.headers?.["authorization"] || req.headers?.["Authorization"];
+	if (typeof auth !== "string" || !timingSafeCompare(auth, `Bearer ${secret}`)) return {
+		status_code: 401,
+		body: { error: "unauthorized" }
+	};
+	return null;
+}
+function requireConfiguredSecret(secret, feature) {
+	if (secret) return null;
+	return {
+		status_code: 503,
+		body: { error: `${feature} requires AGENTMEMORY_SECRET` }
+	};
+}
+function flagDisabledResponse(opts) {
+	return {
+		status_code: 503,
 		body: opts
 	};
 }
@@ -13851,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({
@@ -13946,7 +14672,9 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 				version: VERSION,
 				health: health || null,
 				functionMetrics,
-				circuitBreaker
+				circuitBreaker,
+				viewerPort: getBoundViewerPort(),
+				viewerSkipped: getViewerSkipped()
 			}
 		};
 	});
@@ -14199,13 +14927,18 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			status_code: 400,
 			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,
 			cwd,
 			startedAt: (/* @__PURE__ */ new Date()).toISOString(),
 			status: "active",
-			observationCount: 0
+			observationCount: 0,
+			...title ? { summary: title.slice(0, 200) } : {},
+			...title ? { firstPrompt: title.slice(0, 200) } : {},
+			...agentId ? { agentId } : {}
 		};
 		await kv.set(KV.sessions, sessionId, session);
 		return {
@@ -14392,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({
@@ -14413,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({
@@ -14691,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
 			})
 		};
 	});
@@ -15181,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({
@@ -18263,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
@@ -19902,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 {
@@ -20234,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";
 }
@@ -20274,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);
@@ -20369,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;
@@ -20386,23 +20986,22 @@ async function main() {
 		if (mismatches.length > 0) {
 			const sample = mismatches.slice(0, 5).map((m) => `${m.obsId} (dim=${m.dim})`).join(", ");
 			const distinct = Array.from(seenDimensions).sort((a, b) => a - b).join(", ");
-			if (process.env["AGENTMEMORY_DROP_STALE_INDEX"] === "true") console.warn(`[agentmemory] Persisted vector index has ${mismatches.length} of ${loaded.vector.size} vectors with the wrong dimension. Active provider (${embeddingProvider?.name}) declares ${activeDim}; dimensions seen on disk: ${distinct}. AGENTMEMORY_DROP_STALE_INDEX=true is set — discarding the persisted vectors. Live observations will rebuild the index over time.`);
+			if (isDropStaleIndexEnabled()) console.warn(`[agentmemory] Persisted vector index has ${mismatches.length} of ${loaded.vector.size} vectors with the wrong dimension. Active provider (${embeddingProvider?.name}) declares ${activeDim}; dimensions seen on disk: ${distinct}. AGENTMEMORY_DROP_STALE_INDEX=true is set — discarding the persisted vectors. Live observations will rebuild the index over time.`);
 			else throw new Error(`[agentmemory] Refusing to start: persisted vector index has ${mismatches.length} of ${loaded.vector.size} vectors with the wrong dimension. Active provider (${embeddingProvider?.name}) declares ${activeDim}; dimensions seen on disk: ${distinct}. First mismatched obsIds: ${sample}. Loading would silently corrupt search (cross-dimension cosine returns 0). Choose one:\n  - Re-embed the existing index against the new provider, then start.\n  - Set AGENTMEMORY_DROP_STALE_INDEX=true to discard the persisted vectors and rebuild from live observations.\n  - Switch the embedding provider back to the one that wrote the index.`);
 		} else {
 			vectorIndex.restoreFrom(loaded.vector);
 			bootLog(`Loaded persisted vector index (${vectorIndex.size} vectors)`);
 		}
 	}
-	if (bm25Index.size === 0) {
-		const indexCount = await rebuildIndex(kv).catch((err) => {
-			console.warn(`[agentmemory] Failed to rebuild search index:`, err);
-			return 0;
-		});
+	if (bm25Index.size === 0) rebuildIndex(kv).then((indexCount) => {
 		if (indexCount > 0) {
 			bootLog(`Search index rebuilt: ${indexCount} entries`);
 			indexPersistence.scheduleSave();
 		}
-	} else try {
+	}).catch((err) => {
+		console.warn(`[agentmemory] Failed to rebuild search index:`, err);
+	});
+	else try {
 		const memories = await kv.list(KV.memories);
 		let backfilled = 0;
 		for (const memory of memories) {
@@ -20487,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);