@agentmemory/agentmemory 0.9.13 → 0.9.15

package/dist/cli.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync, readlinkSync, statSync } from "node:fs";
+import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir, platform } from "node:os";
 import * as p from "@clack/prompts";
 import { createHash } from "node:crypto";
+import { copyFile, mkdir } from "node:fs/promises";
 
 //#region src/state/schema.ts
 const KV = {
@@ -75,12 +76,741 @@ function jaccardSimilarity(a, b) {
 	return intersection / (setA.size + setB.size - intersection);
 }
 
+//#endregion
+//#region src/cli/doctor-diagnostics.ts
+/** Common placeholder values shipped in .env.example. */
+const PLACEHOLDER_VALUES = new Set([
+	"",
+	"your-key-here",
+	"sk-ant-...",
+	"sk-...",
+	"changeme",
+	"todo",
+	"xxx"
+]);
+const PROVIDER_KEY_NAMES = [
+	"ANTHROPIC_API_KEY",
+	"OPENAI_API_KEY",
+	"GEMINI_API_KEY",
+	"GOOGLE_API_KEY",
+	"OPENROUTER_API_KEY",
+	"MINIMAX_API_KEY"
+];
+function parseEnvFile(content) {
+	const out = {};
+	for (const rawLine of content.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq < 0) continue;
+		const key = line.slice(0, eq).trim();
+		let value = line.slice(eq + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+		out[key] = value;
+	}
+	return out;
+}
+/** Returns the list of provider keys that look real (non-placeholder). */
+function realProviderKeys(env) {
+	return PROVIDER_KEY_NAMES.filter((k) => {
+		const v = (env[k] ?? "").trim();
+		if (!v) return false;
+		if (PLACEHOLDER_VALUES.has(v.toLowerCase())) return false;
+		if (/^x+$/i.test(v.replace(/[-_]/g, ""))) return false;
+		return true;
+	});
+}
+/** Returns the list of provider key NAMES that exist but are placeholders. */
+function placeholderProviderKeys(env) {
+	return PROVIDER_KEY_NAMES.filter((k) => {
+		const v = (env[k] ?? "").trim();
+		if (!v) return false;
+		if (PLACEHOLDER_VALUES.has(v.toLowerCase())) return true;
+		if (/^x+$/i.test(v.replace(/[-_]/g, ""))) return true;
+		return false;
+	});
+}
+function buildDiagnostics(effects) {
+	return [
+		{
+			id: "env-missing",
+			message: "~/.agentmemory/.env is missing.",
+			fixPreview: "Copy .env.example into ~/.agentmemory/.env (your keys file).",
+			moreInfo: "agentmemory reads provider API keys (Anthropic, OpenAI, Gemini, …) from ~/.agentmemory/.env. Without this file the daemon falls back to BM25-only search and no LLM-backed enrichment runs.",
+			check: async () => ({
+				ok: effects.envFileExists(),
+				detail: effects.envFileExists() ? void 0 : "no env file"
+			}),
+			fix: () => effects.runInit()
+		},
+		{
+			id: "no-llm-provider-key",
+			message: "No LLM provider API key found in ~/.agentmemory/.env.",
+			fixPreview: "Open ~/.agentmemory/.env in $EDITOR and paste your key, then re-check.",
+			moreInfo: "Set at least one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, MINIMAX_API_KEY. The daemon picks the first that resolves to a real (non-placeholder) value at startup.",
+			check: async () => {
+				if (!effects.envFileExists()) return {
+					ok: false,
+					detail: "env file missing (run env-missing fix first)"
+				};
+				const real = realProviderKeys(effects.readEnvFile());
+				return {
+					ok: real.length > 0,
+					detail: real.length > 0 ? `found: ${real.join(", ")}` : "no provider key set"
+				};
+			},
+			fix: (ctx) => effects.openEditor(ctx.envPath)
+		},
+		{
+			id: "engine-version-mismatch",
+			message: "iii binary on PATH doesn't match the version agentmemory pins to.",
+			fixPreview: "Re-run the iii installer for the pinned version and restart the engine.",
+			moreInfo: "agentmemory pins the iii engine to a specific release because newer engines use a different worker model. Running a mismatched binary surfaces as EPIPE reconnect loops and empty search results.",
+			check: async (ctx) => {
+				const bin = effects.findIiiBinary();
+				if (!bin) return {
+					ok: false,
+					detail: "iii not on PATH"
+				};
+				const v = effects.iiiBinaryVersion(bin);
+				if (!v) return {
+					ok: false,
+					detail: "iii on PATH but --version failed"
+				};
+				return {
+					ok: v === ctx.pinnedVersion,
+					detail: `${v} (pinned ${ctx.pinnedVersion})`
+				};
+			},
+			fix: async () => {
+				const r = await effects.runIiiInstaller();
+				if (!r.ok) return r;
+				await effects.runStop();
+				return effects.runStart();
+			}
+		},
+		{
+			id: "viewer-unreachable",
+			message: "Viewer port not reachable.",
+			fixPreview: "Stop the engine, restart it, and retry the viewer probe.",
+			moreInfo: "The viewer is served on REST port + 2 (default 3113). If it never came up the most common cause is port collision; a sibling PR ships auto-bump for this case. If that lands first this check just verifies; otherwise restart the engine to retry binding.",
+			check: async () => ({
+				ok: await effects.viewerReachable(),
+				detail: void 0
+			}),
+			fix: async () => {
+				const stopped = await effects.runStop();
+				if (!stopped.ok) return stopped;
+				return effects.runStart();
+			}
+		},
+		{
+			id: "stale-pidfile",
+			message: "Stale pidfile: pid recorded but the process is gone.",
+			fixPreview: "Clear ~/.agentmemory/iii.pid + engine-state.json, then restart.",
+			moreInfo: "When the engine crashes hard (kill -9, OOM, host reboot) the pidfile sticks around. agentmemory refuses to start a second engine on top of a stale pid, so this state must be cleared explicitly.",
+			check: async () => {
+				if (!effects.pidfileExists()) return {
+					ok: true,
+					detail: "no pidfile"
+				};
+				const alive = effects.pidfilePidIsAlive();
+				if (alive === null) return {
+					ok: true,
+					detail: "pidfile unreadable"
+				};
+				return {
+					ok: alive,
+					detail: alive ? "pid is alive" : "pid is gone"
+				};
+			},
+			fix: async () => {
+				effects.clearEnginePidAndState();
+				return effects.runStart();
+			}
+		},
+		{
+			id: "env-placeholder-keys",
+			message: "~/.agentmemory/.env contains placeholder/empty API keys.",
+			fixPreview: "Open ~/.agentmemory/.env in $EDITOR to paste real values.",
+			moreInfo: "Lines like ANTHROPIC_API_KEY=sk-ant-... or =your-key-here are treated as absent. The daemon will fall back to BM25-only search. Replace placeholders with real keys or comment the line out.",
+			check: async () => {
+				if (!effects.envFileExists()) return {
+					ok: true,
+					detail: "env file missing (handled by env-missing)"
+				};
+				const placeholders = placeholderProviderKeys(effects.readEnvFile());
+				return {
+					ok: placeholders.length === 0,
+					detail: placeholders.length === 0 ? void 0 : `placeholder: ${placeholders.join(", ")}`
+				};
+			},
+			fix: (ctx) => effects.openEditor(ctx.envPath)
+		},
+		{
+			id: "iii-on-path-not-local-bin",
+			message: "iii is on PATH but not in ~/.local/bin/iii (where we install).",
+			fixPreview: "Suggest re-installing the pinned version via the installer — won't touch your PATH.",
+			moreInfo: "agentmemory's installer writes to ~/.local/bin/iii. When a user-managed iii lives somewhere else (homebrew, cargo, $XDG_BIN) we don't auto-overwrite it. If you want our pinned build, run the installer; otherwise this is informational.",
+			manualOnly: true,
+			check: async () => {
+				const bin = effects.findIiiBinary();
+				if (!bin) return {
+					ok: true,
+					detail: "iii not on PATH (handled elsewhere)"
+				};
+				const localBin = effects.localBinIiiPath();
+				return {
+					ok: bin === localBin,
+					detail: bin === localBin ? void 0 : `iii at: ${bin}`
+				};
+			},
+			fix: async () => effects.runIiiInstaller().then((r) => ({
+				ok: r.ok,
+				message: r.message ?? "Installer wrote to ~/.local/bin/iii. Your PATH wasn't modified — adjust it yourself if needed."
+			}))
+		}
+	];
+}
+/**
+* Dry-run output: each failing check's fix preview, prefixed by the diagnostic
+* message. Pure function so we can snapshot-test the format.
+*/
+function dryRunPlan(ctx, results) {
+	const lines = [];
+	let n = 0;
+	for (const { diagnostic, status } of results) {
+		if (status.ok) continue;
+		n++;
+		lines.push(`${n}. [${diagnostic.id}] ${diagnostic.message}`);
+		lines.push(`   would fix: ${diagnostic.fixPreview}`);
+		if (status.detail) lines.push(`   detail: ${status.detail}`);
+	}
+	if (lines.length === 0) lines.push(`All checks passing for ${ctx.baseUrl} — no fixes to run.`);
+	return lines;
+}
+
+//#endregion
+//#region src/cli/remove-plan.ts
+function pidfilePath(home) {
+	return join(home, ".agentmemory", "iii.pid");
+}
+function enginePath(home) {
+	return join(home, ".agentmemory", "engine-state.json");
+}
+function envPath(home) {
+	return join(home, ".agentmemory", ".env");
+}
+function preferencesPath(home) {
+	return join(home, ".agentmemory", "preferences.json");
+}
+function backupsDir(home) {
+	return join(home, ".agentmemory", "backups");
+}
+function dataDir(home) {
+	return join(home, ".agentmemory", "data");
+}
+function localBinIii(home) {
+	return join(home, ".local", "bin", "iii");
+}
+function safeSize(path) {
+	try {
+		return statSync(path).size;
+	} catch {
+		return -1;
+	}
+}
+function pathExists(path) {
+	try {
+		return existsSync(path);
+	} catch {
+		return false;
+	}
+}
+/**
+* Build the destruction plan for `agentmemory remove`.
+*
+* Plan items are returned regardless of whether `applicable` is true — the
+* caller can decide whether to skip-and-log or hide entirely. This keeps
+* the structure stable for tests.
+*/
+function buildRemovePlan(ctx, options) {
+	const { home, pinnedVersion, localBinIiiVersion, connectManifest } = ctx;
+	const plan = [];
+	plan.push({
+		id: "stop-engine",
+		description: "Stop running iii-engine (if any) cleanly",
+		path: null,
+		alwaysAsk: false,
+		applicable: pathExists(pidfilePath(home)) || pathExists(enginePath(home)),
+		sizeBytes: -1
+	});
+	plan.push({
+		id: "pidfile",
+		description: "Delete pidfile",
+		path: pidfilePath(home),
+		alwaysAsk: false,
+		applicable: pathExists(pidfilePath(home)),
+		sizeBytes: safeSize(pidfilePath(home))
+	});
+	plan.push({
+		id: "engine-state",
+		description: "Delete engine-state.json",
+		path: enginePath(home),
+		alwaysAsk: false,
+		applicable: pathExists(enginePath(home)),
+		sizeBytes: safeSize(enginePath(home))
+	});
+	plan.push({
+		id: "env",
+		description: "Delete .env (your API keys) — will ask separately",
+		path: envPath(home),
+		alwaysAsk: true,
+		applicable: !options.keepData && pathExists(envPath(home)),
+		sizeBytes: safeSize(envPath(home))
+	});
+	plan.push({
+		id: "preferences",
+		description: "Delete preferences.json",
+		path: preferencesPath(home),
+		alwaysAsk: false,
+		applicable: !options.keepData && pathExists(preferencesPath(home)),
+		sizeBytes: safeSize(preferencesPath(home))
+	});
+	plan.push({
+		id: "backups",
+		description: "Delete backups/ directory (connect manifest + backups)",
+		path: backupsDir(home),
+		alwaysAsk: false,
+		applicable: !options.keepData && pathExists(backupsDir(home)),
+		sizeBytes: -1
+	});
+	if (connectManifest?.installed?.length) for (const entry of connectManifest.installed) plan.push({
+		id: `connect:${entry.target}`,
+		description: `Remove agent connection (${entry.agent ?? "unknown"})`,
+		path: entry.target,
+		alwaysAsk: false,
+		applicable: pathExists(entry.target),
+		sizeBytes: safeSize(entry.target)
+	});
+	const localIii = localBinIii(home);
+	if (pathExists(localIii)) {
+		const matches = localBinIiiVersion === pinnedVersion;
+		plan.push({
+			id: "local-bin-iii",
+			description: matches ? `Delete ~/.local/bin/iii (matches pinned v${pinnedVersion})` : `Delete ~/.local/bin/iii (version ${localBinIiiVersion ?? "unknown"} != pinned v${pinnedVersion}) — will ask`,
+			path: localIii,
+			alwaysAsk: !matches,
+			applicable: true,
+			sizeBytes: safeSize(localIii)
+		});
+	}
+	plan.push({
+		id: "data-dir",
+		description: "Delete memory data directory (~/.agentmemory/data/) — will ask separately",
+		path: dataDir(home),
+		alwaysAsk: true,
+		applicable: !options.keepData && pathExists(dataDir(home)),
+		sizeBytes: -1
+	});
+	return plan;
+}
+/** Format a plan for the user — one line per item. */
+function formatPlan(plan) {
+	return plan.filter((p) => p.applicable).map((p, i) => {
+		const tag = p.alwaysAsk ? " [asks]" : "";
+		const sz = p.sizeBytes > 0 ? ` (${humanBytes(p.sizeBytes)})` : "";
+		return `  ${i + 1}. ${p.description}${tag}${sz}${p.path ? `\n     ${p.path}` : ""}`;
+	}).join("\n");
+}
+function humanBytes(n) {
+	if (n < 1024) return `${n} B`;
+	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+	return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+//#endregion
+//#region src/cli/splash.ts
+const IS_COLOR_TTY = !!process.stdout.isTTY && !process.env["NO_COLOR"];
+function accent(s) {
+	return IS_COLOR_TTY ? `\x1b[38;5;208m${s}\x1b[0m` : s;
+}
+function dim(s) {
+	return IS_COLOR_TTY ? `\x1b[2m${s}\x1b[22m` : s;
+}
+function bold(s) {
+	return IS_COLOR_TTY ? `\x1b[1m${s}\x1b[22m` : s;
+}
+function getTerminalWidth() {
+	const w = process.stdout.columns;
+	return typeof w === "number" && w > 0 ? w : 80;
+}
+const TAGLINE = "Persistent memory for AI coding agents";
+function fullBanner(version) {
+	const lines = ["", ...[
+		"                       _                                                  ",
+		"  __ _  __ _  ___ _ _ | |_ _ __  ___ _ __ ___   ___  _ __ _   _          ",
+		" / _` |/ _` |/ _ \\ '_\\| __| '  \\/ -_) '  \\ _ \\ / _ \\| '__| | | |         ",
+		"| (_| | (_| |  __/ | || |_| | | \\___| | | | | | (_) | |  | |_| |         ",
+		" \\__,_|\\__, |\\___|_|  \\__|_| |_|    |_| |_| |_|\\___/|_|   \\__, |         ",
+		"       |___/                                              |___/          "
+	].map((line) => "  " + accent(line))];
+	lines.push("");
+	lines.push("  " + bold(TAGLINE) + "  " + dim(`v${version}`));
+	lines.push("");
+	return lines.join("\n");
+}
+function compactBanner(version) {
+	return [
+		"",
+		"  " + bold(accent("agentmemory")),
+		"  " + dim(`v${version} · ${TAGLINE}`),
+		""
+	].join("\n");
+}
+function minimalBanner(version) {
+	return `${accent("agentmemory")} ${dim(`v${version}`)}`;
+}
+function renderSplash(version) {
+	const width = getTerminalWidth();
+	let out;
+	if (width >= 120) out = fullBanner(version);
+	else if (width >= 80) out = compactBanner(version);
+	else out = minimalBanner(version);
+	process.stdout.write(out + "\n");
+}
+
+//#endregion
+//#region src/cli/preferences.ts
+const DEFAULTS = {
+	schemaVersion: 1,
+	lastAgent: null,
+	lastAgents: [],
+	lastProvider: null,
+	skipSplash: false,
+	skipNpxHint: false,
+	firstRunAt: null
+};
+function prefsDir() {
+	return join(homedir(), ".agentmemory");
+}
+function prefsPath() {
+	return join(prefsDir(), "preferences.json");
+}
+function readPrefs() {
+	try {
+		if (!existsSync(prefsPath())) return { ...DEFAULTS };
+		const raw = readFileSync(prefsPath(), "utf-8");
+		const parsed = JSON.parse(raw);
+		return {
+			...DEFAULTS,
+			...parsed,
+			schemaVersion: 1
+		};
+	} catch {
+		return { ...DEFAULTS };
+	}
+}
+function writePrefs(p) {
+	try {
+		mkdirSync(prefsDir(), { recursive: true });
+		const next = {
+			...readPrefs(),
+			...p,
+			schemaVersion: 1
+		};
+		const target = prefsPath();
+		const tmp = target + ".tmp";
+		const fd = openSync(tmp, "w", 384);
+		try {
+			writeSync(fd, JSON.stringify(next, null, 2) + "\n");
+			try {
+				fsyncSync(fd);
+			} catch {}
+		} finally {
+			closeSync(fd);
+		}
+		renameSync(tmp, target);
+	} catch {}
+}
+function resetPrefs() {
+	try {
+		unlinkSync(prefsPath());
+	} catch {}
+}
+function isFirstRun() {
+	if (!existsSync(prefsPath())) return true;
+	return readPrefs().firstRunAt === null;
+}
+
+//#endregion
+//#region src/cli/onboarding.ts
+const __dirname$1 = dirname(fileURLToPath(import.meta.url));
+const NATIVE_AGENTS = [
+	{
+		value: "claude-code",
+		label: "Claude Code",
+		glyph: "⟁"
+	},
+	{
+		value: "codex",
+		label: "Codex",
+		glyph: "◎"
+	},
+	{
+		value: "openhuman",
+		label: "OpenHuman",
+		glyph: "◇"
+	},
+	{
+		value: "openclaw",
+		label: "OpenClaw",
+		glyph: "◇"
+	},
+	{
+		value: "hermes",
+		label: "Hermes",
+		glyph: "◇"
+	},
+	{
+		value: "pi",
+		label: "Pi",
+		glyph: "◇"
+	},
+	{
+		value: "cursor",
+		label: "Cursor",
+		glyph: "◫"
+	},
+	{
+		value: "gemini-cli",
+		label: "Gemini CLI",
+		glyph: "✦"
+	}
+];
+const MCP_AGENTS = [
+	{
+		value: "opencode",
+		label: "OpenCode",
+		glyph: "⬡"
+	},
+	{
+		value: "cline",
+		label: "Cline",
+		glyph: "◇"
+	},
+	{
+		value: "goose",
+		label: "Goose",
+		glyph: "◇"
+	},
+	{
+		value: "kilo",
+		label: "Kilo",
+		glyph: "◇"
+	},
+	{
+		value: "aider",
+		label: "Aider",
+		glyph: "◇"
+	},
+	{
+		value: "claude-desktop",
+		label: "Claude Desktop",
+		glyph: "⟁"
+	},
+	{
+		value: "windsurf",
+		label: "Windsurf",
+		glyph: "◇"
+	},
+	{
+		value: "roo",
+		label: "Roo",
+		glyph: "◇"
+	}
+];
+const PROVIDERS = [
+	{
+		value: "anthropic",
+		label: "Anthropic — claude",
+		envKey: "ANTHROPIC_API_KEY"
+	},
+	{
+		value: "openai",
+		label: "OpenAI — gpt",
+		envKey: "OPENAI_API_KEY"
+	},
+	{
+		value: "gemini",
+		label: "Google — gemini",
+		envKey: "GEMINI_API_KEY"
+	},
+	{
+		value: "openrouter",
+		label: "OpenRouter — multi-model",
+		envKey: "OPENROUTER_API_KEY"
+	},
+	{
+		value: "minimax",
+		label: "MiniMax — minimax-m1",
+		envKey: "MINIMAX_API_KEY"
+	},
+	{
+		value: "skip",
+		label: "Skip — BM25-only mode (no LLM key)",
+		envKey: null
+	}
+];
+function buildAgentOptions() {
+	return [...NATIVE_AGENTS.map((a) => ({
+		value: a.value,
+		label: `${a.glyph} ${a.label}`,
+		hint: "native plugin"
+	})), ...MCP_AGENTS.map((a) => ({
+		value: a.value,
+		label: `${a.glyph} ${a.label}`,
+		hint: "MCP server"
+	}))];
+}
+function findEnvExample$1() {
+	const candidates = [
+		join(__dirname$1, "..", "..", ".env.example"),
+		join(__dirname$1, "..", ".env.example"),
+		join(__dirname$1, ".env.example"),
+		join(process.cwd(), ".env.example")
+	];
+	for (const c of candidates) if (existsSync(c)) return c;
+	return null;
+}
+async function seedEnvFile(provider) {
+	const target = join(homedir(), ".agentmemory", ".env");
+	await mkdir(dirname(target), { recursive: true });
+	const template = findEnvExample$1();
+	if (template && !existsSync(target)) try {
+		await copyFile(template, target, constants.COPYFILE_EXCL);
+	} catch (err) {
+		if (err?.code !== "EEXIST") return null;
+	}
+	else if (!template && !existsSync(target)) {
+		const lines = [
+			"# agentmemory environment — uncomment what you need",
+			"# AGENTMEMORY_URL=http://localhost:3111",
+			""
+		];
+		const envKey = PROVIDERS.find((x) => x.value === provider)?.envKey;
+		if (envKey) lines.push(`# ${envKey}=`);
+		writeFileSync(target, lines.join("\n"), { mode: 384 });
+	}
+	return target;
+}
+async function runOnboarding() {
+	p.note([
+		"Welcome to agentmemory.",
+		"",
+		"Persistent memory for your AI coding agents. We'll pick which",
+		"agents to wire up and which provider (if any) handles compression",
+		"and consolidation. Either step can be changed later in ~/.agentmemory/.env."
+	].join("\n"), "first-run setup");
+	const agentsPicked = await p.multiselect({
+		message: "Which agents will use agentmemory? (space to toggle, enter to confirm)",
+		options: buildAgentOptions(),
+		required: false,
+		initialValues: ["claude-code"]
+	});
+	if (p.isCancel(agentsPicked)) {
+		p.cancel("Setup cancelled. Re-run any time with: agentmemory --reset");
+		process.exit(0);
+	}
+	const providerPicked = await p.select({
+		message: "Which LLM provider should agentmemory use for compress/consolidate?",
+		options: PROVIDERS.map(({ value, label }) => ({
+			value,
+			label
+		})),
+		initialValue: "anthropic"
+	});
+	if (p.isCancel(providerPicked)) {
+		p.cancel("Setup cancelled. Re-run any time with: agentmemory --reset");
+		process.exit(0);
+	}
+	const provider = providerPicked === "skip" ? null : providerPicked;
+	const agents = agentsPicked ?? [];
+	const envPath = await seedEnvFile(provider);
+	writePrefs({
+		lastAgent: agents[0] ?? null,
+		lastAgents: agents,
+		lastProvider: provider,
+		skipSplash: true,
+		firstRunAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	const lines = [`✓ Saved preferences to ${join(homedir(), ".agentmemory", "preferences.json")}`];
+	if (envPath) lines.push(`✓ Wrote ${envPath} (edit to add your API key)`);
+	else lines.push(`! Could not write ~/.agentmemory/.env — run \`agentmemory init\` after this completes.`);
+	if (provider) {
+		const envKey = PROVIDERS.find((x) => x.value === provider)?.envKey;
+		if (envKey) lines.push(`  Uncomment ${envKey}= in that file to enable ${provider}.`);
+	} else lines.push("  No provider chosen — agentmemory will run in BM25-only mode.");
+	p.note(lines.join("\n"), "ready");
+	return {
+		agents,
+		provider
+	};
+}
+
+//#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);
+}
+
+//#endregion
+//#region src/version.ts
+const VERSION = "0.9.15";
+
 //#endregion
 //#region src/cli.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
 const IS_WINDOWS = platform() === "win32";
-const IS_VERBOSE = args.includes("--verbose") || args.includes("-v");
+const IS_VERBOSE = args.includes("--verbose") || args.includes("-v") || process.env["AGENTMEMORY_VERBOSE"] === "1" || process.env["AGENTMEMORY_VERBOSE"] === "true";
+setBootVerbose(IS_VERBOSE);
+const IS_RESET = args.includes("--reset");
 const IIPINNED_VERSION = process.env["AGENTMEMORY_III_VERSION"] || "0.11.2";
 function iiiReleaseAsset() {
 	const p = platform();
@@ -111,10 +841,22 @@ Usage: agentmemory [command] [options]
 Commands:
   (default)          Start agentmemory worker
   init               Copy bundled .env.example to ~/.agentmemory/.env if absent
+  connect [agent]    Wire agentmemory into an installed agent (claude-code, codex,
+                     cursor, gemini-cli, openclaw, hermes, pi, openhuman).
+                     No arg = interactive picker. --all wires every detected agent.
+                     --dry-run shows what would change. --force re-installs.
   status             Show connection status, memory count, flags, and health
-  doctor             Run diagnostic checks (server, flags, graph, providers)
+  doctor             Interactive diagnostic + fixer. [F]ix · [S]kip · [?]more · [Q]uit
+                     --all: apply every fix without prompting (CI)
+                     --dry-run: show what each fix would do, don't execute
+  remove             Cleanly uninstall agentmemory (pidfile, state, .env, binaries).
+                     --force: skip confirmations · --keep-data: keep memory data
   demo               Seed sample sessions and show recall in action
   upgrade            Upgrade local deps + iii runtime (best effort)
+  stop [--force]     Stop the running iii-engine started by this CLI.
+                     --force bypasses the Docker-heuristic guard and signals
+                     whatever pidfile+lsof report on the REST port (use when
+                     the engine was started natively but state file is missing).
   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;
@@ -122,14 +864,18 @@ Commands:
 
 Options:
   --help, -h         Show this help
-  --verbose, -v      Show engine stderr and diagnostic info on startup
+  --verbose, -v      Show engine stderr, boot log, and diagnostic info
+  --reset            Wipe ~/.agentmemory/preferences.json and re-run onboarding
   --tools all|core   Tool visibility (default: core = 7 tools)
   --no-engine        Skip auto-starting iii-engine
   --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 +966,179 @@ 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;
+	}
+}
+let warnedVersionMismatch = false;
+function warnIfEngineVersionMismatch(iiiBinPath) {
+	if (!iiiBinPath || warnedVersionMismatch) return;
+	const detected = iiiBinVersion(iiiBinPath);
+	if (!detected || detected === IIPINNED_VERSION) return;
+	warnedVersionMismatch = true;
+	const asset = iiiReleaseAsset();
+	const downloadHint = asset ? `curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v${IIPINNED_VERSION}/${asset} | tar -xz -C ~/.local/bin` : `download v${IIPINNED_VERSION} from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
+	p.log.warn(`iii-engine on PATH is v${detected} but agentmemory v0.9.14+ pins v${IIPINNED_VERSION}. Set AGENTMEMORY_III_VERSION=${detected} to silence, or downgrade with: \`${downloadHint}\``);
+}
+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;
+}
+function isInvokedViaNpx() {
+	if (process.env["npm_lifecycle_event"] === "npx") return true;
+	if ((process.argv[1] ?? "").includes("_npx")) return true;
+	const ua = process.env["npm_config_user_agent"] ?? "";
+	if (ua.startsWith("npm/") || ua.includes(" npm/")) return true;
+	return false;
+}
+function shouldSkipNpxHint() {
+	try {
+		const prefsPath = join(homedir(), ".agentmemory", "preferences.json");
+		if (!existsSync(prefsPath)) return false;
+		const raw = readFileSync(prefsPath, "utf-8");
+		return JSON.parse(raw)?.skipNpxHint === true;
+	} catch {
+		return false;
+	}
+}
+function maybeEmitNpxHint() {
+	if (!isInvokedViaNpx()) return;
+	if (shouldSkipNpxHint()) return;
+	p.log.info("Tip: install globally for the bare `agentmemory` command:\n  npm install -g @agentmemory/agentmemory");
+}
+function adoptRunningEngine() {
+	try {
+		const existingState = readEngineState();
+		const existingPid = readEnginePidfile();
+		if (existingState && existingPid) return;
+		const enginePid = findEnginePidsByPort(getRestPort())[0];
+		if (enginePid && !existingPid) writeEnginePidfile(enginePid);
+		if (!existingState) writeEngineState({
+			kind: "native",
+			configPath: findIiiConfig() || "",
+			attached: true
+		});
+		if (enginePid && !existingPid) p.log.info(`Attached to existing iii-engine (pid ${enginePid})`);
+	} catch (err) {
+		vlog(`adoptRunningEngine: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+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 +1151,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 +1166,48 @@ 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) {
+	warnIfEngineVersionMismatch(iiiBin);
+	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 +1217,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 +1294,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,58 +1309,70 @@ 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) {
 	return IS_WINDOWS ? `  netstat -ano | findstr :${port}` : `  lsof -i :${port}   # or: ss -tlnp | grep :${port}`;
 }
+async function waitForAgentmemoryReady(timeoutMs) {
+	const start = Date.now();
+	while (Date.now() - start < timeoutMs) {
+		if (await isAgentmemoryReady()) return true;
+		await new Promise((r) => setTimeout(r, 250));
+	}
+	return false;
+}
+function printReadyHint() {
+	const hint = `Memory ready on :${getRestPort()} · viewer on ${getViewerUrl()} · try: agentmemory demo`;
+	process.stdout.write("\n" + hint + "\n");
+}
 async function main() {
-	p.intro("agentmemory");
+	if (IS_RESET) resetPrefs();
+	const firstRun = isFirstRun();
+	const prefs = readPrefs();
+	if (firstRun || IS_RESET || IS_VERBOSE || !prefs.skipSplash) renderSplash(VERSION);
+	if (firstRun || IS_RESET) await runOnboarding();
 	if (skipEngine) {
-		p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-Ca9oX6Hq.mjs");
+		if (IS_VERBOSE) p.log.info("Skipping engine check (--no-engine)");
+		await import("./src-BGcqJR1a.mjs");
+		if (await waitForAgentmemoryReady(15e3)) printReadyHint();
 		return;
 	}
 	if (await isEngineRunning()) {
-		p.log.success("iii-engine is running");
-		await import("./src-Ca9oX6Hq.mjs");
+		if (IS_VERBOSE) p.log.success("iii-engine is running");
+		warnIfEngineVersionMismatch(whichBinary("iii") ?? fallbackIiiPaths().find((p) => existsSync(p)) ?? null);
+		adoptRunningEngine();
+		maybeEmitNpxHint();
+		await import("./src-BGcqJR1a.mjs");
+		if (await waitForAgentmemoryReady(15e3)) printReadyHint();
 		return;
 	}
 	if (!await startEngine()) {
@@ -411,7 +1416,10 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-Ca9oX6Hq.mjs");
+	maybeEmitNpxHint();
+	await import("./src-BGcqJR1a.mjs");
+	if (await waitForAgentmemoryReady(15e3)) printReadyHint();
+	writePrefs({ skipSplash: true });
 }
 async function apiFetch(base, path, timeoutMs = 5e3) {
 	try {
@@ -525,10 +1533,143 @@ function checkClaudeCodeHooks() {
 	if (content.includes("Loading hooks from plugin: agentmemory")) return { state: "loaded" };
 	return { state: "not-loaded" };
 }
-async function runDoctor() {
-	p.intro("agentmemory doctor");
+function buildDoctorContext() {
+	return {
+		baseUrl: getBaseUrl(),
+		viewerUrl: getViewerUrl(),
+		envPath: join(homedir(), ".agentmemory", ".env"),
+		pidfilePath: enginePidfilePath(),
+		enginePath: engineStatePath(),
+		pinnedVersion: IIPINNED_VERSION
+	};
+}
+function buildDoctorEffects() {
+	return {
+		envFileExists: () => existsSync(join(homedir(), ".agentmemory", ".env")),
+		readEnvFile: () => {
+			try {
+				return parseEnvFile(readFileSync(join(homedir(), ".agentmemory", ".env"), "utf-8"));
+			} catch {
+				return {};
+			}
+		},
+		pidfileExists: () => existsSync(enginePidfilePath()),
+		pidfilePidIsAlive: () => {
+			const pid = readEnginePidfile();
+			if (pid === null) return null;
+			return pidAlive(pid);
+		},
+		findIiiBinary: () => whichBinary("iii"),
+		localBinIiiPath: () => join(homedir(), ".local", "bin", IS_WINDOWS ? "iii.exe" : "iii"),
+		iiiBinaryVersion: (binPath) => iiiBinVersion(binPath),
+		viewerReachable: async (timeoutMs = 2e3) => {
+			try {
+				return (await fetch(getViewerUrl(), { signal: AbortSignal.timeout(timeoutMs) })).ok;
+			} catch {
+				return false;
+			}
+		},
+		runInit: async () => {
+			try {
+				await runInit();
+				return {
+					ok: true,
+					message: "Wrote ~/.agentmemory/.env"
+				};
+			} catch (err) {
+				return {
+					ok: false,
+					message: err instanceof Error ? err.message : String(err)
+				};
+			}
+		},
+		openEditor: async (path) => {
+			const editor = process.env["EDITOR"] || process.env["VISUAL"] || "nano";
+			p.log.info(`Opening ${path} in ${editor}…`);
+			try {
+				const result = spawnSync(editor, [path], { stdio: "inherit" });
+				if (result.error) return {
+					ok: false,
+					message: `Failed to launch ${editor}: ${result.error.message}`
+				};
+				if ((result.status ?? 0) !== 0) return {
+					ok: false,
+					message: `${editor} exited with code ${result.status}`
+				};
+				return {
+					ok: true,
+					message: `Saved ${path}`
+				};
+			} catch (err) {
+				return {
+					ok: false,
+					message: err instanceof Error ? err.message : String(err)
+				};
+			}
+		},
+		runIiiInstaller: async () => {
+			const r = await runIiiInstaller();
+			return {
+				ok: r.ok,
+				message: r.ok ? `Installed iii v${IIPINNED_VERSION} to ${r.binPath}` : "iii installer failed (see warnings above)"
+			};
+		},
+		runStop: async () => {
+			try {
+				const portPids = findEnginePidsByPort(getRestPort());
+				const pidfilePid = readEnginePidfile();
+				if (portPids.length === 0 && pidfilePid === null) {
+					clearEnginePidfile();
+					clearEngineState();
+					return {
+						ok: true,
+						message: "Nothing to stop."
+					};
+				}
+				const candidates = /* @__PURE__ */ new Set();
+				if (pidfilePid) candidates.add(pidfilePid);
+				for (const pid of portPids) candidates.add(pid);
+				let allStopped = true;
+				for (const pid of candidates) if (!await signalAndWait(pid, "SIGTERM", 3e3)) allStopped = false;
+				clearEnginePidfile();
+				clearEngineState();
+				return {
+					ok: allStopped,
+					message: allStopped ? "Engine stopped." : "Some engine pids survived."
+				};
+			} catch (err) {
+				return {
+					ok: false,
+					message: err instanceof Error ? err.message : String(err)
+				};
+			}
+		},
+		runStart: async () => {
+			try {
+				if (!await startEngine()) return {
+					ok: false,
+					message: "startEngine() returned false"
+				};
+				const ready = await waitForEngine(15e3);
+				return {
+					ok: ready,
+					message: ready ? "Engine ready" : "Engine did not become ready within 15s"
+				};
+			} catch (err) {
+				return {
+					ok: false,
+					message: err instanceof Error ? err.message : String(err)
+				};
+			}
+		},
+		clearEnginePidAndState: () => {
+			clearEnginePidfile();
+			clearEngineState();
+		}
+	};
+}
+async function passiveServerChecks() {
 	const base = getBaseUrl();
-	const viewerUrl = getViewerUrl();
 	const checks = [];
 	const serverUp = await isEngineRunning();
 	checks.push({
@@ -536,16 +1677,12 @@ async function runDoctor() {
 		ok: serverUp,
 		hint: serverUp ? void 0 : `Start with: npx @agentmemory/agentmemory (tried ${base})`
 	});
-	if (!serverUp) {
-		p.note(formatChecks(checks), "server unreachable");
-		process.exit(1);
-	}
+	if (!serverUp) return checks;
 	const [health, flags, graph] = await Promise.all([
 		apiFetch(base, "health", 3e3),
 		apiFetch(base, "config/flags", 3e3),
 		apiFetch(base, "graph/stats", 3e3)
 	]);
-	const viewerUp = await fetch(viewerUrl, { signal: AbortSignal.timeout(2e3) }).then((r) => r.ok).catch(() => false);
 	const hasLlm = flags?.provider === "llm";
 	const hasEmbed = flags?.embeddingProvider === "embeddings";
 	const graphHas = Number(graph?.totalNodes ?? graph?.nodes ?? graph?.nodeCount ?? 0) > 0;
@@ -553,18 +1690,14 @@ async function runDoctor() {
 		name: "Health status",
 		ok: health?.status === "healthy",
 		hint: health?.status === "healthy" ? void 0 : `Status: ${health?.status || "unknown"}`
-	}, {
-		name: "Viewer reachable",
-		ok: viewerUp,
-		hint: viewerUp ? void 0 : `${viewerUrl} not responding`
 	}, {
 		name: "LLM provider",
 		ok: hasLlm,
-		hint: hasLlm ? void 0 : "export ANTHROPIC_API_KEY=sk-ant-... (or GEMINI/OPENROUTER/MINIMAX) then restart"
+		hint: hasLlm ? void 0 : "set ANTHROPIC_API_KEY (or GEMINI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env"
 	}, {
 		name: "Embedding provider",
 		ok: hasEmbed,
-		hint: hasEmbed ? void 0 : "Running BM25-only. Add OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY / OLLAMA_HOST for semantic recall"
+		hint: hasEmbed ? void 0 : "Running BM25-only. Add OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY / OLLAMA_HOST"
 	});
 	for (const f of flags?.flags || []) checks.push({
 		name: f.label,
@@ -580,7 +1713,7 @@ async function runDoctor() {
 			};
 			case "not-loaded": return {
 				ok: false,
-				hint: "Plugin enabled but hooks not loaded by Claude Code. Try: /plugin uninstall agentmemory@agentmemory && /plugin install agentmemory@agentmemory, then restart the session. CC must be >= 2.1.x for plugin-hook auto-load."
+				hint: "Plugin enabled but hooks not loaded by Claude Code. Try: /plugin uninstall agentmemory@agentmemory && /plugin install agentmemory@agentmemory, then restart the session."
 			};
 			case "no-debug-log": return {
 				ok: false,
@@ -596,16 +1729,136 @@ async function runDoctor() {
 	checks.push({
 		name: "Knowledge graph populated",
 		ok: graphHas,
-		hint: graphHas ? void 0 : "Graph is empty. Run a session with GRAPH_EXTRACTION_ENABLED=true, or POST /agentmemory/graph/extract"
+		hint: graphHas ? void 0 : "Graph is empty. Run a session with GRAPH_EXTRACTION_ENABLED=true."
 	});
-	const passed = checks.filter((c) => c.ok).length;
-	const total = checks.length;
-	p.note(formatChecks(checks), `${passed}/${total} checks passing`);
-	if (passed === total) p.outro("✓ All checks passed. agentmemory is healthy.");
-	else {
-		p.outro(`${total - passed} issue(s) — follow hints above to fix.`);
+	return checks;
+}
+async function askFixAction(d) {
+	const choice = await p.select({
+		message: `[${d.id}] ${d.message}`,
+		options: [
+			{
+				value: "fix",
+				label: "F  Fix",
+				hint: d.fixPreview
+			},
+			{
+				value: "skip",
+				label: "S  Skip"
+			},
+			{
+				value: "more",
+				label: "?  More info"
+			},
+			{
+				value: "quit",
+				label: "Q  Quit doctor"
+			}
+		],
+		initialValue: "fix"
+	});
+	if (p.isCancel(choice)) return "quit";
+	return choice;
+}
+async function applyFixWithReport(d, ctx, dryRun) {
+	if (dryRun) {
+		p.log.info(`[dry-run] would: ${d.fixPreview}`);
+		return {
+			ok: true,
+			message: "(dry-run)"
+		};
+	}
+	const result = await d.fix(ctx);
+	if (result.ok) p.log.success(result.message ?? `${d.id} fixed.`);
+	else p.log.error(result.message ?? `${d.id} fix failed.`);
+	return result;
+}
+async function runDoctor() {
+	p.intro("agentmemory doctor");
+	const applyAll = args.includes("--all");
+	const dryRun = args.includes("--dry-run");
+	if (applyAll && dryRun) {
+		p.log.error("Cannot combine --all and --dry-run.");
+		process.exit(2);
+	}
+	const passive = await passiveServerChecks();
+	const passivePassed = passive.filter((c) => c.ok).length;
+	p.note(formatChecks(passive), `server: ${passivePassed}/${passive.length} passing`);
+	const ctx = buildDoctorContext();
+	const diagnostics = buildDiagnostics(buildDoctorEffects());
+	if (dryRun) {
+		const results = [];
+		for (const d of diagnostics) results.push({
+			diagnostic: d,
+			status: await d.check(ctx)
+		});
+		const lines = dryRunPlan(ctx, results);
+		p.note(lines.join("\n"), "dry-run plan");
+		p.outro("Dry-run complete. Re-run without --dry-run to apply.");
+		return;
+	}
+	let failed = 0;
+	let fixed = 0;
+	let skipped = 0;
+	let quit = false;
+	for (const d of diagnostics) {
+		if (quit) {
+			skipped++;
+			continue;
+		}
+		const status = await d.check(ctx);
+		if (status.ok) {
+			p.log.success(`${d.id} ✓${status.detail ? ` (${status.detail})` : ""}`);
+			continue;
+		}
+		failed++;
+		p.log.warn(`${d.id} ✗ ${status.detail ?? ""}`.trim());
+		p.log.info(`why: ${d.fixPreview}`);
+		if (d.manualOnly) p.log.info(`(manual fix only — see "${d.id}" docs)`);
+		if (applyAll) {
+			if ((await applyFixWithReport(d, ctx, false)).ok) fixed++;
+			if (!(await d.check(ctx)).ok) p.log.warn(`${d.id} still failing after fix.`);
+			continue;
+		}
+		while (true) {
+			const action = await askFixAction(d);
+			if (action === "fix") {
+				if ((await applyFixWithReport(d, ctx, false)).ok) {
+					const after = await d.check(ctx);
+					if (after.ok) fixed++;
+					else p.log.warn(`${d.id} still failing after fix: ${after.detail ?? ""}`);
+				}
+				break;
+			}
+			if (action === "skip") {
+				skipped++;
+				break;
+			}
+			if (action === "more") {
+				p.note(d.moreInfo, `[${d.id}] more info`);
+				continue;
+			}
+			if (action === "quit") {
+				quit = true;
+				break;
+			}
+		}
+	}
+	const summary = `${diagnostics.length} checks · ${failed} failing · ${fixed} fixed · ${skipped} skipped`;
+	if (quit) {
+		p.outro(`Quit early. ${summary}`);
 		process.exit(1);
 	}
+	if (failed === 0) {
+		p.outro("All diagnostics passing. agentmemory is healthy.");
+		return;
+	}
+	if (failed - fixed === 0) {
+		p.outro(`All fixes applied. ${summary}`);
+		return;
+	}
+	p.outro(summary);
+	process.exit(1);
 }
 function buildDemoSessions() {
 	return [
@@ -872,36 +2125,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 +2149,160 @@ 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();
+	const force = args.includes("--force");
+	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) if (force) p.log.warn(`--force: bypassing Docker-heuristic guard. Falling back to native pidfile + lsof on :${port}.`);
+		else {
+			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 --force to signal whatever lsof finds on :${port}, or 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-BQOaGF4z.mjs");
+}
+async function runConnectCmd() {
+	const { runConnect } = await import("./connect-hRTF7E2c.mjs");
+	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {
 	const VALUE_FLAGS = new Set(["--port", "--tools"]);
@@ -1021,12 +2406,126 @@ async function runImportJsonl() {
 		process.exit(1);
 	}
 }
+function loadConnectManifest(home) {
+	const path = join(home, ".agentmemory", "backups", "connect-manifest.json");
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (Array.isArray(parsed?.installed)) return { installed: parsed.installed };
+		return null;
+	} catch {
+		return null;
+	}
+}
+function probeLocalBinIiiVersion(home) {
+	const path = localBinIii(home);
+	if (!existsSync(path)) return null;
+	return iiiBinVersion(path);
+}
+function safeDelete(path) {
+	try {
+		if (!existsSync(path)) return {
+			ok: true,
+			message: `not present (${path})`
+		};
+		if (statSync(path).isDirectory()) rmSync(path, {
+			recursive: true,
+			force: true
+		});
+		else unlinkSync(path);
+		return {
+			ok: true,
+			message: `deleted ${path}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: `failed ${path}: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+}
+async function runRemove() {
+	p.intro("agentmemory remove");
+	const force = args.includes("--force");
+	const keepData = args.includes("--keep-data");
+	const home = homedir();
+	const connectManifest = loadConnectManifest(home);
+	const plan = buildRemovePlan({
+		home,
+		pinnedVersion: IIPINNED_VERSION,
+		localBinIiiVersion: probeLocalBinIiiVersion(home),
+		connectManifest
+	}, {
+		force,
+		keepData
+	});
+	if (plan.filter((it) => it.applicable).length === 0) {
+		p.outro("Nothing to remove. agentmemory is already gone.");
+		return;
+	}
+	p.note(formatPlan(plan), "destruction plan");
+	if (!force) {
+		const proceed = await p.confirm({
+			message: "Proceed with these deletions?",
+			initialValue: false
+		});
+		if (p.isCancel(proceed) || proceed !== true) {
+			p.cancel("Cancelled. Nothing was deleted.");
+			return;
+		}
+		const sure = await p.confirm({
+			message: "This is irreversible. Continue?",
+			initialValue: false
+		});
+		if (p.isCancel(sure) || sure !== true) {
+			p.cancel("Cancelled. Nothing was deleted.");
+			return;
+		}
+	}
+	for (const item of plan) {
+		if (!item.applicable) continue;
+		if (item.alwaysAsk) {
+			const ok = await p.confirm({
+				message: `${item.description} — really delete${item.path ? ` ${item.path}` : ""}?`,
+				initialValue: false
+			});
+			if (p.isCancel(ok) || ok !== true) {
+				p.log.info(`skipped: ${item.id}`);
+				continue;
+			}
+		}
+		if (item.id === "stop-engine") {
+			try {
+				const portPids = findEnginePidsByPort(getRestPort());
+				const pidfilePid = readEnginePidfile();
+				const cands = /* @__PURE__ */ new Set();
+				if (pidfilePid) cands.add(pidfilePid);
+				for (const pid of portPids) cands.add(pid);
+				for (const pid of cands) await signalAndWait(pid, "SIGTERM", 3e3);
+				clearEnginePidfile();
+				clearEngineState();
+				p.log.success(cands.size > 0 ? `stopped engine (${cands.size} pid${cands.size === 1 ? "" : "s"})` : "no engine running");
+			} catch (err) {
+				p.log.warn(`engine stop best-effort: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			continue;
+		}
+		if (!item.path) continue;
+		const r = safeDelete(item.path);
+		if (r.ok) p.log.success(r.message);
+		else p.log.error(r.message);
+	}
+	p.outro("Done. agentmemory cleanly removed. The npm package itself: npm uninstall -g @agentmemory/agentmemory");
+}
 ({
 	init: runInit,
+	connect: runConnectCmd,
 	status: runStatus,
 	doctor: runDoctor,
 	demo: runDemo,
 	upgrade: runUpgrade,
+	stop: runStop,
+	remove: runRemove,
 	mcp: runMcp,
 	"import-jsonl": runImportJsonl
 }[args[0] ?? ""] ?? main)().catch((err) => {
@@ -1035,5 +2534,5 @@ async function runImportJsonl() {
 });
 
 //#endregion
-export { jaccardSimilarity as a, generateId as i, STREAM as n, fingerprintId as r, KV as t };
+export { STREAM as a, jaccardSimilarity as c, KV as i, bootLog as n, fingerprintId as o, logger as r, generateId as s, VERSION as t };
 //# sourceMappingURL=cli.mjs.map