@agentmemory/agentmemory 0.9.13 → 0.9.14

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync, readlinkSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir, platform } from "node:os";
@@ -115,6 +115,7 @@ Commands:
   doctor             Run diagnostic checks (server, flags, graph, providers)
   demo               Seed sample sessions and show recall in action
   upgrade            Upgrade local deps + iii runtime (best effort)
+  stop               Stop the running iii-engine started by this CLI
   mcp                Start standalone MCP server (no engine required)
   import-jsonl [p]   Import Claude Code JSONL transcripts (default: ~/.claude/projects)
                      --max-files <N> | --max-files=<N>: override scan cap (default 200, max 1000;
@@ -128,8 +129,11 @@ Options:
   --port <N>         Override REST port (default: 3111)
 
 Environment:
-  AGENTMEMORY_URL    Full REST base URL (e.g. http://localhost:3111).
-                     Honored by status, doctor, and MCP shim commands.
+  AGENTMEMORY_URL              Full REST base URL (e.g. http://localhost:3111).
+                               Honored by status, doctor, and MCP shim commands.
+  AGENTMEMORY_USE_DOCKER=1     Prefer the bundled docker-compose path over the
+                               native iii-engine binary on first run.
+  AGENTMEMORY_III_VERSION      Override pinned iii-engine version (default ${IIPINNED_VERSION}).
 
 Quick start:
   npx @agentmemory/agentmemory          # start with local iii-engine or Docker
@@ -220,6 +224,130 @@ function fallbackIiiPaths() {
 	if (!home) return ["/usr/local/bin/iii"];
 	return [join(home, ".local", "bin", "iii"), "/usr/local/bin/iii"];
 }
+function iiiBinVersion(binPath) {
+	try {
+		const match = execFileSync(binPath, ["--version"], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			timeout: 3e3
+		}).match(/(\d+\.\d+\.\d+(?:[-+][\w.]+)?)/);
+		return match ? match[1] : null;
+	} catch {
+		return null;
+	}
+}
+function enginePidfilePath() {
+	return join(homedir(), ".agentmemory", "iii.pid");
+}
+function engineStatePath() {
+	return join(homedir(), ".agentmemory", "engine-state.json");
+}
+function writeEnginePidfile(pid) {
+	try {
+		const pidPath = enginePidfilePath();
+		mkdirSync(dirname(pidPath), { recursive: true });
+		writeFileSync(pidPath, `${pid}\n`, { encoding: "utf-8" });
+	} catch (err) {
+		vlog(`writeEnginePidfile: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+function readEnginePidfile() {
+	try {
+		const pidStr = readFileSync(enginePidfilePath(), "utf-8").trim();
+		const pid = parseInt(pidStr, 10);
+		return Number.isFinite(pid) && pid > 0 ? pid : null;
+	} catch {
+		return null;
+	}
+}
+function clearEnginePidfile() {
+	try {
+		unlinkSync(enginePidfilePath());
+	} catch {}
+}
+function writeEngineState(state) {
+	try {
+		const statePath = engineStatePath();
+		mkdirSync(dirname(statePath), { recursive: true });
+		writeFileSync(statePath, `${JSON.stringify(state)}\n`, { encoding: "utf-8" });
+	} catch (err) {
+		vlog(`writeEngineState: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+function readEngineState() {
+	try {
+		const raw = readFileSync(engineStatePath(), "utf-8");
+		const parsed = JSON.parse(raw);
+		if (parsed && (parsed.kind === "native" || parsed.kind === "docker")) return parsed;
+		return null;
+	} catch {
+		return null;
+	}
+}
+function clearEngineState() {
+	try {
+		unlinkSync(engineStatePath());
+	} catch {}
+}
+function discoverComposeFile() {
+	return [
+		join(__dirname, "..", "docker-compose.yml"),
+		join(__dirname, "docker-compose.yml"),
+		join(process.cwd(), "docker-compose.yml")
+	].find((c) => existsSync(c)) ?? null;
+}
+async function runIiiInstaller() {
+	const releaseUrl = iiiReleaseUrl();
+	const asset = iiiReleaseAsset();
+	const isZipAsset = asset?.endsWith(".zip") === true;
+	if (!releaseUrl) {
+		p.log.warn(`iii-engine binary not available for ${platform()}/${process.arch}. Use Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`);
+		return {
+			ok: false,
+			binPath: null
+		};
+	}
+	if (IS_WINDOWS || isZipAsset) {
+		p.log.info(`Auto-install unavailable on ${platform()} — ${asset} isn't tar-compatible. Install manually:\n  1. Download ${releaseUrl}\n  2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\nOr use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`);
+		return {
+			ok: false,
+			binPath: null
+		};
+	}
+	const shBin = whichBinary("sh");
+	const curlBin = whichBinary("curl");
+	if (!shBin || !curlBin) {
+		p.log.warn("curl or sh not found. Cannot auto-install iii-engine.");
+		return {
+			ok: false,
+			binPath: null
+		};
+	}
+	const binDir = join(homedir(), ".local", "bin");
+	const binPath = join(binDir, "iii");
+	if (!runCommand(shBin, ["-c", [
+		`mkdir -p "${binDir}"`,
+		`curl -fsSL "${releaseUrl}" | tar -xz -C "${binDir}"`,
+		`chmod +x "${binPath}"`
+	].join(" && ")], {
+		label: `Installing iii-engine v${IIPINNED_VERSION} (pinned)`,
+		optional: true
+	})) {
+		p.log.warn(`iii-engine installer failed. Fallbacks: Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`);
+		return {
+			ok: false,
+			binPath: null
+		};
+	}
+	return {
+		ok: true,
+		binPath
+	};
+}
 let startupFailure = null;
 function spawnEngineBackground(bin, spawnArgs, label) {
 	vlog(`spawn: ${bin} ${spawnArgs.join(" ")}`);
@@ -232,6 +360,8 @@ function spawnEngineBackground(bin, spawnArgs, label) {
 		],
 		windowsHide: true
 	});
+	const isDocker = label.includes("Docker");
+	if (!isDocker && typeof child.pid === "number") writeEnginePidfile(child.pid);
 	const stderrChunks = [];
 	let stderrBytes = 0;
 	const MAX_STDERR_CAPTURE = 16 * 1024;
@@ -245,27 +375,47 @@ function spawnEngineBackground(bin, spawnArgs, label) {
 		if (code !== null && code !== 0 || code === null && signal !== null) {
 			const stderr = Buffer.concat(stderrChunks).toString("utf-8");
 			startupFailure = {
-				kind: label.includes("Docker") ? "docker-crashed" : "engine-crashed",
+				kind: isDocker ? "docker-crashed" : "engine-crashed",
 				stderr: stderr.trim() || (signal ? `process killed by signal ${signal}` : `process exited with code ${code}`),
 				binary: bin
 			};
 			vlog(`engine exited early: code=${code} signal=${signal}`);
 			if (IS_VERBOSE && stderr.trim()) p.log.error(`engine stderr:\n${stderr}`);
+			if (!isDocker) clearEnginePidfile();
+			clearEngineState();
 		}
 	});
 	child.unref();
 	return child;
 }
+function startIiiBin(iiiBin, configPath) {
+	const s = p.spinner();
+	s.start(`Starting iii-engine: ${iiiBin}`);
+	writeEngineState({
+		kind: "native",
+		configPath
+	});
+	spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
+	s.stop("iii-engine process started");
+	return true;
+}
 async function startEngine() {
 	const configPath = findIiiConfig();
 	let iiiBin = whichBinary("iii");
 	vlog(`iii binary: ${iiiBin ?? "(not on PATH)"}, config: ${configPath || "(not found)"}`);
-	if (iiiBin && configPath) {
-		const s = p.spinner();
-		s.start(`Starting iii-engine: ${iiiBin}`);
-		spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
-		s.stop("iii-engine process started");
-		return true;
+	if (iiiBin && configPath) return startIiiBin(iiiBin, configPath);
+	for (const iiiPath of fallbackIiiPaths()) if (existsSync(iiiPath)) {
+		const v = iiiBinVersion(iiiPath);
+		vlog(`fallback iii at ${iiiPath} reports version: ${v ?? "unknown"}`);
+		p.log.info(`Found iii at: ${iiiPath}${v ? ` (v${v})` : ""}`);
+		process.env["PATH"] = `${dirname(iiiPath)}${delimiter}${process.env["PATH"] ?? ""}`;
+		iiiBin = iiiPath;
+		break;
+	}
+	if (iiiBin && configPath) return startIiiBin(iiiBin, configPath);
+	if (!configPath) {
+		startupFailure = { kind: "no-engine" };
+		return false;
 	}
 	const dockerBin = whichBinary("docker");
 	vlog(`docker binary: ${dockerBin ?? "(not on PATH)"}`);
@@ -275,9 +425,73 @@ async function startEngine() {
 		join(process.cwd(), "docker-compose.yml")
 	].find((c) => existsSync(c));
 	vlog(`docker-compose.yml: ${composeFile ?? "(not found)"}`);
-	if (dockerBin && composeFile) {
+	const dockerOptIn = process.env["AGENTMEMORY_USE_DOCKER"] === "1" || process.env["AGENTMEMORY_USE_DOCKER"] === "true";
+	const interactive = !!process.stdin.isTTY && !process.env["CI"];
+	let choice;
+	if (dockerOptIn && dockerBin && composeFile) choice = "docker";
+	else if (!interactive) {
+		choice = "install";
+		p.log.info("Non-interactive environment detected — auto-installing iii-engine.");
+	} else {
+		p.log.warn(`iii-engine binary not found locally.`);
+		const options = [{
+			value: "install",
+			label: `Install iii v${IIPINNED_VERSION} to ~/.local/bin (~6MB, ~5s)`,
+			hint: "recommended"
+		}];
+		if (dockerBin && composeFile) options.push({
+			value: "docker",
+			label: "Use Docker compose",
+			hint: "advanced"
+		});
+		options.push({
+			value: "manual",
+			label: "Show manual install steps and exit"
+		});
+		const picked = await p.select({
+			message: "How would you like to start iii-engine?",
+			options,
+			initialValue: "install"
+		});
+		if (p.isCancel(picked)) {
+			startupFailure = { kind: "no-engine" };
+			return false;
+		}
+		choice = picked;
+	}
+	if (choice === "manual") {
+		startupFailure = { kind: "no-engine" };
+		return false;
+	}
+	if (choice === "install") {
+		const result = await runIiiInstaller();
+		if (result.ok && result.binPath) {
+			process.env["PATH"] = `${dirname(result.binPath)}${delimiter}${process.env["PATH"] ?? ""}`;
+			iiiBin = result.binPath;
+			return startIiiBin(iiiBin, configPath);
+		}
+		if (dockerBin && composeFile && interactive) {
+			const fallback = await p.confirm({
+				message: "Auto-install failed. Try Docker compose instead?",
+				initialValue: true
+			});
+			if (p.isCancel(fallback) || fallback !== true) {
+				startupFailure = { kind: "no-engine" };
+				return false;
+			}
+			choice = "docker";
+		} else {
+			startupFailure = { kind: "no-engine" };
+			return false;
+		}
+	}
+	if (choice === "docker" && dockerBin && composeFile) {
 		const s = p.spinner();
 		s.start("Starting iii-engine via Docker...");
+		writeEngineState({
+			kind: "docker",
+			composeFile
+		});
 		spawnEngineBackground(dockerBin, [
 			"compose",
 			"-f",
@@ -288,21 +502,8 @@ async function startEngine() {
 		s.stop("Docker compose started");
 		return true;
 	}
-	for (const iiiPath of fallbackIiiPaths()) if (existsSync(iiiPath)) {
-		p.log.info(`Found iii at: ${iiiPath}`);
-		process.env["PATH"] = `${dirname(iiiPath)}${delimiter}${process.env["PATH"] ?? ""}`;
-		iiiBin = iiiPath;
-		break;
-	}
-	if (iiiBin && configPath) {
-		const s = p.spinner();
-		s.start(`Starting iii-engine: ${iiiBin}`);
-		spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
-		s.stop("iii-engine process started");
-		return true;
-	}
-	if (!iiiBin && (!dockerBin || !composeFile)) startupFailure = { kind: "no-engine" };
-	else if (!composeFile && dockerBin) startupFailure = { kind: "no-docker-compose" };
+	if (!composeFile && dockerBin) startupFailure = { kind: "no-docker-compose" };
+	else startupFailure = { kind: "no-engine" };
 	return false;
 }
 async function waitForEngine(timeoutMs) {
@@ -316,43 +517,34 @@ async function waitForEngine(timeoutMs) {
 function installInstructions() {
 	const releaseUrl = iiiReleaseUrl();
 	if (IS_WINDOWS) return [
-		`agentmemory requires the \`iii-engine\` runtime, pinned to v${IIPINNED_VERSION}. Pick one:`,
+		`agentmemory needs iii-engine v${IIPINNED_VERSION}. Pick one:`,
 		"",
 		"  A) Download the prebuilt Windows binary:",
 		`     1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`,
-		`     2. Download iii-x86_64-pc-windows-msvc.zip`,
-		"        (or iii-aarch64-pc-windows-msvc.zip on ARM)",
-		"     3. Extract iii.exe and either add its folder to PATH",
-		"        or move it to %USERPROFILE%\\.local\\bin\\iii.exe",
+		`     2. Download iii-x86_64-pc-windows-msvc.zip (or iii-aarch64-pc-windows-msvc.zip on ARM)`,
+		"     3. Extract iii.exe to %USERPROFILE%\\.local\\bin\\iii.exe (or add to PATH)",
 		"     4. Re-run: npx @agentmemory/agentmemory",
 		"",
-		"  B) Docker Desktop:",
-		"     1. Install Docker Desktop for Windows",
-		`     2. docker pull iiidev/iii:${IIPINNED_VERSION}`,
-		"     3. Start Docker Desktop (engine must be running)",
-		"     4. Re-run: npx @agentmemory/agentmemory",
+		`  B) Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
+		"     Re-run with AGENTMEMORY_USE_DOCKER=1 npx @agentmemory/agentmemory",
 		"",
-		"Or skip the engine entirely for standalone MCP:",
-		"  npx @agentmemory/agentmemory mcp"
+		"Or skip the engine entirely (standalone MCP):  npx @agentmemory/agentmemory mcp",
+		"",
+		"Docs: https://iii.dev/docs"
 	];
-	const linuxInstall = releaseUrl ? `  A) mkdir -p ~/.local/bin && curl -fsSL "${releaseUrl}" | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii` : `  A) Manual download from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
+	const linuxInstall = releaseUrl ? `  A) curl -fsSL "${releaseUrl}" | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii` : `  A) Manual download: https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
 	return [
-		`agentmemory requires the \`iii-engine\` runtime, pinned to v${IIPINNED_VERSION}. Pick one:`,
+		`agentmemory needs iii-engine v${IIPINNED_VERSION}. Pick one:`,
 		"",
 		linuxInstall,
-		`     (installs iii v${IIPINNED_VERSION} into ~/.local/bin/iii)`,
+		"     Then re-run: npx @agentmemory/agentmemory",
 		"",
-		`  B) Docker: \`docker pull iiidev/iii:${IIPINNED_VERSION}\``,
+		`  B) Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
+		"     Re-run with AGENTMEMORY_USE_DOCKER=1 npx @agentmemory/agentmemory",
 		"",
-		"Or skip the engine entirely for standalone MCP:",
-		"  npx @agentmemory/agentmemory mcp",
+		"Or skip the engine entirely (standalone MCP):  npx @agentmemory/agentmemory mcp",
 		"",
-		"Docs: https://iii.dev/docs",
-		`Why pinned: iii v0.11.6 introduces the new sandbox-everything model`,
-		`(\`iii worker add\` registration). agentmemory still uses the older`,
-		`iii-exec config-file worker model and needs a refactor before it`,
-		`runs cleanly under the new engine. Override with`,
-		`AGENTMEMORY_III_VERSION=<version> when you've migrated manually.`
+		"Docs: https://iii.dev/docs"
 	];
 }
 function portInUseDiagnostic(port) {
@@ -362,12 +554,12 @@ async function main() {
 	p.intro("agentmemory");
 	if (skipEngine) {
 		p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-Ca9oX6Hq.mjs");
+		await import("./src-BBI-ah3h.mjs");
 		return;
 	}
 	if (await isEngineRunning()) {
 		p.log.success("iii-engine is running");
-		await import("./src-Ca9oX6Hq.mjs");
+		await import("./src-BBI-ah3h.mjs");
 		return;
 	}
 	if (!await startEngine()) {
@@ -411,7 +603,7 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-Ca9oX6Hq.mjs");
+	await import("./src-BBI-ah3h.mjs");
 }
 async function apiFetch(base, path, timeoutMs = 5e3) {
 	try {
@@ -872,36 +1064,16 @@ async function runUpgrade() {
 		});
 	} else p.log.warn("No package manager found (pnpm/npm). Skipping JS dependency upgrade.");
 	else p.log.warn("No package.json in current directory. Skipping JS dependency upgrade.");
-	const shBin = whichBinary("sh");
-	const curlBin = whichBinary("curl");
-	if (shBin && curlBin) {
-		const upgradeEngine = await p.confirm({
-			message: "Re-run the iii-engine install script (curl | sh)?",
-			initialValue: true
-		});
-		if (p.isCancel(upgradeEngine)) {
-			p.cancel("Cancelled.");
-			return process.exit(0);
-		}
-		if (upgradeEngine === true) {
-			const releaseUrl = iiiReleaseUrl();
-			const asset = iiiReleaseAsset();
-			const isZipAsset = asset?.endsWith(".zip") === true;
-			if (!releaseUrl) p.log.warn(`iii-engine binary not available for ${platform()}/${process.arch}. Use Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`);
-			else if (IS_WINDOWS || isZipAsset) p.log.info(`Skipping auto-install on ${platform()} — the ${asset} asset isn't tar-compatible. Install manually:\n  1. Download ${releaseUrl}\n  2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\nOr use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`);
-			else {
-				const binDir = join(homedir(), ".local", "bin");
-				if (!runCommand(shBin, ["-c", [
-					`mkdir -p "${binDir}"`,
-					`curl -fsSL "${releaseUrl}" | tar -xz -C "${binDir}"`,
-					`chmod +x "${binDir}/iii"`
-				].join(" && ")], {
-					label: `Installing iii-engine v${IIPINNED_VERSION} (pinned)`,
-					optional: true
-				})) p.log.warn(`iii-engine installer failed. Fallbacks: Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`);
-			}
-		} else p.log.info("Skipped iii-engine installer.");
-	} else p.log.warn("curl or sh not found. Skipping iii-engine installer.");
+	const upgradeEngine = await p.confirm({
+		message: "Re-run the iii-engine install script (curl | sh)?",
+		initialValue: true
+	});
+	if (p.isCancel(upgradeEngine)) {
+		p.cancel("Cancelled.");
+		return process.exit(0);
+	}
+	if (upgradeEngine === true) await runIiiInstaller();
+	else p.log.info("Skipped iii-engine installer.");
 	if (dockerBin) runCommand(dockerBin, ["pull", `iiidev/iii:${IIPINNED_VERSION}`], {
 		label: `Pulling iii Docker image v${IIPINNED_VERSION} (pinned)`,
 		optional: true
@@ -916,8 +1088,154 @@ async function runUpgrade() {
 		"  3) restart agentmemory process"
 	].join("\n"), "agentmemory upgrade");
 }
+function pidAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err?.code === "EPERM";
+	}
+}
+async function signalAndWait(pid, initialSignal, timeoutMs) {
+	try {
+		process.kill(pid, initialSignal);
+	} catch (err) {
+		const code = err?.code;
+		if (code === "ESRCH") return true;
+		if (code === "EPERM") {
+			p.log.warn(`No permission to signal pid ${pid}. Try: kill ${pid}`);
+			return false;
+		}
+		vlog(`${initialSignal} ${pid}: ${err instanceof Error ? err.message : String(err)}`);
+		return false;
+	}
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (!pidAlive(pid)) return true;
+		await new Promise((r) => setTimeout(r, 200));
+	}
+	if (!pidAlive(pid)) return true;
+	try {
+		process.kill(pid, "SIGKILL");
+	} catch (err) {
+		if (err?.code === "ESRCH") return true;
+		vlog(`SIGKILL ${pid}: ${err instanceof Error ? err.message : String(err)}`);
+		return false;
+	}
+	await new Promise((r) => setTimeout(r, 200));
+	return !pidAlive(pid);
+}
+function findEnginePidsByPort(port) {
+	if (IS_WINDOWS) return [];
+	const lsof = whichBinary("lsof");
+	if (!lsof) return [];
+	const selfPid = process.pid;
+	try {
+		return execFileSync(lsof, [
+			"-i",
+			`:${port}`,
+			"-sTCP:LISTEN",
+			"-t"
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).split(/\s+/).map((s) => parseInt(s, 10)).filter((n) => Number.isFinite(n) && n > 0 && n !== selfPid);
+	} catch (err) {
+		vlog(`lsof :${port}: ${err instanceof Error ? err.message : String(err)}`);
+		return [];
+	}
+}
+async function stopDockerEngine(composeFile, port) {
+	const dockerBin = whichBinary("docker");
+	if (!dockerBin) {
+		p.log.error(`Engine was started via Docker compose, but \`docker\` is no longer on PATH. Stop it manually:\n  docker compose -f ${composeFile} down`);
+		process.exit(1);
+	}
+	if (!existsSync(composeFile)) {
+		p.log.error(`Engine state references ${composeFile}, but the file is gone. Stop it manually:\n  docker compose down  (from the dir holding the original docker-compose.yml)`);
+		process.exit(1);
+	}
+	const ok = runCommand(dockerBin, [
+		"compose",
+		"-f",
+		composeFile,
+		"down"
+	], { label: `docker compose -f ${composeFile} down` });
+	clearEnginePidfile();
+	clearEngineState();
+	if (!ok) {
+		p.log.error(`docker compose down failed. The engine may still be running on :${port}. Inspect with:\n  docker compose -f ${composeFile} ps`);
+		process.exit(1);
+	}
+	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
+}
+async function runStop() {
+	p.intro("agentmemory stop");
+	const port = getRestPort();
+	const state = readEngineState();
+	const running = await isEngineRunning();
+	if (state?.kind === "docker") {
+		if (!running) {
+			p.log.info(`No engine responding on port ${port}.`);
+			clearEnginePidfile();
+			clearEngineState();
+			p.outro("Nothing to stop.");
+			return;
+		}
+		await stopDockerEngine(state.composeFile, port);
+		return;
+	}
+	const portPids = findEnginePidsByPort(port);
+	const pidfilePid = readEnginePidfile();
+	if (!running) {
+		if (portPids.length === 0 && pidfilePid === null) {
+			clearEnginePidfile();
+			clearEngineState();
+			p.outro("Nothing to stop.");
+			return;
+		}
+		const survivors = new Set(portPids);
+		if (pidfilePid) survivors.add(pidfilePid);
+		p.log.warn(`Engine not responding on :${port}, but ${survivors.size} process(es) still hold the port or pidfile: ${[...survivors].join(", ")}`);
+		p.log.info(`Preserving ~/.agentmemory/iii.pid. Investigate before manual cleanup:\n  ps -p ${[...survivors].join(",")} -o pid,ppid,comm,etime\n  ${IS_WINDOWS ? "netstat -ano | findstr :" + port : "lsof -i :" + port}`);
+		process.exit(1);
+	}
+	if (!state) {
+		const compose = discoverComposeFile();
+		if (compose && pidfilePid === null) {
+			p.log.error(`Engine is running on :${port} but no pidfile or state file is present. It may have been started via Docker compose by a different shell. Refusing to signal host PIDs.\n\nStop it with:\n  docker compose -f ${compose} down\n\nOr re-run with AGENTMEMORY_USE_DOCKER=1 to record state next time.`);
+			process.exit(1);
+		}
+	}
+	const candidates = /* @__PURE__ */ new Set();
+	if (pidfilePid) candidates.add(pidfilePid);
+	for (const pid of portPids) candidates.add(pid);
+	if (candidates.size === 0) {
+		p.log.error(`Could not locate engine process. Try:\n  ${IS_WINDOWS ? "netstat -ano | findstr :" + port : "lsof -i :" + port + " -t | xargs kill -9"}`);
+		process.exit(1);
+	}
+	let allStopped = true;
+	for (const pid of candidates) {
+		const s = p.spinner();
+		s.start(`Stopping iii-engine (pid ${pid})...`);
+		const ok = await signalAndWait(pid, "SIGTERM", 3e3);
+		s.stop(ok ? `Stopped pid ${pid}` : `Failed to stop pid ${pid}`);
+		if (!ok) allStopped = false;
+	}
+	clearEnginePidfile();
+	clearEngineState();
+	if (!allStopped) {
+		p.log.error("One or more engine processes survived SIGKILL. Investigate with `ps`.");
+		process.exit(1);
+	}
+	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
+}
 async function runMcp() {
-	await import("./standalone-BpbiNqr9.mjs");
+	await import("./standalone-Cf5sp0XM.mjs");
 }
 async function runImportJsonl() {
 	const VALUE_FLAGS = new Set(["--port", "--tools"]);
@@ -1027,6 +1345,7 @@ async function runImportJsonl() {
 	doctor: runDoctor,
 	demo: runDemo,
 	upgrade: runUpgrade,
+	stop: runStop,
 	mcp: runMcp,
 	"import-jsonl": runImportJsonl
 }[args[0] ?? ""] ?? main)().catch((err) => {