@agentmemory/agentmemory 0.9.30 → 0.9.31

package/dist/{secret-store-BnY3A50C.mjs → secret-store-D9GwO0xp.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,23 +51,33 @@ 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`);
 }
 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["OPENAI_API_KEY"]) && env["OPENAI_API_KEY_FOR_LLM"] !== "false") {
+		const model = env["OPENAI_MODEL"] || "gpt-5.6-luna";
+		warnIfPremiumModel(env, "OPENAI_MODEL", model);
+		return {
+			provider: "openai",
+			model,
+			maxTokens,
+			baseURL: env["OPENAI_BASE_URL"]
+		};
+	}
 	if (hasRealValue(env["MINIMAX_API_KEY"])) return {
 		provider: "minimax",
 		model: env["MINIMAX_MODEL"] || "MiniMax-M3",
@@ -437,10 +99,7 @@ function detectProvider(env) {
 	}
 	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`);
-		}
+		warnIfPremiumModel(env, "OPENROUTER_MODEL", model);
 		return {
 			provider: "openrouter",
 			model,
@@ -466,16 +125,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 +163,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";
 }
@@ -526,6 +195,16 @@ 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";
 	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");
@@ -613,20 +292,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 +324,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 +367,105 @@ 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.31";
+const III_PINNED_VERSION = "0.25.0";
 //#endregion
 //#region src/mcp/tools-registry.ts
 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 +483,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 +593,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 +628,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 +733,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."
+				}
+			}
 		}
 	},
 	{
@@ -1925,7 +1763,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 +2062,225 @@ 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
+function memoryToObservation(memory) {
+	return {
+		id: memory.id,
+		sessionId: memory.sessionIds?.[0] ?? "memory",
+		timestamp: memory.createdAt,
+		type: "decision",
+		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
+	};
+}
+//#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,
+		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,
+			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,
+			score: result.score,
+			timestamp: observation.timestamp,
+			...layer,
+			content_truncated: true
+		};
+		return {
+			observation: {
+				id: observation.id,
+				sessionId: observation.sessionId,
+				timestamp: observation.timestamp,
+				type: observation.type,
+				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 +2304,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 +2320,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 +2359,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, `${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, `${generated}\n`);
+		writeSync(fd, `${secret}\n`);
 	} finally {
 		closeSync(fd);
 	}
@@ -2322,20 +2405,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 +2444,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 { getVectorBucketSize as $, engineFlushWaitMs as A, getConsolidationCooldownMs as B, III_PINNED_VERSION as C, logger as D, bootWarn as E, describeLlmRoute as F, getFollowupWindowSeconds as G, getConsolidationIntervalMs as H, detectEmbeddingProvider as I, getSessionSweepStaleHours as J, getIndexSaveIntervalMs as K, detectLlmProviderKind as L, redactCredentialUrls as M, runtimeConfigPath as N, setBootVerbose as O, MAX_IMPORT_OBS_PER_SESSION as P, getVectorBackfillMax as Q, getAgentId as R, getVisibleTools as S, bootLog as T, getEnvVar as U, getConsolidationDecayDays as V, getFinalizeIdleMs as W, getStateBackend as X, getStandalonePersistPath as Y, getStateSaveIntervalMs as Z, safeAudit as _, secretFilePath as a, isDropStaleIndexEnabled as at, ESSENTIAL_TOOLS as b, memoryToObservation as c, isSessionSweepEnabled as ct, isSearchResultLayer as d, loadConfig as dt, hydrateProcessEnvFromFile as et, matchesSearchLayer as f, loadEmbeddingConfig as ft, runAuditRetentionSweep as g, parseEnvContent as gt, recordAudit as h, loadTeamConfig as ht, resolveClientSecret as i, isContextInjectionEnabled as it, engineStateConfigPaths as j, captureDurableAfterMs as k, getSearchResultLayer as l, isVectorBackfillAllEnabled as lt, queryAudit as m, loadSnapshotConfig as mt, ensureServerSecret as n, isAutoCompressEnabled as nt, buildRecallResponse as o, isGraphCompactOnBootEnabled as ot, AUDIT_MIGRATION_STATE_KEY as p, loadFallbackConfig as pt, getRedisUrl as q, explicitSecret as r, isConsolidationEnabled as rt, lessonToObservation as s, isGraphExtractionEnabled as st, bearerHeaders as t, isAgentScopeIsolated as tt, isSearchLayer as u, loadClaudeBridgeConfig as ut, setAuditRecordedListener as v, VERSION as w, getAllTools as x, startAuditMigration as y, getAuditRetentionMonths as z };
 
-//# sourceMappingURL=secret-store-BnY3A50C.mjs.map
+//# sourceMappingURL=secret-store-D9GwO0xp.mjs.map