@agentmemory/agentmemory 0.9.21 → 0.9.23

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 {
@@ -208,7 +233,17 @@ function isGraphExtractionEnabled() {
 	return getMergedEnv()["GRAPH_EXTRACTION_ENABLED"] === "true";
 }
 function isConsolidationEnabled() {
-	return getMergedEnv()["CONSOLIDATION_ENABLED"] === "true";
+	const env = getMergedEnv();
+	const explicit = env["CONSOLIDATION_ENABLED"];
+	if (explicit === "false" || explicit === "0") return false;
+	if (explicit === "true" || explicit === "1") return true;
+	return hasLLMProviderConfigured(env);
+}
+function hasLLMProviderConfigured(env) {
+	const provider = (env["AGENTMEMORY_PROVIDER"] || "").toLowerCase();
+	if (provider === "noop") return false;
+	const openaiKeyForLlm = env["OPENAI_API_KEY"] && (env["OPENAI_API_KEY_FOR_LLM"] || "").toLowerCase() !== "false";
+	return Boolean(env["ANTHROPIC_API_KEY"] || openaiKeyForLlm || env["OPENROUTER_API_KEY"] || env["GEMINI_API_KEY"] || env["GOOGLE_API_KEY"] || env["MINIMAX_API_KEY"] || env["OPENAI_BASE_URL"] || provider === "agent-sdk");
 }
 function isAutoCompressEnabled() {
 	return getMergedEnv()["AGENTMEMORY_AUTO_COMPRESS"] === "true";
@@ -453,13 +488,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 +588,7 @@ var OpenAIProvider = class {
 		const body = {
 			model: this.model,
 			max_tokens: this.maxTokens,
+			stream: false,
 			messages: [{
 				role: "system",
 				content: systemPrompt
@@ -569,7 +617,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)}`);
 	}
@@ -848,16 +896,30 @@ function resolveDimensions(model, override) {
 * `api-key` header instead of `Authorization: Bearer`.
 *
 * Required env vars:
-*   OPENAI_API_KEY            — API key
+*   OPENAI_API_KEY               — API key (fallback for OPENAI_EMBEDDING_API_KEY)
 *
 * Optional:
-*   OPENAI_BASE_URL           — base URL without path (default: https://api.openai.com).
-*                               Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-*   OPENAI_API_VERSION        — Azure api-version query param (default: 2024-08-01-preview)
-*   OPENAI_EMBEDDING_MODEL    — model name (default: text-embedding-3-small)
-*   OPENAI_EMBEDDING_DIMENSIONS — override reported dimensions (required for
-*                                 custom / self-hosted models not in the
-*                                 MODEL_DIMENSIONS table above)
+*   OPENAI_BASE_URL              — base URL without path (default: https://api.openai.com).
+*                                  Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+*   OPENAI_EMBEDDING_BASE_URL    — embedding-specific base URL override (defaults
+*                                  to OPENAI_BASE_URL). Lets operators run
+*                                  embeddings on a separate endpoint from chat —
+*                                  e.g. local Ollama / LM Studio / llama.cpp /
+*                                  vLLM at http://localhost:1234 for unlimited
+*                                  free embeddings, while keeping chat
+*                                  completions on a rate-limited but high-quality
+*                                  hosted provider. Azure detection runs on
+*                                  whichever URL ends up selected.
+*   OPENAI_EMBEDDING_API_KEY     — separate API key for the embedding endpoint
+*                                  (defaults to OPENAI_API_KEY). Useful when the
+*                                  embedding endpoint requires a different key
+*                                  or no key at all (set to e.g. "local" for
+*                                  endpoints that ignore Authorization).
+*   OPENAI_API_VERSION           — Azure api-version query param (default: 2024-08-01-preview)
+*   OPENAI_EMBEDDING_MODEL       — model name (default: text-embedding-3-small)
+*   OPENAI_EMBEDDING_DIMENSIONS  — override reported dimensions (required for
+*                                  custom / self-hosted models not in the
+*                                  MODEL_DIMENSIONS table above)
 */
 var OpenAIEmbeddingProvider = class {
 	name = "openai";
@@ -868,9 +930,9 @@ var OpenAIEmbeddingProvider = class {
 	isAzure;
 	azureApiVersion;
 	constructor(apiKey) {
-		this.apiKey = apiKey || getEnvVar("OPENAI_API_KEY") || "";
-		if (!this.apiKey) throw new Error("OPENAI_API_KEY is required");
-		this.baseUrl = normalizeBaseUrl(getEnvVar("OPENAI_BASE_URL"));
+		this.apiKey = apiKey || getEnvVar("OPENAI_EMBEDDING_API_KEY") || getEnvVar("OPENAI_API_KEY") || "";
+		if (!this.apiKey) throw new Error("API key is required (via constructor, OPENAI_EMBEDDING_API_KEY, or OPENAI_API_KEY)");
+		this.baseUrl = normalizeBaseUrl(getEnvVar("OPENAI_EMBEDDING_BASE_URL") || getEnvVar("OPENAI_BASE_URL"));
 		this.model = getEnvVar("OPENAI_EMBEDDING_MODEL") || DEFAULT_MODEL$1;
 		this.dimensions = resolveDimensions(this.model, getEnvVar("OPENAI_EMBEDDING_DIMENSIONS"));
 		this.isAzure = detectAzure(this.baseUrl);
@@ -1317,10 +1379,11 @@ function jaccardSimilarity(a, b) {
 //#endregion
 //#region src/state/vector-index.ts
 function float32ToBase64(arr) {
-	return Buffer.from(arr.buffer).toString("base64");
+	return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength).toString("base64");
 }
 function base64ToFloat32(b64) {
-	return new Float32Array(Buffer.from(b64, "base64").buffer);
+	const buf = Buffer.from(b64, "base64");
+	return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / Float32Array.BYTES_PER_ELEMENT);
 }
 function cosineSimilarity(a, b) {
 	if (a.length !== b.length) return 0;
@@ -1441,7 +1504,7 @@ var VectorIndex = class VectorIndex {
 function memoryToObservation(memory) {
 	return {
 		id: memory.id,
-		sessionId: memory.sessionIds[0] ?? "memory",
+		sessionId: memory.sessionIds?.[0] ?? "memory",
 		timestamp: memory.createdAt,
 		type: "decision",
 		title: memory.title,
@@ -2514,6 +2577,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 +2947,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 +3037,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;
@@ -3084,7 +3176,7 @@ async function rebuildIndex(kv) {
 			idx.add(memoryToObservation(memory));
 			await enqueue({
 				id: memory.id,
-				sessionId: memory.sessionIds[0] ?? "memory",
+				sessionId: memory.sessionIds?.[0] ?? "memory",
 				text: memory.title + " " + memory.content,
 				context: {
 					kind: "memory",
@@ -3143,8 +3235,8 @@ function registerSearchFunction(sdk, kv) {
 			if (!Number.isInteger(data.limit) || data.limit < 1) throw new Error("mem::search: limit must be a positive integer");
 			effectiveLimit = Math.min(data.limit, MAX_LIMIT);
 		}
-		const projectFilter = typeof data.project === "string" && data.project.length > 0 ? data.project : void 0;
-		const cwdFilter = typeof data.cwd === "string" && data.cwd.length > 0 ? data.cwd : void 0;
+		const projectFilter = typeof data.project === "string" && data.project.trim().length > 0 ? data.project.trim() : void 0;
+		const cwdFilter = typeof data.cwd === "string" && data.cwd.trim().length > 0 ? data.cwd.trim() : void 0;
 		const format = typeof data.format === "string" ? data.format : "full";
 		if (![
 			"full",
@@ -3170,14 +3262,25 @@ function registerSearchFunction(sdk, kv) {
 			sessionCache.set(sessionId, s ?? null);
 			return s ?? null;
 		};
+		const memoryProjectCache = /* @__PURE__ */ new Map();
+		const loadMemoryProject = async (obsId) => {
+			if (memoryProjectCache.has(obsId)) return memoryProjectCache.get(obsId);
+			const proj = (await kv.get(KV.memories, obsId).catch(() => null))?.project ?? null;
+			memoryProjectCache.set(obsId, proj);
+			return proj;
+		};
 		const candidates = [];
 		for (const r of results) {
 			if (candidates.length >= effectiveLimit) break;
 			if (filtering) {
 				const s = await loadSession(r.sessionId);
-				if (!s) continue;
-				if (projectFilter && s.project !== projectFilter) continue;
-				if (cwdFilter && s.cwd !== cwdFilter) continue;
+				if (s) {
+					if (projectFilter && s.project !== projectFilter) continue;
+					if (cwdFilter && s.cwd !== cwdFilter) continue;
+				} else if (projectFilter) {
+					const memProject = await loadMemoryProject(r.obsId);
+					if (memProject !== null && memProject !== projectFilter) continue;
+				}
 			}
 			candidates.push(r);
 		}
@@ -3349,6 +3452,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 +3506,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 +3526,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",
@@ -3912,10 +4032,10 @@ const DEFAULT_SLOTS = [
 	}
 ];
 function isSlotsEnabled() {
-	return process.env["AGENTMEMORY_SLOTS"] === "true";
+	return getEnvVar("AGENTMEMORY_SLOTS") === "true";
 }
 function isReflectEnabled() {
-	return process.env["AGENTMEMORY_REFLECT"] === "true";
+	return getEnvVar("AGENTMEMORY_REFLECT") === "true";
 }
 function scopeKv(scope) {
 	return scope === "global" ? KV.globalSlots : KV.slots;
@@ -4679,7 +4799,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 {
@@ -5179,8 +5300,78 @@ function isAllowedPath(dbPath) {
 	const resolved = resolve(dbPath);
 	return ALLOWED_DIRS.some((dir) => resolved.startsWith(dir + "/"));
 }
+async function inferMemoryProjects(kv, dryRun = false) {
+	const memories = await kv.list(KV.memories);
+	const sessionCache = /* @__PURE__ */ new Map();
+	const loadSession = async (sid) => {
+		if (sessionCache.has(sid)) return sessionCache.get(sid);
+		const s = await kv.get(KV.sessions, sid).catch(() => null);
+		sessionCache.set(sid, s);
+		return s;
+	};
+	let updated = 0;
+	let skipped = 0;
+	let ambiguous = 0;
+	for (const memory of memories) {
+		if (memory.project) {
+			skipped++;
+			continue;
+		}
+		const sessionIds = memory.sessionIds ?? [];
+		if (sessionIds.length === 0) {
+			ambiguous++;
+			continue;
+		}
+		const projects = [];
+		for (const sid of sessionIds) {
+			const session = await loadSession(sid);
+			if (session?.project) projects.push(session.project);
+		}
+		if (projects.length === 0) {
+			ambiguous++;
+			continue;
+		}
+		const freq = /* @__PURE__ */ new Map();
+		for (const p of projects) freq.set(p, (freq.get(p) ?? 0) + 1);
+		const sorted = [...freq.entries()].sort((a, b) => b[1] - a[1]);
+		const [topProject, topCount] = sorted[0];
+		if (topCount <= projects.length / 2 && sorted.length > 1) {
+			ambiguous++;
+			continue;
+		}
+		if (!dryRun) {
+			memory.project = topProject;
+			await kv.set(KV.memories, memory.id, memory);
+		}
+		updated++;
+	}
+	logger.info("inferMemoryProjects complete", {
+		updated,
+		skipped,
+		ambiguous,
+		dryRun
+	});
+	return {
+		updated,
+		skipped,
+		ambiguous
+	};
+}
 function registerMigrateFunction(sdk, kv) {
 	sdk.registerFunction("mem::migrate", async (data) => {
+		if (data.step === "infer-memory-projects") {
+			const dryRun = data.dryRun ?? false;
+			logger.info("Migration step: infer-memory-projects", { dryRun });
+			return {
+				success: true,
+				step: "infer-memory-projects",
+				...await inferMemoryProjects(kv, dryRun)
+			};
+		}
+		if (!data.dbPath) return {
+			success: false,
+			error: "Either step or dbPath is required"
+		};
 		logger.info("Migration started", { dbPath: data.dbPath });
 		if (!isAllowedPath(data.dbPath)) return {
 			success: false,
@@ -5456,9 +5647,10 @@ function registerConsolidateFunction(sdk, kv, provider) {
 				llmCallCount++;
 				const parsed = parseMemoryXml(response, sessionIds);
 				if (!parsed) continue;
-				const existingMatch = existingMemories.find((m) => m.title.toLowerCase() === parsed.title.toLowerCase());
 				const now = (/* @__PURE__ */ new Date()).toISOString();
 				const obsIds = [...new Set(top.map((o) => o.id))];
+				const scopedProject = typeof data.project === "string" && data.project.trim().length > 0 ? data.project.trim() : void 0;
+				const existingMatch = existingMemories.find((m) => m.title.toLowerCase() === parsed.title.toLowerCase() && (!scopedProject || !m.project || m.project === scopedProject));
 				if (existingMatch) {
 					existingMatch.isLatest = false;
 					await kv.set(KV.memories, existingMatch.id, existingMatch);
@@ -5475,7 +5667,8 @@ function registerConsolidateFunction(sdk, kv, provider) {
 						parentId: existingMatch.id,
 						supersedes: [existingMatch.id, ...existingMatch.supersedes || []],
 						sourceObservationIds: obsIds,
-						isLatest: true
+						isLatest: true,
+						...scopedProject !== void 0 && { project: scopedProject }
 					};
 					await kv.set(KV.memories, evolved.id, evolved);
 					await recordAudit(kv, "evolve", "mem::consolidate", [evolved.id], {
@@ -5494,7 +5687,8 @@ function registerConsolidateFunction(sdk, kv, provider) {
 						...parsed,
 						sourceObservationIds: obsIds,
 						version: 1,
-						isLatest: true
+						isLatest: true,
+						...scopedProject !== void 0 && { project: scopedProject }
 					};
 					await kv.set(KV.memories, memory.id, memory);
 					await recordAudit(kv, "remember", "mem::consolidate", [memory.id], {
@@ -5635,6 +5829,7 @@ function registerRememberFunction(sdk, kv) {
 			"fact"
 		]).has(data.type || "") ? data.type : "fact";
 		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const project = typeof data.project === "string" && data.project.trim().length > 0 ? data.project.trim() : void 0;
 		return withKeyedLock("mem:remember", async () => {
 			const existingMemories = await kv.list(KV.memories);
 			let supersededId;
@@ -5643,6 +5838,7 @@ function registerRememberFunction(sdk, kv) {
 			const lowerContent = data.content.toLowerCase();
 			for (const existing of existingMemories) {
 				if (existing.isLatest === false) continue;
+				if (project && existing.project && existing.project !== project) continue;
 				if (jaccardSimilarity(lowerContent, existing.content.toLowerCase()) > .7) {
 					supersededId = existing.id;
 					supersededVersion = existing.version ?? 1;
@@ -5650,6 +5846,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 +5862,9 @@ 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 } : {},
+				...project !== void 0 && { project }
 			};
 			if (data.ttlDays && typeof data.ttlDays === "number" && data.ttlDays > 0) memory.forgetAfter = new Date(Date.now() + data.ttlDays * 864e5).toISOString();
 			if (supersededMemory) {
@@ -5681,7 +5880,7 @@ function registerRememberFunction(sdk, kv) {
 					error: err instanceof Error ? err.message : String(err)
 				});
 			}
-			await vectorIndexAddGuarded(memory.id, memory.sessionIds[0] ?? "memory", memory.title + " " + memory.content, {
+			await vectorIndexAddGuarded(memory.id, memory.sessionIds?.[0] ?? "memory", memory.title + " " + memory.content, {
 				kind: "memory",
 				logId: memory.id
 			});
@@ -5692,7 +5891,8 @@ function registerRememberFunction(sdk, kv) {
 			});
 			logger.info("Memory saved", {
 				memId: memory.id,
-				type: memory.type
+				type: memory.type,
+				project: memory.project
 			});
 			return {
 				success: true,
@@ -5711,6 +5911,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 +5921,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 +5932,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 +5942,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 +6467,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 +6490,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 +6514,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 +6695,8 @@ function registerAutoForgetFunction(sdk, kv) {
 						timestamp: mem.forgetAfter
 					});
 					await deleteAccessLog(kv, mem.id);
+					getSearchIndex().remove(mem.id);
+					vectorIndexRemove(mem.id);
 				}
 			}
 		}
@@ -6557,10 +6774,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 +6793,7 @@ function registerAutoForgetFunction(sdk, kv) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.9.21";
+const VERSION = "0.9.23";
 
 //#endregion
 //#region src/functions/export-import.ts
@@ -6712,7 +6932,9 @@ function registerExportImportFunction(sdk, kv) {
 			"0.9.18",
 			"0.9.19",
 			"0.9.20",
-			"0.9.21"
+			"0.9.21",
+			"0.9.22",
+			"0.9.23"
 		]).has(importData.version)) return {
 			success: false,
 			error: `Unsupported export version: ${importData.version}`
@@ -6835,6 +7057,7 @@ function registerExportImportFunction(sdk, kv) {
 					continue;
 				}
 			}
+			if (!Array.isArray(memory.sessionIds)) memory.sessionIds = [];
 			await kv.set(KV.memories, memory.id, memory);
 			stats.memories++;
 		}
@@ -7038,6 +7261,7 @@ function escapeXml(s) {
 }
 function registerEnrichFunction(sdk, kv) {
 	sdk.registerFunction("mem::enrich", async (data) => {
+		const project = typeof data.project === "string" && data.project.trim().length > 0 ? data.project.trim() : void 0;
 		const parts = [];
 		const fileContextPromise = sdk.trigger({
 			function_id: "mem::file-context",
@@ -7051,10 +7275,11 @@ function registerEnrichFunction(sdk, kv) {
 			function_id: "mem::search",
 			payload: {
 				query: searchQueries.join(" "),
-				limit: 5
+				limit: 5,
+				...project !== void 0 && { project }
 			}
 		}).catch(() => ({ results: [] })) : Promise.resolve({ results: [] });
-		const bugMemoriesPromise = kv.list(KV.memories).then((memories) => memories.filter((m) => m.type === "bug" && m.isLatest && m.files.some((f) => data.files.some((df) => f.includes(df) || df.includes(f)))).sort((a, b) => new Date(b.updatedAt || b.createdAt).getTime() - new Date(a.updatedAt || a.createdAt).getTime())).catch(() => []);
+		const bugMemoriesPromise = kv.list(KV.memories).then((memories) => memories.filter((m) => m.type === "bug" && m.isLatest && (!project || !m.project || m.project === project) && m.files.some((f) => data.files.some((df) => f.includes(df) || df.includes(f)))).sort((a, b) => new Date(b.updatedAt || b.createdAt).getTime() - new Date(a.updatedAt || a.createdAt).getTime())).catch(() => []);
 		const [fileContext, searchResult, bugMemories] = await Promise.all([
 			fileContextPromise,
 			searchPromise,
@@ -7077,6 +7302,7 @@ function registerEnrichFunction(sdk, kv) {
 		}
 		logger.info("Enrichment completed", {
 			sessionId: data.sessionId,
+			project,
 			fileCount: data.files.length,
 			contextLength: context.length,
 			truncated
@@ -7234,16 +7460,24 @@ function buildGraphExtractionPrompt(observations) {
 
 //#endregion
 //#region src/functions/graph.ts
+function parseAttrs(raw) {
+	const attrs = {};
+	const attrRegex = /([A-Za-z_][\w:-]*)="([^"]*)"/g;
+	let m;
+	while ((m = attrRegex.exec(raw)) !== null) attrs[m[1]] = m[2];
+	return attrs;
+}
 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;
-	let match;
-	while ((match = entityRegex.exec(xml)) !== null) {
-		const type = match[1];
-		const name = match[2];
-		const propsBlock = match[3];
+	const entitySelfClose = /<entity\b([^>]*?)\/>/g;
+	const entityWithBody = /<entity\b([^>]*[^/])>([\s\S]*?)<\/entity>/g;
+	const addEntity = (rawAttrs, propsBlock = "") => {
+		const attrs = parseAttrs(rawAttrs);
+		const type = attrs["type"];
+		const name = attrs["name"];
+		if (!type || !name) return;
 		const properties = {};
 		const propRegex = /<property\s+key="([^"]+)">([^<]*)<\/property>/g;
 		let propMatch;
@@ -7256,17 +7490,23 @@ function parseGraphXml(xml, observationIds) {
 			sourceObservationIds: observationIds,
 			createdAt: now
 		});
-	}
-	const relRegex = /<relationship\s+type="([^"]+)"\s+source="([^"]+)"\s+target="([^"]+)"\s+weight="([^"]+)"\s*\/>/g;
+	};
+	let match;
+	while ((match = entitySelfClose.exec(xml)) !== null) addEntity(match[1]);
+	while ((match = entityWithBody.exec(xml)) !== null) addEntity(match[1], match[2]);
+	const relRegex = /<relationship\b([^>]*?)\/>/g;
 	while ((match = relRegex.exec(xml)) !== null) {
-		const type = match[1];
-		const sourceName = match[2];
-		const targetName = match[3];
-		const parsedWeight = parseFloat(match[4]);
-		const weight = Number.isNaN(parsedWeight) ? .5 : parsedWeight;
+		const attrs = parseAttrs(match[1]);
+		const type = attrs["type"];
+		const sourceName = attrs["source"];
+		const targetName = attrs["target"];
+		if (!type || !sourceName || !targetName) continue;
+		const parsedWeight = parseFloat(attrs["weight"] ?? "");
+		const weight = Number.isFinite(parsedWeight) ? parsedWeight : .5;
 		const sourceNode = nodes.find((n) => n.name === sourceName);
 		const targetNode = nodes.find((n) => n.name === targetName);
-		if (sourceNode && targetNode) edges.push({
+		if (!sourceNode || !targetNode) continue;
+		edges.push({
 			id: generateId("ge"),
 			type,
 			sourceNodeId: sourceNode.id,
@@ -7480,7 +7720,7 @@ function registerConsolidationPipelineFunction(sdk, kv, provider) {
 		if (!data?.force && !isConsolidationEnabled()) return {
 			success: false,
 			skipped: true,
-			reason: "CONSOLIDATION_ENABLED is not set to true"
+			reason: "Consolidation disabled: set CONSOLIDATION_ENABLED=true or configure an LLM provider (ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY / MINIMAX_API_KEY / OPENAI_BASE_URL / AGENTMEMORY_PROVIDER=agent-sdk)"
 		};
 		const tier = data?.tier || "all";
 		const decayDays = getConsolidationDecayDays();
@@ -7771,8 +8011,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 +8068,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 +8085,7 @@ function registerGovernanceFunction(sdk, kv) {
 				}
 			});
 		}
+		if (successfulIds.length > 0) await flushIndexSave();
 		await safeAudit(kv, "delete", "mem::governance-bulk", successfulIds, {
 			filter: data,
 			deleted: successfulIds.length,
@@ -10644,11 +10890,34 @@ function registerDiagnosticsFunction(sdk, kv) {
 				});
 				memoryIssues++;
 			}
+			const latestMemories = memories.filter((m) => m.isLatest);
+			const unscopedCount = latestMemories.filter((m) => !m.project).length;
+			if (unscopedCount === 0) checks.push({
+				name: "memory-project-coverage",
+				category: "memories",
+				status: "pass",
+				message: `All ${latestMemories.length} latest memories have a project scope`,
+				fixable: false
+			});
+			else if (unscopedCount <= 10) checks.push({
+				name: "memory-project-coverage",
+				category: "memories",
+				status: "warn",
+				message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — run POST /agentmemory/migrate {"step":"infer-memory-projects"} to backfill`,
+				fixable: true
+			});
+			else checks.push({
+				name: "memory-project-coverage",
+				category: "memories",
+				status: "fail",
+				message: `${unscopedCount} of ${latestMemories.length} latest memories have no project scope — run POST /agentmemory/migrate {"step":"infer-memory-projects"} to backfill`,
+				fixable: true
+			});
 			if (memoryIssues === 0) checks.push({
 				name: "memories-ok",
 				category: "memories",
 				status: "pass",
-				message: `All ${memories.length} memories are consistent`,
+				message: `All ${memories.length} memories are structurally consistent`,
 				fixable: false
 			});
 		}
@@ -13239,6 +13508,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 +13517,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,
@@ -14157,107 +14431,340 @@ 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;
-	return {
-		status_code: 503,
-		body: { error: `${feature} requires AGENTMEMORY_SECRET` }
-	};
+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 flagDisabledResponse(opts) {
+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: opts
+		"Access-Control-Allow-Origin": allowed,
+		"Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+		"Access-Control-Allow-Headers": "Content-Type, Authorization",
+		Vary: "Origin"
 	};
 }
-function graphDisabledResponse() {
-	return flagDisabledResponse({
-		error: "Knowledge graph not enabled",
-		flag: "GRAPH_EXTRACTION_ENABLED",
-		enableHow: "Set GRAPH_EXTRACTION_ENABLED=true and restart. Requires an LLM provider key.",
-		docsHref: "https://github.com/rohitg00/agentmemory#knowledge-graph"
+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 consolidationDisabledResponse() {
-	return flagDisabledResponse({
-		error: "Consolidation pipeline not enabled",
-		flag: "CONSOLIDATION_ENABLED",
-		enableHow: "Set CONSOLIDATION_ENABLED=true and restart. Requires an LLM provider key.",
-		docsHref: "https://github.com/rohitg00/agentmemory#consolidation"
+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);
 	});
 }
-function asNonEmptyString$1(value) {
-	if (typeof value !== "string") return null;
-	const trimmed = value.trim();
-	return trimmed ? trimmed : null;
-}
-function parseOptionalFiniteNumber(value) {
-	if (value === void 0 || value === null) return void 0;
-	if (typeof value === "number") return Number.isFinite(value) ? value : null;
-	if (typeof value === "string") {
-		const trimmed = value.trim();
-		if (!trimmed) return void 0;
-		const parsed = Number(trimmed);
-		return Number.isFinite(parsed) ? parsed : null;
-	}
-	return null;
+const MAX_VIEWER_PORT_RETRIES = 10;
+let boundViewerPort = null;
+let viewerSkipped = false;
+function getBoundViewerPort() {
+	return boundViewerPort;
 }
-function parseOptionalPositiveInt(value) {
-	const parsed = parseOptionalFiniteNumber(value);
-	if (parsed === void 0 || parsed === null) return parsed;
-	if (!Number.isInteger(parsed) || parsed < 1) return null;
-	return parsed;
+function getViewerSkipped() {
+	return viewerSkipped;
 }
-function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
-	sdk.registerFunction("middleware::api-auth", async (input) => {
-		if (!secret) return { action: "continue" };
-		const headers = input?.request?.headers || {};
-		const auth = headers["authorization"] || headers["Authorization"];
-		if (typeof auth !== "string" || !timingSafeCompare(auth, `Bearer ${secret}`)) return {
-			action: "respond",
-			response: {
-				status_code: 401,
-				body: { error: "unauthorized" }
-			}
-		};
-		return { action: "continue" };
-	});
-	sdk.registerFunction("api::liveness", async () => ({
-		status_code: 200,
-		body: {
-			status: "ok",
-			service: "agentmemory"
+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);
 		}
-	}));
-	sdk.registerTrigger({
-		type: "http",
-		function_id: "api::liveness",
-		config: {
-			api_path: "/agentmemory/livez",
-			http_method: "GET"
+		if (!isHostAllowed(req.headers.host, allowedHosts)) {
+			res.writeHead(403, { "Content-Type": "text/plain" });
+			res.end("forbidden host");
+			return;
 		}
-	});
-	sdk.registerFunction("api::config-flags", async (req) => {
-		const authErr = checkAuth(req, secret);
-		if (authErr) return authErr;
-		return {
-			status_code: 200,
-			body: {
+		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
+	};
+}
+function graphDisabledResponse() {
+	return flagDisabledResponse({
+		error: "Knowledge graph not enabled",
+		flag: "GRAPH_EXTRACTION_ENABLED",
+		enableHow: "Set GRAPH_EXTRACTION_ENABLED=true and restart. Requires an LLM provider key.",
+		docsHref: "https://github.com/rohitg00/agentmemory#knowledge-graph"
+	});
+}
+function consolidationDisabledResponse() {
+	return flagDisabledResponse({
+		error: "Consolidation pipeline not enabled",
+		flag: "CONSOLIDATION_ENABLED",
+		enableHow: "Set CONSOLIDATION_ENABLED=true and restart. Requires an LLM provider key.",
+		docsHref: "https://github.com/rohitg00/agentmemory#consolidation"
+	});
+}
+function slotsDisabledResponse() {
+	return flagDisabledResponse({
+		error: "Memory slots not enabled",
+		flag: "AGENTMEMORY_SLOTS",
+		enableHow: "Set AGENTMEMORY_SLOTS=true (in ~/.agentmemory/.env or the shell) and restart.",
+		docsHref: "https://github.com/rohitg00/agentmemory#memory-slots"
+	});
+}
+function reflectDisabledResponse() {
+	return flagDisabledResponse({
+		error: "Slot reflection not enabled",
+		flag: "AGENTMEMORY_REFLECT",
+		enableHow: "Set AGENTMEMORY_REFLECT=true (in ~/.agentmemory/.env or the shell) and restart. Requires AGENTMEMORY_SLOTS=true.",
+		docsHref: "https://github.com/rohitg00/agentmemory#memory-slots"
+	});
+}
+function asNonEmptyString$1(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed ? trimmed : null;
+}
+function parseOptionalFiniteNumber(value) {
+	if (value === void 0 || value === null) return void 0;
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (!trimmed) return void 0;
+		const parsed = Number(trimmed);
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	return null;
+}
+function parseOptionalPositiveInt(value) {
+	const parsed = parseOptionalFiniteNumber(value);
+	if (parsed === void 0 || parsed === null) return parsed;
+	if (!Number.isInteger(parsed) || parsed < 1) return null;
+	return parsed;
+}
+function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
+	sdk.registerFunction("middleware::api-auth", async (input) => {
+		if (!secret) return { action: "continue" };
+		const headers = input?.request?.headers || {};
+		const auth = headers["authorization"] || headers["Authorization"];
+		if (typeof auth !== "string" || !timingSafeCompare(auth, `Bearer ${secret}`)) return {
+			action: "respond",
+			response: {
+				status_code: 401,
+				body: { error: "unauthorized" }
+			}
+		};
+		return { action: "continue" };
+	});
+	sdk.registerFunction("api::liveness", async () => ({
+		status_code: 200,
+		body: {
+			status: "ok",
+			service: "agentmemory",
+			viewerPort: getBoundViewerPort(),
+			viewerSkipped: getViewerSkipped()
+		}
+	}));
+	sdk.registerTrigger({
+		type: "http",
+		function_id: "api::liveness",
+		config: {
+			api_path: "/agentmemory/livez",
+			http_method: "GET"
+		}
+	});
+	sdk.registerFunction("api::config-flags", async (req) => {
+		const authErr = checkAuth(req, secret);
+		if (authErr) return authErr;
+		return {
+			status_code: 200,
+			body: {
 				version: VERSION,
 				provider: detectLlmProviderKind(),
 				embeddingProvider: detectEmbeddingProvider() ? "embeddings" : "none",
@@ -14336,7 +14843,9 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 				version: VERSION,
 				health: health || null,
 				functionMetrics,
-				circuitBreaker
+				circuitBreaker,
+				viewerPort: getBoundViewerPort(),
+				viewerSkipped: getViewerSkipped()
 			}
 		};
 	});
@@ -14590,6 +15099,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 +15108,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 {
@@ -14639,6 +15150,14 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			path: "status",
 			value: "completed"
 		}]);
+		try {
+			sdk.triggerVoid("event::session::stopped", { sessionId });
+		} catch (err) {
+			logger.warn("event::session::stopped triggerVoid failed", {
+				sessionId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
 		return {
 			status_code: 200,
 			body: { success: true }
@@ -14785,9 +15304,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 +15329,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({
@@ -14849,11 +15376,21 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			status_code: 400,
 			body: { error: "terms must be an array of strings" }
 		};
+		if (req.body.project !== void 0 && (typeof req.body.project !== "string" || !req.body.project.trim())) return {
+			status_code: 400,
+			body: { error: "project must be a non-empty string" }
+		};
 		return {
 			status_code: 200,
 			body: await sdk.trigger({
 				function_id: "mem::enrich",
-				payload: req.body
+				payload: {
+					sessionId: req.body.sessionId,
+					files: req.body.files,
+					...req.body.terms !== void 0 && { terms: req.body.terms },
+					...req.body.toolName !== void 0 && { toolName: req.body.toolName },
+					...req.body.project !== void 0 && { project: req.body.project }
+				}
 			})
 		};
 	});
@@ -14872,11 +15409,23 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			status_code: 400,
 			body: { error: "content is required" }
 		};
+		if (req.body.project !== void 0 && (typeof req.body.project !== "string" || !req.body.project.trim())) return {
+			status_code: 400,
+			body: { error: "project must be a non-empty string" }
+		};
 		return {
 			status_code: 201,
 			body: await sdk.trigger({
 				function_id: "mem::remember",
-				payload: req.body
+				payload: {
+					content: req.body.content,
+					...req.body.type !== void 0 && { type: req.body.type },
+					...req.body.concepts !== void 0 && { concepts: req.body.concepts },
+					...req.body.files !== void 0 && { files: req.body.files },
+					...req.body.ttlDays !== void 0 && { ttlDays: req.body.ttlDays },
+					...req.body.sourceObservationIds !== void 0 && { sourceObservationIds: req.body.sourceObservationIds },
+					...req.body.project !== void 0 && { project: req.body.project }
+				}
 			})
 		};
 	});
@@ -14971,15 +15520,21 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::migrate", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
-		if (!req.body?.dbPath || typeof req.body.dbPath !== "string") return {
+		const hasStep = typeof req.body?.step === "string" && req.body.step.trim().length > 0;
+		const hasDbPath = typeof req.body?.dbPath === "string" && req.body.dbPath.trim().length > 0;
+		if (!hasStep && !hasDbPath) return {
 			status_code: 400,
-			body: { error: "dbPath is required" }
+			body: { error: "Either step (string) or dbPath (string) is required" }
 		};
 		return {
 			status_code: 200,
 			body: await sdk.trigger({
 				function_id: "mem::migrate",
-				payload: req.body
+				payload: {
+					...req.body.step !== void 0 && { step: req.body.step },
+					...req.body.dbPath !== void 0 && { dbPath: req.body.dbPath },
+					...req.body.dryRun !== void 0 && { dryRun: req.body.dryRun }
+				}
 			})
 		};
 	});
@@ -15084,11 +15639,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
 			})
 		};
 	});
@@ -15314,6 +15880,63 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			http_method: "POST"
 		}
 	});
+	sdk.registerFunction("api::graph-build", async (req) => {
+		const authErr = checkAuth(req, secret);
+		if (authErr) return authErr;
+		const batchSize = Math.max(1, Math.min(100, Number(req.body?.batchSize) || 25));
+		try {
+			const sessions = await kv.list(KV.sessions);
+			let totalNodes = 0;
+			let totalEdges = 0;
+			let batchesRun = 0;
+			for (const session of sessions) {
+				const sid = session?.id;
+				if (typeof sid !== "string" || sid.length === 0) continue;
+				const compressed = (await kv.list(KV.observations(sid))).filter((o) => o && typeof o.title === "string" && o.title.length > 0);
+				if (compressed.length === 0) continue;
+				for (let i = 0; i < compressed.length; i += batchSize) {
+					const batch = compressed.slice(i, i + batchSize);
+					try {
+						const result = await sdk.trigger({
+							function_id: "mem::graph-extract",
+							payload: { observations: batch }
+						});
+						if (result?.success) {
+							totalNodes += Number(result.nodesAdded) || 0;
+							totalEdges += Number(result.edgesAdded) || 0;
+						}
+						batchesRun++;
+					} catch (err) {
+						logger.warn("graph-build batch failed", {
+							sessionId: sid,
+							batchIndex: Math.floor(i / batchSize),
+							error: err instanceof Error ? err.message : String(err)
+						});
+					}
+				}
+			}
+			return {
+				status_code: 200,
+				body: {
+					success: true,
+					sessions: sessions.length,
+					batches: batchesRun,
+					nodes: totalNodes,
+					edges: totalEdges
+				}
+			};
+		} catch {
+			return graphDisabledResponse();
+		}
+	});
+	sdk.registerTrigger({
+		type: "http",
+		function_id: "api::graph-build",
+		config: {
+			api_path: "/agentmemory/graph/build",
+			http_method: "POST"
+		}
+	});
 	sdk.registerFunction("api::consolidate-pipeline", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
@@ -15574,9 +16197,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({
@@ -15745,6 +16394,7 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::slot-list", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		if (!isSlotsEnabled()) return slotsDisabledResponse();
 		return {
 			status_code: 200,
 			body: await sdk.trigger({
@@ -15764,6 +16414,7 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::slot-get", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		if (!isSlotsEnabled()) return slotsDisabledResponse();
 		const label = asNonEmptyString$1(req.query_params?.["label"]);
 		if (!label) return {
 			status_code: 400,
@@ -15794,6 +16445,7 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::slot-create", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		if (!isSlotsEnabled()) return slotsDisabledResponse();
 		const body = req.body ?? {};
 		const label = asNonEmptyString$1(body["label"]);
 		if (!label) return {
@@ -15856,6 +16508,7 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::slot-append", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		if (!isSlotsEnabled()) return slotsDisabledResponse();
 		const body = req.body ?? {};
 		const label = asNonEmptyString$1(body["label"]);
 		const text = typeof body["text"] === "string" ? body["text"] : null;
@@ -15895,6 +16548,7 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::slot-replace", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		if (!isSlotsEnabled()) return slotsDisabledResponse();
 		const body = req.body ?? {};
 		const label = asNonEmptyString$1(body["label"]);
 		const content = body["content"];
@@ -15934,6 +16588,7 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::slot-delete", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		if (!isSlotsEnabled()) return slotsDisabledResponse();
 		const label = asNonEmptyString$1(req.query_params?.["label"]);
 		if (!label) return {
 			status_code: 400,
@@ -15964,6 +16619,8 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::slot-reflect", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		if (!isSlotsEnabled()) return slotsDisabledResponse();
+		if (!isReflectEnabled()) return reflectDisabledResponse();
 		const body = req.body ?? {};
 		const sessionId = asNonEmptyString$1(body["sessionId"]);
 		if (!sessionId) return {
@@ -17616,6 +18273,10 @@ const CORE_TOOLS = [
 				files: {
 					type: "string",
 					description: "Comma-separated relevant file paths"
+				},
+				project: {
+					type: "string",
+					description: "Stable canonical project identifier this memory belongs to (e.g. a slug, UUID, or registry key). Must match the value used when the session was started. Do not use filesystem paths or ad-hoc display names — those change across machines and will silently break project scoping."
 				}
 			},
 			required: ["content"]
@@ -18656,8 +19317,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
@@ -18772,13 +19433,15 @@ function registerMcpEndpoints(sdk, kv, secret) {
 					const type = args.type || "fact";
 					const concepts = typeof args.concepts === "string" ? args.concepts.split(",").map((c) => c.trim()).filter(Boolean) : [];
 					const files = typeof args.files === "string" ? args.files.split(",").map((f) => f.trim()).filter(Boolean) : [];
+					const project = typeof args.project === "string" && args.project.trim().length > 0 ? args.project.trim() : void 0;
 					const result = await sdk.trigger({
 						function_id: "mem::remember",
 						payload: {
 							content: args.content,
 							type,
 							concepts,
-							files
+							files,
+							...project !== void 0 && { project }
 						}
 					});
 					return {
@@ -20295,201 +20958,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 +21095,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 +21150,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 +21246,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;
@@ -20803,7 +21288,7 @@ async function main() {
 			if (bm25Index.has(memory.id)) continue;
 			bm25Index.add({
 				id: memory.id,
-				sessionId: memory.sessionIds[0] ?? "memory",
+				sessionId: memory.sessionIds?.[0] ?? "memory",
 				timestamp: memory.createdAt,
 				type: "decision",
 				title: memory.title,
@@ -20823,7 +21308,7 @@ async function main() {
 		console.warn(`[agentmemory] Failed to backfill memories into BM25:`, err);
 	}
 	bootLog(`Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`);
-	bootLog(`REST API: 124 endpoints at http://localhost:${config.restPort}/agentmemory/*`);
+	bootLog(`REST API: 125 endpoints at http://localhost:${config.restPort}/agentmemory/*`);
 	bootLog(`MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`);
 	const viewerServer = startViewerServer(config.restPort + 2, kv, sdk, secret, config.restPort);
 	const autoForgetIntervalMs = parseInt(process.env.AUTO_FORGET_INTERVAL_MS || "3600000", 10);
@@ -20879,6 +21364,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);