@agentmemory/agentmemory 0.9.30 → 0.9.32

package/dist/{secret-store-BnY3A50C.mjs → secret-store-iYXRcrO8.mjs}

@@ -1,373 +1,22 @@
-import { o as generateId, r as KV, t as withKeyedLock } from "./keyed-mutex-DchXsyfP.mjs";
-import { chmodSync, closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync, writeSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { a as KV, r as withKeyedLock, s as generateId } from "./keyed-mutex-DCUh7PG-.mjs";
+import { chmodSync, closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
 import { homedir } from "node:os";
 import pc from "picocolors";
 import { randomBytes } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
-//#region src/cli/engine-config.ts
-const SEEDED_BUILTIN_WORKERS = [
-	"http",
-	"iii-http",
-	"state",
-	"iii-state",
-	"queue",
-	"iii-queue",
-	"pubsub",
-	"iii-pubsub",
-	"cron",
-	"iii-cron",
-	"iii-stream",
-	"iii-observability",
-	"iii-worker-manager"
-];
-function configuredPersistDir(renderedConfig) {
-	const lines = renderedConfig.split("\n");
-	const block = workerBlock(lines, "configuration");
-	if (!block) return null;
-	for (let i = block.start + 1; i < block.end; i++) {
-		const match = lines[i].trim().match(/^directory:\s*(.+?)\s*$/);
-		if (match) return match[1].replace(/^(['"])(.*)\1$/, "$2");
-	}
-	return null;
-}
-const ENGINE_DEFAULT_SAVE_INTERVAL_MS = 5e3;
-const ENGINE_FLUSH_MARGIN_MS = 1500;
-function engineFlushWaitMs(stateBackend, configTexts) {
-	if (stateBackend === "redis") return 0;
-	return engineSaveIntervalMs(configTexts) + ENGINE_FLUSH_MARGIN_MS;
-}
-function captureDurableAfterMs(stateBackend, configTexts) {
-	if (stateBackend === "redis") return ENGINE_FLUSH_MARGIN_MS;
-	return engineSaveIntervalMs(configTexts) + ENGINE_FLUSH_MARGIN_MS;
-}
-function engineSaveIntervalMs(configTexts) {
-	const intervals = [];
-	for (const text of configTexts) {
-		const explicit = [...text.matchAll(/save_interval_ms:\s*(\d+)/g)].map((m) => parseInt(m[1], 10));
-		intervals.push(...explicit);
-		if ((text.match(/store_method:\s*file_based/g)?.length ?? 0) > explicit.length) intervals.push(ENGINE_DEFAULT_SAVE_INTERVAL_MS);
-	}
-	return intervals.length > 0 ? Math.max(...intervals) : ENGINE_DEFAULT_SAVE_INTERVAL_MS;
-}
-function engineStateConfigPaths(engineCwd, runtimePath) {
-	return [...persistedBuiltinConfigDirs(engineCwd, runtimePath).map((dir) => join(dir, "iii-state.yaml")), runtimePath];
-}
-function persistedBuiltinConfigDirs(engineCwd, configPath, renderedConfig) {
-	const dirs = [
-		join(engineCwd, "config"),
-		join(dirname(configPath), "config"),
-		join(engineCwd, "data", "configuration")
-	];
-	const custom = renderedConfig ? configuredPersistDir(renderedConfig) : null;
-	if (custom) dirs.unshift(resolve(engineCwd, custom));
-	return [...new Set(dirs)];
-}
-function persistedBuiltinConfigPaths(engineCwd, configPath, renderedConfig) {
-	return persistedBuiltinConfigDirs(engineCwd, configPath, renderedConfig).flatMap((dir) => SEEDED_BUILTIN_WORKERS.map((id) => join(dir, `${id}.yaml`)));
-}
-function isPersistedBuiltinEntry(content, id) {
-	return content.split("\n").find((line) => line.trim() !== "")?.trim() === `id: ${id}`;
-}
-function clearPersistedBuiltinConfig(engineCwd, configPath, renderedConfig) {
-	const cleared = [];
-	for (const path of persistedBuiltinConfigPaths(engineCwd, configPath, renderedConfig)) try {
-		if (!isPersistedBuiltinEntry(readFileSync(path, "utf8"), basename(path, ".yaml"))) continue;
-		rmSync(path);
-		cleared.push(path);
-	} catch (err) {
-		if (err.code === "ENOENT") continue;
-		throw new Error(`could not remove persisted engine config ${path}: ${String(err)}`);
-	}
-	return cleared;
-}
-function yamlSingleQuote(value) {
-	return `'${value.replace(/'/g, "''")}'`;
-}
-function workerBlock(lines, name) {
-	const marker = `- name: ${name}`;
-	const start = lines.findIndex((line) => line.trim() === marker);
-	if (start === -1) return null;
-	const indent = lines[start].match(/^\s*/)?.[0] ?? "";
-	let end = lines.length;
-	for (let i = start + 1; i < lines.length; i++) {
-		const line = lines[i];
-		if (line.startsWith(indent) && line.trim().startsWith("- name: ")) {
-			end = i;
-			break;
-		}
-	}
-	return {
-		start,
-		end,
-		indent
-	};
-}
-function setWorkerPort(lines, name, port) {
-	let block = workerBlock(lines, name);
-	if (!block && name === "iii-worker-manager") {
-		const workersIndex = lines.findIndex((line) => line.trim() === "workers:");
-		if (workersIndex === -1) return;
-		lines.splice(workersIndex + 1, 0, "  - name: iii-worker-manager", "    config:", `      port: ${port}`, "      host: 127.0.0.1");
-		return;
-	}
-	if (!block) return;
-	const portIndex = lines.findIndex((line, index) => index > block.start && index < block.end && line.trim().startsWith("port:"));
-	if (portIndex !== -1) {
-		lines[portIndex] = `${lines[portIndex].match(/^\s*/)?.[0] ?? `${block.indent}    `}port: ${port}`;
-		return;
-	}
-	const configIndex = lines.findIndex((line, index) => index > block.start && index < block.end && line.trim() === "config:");
-	if (configIndex !== -1) {
-		const configIndent = lines[configIndex].match(/^\s*/)?.[0] ?? `${block.indent}  `;
-		lines.splice(configIndex + 1, 0, `${configIndent}  port: ${port}`);
-	}
-}
-function setFileStoreSaveInterval(lines, workerName, override) {
-	const block = workerBlock(lines, workerName);
-	if (!block) return;
-	const methodIndex = lines.findIndex((line, index) => index > block.start && index < block.end && line.trim() === "store_method: file_based");
-	if (methodIndex === -1) return;
-	const indent = lines[methodIndex].match(/^\s*/)?.[0] ?? "";
-	const intervalIndex = lines.findIndex((line, index) => index > block.start && index < block.end && line.trim().startsWith("save_interval_ms:"));
-	if (intervalIndex !== -1) {
-		if (override === void 0) return;
-		lines[intervalIndex] = `${lines[intervalIndex].match(/^\s*/)?.[0] ?? indent}save_interval_ms: ${override}`;
-		return;
-	}
-	lines.splice(methodIndex + 1, 0, `${indent}save_interval_ms: ${override ?? 2e3}`);
-}
-const REDIS_URL_ENV_REF = "${AGENTMEMORY_REDIS_URL}";
-const UNSAFE_REDIS_URL_CHARS = /['\u0000-\u001f\u007f]/;
-function replaceKvAdapterWithRedis(lines, workerName) {
-	const block = workerBlock(lines, workerName);
-	if (!block) throw new Error(`AGENTMEMORY_STATE_BACKEND=redis requires a "${workerName}" worker in the engine config, but none was found.`);
-	const adapterIndex = lines.findIndex((line, index) => index > block.start && index < block.end && line.trim() === "adapter:");
-	if (adapterIndex === -1) throw new Error(`AGENTMEMORY_STATE_BACKEND=redis requires an "adapter:" block under the "${workerName}" worker in the engine config, but none was found.`);
-	const adapterIndent = lines[adapterIndex].match(/^\s*/)?.[0] ?? "";
-	let end = block.end;
-	for (let i = adapterIndex + 1; i < block.end; i++) {
-		const line = lines[i];
-		if (line.trim() === "") continue;
-		if ((line.match(/^\s*/)?.[0] ?? "").length <= adapterIndent.length) {
-			end = i;
-			break;
-		}
-	}
-	const childIndent = `${adapterIndent}  `;
-	const grandchildIndent = `${adapterIndent}    `;
-	lines.splice(adapterIndex + 1, end - (adapterIndex + 1), `${childIndent}name: redis`, `${childIndent}config:`, `${grandchildIndent}redis_url: ${yamlSingleQuote(REDIS_URL_ENV_REF)}`);
-}
-function setManagedCorsOrigins(lines, restPort, viewerPort) {
-	const block = workerBlock(lines, "iii-http");
-	if (!block) return;
-	const originsIndex = lines.findIndex((line, index) => index > block.start && index < block.end && line.trim().startsWith("allowed_origins:"));
-	if (originsIndex === -1) return;
-	lines[originsIndex] = `${lines[originsIndex].match(/^\s*/)?.[0] ?? "        "}allowed_origins: ["http://localhost:${restPort}", "http://localhost:${viewerPort}", "http://127.0.0.1:${restPort}", "http://127.0.0.1:${viewerPort}"]`;
-}
-function renderEngineConfig(template, options) {
-	if (options.stateBackend?.kind === "redis" && !options.stateBackend.redisUrl) throw new Error("AGENTMEMORY_STATE_BACKEND=redis requires AGENTMEMORY_REDIS_URL to be set (e.g. redis://localhost:6379).");
-	if (options.stateBackend?.kind === "redis" && UNSAFE_REDIS_URL_CHARS.test(options.stateBackend.redisUrl ?? "")) throw new Error("AGENTMEMORY_REDIS_URL contains a single quote or a control character, which breaks the engine config once the engine expands it. Percent-encode those characters in the URL (for example a single quote as %27).");
-	const rendered = template.replace("file_path: ./data/state_store.db", `file_path: ${yamlSingleQuote(join(options.dataDir, "state_store.db"))}`).replace("file_path: ./data/stream_store", `file_path: ${yamlSingleQuote(join(options.dataDir, "stream_store"))}`);
-	const usesRedis = options.stateBackend?.kind === "redis";
-	const lines = rendered.split("\n");
-	setFileStoreSaveInterval(lines, "iii-state", options.saveIntervalMs);
-	setFileStoreSaveInterval(lines, "iii-stream", options.saveIntervalMs);
-	if (options.ports) {
-		setWorkerPort(lines, "iii-http", options.ports.restPort);
-		setWorkerPort(lines, "iii-stream", options.ports.streamPort);
-		setWorkerPort(lines, "iii-worker-manager", options.ports.enginePort);
-		setManagedCorsOrigins(lines, options.ports.restPort, options.ports.viewerPort);
-	}
-	if (usesRedis) {
-		replaceKvAdapterWithRedis(lines, "iii-state");
-		replaceKvAdapterWithRedis(lines, "iii-stream");
-	}
-	return lines.join("\n");
-}
-//#endregion
-//#region src/cli/engine-launch.ts
-function agentmemoryHome(home) {
-	return join(home, ".agentmemory");
-}
-function runtimeConfigPath(dataDir) {
-	return join(dataDir, "iii-config.runtime.yaml");
-}
-function dockerProjectName(restPort) {
-	return `agentmemory-${restPort}`;
-}
-function dockerComposeArgs(composeFile, projectName, command) {
-	return [
-		"compose",
-		...projectName ? ["-p", projectName] : [],
-		"-f",
-		composeFile,
-		...command
-	];
-}
-function isBundledConfig(configPath, packageDir) {
-	const resolved = resolve(configPath);
-	return resolved === resolve(join(packageDir, "iii-config.yaml")) || resolved === resolve(join(packageDir, "..", "iii-config.yaml"));
-}
-function resolveEngineCwd(configPath, invocationCwd, home, bundledConfig = false) {
-	if (bundledConfig) return agentmemoryHome(home);
-	return dirname(isAbsolute(configPath) ? configPath : resolve(invocationCwd, configPath));
-}
-function indentation(line) {
-	return line.length - line.trimStart().length;
-}
-function yamlScalar(value) {
-	const trimmed = value.trim();
-	const first = trimmed[0];
-	const last = trimmed.at(-1);
-	if (first === "\"" && last === "\"" || first === "'" && last === "'") return trimmed.slice(1, -1);
-	return trimmed;
-}
-function isAgentmemoryExecCommand(line, nodeBin, workerEntry) {
-	const match = line.match(/^\s*-\s+(.+?)\s*$/);
-	if (!match) return false;
-	const command = yamlScalar(match[1]).replaceAll("\\", "/");
-	return command === `${nodeBin} ${workerEntry}`.replaceAll("\\", "/") || /^(?:node|node\.exe)\s+\.\/dist\/index\.mjs$/.test(command) || /^(?:node|node\.exe)\s+dist\/index\.mjs$/.test(command);
-}
-function removeAgentmemoryExecCommand(raw, nodeBin, workerEntry) {
-	const lines = raw.split("\n");
-	const output = [];
-	let index = 0;
-	while (index < lines.length) {
-		const line = lines[index];
-		if (line.trim() !== "- name: iii-exec") {
-			output.push(line);
-			index++;
-			continue;
-		}
-		const blockIndent = indentation(line);
-		let blockEnd = index + 1;
-		while (blockEnd < lines.length) {
-			const candidate = lines[blockEnd];
-			if (candidate.trim() !== "") {
-				const candidateIndent = indentation(candidate);
-				if (candidateIndent < blockIndent || candidateIndent === blockIndent && candidate.trim().startsWith("- name: ")) break;
-			}
-			blockEnd++;
-		}
-		const block = lines.slice(index, blockEnd);
-		const execIndex = block.findIndex((candidate) => candidate.trim() === "exec:");
-		if (execIndex === -1) {
-			output.push(...block);
-			index = blockEnd;
-			continue;
-		}
-		const execIndent = indentation(block[execIndex]);
-		let execEnd = execIndex + 1;
-		while (execEnd < block.length) {
-			const candidate = block[execEnd];
-			if (candidate.trim() !== "" && indentation(candidate) <= execIndent) break;
-			execEnd++;
-		}
-		const beforeExec = block.slice(0, execIndex + 1);
-		const execLines = block.slice(execIndex + 1, execEnd);
-		const afterExec = block.slice(execEnd);
-		const remainingExecLines = execLines.filter((candidate) => !isAgentmemoryExecCommand(candidate, nodeBin, workerEntry));
-		const removed = remainingExecLines.length !== execLines.length;
-		const hasExecCommand = remainingExecLines.some((candidate) => /^\s*-\s+/.test(candidate) && indentation(candidate) > execIndent);
-		if (!removed) output.push(...block);
-		else if (hasExecCommand) output.push(...beforeExec, ...remainingExecLines, ...afterExec);
-		index = blockEnd;
-	}
-	return output.join("\n");
-}
-function rewriteBundledConfig(raw, home, nodeBin, workerEntry, options) {
-	return removeAgentmemoryExecCommand(renderEngineConfig(raw, {
-		dataDir: options?.dataDir ?? join(agentmemoryHome(home), "data"),
-		...options?.ports ? { ports: options.ports } : {},
-		...options?.stateBackend ? { stateBackend: options.stateBackend } : {},
-		...options?.saveIntervalMs !== void 0 ? { saveIntervalMs: options.saveIntervalMs } : {}
-	}), nodeBin, workerEntry);
-}
-function legacyDataMigrations(invocationCwd, home, resolvedDataDir = join(agentmemoryHome(home), "data")) {
-	return [{
-		from: join(invocationCwd, "data", "state_store.db"),
-		to: join(resolvedDataDir, "state_store.db")
-	}, {
-		from: join(invocationCwd, "data", "stream_store"),
-		to: join(resolvedDataDir, "stream_store")
-	}];
-}
-function engineChildEnv(base, platform = process.platform) {
-	const env = {
-		...base,
-		III_TELEMETRY_ENABLED: base["III_TELEMETRY_ENABLED"] ?? "false"
-	};
-	if (platform === "linux" && !base.MALLOC_ARENA_MAX) env.MALLOC_ARENA_MAX = "2";
-	return env;
-}
-function resolveLaunchRenderFailure(stateBackendKind, err) {
-	if (stateBackendKind !== "redis") return { fatal: false };
-	return {
-		fatal: true,
-		message: `Failed to render the Redis state backend into the engine config: ${err instanceof Error ? err.message : String(err)} Refusing to start the engine, since it would silently fall back to the file (or in-memory) store instead of Redis. Fix the config or unset AGENTMEMORY_STATE_BACKEND to use the default file store.`
-	};
-}
-const CREDENTIAL_URL_PATTERN = /:\/\/[^@\s/]*@/g;
-function redactCredentialUrls(text) {
-	return text.replace(CREDENTIAL_URL_PATTERN, "://***@");
-}
-//#endregion
-//#region src/logger.ts
-function fmt(level, msg, fields) {
-	if (!fields || Object.keys(fields).length === 0) return `[agentmemory] ${level} ${msg}`;
-	try {
-		return `[agentmemory] ${level} ${msg} ${JSON.stringify(fields)}`;
-	} catch {
-		return `[agentmemory] ${level} ${msg}`;
-	}
-}
-function emit(level, msg, fields) {
-	try {
-		process.stderr.write(fmt(level, msg, fields) + "\n");
-	} catch {}
-}
-const logger = {
-	info(msg, fields) {
-		emit("info", msg, fields);
-	},
-	warn(msg, fields) {
-		emit("warn", msg, fields);
-	},
-	error(msg, fields) {
-		emit("error", msg, fields);
-	}
-};
-let bootVerbose = process.env["AGENTMEMORY_VERBOSE"] === "1" || process.env["AGENTMEMORY_VERBOSE"] === "true";
-const bootBuffer = [];
-function setBootVerbose(enabled) {
-	bootVerbose = enabled;
-}
-function bootLog(msg) {
-	if (bootVerbose) {
-		try {
-			process.stderr.write(`[agentmemory] ${msg}\n`);
-		} catch {}
-		return;
-	}
-	if (bootBuffer.length < 500) bootBuffer.push(msg);
-}
-function bootWarn(msg) {
-	try {
-		process.stderr.write(`[agentmemory] warn ${msg}\n`);
-	} catch {}
-}
-//#endregion
 //#region src/config.ts
+const MAX_IMPORT_OBS_PER_SESSION = 5e3;
 function safeParseInt(value, fallback) {
 	if (!value) return fallback;
 	const parsed = parseInt(value, 10);
 	return Number.isNaN(parsed) ? fallback : parsed;
 }
-const DATA_DIR = join(homedir(), ".agentmemory");
-const ENV_FILE = join(DATA_DIR, ".env");
+const DATA_DIR = process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
+const ENV_FILE = process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env");
 let warnPremiumModelShown = false;
 let providerNoticeShown = false;
+let obsCapImportCeilingWarned = false;
 function writeProviderNoticeOnce(text) {
 	if (providerNoticeShown) return;
 	providerNoticeShown = true;
@@ -380,7 +29,10 @@ function loadEnvFile() {
 		envFileCache = {};
 		return envFileCache;
 	}
-	const content = readFileSync(ENV_FILE, "utf-8");
+	envFileCache = parseEnvContent(readFileSync(ENV_FILE, "utf-8"));
+	return envFileCache;
+}
+function parseEnvContent(content) {
 	const vars = {};
 	for (const line of content.split("\n")) {
 		const trimmed = line.trim();
@@ -399,61 +51,135 @@ function loadEnvFile() {
 		}
 		vars[key] = val;
 	}
-	envFileCache = vars;
-	return envFileCache;
+	return vars;
 }
 function hasRealValue(v) {
 	return typeof v === "string" && v.trim().length > 0;
 }
 function hydrateProcessEnvFromFile() {
+	const beforeHydration = { ...process.env };
 	for (const [k, v] of Object.entries(loadEnvFile())) if (process.env[k] === void 0) process.env[k] = v;
+	return beforeHydration;
+}
+function warnIfPremiumModel(env, envName, model) {
+	if (warnPremiumModelShown || !/sonnet|opus|gpt-5\.\d+-sol|gpt-4o(?!.*mini)|gpt-4-turbo/i.test(model) || env["AGENTMEMORY_SUPPRESS_COST_WARNING"] === "1" || env["AGENTMEMORY_SUPPRESS_COST_WARNING"] === "true") return;
+	warnPremiumModelShown = true;
+	process.stderr.write(`[agentmemory] ${envName}=${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-flash-0731, deepseek/deepseek-v4-pro, qwen/qwen3-coder. See README "Cost-aware model selection" for the full table. Set AGENTMEMORY_SUPPRESS_COST_WARNING=1 to silence.\n`);
+}
+const LLM_PROVIDER_NAMES = [
+	"anthropic",
+	"openai",
+	"gemini",
+	"openrouter",
+	"minimax"
+];
+const LLM_PROVIDER_KEYS = {
+	anthropic: ["ANTHROPIC_API_KEY"],
+	openai: ["OPENAI_API_KEY"],
+	gemini: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+	openrouter: ["OPENROUTER_API_KEY"],
+	minimax: ["MINIMAX_API_KEY"]
+};
+const REMOTE_EMBEDDING_PROVIDER_KEYS = {
+	gemini: ["GEMINI_API_KEY"],
+	openai: ["OPENAI_API_KEY", "OPENAI_EMBEDDING_API_KEY"],
+	voyage: ["VOYAGE_API_KEY"],
+	cohere: ["COHERE_API_KEY"],
+	openrouter: ["OPENROUTER_API_KEY"]
+};
+function isLlmProviderName(value) {
+	return LLM_PROVIDER_NAMES.includes(value);
+}
+function selectedLlmProviderValue(env) {
+	return (env["AGENTMEMORY_LLM_PROVIDER"] || "").trim().toLowerCase();
+}
+function llmProviderHasKey(env, name) {
+	return LLM_PROVIDER_KEYS[name].some((k) => hasRealValue(env[k]));
+}
+function envFileLabel(path = ENV_FILE) {
+	const home = homedir();
+	return path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+function llmOptInHint(env = getMergedEnv()) {
+	const selected = selectedLlmProviderValue(env);
+	if (selected) {
+		if (!isLlmProviderName(selected)) return `AGENTMEMORY_LLM_PROVIDER=${selected} is not a known provider. Use one of: ${LLM_PROVIDER_NAMES.join(", ")}.`;
+		if (!llmProviderHasKey(env, selected)) return `AGENTMEMORY_LLM_PROVIDER=${selected} is set, but ${LLM_PROVIDER_KEYS[selected].join(" or ")} is not. Add the key to ${envFileLabel()}.`;
+		return null;
+	}
+	if (env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true") return null;
+	const withKey = LLM_PROVIDER_NAMES.filter((name) => llmProviderHasKey(env, name));
+	if (withKey.length === 0) return null;
+	return `Found ${withKey.flatMap((name) => LLM_PROVIDER_KEYS[name].filter((k) => hasRealValue(env[k]))).join(", ")}, but agentmemory sends nothing to an LLM provider until you choose one for it. To turn on LLM summaries and compression, add AGENTMEMORY_LLM_PROVIDER=${withKey[0]} to ${envFileLabel()}.`;
+}
+function embeddingOptInHint(env = getMergedEnv()) {
+	const chosen = (env["EMBEDDING_PROVIDER"] || "").trim().toLowerCase();
+	if (chosen) {
+		const keys = REMOTE_EMBEDDING_PROVIDER_KEYS[chosen];
+		if (keys && !keys.some((k) => hasRealValue(env[k]))) return `EMBEDDING_PROVIDER=${chosen} is set, but ${keys.join(" or ")} is not. Add the key to ${envFileLabel()}, or set EMBEDDING_PROVIDER=local for on-device embeddings.`;
+		return null;
+	}
+	const withKey = Object.keys(REMOTE_EMBEDDING_PROVIDER_KEYS).filter((name) => REMOTE_EMBEDDING_PROVIDER_KEYS[name].some((k) => hasRealValue(env[k])));
+	if (withKey.length === 0) return null;
+	return `A ${withKey.join("/")} key is present, but cloud embeddings stay off until you choose them. Add EMBEDDING_PROVIDER=${withKey[0]} to ${envFileLabel()}, or EMBEDDING_PROVIDER=local for on-device embeddings.`;
 }
 function detectProvider(env) {
 	const maxTokens = parseInt(env["MAX_TOKENS"] || "4096", 10);
-	if (hasRealValue(env["OPENAI_API_KEY"]) && env["OPENAI_API_KEY_FOR_LLM"] !== "false") return {
-		provider: "openai",
-		model: env["OPENAI_MODEL"] || "gpt-5.6-luna",
-		maxTokens,
-		baseURL: env["OPENAI_BASE_URL"]
-	};
-	if (hasRealValue(env["MINIMAX_API_KEY"])) return {
-		provider: "minimax",
-		model: env["MINIMAX_MODEL"] || "MiniMax-M3",
+	const noop = {
+		provider: "noop",
+		model: "noop",
 		maxTokens
 	};
-	if (hasRealValue(env["ANTHROPIC_API_KEY"])) return {
-		provider: "anthropic",
-		model: env["ANTHROPIC_MODEL"] || "claude-sonnet-5",
-		maxTokens,
-		baseURL: env["ANTHROPIC_BASE_URL"]
-	};
-	if (hasRealValue(env["GEMINI_API_KEY"]) || hasRealValue(env["GOOGLE_API_KEY"])) {
-		if (!hasRealValue(env["GEMINI_API_KEY"]) && hasRealValue(env["GOOGLE_API_KEY"])) process.stderr.write("[agentmemory] GOOGLE_API_KEY detected — treating as GEMINI_API_KEY. Set GEMINI_API_KEY in ~/.agentmemory/.env to silence this warning.\n");
-		return {
-			provider: "gemini",
-			model: env["GEMINI_MODEL"] || "gemini-3.7-flash",
-			maxTokens
-		};
-	}
-	if (hasRealValue(env["OPENROUTER_API_KEY"])) {
-		const model = env["OPENROUTER_MODEL"] || "anthropic/claude-sonnet-5";
-		if (!warnPremiumModelShown && /sonnet|opus|gpt-5\.\d+-sol|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-flash-0731, deepseek/deepseek-v4-pro, qwen/qwen3-coder. See README "Cost-aware model selection" for the full table. Set AGENTMEMORY_SUPPRESS_COST_WARNING=1 to silence.\n`);
+	const selected = selectedLlmProviderValue(env);
+	if (selected) {
+		if (!isLlmProviderName(selected) || !llmProviderHasKey(env, selected)) {
+			writeProviderNoticeOnce(`[agentmemory] ${llmOptInHint(env)} Running zero-LLM.\n`);
+			return noop;
+		}
+		switch (selected) {
+			case "openai": {
+				const model = env["OPENAI_MODEL"] || "gpt-5.6-luna";
+				warnIfPremiumModel(env, "OPENAI_MODEL", model);
+				return {
+					provider: "openai",
+					model,
+					maxTokens,
+					baseURL: env["OPENAI_BASE_URL"]
+				};
+			}
+			case "minimax": return {
+				provider: "minimax",
+				model: env["MINIMAX_MODEL"] || "MiniMax-M3",
+				maxTokens
+			};
+			case "anthropic": return {
+				provider: "anthropic",
+				model: env["ANTHROPIC_MODEL"] || "claude-sonnet-5",
+				maxTokens,
+				baseURL: env["ANTHROPIC_BASE_URL"]
+			};
+			case "gemini":
+				if (!hasRealValue(env["GEMINI_API_KEY"])) process.stderr.write("[agentmemory] GOOGLE_API_KEY detected — treating as GEMINI_API_KEY. Set GEMINI_API_KEY in ~/.agentmemory/.env to silence this warning.\n");
+				return {
+					provider: "gemini",
+					model: env["GEMINI_MODEL"] || "gemini-3.7-flash",
+					maxTokens
+				};
+			case "openrouter": {
+				const model = env["OPENROUTER_MODEL"] || "anthropic/claude-sonnet-5";
+				warnIfPremiumModel(env, "OPENROUTER_MODEL", model);
+				return {
+					provider: "openrouter",
+					model,
+					maxTokens
+				};
+			}
 		}
-		return {
-			provider: "openrouter",
-			model,
-			maxTokens
-		};
 	}
 	if (!(env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true")) {
-		writeProviderNoticeOnce(pc.dim("[agentmemory] No LLM provider key set — running zero-LLM: no LLM compression or summaries; search uses BM25 plus any configured embedding provider. Set EMBEDDING_PROVIDER=local for on-device semantic embeddings if none is configured. Set ANTHROPIC_API_KEY (or GEMINI/OPENAI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env for LLM compression and summaries. Agent-SDK fallback stays off by default to avoid a Stop-hook recursion loop; opt in with AGENTMEMORY_AUTO_COMPRESS=true + AGENTMEMORY_ALLOW_AGENT_SDK=true.\n"));
-		return {
-			provider: "noop",
-			model: "noop",
-			maxTokens
-		};
+		const hint = llmOptInHint(env);
+		writeProviderNoticeOnce(hint ? `[agentmemory] ${hint}\n` : pc.dim("[agentmemory] No LLM provider chosen, so agentmemory runs zero-LLM: no LLM compression or summaries, and no session content leaves this machine for an LLM. Search uses BM25 plus any embedding provider you set with EMBEDDING_PROVIDER (EMBEDDING_PROVIDER=local runs on-device). To turn on LLM summaries, set AGENTMEMORY_LLM_PROVIDER (anthropic, openai, gemini, openrouter or minimax) and that provider's key in ~/.agentmemory/.env.\n"));
+		return noop;
 	}
 	writeProviderNoticeOnce("[agentmemory] WARNING: agent-sdk fallback enabled via AGENTMEMORY_ALLOW_AGENT_SDK=true. This spawns @anthropic-ai/claude-agent-sdk child sessions that can trigger the Stop-hook recursion loop. A SDK-child env marker is set to block re-entry, but prefer setting a real API key in ~/.agentmemory/.env instead.\n");
 	return {
@@ -466,16 +192,21 @@ function loadConfig() {
 	const env = getMergedEnv();
 	const provider = detectProvider(env);
 	const restPort = parseInt(env["III_REST_PORT"] || "3111", 10) || 3111;
-	const streamsPort = parseInt(env["III_STREAM_PORT"] || env["III_STREAMS_PORT"] || "", 10) || restPort + 1;
 	const viewerPort = parseInt(env["III_VIEWER_PORT"] || "", 10) || restPort + 2;
+	const engineUrl = env["III_ENGINE_URL"] || env["III_URL"] || `ws://localhost:${parseInt(env["III_ENGINE_PORT"] || "", 10) || restPort + 46023}`;
+	const maxObservationsPerSession = safeParseInt(env["MAX_OBS_PER_SESSION"], 500);
+	if (!obsCapImportCeilingWarned && (maxObservationsPerSession === 0 || maxObservationsPerSession > 5e3)) {
+		obsCapImportCeilingWarned = true;
+		const capDesc = maxObservationsPerSession === 0 ? "uncapped (0)" : String(maxObservationsPerSession);
+		process.stderr.write(`[agentmemory] WARNING: MAX_OBS_PER_SESSION is ${capDesc}, above the ${MAX_IMPORT_OBS_PER_SESSION}-per-session import ceiling (MAX_IMPORT_OBS_PER_SESSION). Sessions past that ceiling make every mem::export -> mem::import restore fail wholesale. Keep MAX_OBS_PER_SESSION at or below ${MAX_IMPORT_OBS_PER_SESSION} if you rely on export/import backups.\n`);
+	}
 	return {
-		engineUrl: env["III_ENGINE_URL"] || `ws://localhost:${parseInt(env["III_ENGINE_PORT"] || "", 10) || restPort + 46023}`,
+		engineUrl,
 		restPort,
-		streamsPort,
 		viewerPort,
 		provider,
 		tokenBudget: safeParseInt(env["TOKEN_BUDGET"], 2e3),
-		maxObservationsPerSession: safeParseInt(env["MAX_OBS_PER_SESSION"], 500),
+		maxObservationsPerSession,
 		compressionModel: provider.model,
 		dataDir: DATA_DIR
 	};
@@ -499,6 +230,11 @@ function getSessionSweepStaleHours() {
 	const parsed = parseInt(raw.trim(), 10);
 	return parsed > 0 ? parsed : 24;
 }
+function getFinalizeIdleMs() {
+	const raw = getMergedEnv()["AGENTMEMORY_FINALIZE_IDLE_MS"];
+	if (!raw || !/^\d+$/.test(raw.trim())) return 12e4;
+	return parseInt(raw.trim(), 10);
+}
 function isGraphCompactOnBootEnabled() {
 	return getMergedEnv()["AGENTMEMORY_GRAPH_COMPACT_ON_BOOT"] !== "false";
 }
@@ -523,9 +259,21 @@ function getAuditMigrateMaxBytes() {
 	return safeParseInt(getMergedEnv()["AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES"], 32 * 1024 * 1024);
 }
 function detectLlmProviderKind(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" || env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true") return "llm";
+	const selected = selectedLlmProviderValue(env);
+	if (selected && isLlmProviderName(selected) && llmProviderHasKey(env, selected)) return "llm";
+	if (!selected && env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true") return "llm";
 	return "noop";
 }
+function describeLlmRoute(provider) {
+	if (provider.provider === "noop") return null;
+	const parts = [provider.provider, provider.model];
+	if (provider.baseURL) try {
+		parts.push(new URL(provider.baseURL).host);
+	} catch {
+		parts.push("custom base URL");
+	}
+	return parts.join(" · ");
+}
 function loadEmbeddingConfig() {
 	const env = getMergedEnv();
 	let bm25Weight = parseFloat(env["BM25_WEIGHT"] || "0.4");
@@ -539,15 +287,8 @@ function loadEmbeddingConfig() {
 	};
 }
 function detectEmbeddingProvider(env) {
-	const source = env ?? getMergedEnv();
-	const forced = source["EMBEDDING_PROVIDER"];
-	if (forced) return forced;
-	if (source["GEMINI_API_KEY"]) return "gemini";
-	if (source["OPENAI_API_KEY"] || source["OPENAI_EMBEDDING_API_KEY"]) return "openai";
-	if (source["VOYAGE_API_KEY"]) return "voyage";
-	if (source["COHERE_API_KEY"]) return "cohere";
-	if (source["OPENROUTER_API_KEY"]) return "openrouter";
-	return null;
+	const forced = ((env ?? getMergedEnv())["EMBEDDING_PROVIDER"] || "").trim();
+	return forced ? forced : null;
 }
 function loadClaudeBridgeConfig() {
 	const env = getMergedEnv();
@@ -613,20 +354,6 @@ const FOLLOWUP_WINDOW_DEFAULT_SECONDS = 30;
 function getFollowupWindowSeconds() {
 	return safeParseInt(getMergedEnv()["AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS"], FOLLOWUP_WINDOW_DEFAULT_SECONDS);
 }
-const VIEWER_STREAM_MAX_DEFAULT = 500;
-const VIEWER_STREAM_MAX_FLOOR = 200;
-function parseExactInt(value, fallback) {
-	if (!value) return fallback;
-	const trimmed = value.trim();
-	if (!/^-?\d+$/.test(trimmed)) return fallback;
-	const parsed = Number(trimmed);
-	return Number.isSafeInteger(parsed) ? parsed : fallback;
-}
-function getViewerStreamMax() {
-	const parsed = parseExactInt(getMergedEnv()["AGENTMEMORY_VIEWER_STREAM_MAX"], VIEWER_STREAM_MAX_DEFAULT);
-	if (parsed < 0) return VIEWER_STREAM_MAX_DEFAULT;
-	return Math.max(parsed, VIEWER_STREAM_MAX_FLOOR);
-}
 function isConsolidationEnabled() {
 	const env = getMergedEnv();
 	const explicit = env["CONSOLIDATION_ENABLED"];
@@ -659,9 +386,13 @@ function getIndexSaveIntervalMs() {
 	const raw = safeParseInt(getMergedEnv()["AGENTMEMORY_INDEX_SAVE_INTERVAL_MS"], INDEX_SAVE_INTERVAL_DEFAULT_MS);
 	return raw > 0 ? raw : INDEX_SAVE_INTERVAL_DEFAULT_MS;
 }
+const STATE_SAVE_INTERVAL_DEFAULT_MS = 2e3;
 function getStateSaveIntervalMs() {
-	const raw = safeParseInt(getMergedEnv()["AGENTMEMORY_STATE_SAVE_INTERVAL_MS"], 0);
-	return raw > 0 ? raw : void 0;
+	const value = getMergedEnv()["AGENTMEMORY_STATE_SAVE_INTERVAL_MS"];
+	if (value === void 0 || value.trim() === "") return STATE_SAVE_INTERVAL_DEFAULT_MS;
+	if (!/^\d+$/.test(value.trim())) return STATE_SAVE_INTERVAL_DEFAULT_MS;
+	const raw = Number(value);
+	return Number.isSafeInteger(raw) && raw >= 100 && raw <= 36e5 ? raw : STATE_SAVE_INTERVAL_DEFAULT_MS;
 }
 function getVectorBucketSize() {
 	const raw = safeParseInt(getMergedEnv()["AGENTMEMORY_VECTOR_BUCKET_SIZE"], 500);
@@ -698,15 +429,158 @@ function loadFallbackConfig() {
 	}) };
 }
 //#endregion
+//#region src/cli/engine-launch.ts
+function runtimeConfigPath(dataDir) {
+	return join(dataDir, "iii-config.runtime.yaml");
+}
+const CREDENTIAL_URL_PATTERN = /:\/\/[^@\s/]*@/g;
+function redactCredentialUrls(text) {
+	return text.replace(CREDENTIAL_URL_PATTERN, "://***@");
+}
+//#endregion
+//#region src/cli/engine-config.ts
+const ENGINE_DEFAULT_SAVE_INTERVAL_MS = 5e3;
+const ENGINE_FLUSH_MARGIN_MS = 1500;
+function engineFlushWaitMs(stateBackend, configTexts) {
+	if (stateBackend === "redis") return 0;
+	return engineSaveIntervalMs(configTexts) + ENGINE_FLUSH_MARGIN_MS;
+}
+function captureDurableAfterMs(stateBackend, configTexts) {
+	if (stateBackend === "redis") return ENGINE_FLUSH_MARGIN_MS;
+	return engineSaveIntervalMs(configTexts) + ENGINE_FLUSH_MARGIN_MS;
+}
+function engineSaveIntervalMs(configTexts, env = process.env) {
+	const intervals = [];
+	for (const text of configTexts) {
+		const explicit = [];
+		for (const match of text.matchAll(/save_interval_ms:\s*["']?(\d+|\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-(\d+))?\})/g)) {
+			const raw = match[2] ? env[match[2]] || match[3] : match[1];
+			if (raw && /^\d+$/.test(raw) && Number.isSafeInteger(Number(raw))) explicit.push(Number(raw));
+		}
+		intervals.push(...explicit);
+		if ((text.match(/store_method:\s*file_based/g)?.length ?? 0) > explicit.length) intervals.push(ENGINE_DEFAULT_SAVE_INTERVAL_MS);
+	}
+	return intervals.length > 0 ? Math.max(...intervals) : ENGINE_DEFAULT_SAVE_INTERVAL_MS;
+}
+function engineStateConfigPaths(engineCwd, runtimePath) {
+	return [...new Set([
+		join(engineCwd, "compose", "worker-compose.yaml"),
+		join(engineCwd, "compose", "config", "state.yaml"),
+		join(engineCwd, "worker-compose.runtime.yaml"),
+		join(engineCwd, "config", "state.yaml"),
+		runtimePath
+	])];
+}
+//#endregion
+//#region src/logger.ts
+function fmt(level, msg, fields) {
+	if (!fields || Object.keys(fields).length === 0) return `[agentmemory] ${level} ${msg}`;
+	try {
+		return `[agentmemory] ${level} ${msg} ${JSON.stringify(fields)}`;
+	} catch {
+		return `[agentmemory] ${level} ${msg}`;
+	}
+}
+function emit(level, msg, fields) {
+	try {
+		const line = fmt(level, msg, fields) + "\n";
+		if (level === "error" || process.env["AGENTMEMORY_MCP_STDIO__"] === "1") process.stderr.write(line);
+		else process.stdout.write(line);
+	} catch {}
+}
+const logger = {
+	info(msg, fields) {
+		emit("info", msg, fields);
+	},
+	warn(msg, fields) {
+		emit("warn", msg, fields);
+	},
+	error(msg, fields) {
+		emit("error", msg, fields);
+	}
+};
+let bootVerbose = process.env["AGENTMEMORY_VERBOSE"] === "1" || process.env["AGENTMEMORY_VERBOSE"] === "true";
+const bootBuffer = [];
+function setBootVerbose(enabled) {
+	bootVerbose = enabled;
+}
+function bootLog(msg) {
+	if (bootVerbose) {
+		try {
+			process.stderr.write(`[agentmemory] ${msg}\n`);
+		} catch {}
+		return;
+	}
+	if (bootBuffer.length < 500) bootBuffer.push(msg);
+}
+function bootWarn(msg) {
+	try {
+		process.stderr.write(`[agentmemory] warn ${msg}\n`);
+	} catch {}
+}
+//#endregion
 //#region src/version.ts
-const VERSION = "0.9.30";
-const III_PINNED_VERSION = "0.22.1";
+const VERSION = "0.9.32";
+const III_PINNED_VERSION = "0.25.0";
 //#endregion
 //#region src/mcp/tools-registry.ts
+const READ_ONLY_TOOLS = new Set([
+	"memory_recall",
+	"memory_file_history",
+	"memory_patterns",
+	"memory_sessions",
+	"memory_smart_search",
+	"memory_vision_search",
+	"memory_timeline",
+	"memory_export",
+	"memory_relations",
+	"memory_commit_lookup",
+	"memory_commits",
+	"memory_graph_query",
+	"memory_team_feed",
+	"memory_audit",
+	"memory_frontier",
+	"memory_next",
+	"memory_diagnose",
+	"memory_facet_query",
+	"memory_verify",
+	"memory_lesson_recall",
+	"memory_insight_list",
+	"memory_slot_list",
+	"memory_slot_get"
+]);
+const DESTRUCTIVE_TOOLS = new Set([
+	"memory_action_update",
+	"memory_compress_file",
+	"memory_claude_bridge_sync",
+	"memory_governance_delete",
+	"memory_heal",
+	"memory_lesson_delete",
+	"memory_obsidian_export",
+	"memory_slot_replace",
+	"memory_slot_delete"
+]);
+const IDEMPOTENT_WRITE_TOOLS = new Set([
+	"memory_governance_delete",
+	"memory_lesson_delete",
+	"memory_slot_replace",
+	"memory_slot_delete",
+	"memory_claude_bridge_sync"
+]);
+const OPEN_WORLD_TOOLS = new Set(["memory_mesh_sync"]);
+function toolAnnotations(name) {
+	const readOnly = READ_ONLY_TOOLS.has(name);
+	return {
+		readOnlyHint: readOnly,
+		destructiveHint: !readOnly && DESTRUCTIVE_TOOLS.has(name),
+		idempotentHint: readOnly || IDEMPOTENT_WRITE_TOOLS.has(name),
+		openWorldHint: OPEN_WORLD_TOOLS.has(name)
+	};
+}
 const CORE_TOOLS = [
 	{
 		name: "memory_recall",
-		description: "Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before.",
+		description: "Search stored memories and session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -724,7 +598,28 @@ const CORE_TOOLS = [
 				},
 				token_budget: {
 					type: "number",
-					description: "Optional token budget to trim returned results"
+					description: "Optional estimated content token budget; response includes truncation and recovery metadata"
+				},
+				targetLayer: {
+					type: "string",
+					enum: [
+						"all",
+						"memory",
+						"observation"
+					],
+					description: "Search all indexed layers (default), durable memories, or raw observations before ranking"
+				},
+				project: {
+					type: "string",
+					description: "Filter by project path"
+				},
+				cwd: {
+					type: "string",
+					description: "Filter by session working directory"
+				},
+				agentId: {
+					type: "string",
+					description: "Filter by owning agent; '*' reads across agents"
 				}
 			},
 			required: ["query"]
@@ -813,15 +708,32 @@ const CORE_TOOLS = [
 	},
 	{
 		name: "memory_sessions",
-		description: "List recent sessions with their status and observation counts.",
+		description: "List recent sessions with status, observation counts, summaries and a continuation cursor. Filters apply before pagination; retain them when requesting the next page.",
 		inputSchema: {
 			type: "object",
-			properties: {}
+			properties: {
+				project: {
+					type: "string",
+					description: "Exact project identifier used when sessions were started"
+				},
+				agentId: {
+					type: "string",
+					description: "Filter by owning agent; '*' reads across agents"
+				},
+				limit: {
+					type: "integer",
+					description: "Page size (default 20, max 100)"
+				},
+				cursor: {
+					type: "string",
+					description: "nextCursor from the previous page; omit for the first page"
+				}
+			}
 		}
 	},
 	{
 		name: "memory_smart_search",
-		description: "Hybrid semantic+keyword search with progressive disclosure.",
+		description: "Hybrid semantic+keyword search with progressive disclosure. Pass query to search, or expandIds to recover full results.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -831,14 +743,34 @@ const CORE_TOOLS = [
 				},
 				expandIds: {
 					type: "string",
-					description: "Comma-separated observation IDs to expand"
+					description: "Comma-separated memory or observation IDs to expand; query is optional when provided"
 				},
 				limit: {
 					type: "number",
 					description: "Max results (default 10)"
+				},
+				targetLayer: {
+					type: "string",
+					enum: [
+						"all",
+						"memory",
+						"observation"
+					],
+					description: "Search all indexed layers (default), durable memories, or raw observations before ranking"
+				},
+				project: {
+					type: "string",
+					description: "Filter by project path"
+				},
+				agentId: {
+					type: "string",
+					description: "Filter by owning agent; '*' reads across agents"
+				},
+				includeLessons: {
+					type: "boolean",
+					description: "Include lesson matches when targetLayer is all (default true)"
 				}
-			},
-			required: ["query"]
+			}
 		}
 	},
 	{
@@ -916,10 +848,31 @@ const CORE_TOOLS = [
 	},
 	{
 		name: "memory_export",
-		description: "Export all memory data as JSON.",
+		description: "Export memory data as JSON. Past the transport size limit the export is refused, so use the paging arguments on a large store.",
 		inputSchema: {
 			type: "object",
-			properties: {}
+			properties: {
+				maxSessions: {
+					type: "number",
+					description: "Sessions per page (with their observations)"
+				},
+				offset: {
+					type: "number",
+					description: "Session offset"
+				},
+				collectionLimit: {
+					type: "number",
+					description: "Rows per page for memories, summaries, graphNodes, lessons and the other top-level collections; access logs follow the memories on the page. Sessions and their observations are paged only by maxSessions and offset, so pass collections to leave them out of each page"
+				},
+				collectionOffset: {
+					type: "number",
+					description: "Row offset for the top-level collections"
+				},
+				collections: {
+					type: "string",
+					description: "Comma-separated collections to return, e.g. memories,lessons. Sessions and their observations come back only when the list names sessions, access logs only together with memories. Unknown names are ignored. Omit for everything. A paged or selected export cannot be imported with strategy replace."
+				}
+			}
 		}
 	},
 	{
@@ -1604,6 +1557,11 @@ const V070_TOOLS = [
 				tags: {
 					type: "string",
 					description: "Comma-separated tags"
+				},
+				sourceIds: {
+					type: "array",
+					items: { type: "string" },
+					description: "Ids of the session, memory, observation or crystal this lesson came from (max 50)"
 				}
 			},
 			required: ["content"]
@@ -1826,7 +1784,10 @@ function getAllTools() {
 		...V070_TOOLS,
 		...V073_TOOLS,
 		...V010_SLOTS_TOOLS
-	];
+	].map((tool) => ({
+		...tool,
+		annotations: toolAnnotations(tool.name)
+	}));
 }
 function getVisibleTools() {
 	if ((process.env["AGENTMEMORY_TOOLS"] || "all") === "core") return getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name));
@@ -1925,7 +1886,7 @@ async function auditMigrationDeleteDelayMs() {
 	const dataDir = getEnvVar("AGENTMEMORY_DATA_DIR");
 	if (!dataDir) return ENGINE_DEFAULT_SAVE_INTERVAL_MS * AUDIT_MIGRATION_DELETE_WAIT_INTERVALS;
 	const configTexts = [];
-	for (const path of engineStateConfigPaths(join(homedir(), ".agentmemory"), runtimeConfigPath(dataDir))) try {
+	for (const path of engineStateConfigPaths(dataDir, runtimeConfigPath(dataDir))) try {
 		configTexts.push(await readFile(path, "utf-8"));
 	} catch {}
 	return engineSaveIntervalMs(configTexts) * AUDIT_MIGRATION_DELETE_WAIT_INTERVALS;
@@ -2224,10 +2185,244 @@ async function runAuditRetentionSweep(kv, retentionMonths) {
 	};
 }
 //#endregion
+//#region src/state/search-layer.ts
+function isSearchLayer(value) {
+	return value === "all" || value === "memory" || value === "observation";
+}
+function isSearchResultLayer(value) {
+	return value === "memory" || value === "observation" || value === "lesson" || value === "insight";
+}
+function getSearchResultLayer(obsId, sessionId) {
+	if (obsId.startsWith("mem_")) return "memory";
+	if (sessionId === "lesson" || obsId.startsWith("lsn_")) return "lesson";
+	if (sessionId === "insight" || obsId.startsWith("ins_")) return "insight";
+	return "observation";
+}
+function matchesSearchLayer(obsId, sessionId, targetLayer = "all", layer) {
+	return targetLayer === "all" || (layer ?? getSearchResultLayer(obsId, sessionId)) === targetLayer;
+}
+//#endregion
+//#region src/state/memory-utils.ts
+const MAX_DATE_MS = 864e13;
+function supersededAt(previous, now) {
+	const prior = previous ? Date.parse(previous) : NaN;
+	const current = Date.parse(now);
+	if (Number.isNaN(prior) || current > prior) return now;
+	return new Date(Math.min(prior + 1, MAX_DATE_MS)).toISOString();
+}
+function memoryToObservation(memory) {
+	return {
+		id: memory.id,
+		sessionId: memory.sessionIds?.[0] ?? "memory",
+		timestamp: memory.createdAt,
+		type: "decision",
+		memoryType: memory.type,
+		title: memory.title,
+		facts: [memory.content],
+		narrative: memory.content,
+		concepts: memory.concepts,
+		files: memory.files,
+		importance: memory.strength,
+		...memory.agentId ? { agentId: memory.agentId } : {}
+	};
+}
+function lessonToObservation(l) {
+	return {
+		id: l.id,
+		sessionId: "lesson",
+		timestamp: l.createdAt,
+		type: "decision",
+		title: l.content.slice(0, 120),
+		facts: [l.content],
+		narrative: l.context || "",
+		concepts: l.tags,
+		files: [],
+		importance: l.confidence
+	};
+}
+function observationEmbedText(record) {
+	return [
+		record.title,
+		...record.concepts || [],
+		record.narrative || ""
+	].filter((part) => part && part.trim()).join(" ").trim();
+}
+//#endregion
+//#region src/functions/recall-response.ts
+function estimateTokens(value) {
+	return Math.max(1, Math.ceil(JSON.stringify(value).length / 3));
+}
+function prefix(text, length) {
+	let end = Math.min(length, text.length);
+	if (end > 0 && end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1])) end--;
+	return text.slice(0, end);
+}
+function fitText(text, budget, makeResult) {
+	let low = 0;
+	let high = text.length;
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		if (estimateTokens(makeResult(prefix(text, middle))) <= budget) low = middle;
+		else high = middle - 1;
+	}
+	return makeResult(prefix(text, low));
+}
+function formatResult(result, format) {
+	if (format === "full") return result;
+	const observation = result.observation;
+	const compact = {
+		obsId: observation.id,
+		sessionId: result.sessionId,
+		title: observation.title,
+		type: observation.type,
+		...observation.memoryType !== void 0 && { memoryType: observation.memoryType },
+		score: result.score,
+		timestamp: observation.timestamp,
+		...result.layer !== void 0 && { layer: result.layer }
+	};
+	if (format === "compact") return compact;
+	const { type: _type, ...narrative } = compact;
+	return {
+		...narrative,
+		narrative: observation.narrative
+	};
+}
+function clipResult(result, format, budget) {
+	const observation = result.observation;
+	const layer = result.layer !== void 0 ? { layer: result.layer } : {};
+	if (format === "compact") {
+		const base = {
+			obsId: observation.id,
+			sessionId: result.sessionId,
+			title: "",
+			type: observation.type,
+			...observation.memoryType !== void 0 && { memoryType: observation.memoryType },
+			score: result.score,
+			timestamp: observation.timestamp,
+			...layer,
+			content_truncated: true
+		};
+		const minimum = estimateTokens(base);
+		if (minimum > budget) return { minimum };
+		return {
+			result: fitText(observation.title, budget, (title) => ({
+				...base,
+				title
+			})),
+			minimum
+		};
+	}
+	const makeResult = (title, narrative) => {
+		if (format === "narrative") return {
+			obsId: observation.id,
+			sessionId: result.sessionId,
+			title,
+			narrative,
+			...observation.memoryType !== void 0 && { memoryType: observation.memoryType },
+			score: result.score,
+			timestamp: observation.timestamp,
+			...layer,
+			content_truncated: true
+		};
+		return {
+			observation: {
+				id: observation.id,
+				sessionId: observation.sessionId,
+				timestamp: observation.timestamp,
+				type: observation.type,
+				...observation.memoryType !== void 0 && { memoryType: observation.memoryType },
+				title,
+				facts: [],
+				narrative,
+				concepts: [],
+				files: [],
+				importance: observation.importance,
+				...observation.confidence !== void 0 && { confidence: observation.confidence },
+				...observation.agentId !== void 0 && { agentId: observation.agentId },
+				...observation.origin && { origin: {
+					channel: observation.origin.channel,
+					capturedAt: observation.origin.capturedAt
+				} }
+			},
+			score: result.score,
+			sessionId: result.sessionId,
+			...layer,
+			content_truncated: true
+		};
+	};
+	const minimum = estimateTokens(makeResult("", ""));
+	if (minimum > budget) return { minimum };
+	const titleResult = fitText(prefix(observation.title, 120), budget, (title) => makeResult(title, ""));
+	const title = "observation" in titleResult ? titleResult.observation.title : titleResult.title;
+	return {
+		result: fitText(observation.narrative || observation.facts.join("\n"), budget, (text) => makeResult(title, text)),
+		minimum
+	};
+}
+function buildRecallResponse(results, format, tokenBudget) {
+	const selected = [];
+	let used = 0;
+	let clipped = false;
+	let minimumBudget;
+	for (const result of results) {
+		const formatted = formatResult(result, format);
+		const tokens = estimateTokens(formatted);
+		if (tokenBudget === void 0 || used + tokens <= tokenBudget) {
+			selected.push(formatted);
+			used += tokens;
+			continue;
+		}
+		if (selected.length === 0) {
+			const preview = clipResult(result, format, tokenBudget);
+			if (preview.result) {
+				selected.push(preview.result);
+				used = estimateTokens(preview.result);
+				clipped = true;
+				continue;
+			} else minimumBudget = Math.min(preview.minimum, tokens);
+		}
+		break;
+	}
+	const excluded = results.slice(selected.length);
+	const metadata = {
+		tokens_used: used,
+		tokens_budget: tokenBudget,
+		truncated: clipped || excluded.length > 0,
+		matched_count: results.length,
+		excluded_by_budget: excluded.length,
+		excluded_results: excluded.slice(0, 10).map((result) => ({
+			obsId: result.observation.id,
+			sessionId: result.sessionId,
+			title: prefix(result.observation.title, 120)
+		})),
+		excluded_results_truncated: excluded.length > 10,
+		...minimumBudget !== void 0 && { minimum_budget: minimumBudget }
+	};
+	if (format === "narrative") {
+		const narrativeResults = selected;
+		return {
+			...metadata,
+			format,
+			results: narrativeResults,
+			text: narrativeResults.map((result, index) => `${index + 1}. ${result.title}\n${result.narrative}`).join("\n\n")
+		};
+	}
+	if (format === "compact") return {
+		...metadata,
+		format,
+		results: selected
+	};
+	return {
+		...metadata,
+		format,
+		results: selected
+	};
+}
+//#endregion
 //#region src/secret-store.ts
 const SECRET_KEY = "AGENTMEMORY_SECRET";
 function agentmemoryHomeDir() {
-	return join(homedir(), ".agentmemory");
+	return process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
 }
 function secretFilePath() {
 	return join(agentmemoryHomeDir(), "secret");
@@ -2251,7 +2446,7 @@ function unquote(value) {
 function readEnvFileSecret() {
 	let content;
 	try {
-		content = readFileSync(join(agentmemoryHomeDir(), ".env"), "utf-8");
+		content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8");
 	} catch {
 		return "";
 	}
@@ -2267,13 +2462,29 @@ function readEnvFileSecret() {
 	}
 	return found;
 }
-function readStoredSecret() {
+function readSecretFile(path) {
 	try {
-		return usable(readFileSync(secretFilePath(), "utf-8"));
+		return usable(readFileSync(path, "utf-8"));
 	} catch {
 		return "";
 	}
 }
+function legacyDataDirSecretPaths(env = process.env) {
+	const dataDir = env["AGENTMEMORY_DATA_DIR"];
+	if (!dataDir) return [];
+	const paths = [
+		join(dataDir, "secret"),
+		join(dataDir, ".hmac"),
+		join(dataDir, "..", ".hmac")
+	];
+	return [...new Set(paths.filter((path) => path !== secretFilePath()))];
+}
+function readStoredSecret(env = process.env) {
+	const canonicalPath = canonicalSecretPath();
+	const localPath = secretFilePath();
+	const legacyPaths = legacyDataDirSecretPaths(env);
+	return readSecretFile(canonicalPath) || (localPath === canonicalPath ? "" : readSecretFile(localPath)) || legacyPaths.map(readSecretFile).find(Boolean) || "";
+}
 function explicitSecret(env = process.env) {
 	return usable(env[SECRET_KEY]) || readEnvFileSecret();
 }
@@ -2290,30 +2501,44 @@ function isLoopbackUrl(url) {
 function resolveClientSecret(baseUrl, env = process.env) {
 	const fromEnv = usable(env[SECRET_KEY]);
 	if (fromEnv) return fromEnv;
+	if (env.AGENTMEMORY_CREDENTIAL_MODE === "explicit") return "";
 	if (!isLoopbackUrl(baseUrl)) return "";
-	return readEnvFileSecret() || readStoredSecret();
+	return readEnvFileSecret() || readStoredSecret(env);
 }
-function ensureServerSecret(env = process.env) {
-	const configured = explicitSecret(env);
-	if (configured) return {
-		secret: configured,
-		source: "env"
-	};
-	const stored = readStoredSecret();
-	if (stored) return {
-		secret: stored,
-		source: "file"
-	};
-	const generated = randomBytes(32).toString("hex");
-	const path = secretFilePath();
-	mkdirSync(agentmemoryHomeDir(), {
+function canonicalSecretPath() {
+	return join(homedir(), ".agentmemory", "secret");
+}
+function writeSecretFile(path, secret) {
+	mkdirSync(join(path, ".."), {
 		recursive: true,
 		mode: 448
 	});
 	const staging = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
 	const fd = openSync(staging, "wx", 384);
 	try {
-		writeSync(fd, `${generated}\n`);
+		writeSync(fd, `${secret}\n`);
+	} finally {
+		closeSync(fd);
+	}
+	try {
+		chmodSync(staging, 384);
+		renameSync(staging, path);
+		chmodSync(path, 384);
+	} finally {
+		try {
+			unlinkSync(staging);
+		} catch {}
+	}
+}
+function writeSecretIfAbsent(path, secret) {
+	mkdirSync(join(path, ".."), {
+		recursive: true,
+		mode: 448
+	});
+	const staging = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+	const fd = openSync(staging, "wx", 384);
+	try {
+		writeSync(fd, `${secret}\n`);
 	} finally {
 		closeSync(fd);
 	}
@@ -2322,20 +2547,38 @@ function ensureServerSecret(env = process.env) {
 		linkSync(staging, path);
 	} catch (err) {
 		if (err.code !== "EEXIST") throw err;
-		const raced = readStoredSecret();
-		if (!raced) throw err;
-		return {
-			secret: raced,
-			source: "file"
-		};
 	} finally {
 		try {
 			unlinkSync(staging);
 		} catch {}
 	}
+	const stored = readSecretFile(path);
+	if (!stored) throw new Error(`Could not read stored API secret at ${path}.`);
+	return stored;
+}
+function ensureServerSecret(env = process.env) {
+	const configured = explicitSecret(env);
+	if (configured) return {
+		secret: configured,
+		source: "env"
+	};
+	const localPath = secretFilePath();
+	const canonicalPath = canonicalSecretPath();
+	const canonical = localPath === canonicalPath ? "" : readSecretFile(canonicalPath);
+	if (canonical) {
+		if (localPath !== canonicalPath && readSecretFile(localPath) !== canonical) writeSecretFile(localPath, canonical);
+		return {
+			secret: canonical,
+			source: "file"
+		};
+	}
+	const legacy = readSecretFile(localPath) || legacyDataDirSecretPaths(env).map(readSecretFile).find(Boolean) || "";
+	const localSecret = writeSecretIfAbsent(localPath, legacy || randomBytes(32).toString("hex"));
+	const secret = localPath === canonicalPath ? localSecret : writeSecretIfAbsent(canonicalPath, localSecret);
+	if (localPath !== canonicalPath && localSecret !== secret) writeSecretFile(localPath, secret);
 	return {
-		secret: generated,
-		source: "generated"
+		secret,
+		source: legacy ? "file" : "generated"
 	};
 }
 function bearerHeaders(baseUrl, env = process.env) {
@@ -2343,6 +2586,6 @@ function bearerHeaders(baseUrl, env = process.env) {
 	return secret ? { Authorization: `Bearer ${secret}` } : {};
 }
 //#endregion
-export { bootWarn as $, getStandalonePersistPath as A, isContextInjectionEnabled as B, getConsolidationDecayDays as C, getIndexSaveIntervalMs as D, getFollowupWindowSeconds as E, getViewerStreamMax as F, isVectorBackfillAllEnabled as G, isGraphCompactOnBootEnabled as H, hydrateProcessEnvFromFile as I, loadEmbeddingConfig as J, loadClaudeBridgeConfig as K, isAgentScopeIsolated as L, getStateSaveIntervalMs as M, getVectorBackfillMax as N, getRedisUrl as O, getVectorBucketSize as P, bootLog as Q, isAutoCompressEnabled as R, getConsolidationCooldownMs as S, getEnvVar as T, isGraphExtractionEnabled as U, isDropStaleIndexEnabled as V, isSessionSweepEnabled as W, loadSnapshotConfig as X, loadFallbackConfig as Y, loadTeamConfig as Z, VERSION as _, secretFilePath as a, isBundledConfig as at, getAgentId as b, recordAudit as c, resolveEngineCwd as ct, setAuditRecordedListener as d, runtimeConfigPath as dt, logger as et, startAuditMigration as f, captureDurableAfterMs as ft, III_PINNED_VERSION as g, renderEngineConfig as gt, getVisibleTools as h, engineStateConfigPaths as ht, resolveClientSecret as i, engineChildEnv as it, getStateBackend as j, getSessionSweepStaleHours as k, runAuditRetentionSweep as l, resolveLaunchRenderFailure as lt, getAllTools as m, engineFlushWaitMs as mt, ensureServerSecret as n, dockerComposeArgs as nt, AUDIT_MIGRATION_STATE_KEY as o, legacyDataMigrations as ot, ESSENTIAL_TOOLS as p, clearPersistedBuiltinConfig as pt, loadConfig as q, explicitSecret as r, dockerProjectName as rt, queryAudit as s, redactCredentialUrls as st, bearerHeaders as t, setBootVerbose as tt, safeAudit as u, rewriteBundledConfig as ut, detectEmbeddingProvider as v, getConsolidationIntervalMs as w, getAuditRetentionMonths as x, detectLlmProviderKind as y, isConsolidationEnabled as z };
+export { getStandalonePersistPath as $, setBootVerbose as A, detectLlmProviderKind as B, getAllTools as C, bootLog as D, VERSION as E, runtimeConfigPath as F, getConsolidationDecayDays as G, getAgentId as H, LLM_PROVIDER_KEYS as I, getFinalizeIdleMs as J, getConsolidationIntervalMs as K, MAX_IMPORT_OBS_PER_SESSION as L, engineFlushWaitMs as M, engineStateConfigPaths as N, bootWarn as O, redactCredentialUrls as P, getSessionSweepStaleHours as Q, describeLlmRoute as R, ESSENTIAL_TOOLS as S, III_PINNED_VERSION as T, getAuditRetentionMonths as U, embeddingOptInHint as V, getConsolidationCooldownMs as W, getIndexSaveIntervalMs as X, getFollowupWindowSeconds as Y, getRedisUrl as Z, recordAudit as _, loadEmbeddingConfig as _t, secretFilePath as a, isAgentScopeIsolated as at, setAuditRecordedListener as b, loadTeamConfig as bt, memoryToObservation as c, isContextInjectionEnabled as ct, getSearchResultLayer as d, isGraphExtractionEnabled as dt, getStateBackend as et, isSearchLayer as f, isSessionSweepEnabled as ft, queryAudit as g, loadConfig as gt, AUDIT_MIGRATION_STATE_KEY as h, loadClaudeBridgeConfig as ht, resolveClientSecret as i, hydrateProcessEnvFromFile as it, captureDurableAfterMs as j, logger as k, observationEmbedText as l, isDropStaleIndexEnabled as lt, matchesSearchLayer as m, llmOptInHint as mt, ensureServerSecret as n, getVectorBackfillMax as nt, buildRecallResponse as o, isAutoCompressEnabled as ot, isSearchResultLayer as p, isVectorBackfillAllEnabled as pt, getEnvVar as q, explicitSecret as r, getVectorBucketSize as rt, lessonToObservation as s, isConsolidationEnabled as st, bearerHeaders as t, getStateSaveIntervalMs as tt, supersededAt as u, isGraphCompactOnBootEnabled as ut, runAuditRetentionSweep as v, loadFallbackConfig as vt, getVisibleTools as w, startAuditMigration as x, parseEnvContent as xt, safeAudit as y, loadSnapshotConfig as yt, detectEmbeddingProvider as z };
 
-//# sourceMappingURL=secret-store-BnY3A50C.mjs.map
+//# sourceMappingURL=secret-store-iYXRcrO8.mjs.map