@agentmemory/agentmemory 0.9.12 → 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";
@@ -110,10 +110,12 @@ Usage: agentmemory [command] [options]
 
 Commands:
   (default)          Start agentmemory worker
+  init               Copy bundled .env.example to ~/.agentmemory/.env if absent
   status             Show connection status, memory count, flags, and health
   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;
@@ -127,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
@@ -219,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(" ")}`);
@@ -231,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;
@@ -244,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)"}`);
@@ -274,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",
@@ -287,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) {
@@ -315,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 (standalone MCP):  npx @agentmemory/agentmemory mcp",
 		"",
-		"Or skip the engine entirely for 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) {
@@ -361,12 +554,12 @@ async function main() {
 	p.intro("agentmemory");
 	if (skipEngine) {
 		p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-Cqsy23f_.mjs");
+		await import("./src-BBI-ah3h.mjs");
 		return;
 	}
 	if (await isEngineRunning()) {
 		p.log.success("iii-engine is running");
-		await import("./src-Cqsy23f_.mjs");
+		await import("./src-BBI-ah3h.mjs");
 		return;
 	}
 	if (!await startEngine()) {
@@ -410,7 +603,7 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-Cqsy23f_.mjs");
+	await import("./src-BBI-ah3h.mjs");
 }
 async function apiFetch(base, path, timeoutMs = 5e3) {
 	try {
@@ -732,6 +925,50 @@ async function runDemoSearch(base, query) {
 		topTitle: items[0]?.title ?? "(no results)"
 	};
 }
+function findEnvExample() {
+	const candidates = [
+		join(__dirname, "..", ".env.example"),
+		join(__dirname, ".env.example"),
+		join(process.cwd(), ".env.example")
+	];
+	for (const c of candidates) if (existsSync(c)) return c;
+	return null;
+}
+async function runInit() {
+	p.intro("agentmemory init");
+	const target = join(homedir(), ".agentmemory", ".env");
+	const template = findEnvExample();
+	if (!template) {
+		p.log.error("Could not locate .env.example in the package. Re-install with: npm i -g @agentmemory/agentmemory");
+		process.exit(1);
+	}
+	const dir = dirname(target);
+	const { mkdir, copyFile } = await import("node:fs/promises");
+	const { constants: fsConstants } = await import("node:fs");
+	try {
+		await mkdir(dir, { recursive: true });
+		await copyFile(template, target, fsConstants.COPYFILE_EXCL);
+	} catch (err) {
+		if (err?.code === "EEXIST") {
+			p.log.warn(`${target} already exists — leaving it untouched.`);
+			p.log.info(`Compare against the latest template: diff ${target} ${template}`);
+			p.outro("Nothing changed.");
+			return;
+		}
+		p.log.error(`Failed to copy template: ${err instanceof Error ? err.message : String(err)}`);
+		process.exit(1);
+	}
+	p.log.success(`Wrote ${target}`);
+	p.note([
+		"All keys are commented out by default. Uncomment the ones you want.",
+		"",
+		"Common next steps:",
+		"  1. Pick an LLM provider key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / etc.)",
+		"  2. Run `npx @agentmemory/agentmemory doctor` to verify the daemon sees them",
+		"  3. Run `npx @agentmemory/agentmemory` to start the worker"
+	].join("\n"), "Next steps");
+	p.outro(`Edit ${target} and you're set.`);
+}
 async function runDemo() {
 	const port = getRestPort();
 	const base = `http://localhost:${port}`;
@@ -827,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
@@ -871,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-DNt6O3zG.mjs");
+	await import("./standalone-Cf5sp0XM.mjs");
 }
 async function runImportJsonl() {
 	const VALUE_FLAGS = new Set(["--port", "--tools"]);
@@ -977,10 +1340,12 @@ async function runImportJsonl() {
 	}
 }
 ({
+	init: runInit,
 	status: runStatus,
 	doctor: runDoctor,
 	demo: runDemo,
 	upgrade: runUpgrade,
+	stop: runStop,
 	mcp: runMcp,
 	"import-jsonl": runImportJsonl
 }[args[0] ?? ""] ?? main)().catch((err) => {