@agentmemory/agentmemory 0.9.14 → 0.9.16

package/dist/cli.mjs

@@ -1,12 +1,31 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, constants, copyFileSync, 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 \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
 //#region src/state/schema.ts
 const KV = {
 	sessions: "mem:sessions",
@@ -75,12 +94,1355 @@ 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$1(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$1(home),
+		alwaysAsk: false,
+		applicable: !options.keepData && pathExists(backupsDir$1(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,
+	skipGlobalInstall: false,
+	skipConsoleInstall: 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/connect/util.ts
+const AGENTMEMORY_MCP_BLOCK = {
+	command: "npx",
+	args: ["-y", "@agentmemory/mcp"],
+	env: { AGENTMEMORY_URL: "http://localhost:3111" }
+};
+function backupsDir() {
+	return join(homedir(), ".agentmemory", "backups");
+}
+function ensureBackupsDir() {
+	const dir = backupsDir();
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+function timestampSlug() {
+	return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+}
+function backupFile(sourcePath, agent, ext = "json") {
+	ensureBackupsDir();
+	const stamp = timestampSlug();
+	const target = join(backupsDir(), `${agent}-${stamp}.${ext}`);
+	copyFileSync(sourcePath, target);
+	return target;
+}
+function readJsonSafe(path) {
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+function writeJsonAtomic(path, value) {
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+	writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+	renameSync(tmp, path);
+}
+function logInstalled(label, target) {
+	p.log.success(`${label} → wired into ${target}`);
+}
+function logAlreadyWired(label, target) {
+	p.log.info(`${label} already wired in ${target} (use --force to re-install)`);
+}
+function logBackup(target) {
+	p.log.info(`Backup: ${target}`);
+}
+
+//#endregion
+//#region src/cli/connect/claude-code.ts
+const CLAUDE_DIR = join(homedir(), ".claude");
+const CLAUDE_JSON = join(homedir(), ".claude.json");
+function entryMatches$1(entry) {
+	if (!entry || typeof entry !== "object") return false;
+	const e = entry;
+	if (e["command"] !== "npx") return false;
+	return (Array.isArray(e["args"]) ? e["args"] : []).includes("@agentmemory/mcp");
+}
+const adapter$7 = {
+	name: "claude-code",
+	displayName: "Claude Code",
+	docs: "https://github.com/rohitg00/agentmemory#claude-code-one-block-paste-it",
+	protocolNote: "→ Using MCP. Hooks are also available — see docs/claude-code.md.",
+	detect() {
+		return existsSync(CLAUDE_DIR);
+	},
+	async install(opts) {
+		const existing = readJsonSafe(CLAUDE_JSON);
+		const next = existing ? { ...existing } : {};
+		const servers = { ...next.mcpServers ?? {} };
+		const alreadyHas = entryMatches$1(servers["agentmemory"]);
+		if (alreadyHas && !opts.force) {
+			logAlreadyWired("Claude Code", CLAUDE_JSON);
+			return {
+				kind: "already-wired",
+				mutatedPath: CLAUDE_JSON
+			};
+		}
+		if (opts.dryRun) {
+			p.log.info(`[dry-run] Would ${alreadyHas ? "overwrite" : "add"} mcpServers.agentmemory in ${CLAUDE_JSON}`);
+			return {
+				kind: "installed",
+				mutatedPath: CLAUDE_JSON
+			};
+		}
+		let backupPath;
+		if (existsSync(CLAUDE_JSON)) {
+			backupPath = backupFile(CLAUDE_JSON, "claude-code");
+			logBackup(backupPath);
+		} else {
+			mkdirSync(CLAUDE_DIR, { recursive: true });
+			writeFileSync(CLAUDE_JSON, "{}\n", "utf-8");
+		}
+		servers["agentmemory"] = AGENTMEMORY_MCP_BLOCK;
+		next.mcpServers = servers;
+		writeJsonAtomic(CLAUDE_JSON, next);
+		if (!entryMatches$1(readJsonSafe(CLAUDE_JSON)?.mcpServers?.["agentmemory"])) {
+			p.log.error(`Verification failed: ${CLAUDE_JSON} did not contain mcpServers.agentmemory after write.`);
+			return {
+				kind: "skipped",
+				reason: "verification-failed"
+			};
+		}
+		logInstalled("Claude Code", CLAUDE_JSON);
+		p.log.info("Restart Claude Code (or run `/mcp` inside a session) to pick up the new server.");
+		return {
+			kind: "installed",
+			mutatedPath: CLAUDE_JSON,
+			backupPath
+		};
+	}
+};
+
+//#endregion
+//#region src/cli/connect/codex.ts
+const CODEX_DIR = join(homedir(), ".codex");
+const CODEX_TOML = join(CODEX_DIR, "config.toml");
+const TOML_BLOCK = `[mcp_servers.agentmemory]
+command = "npx"
+args = ["-y", "@agentmemory/mcp"]
+
+[mcp_servers.agentmemory.env]
+AGENTMEMORY_URL = "http://localhost:3111"
+`;
+const SECTION_HEADER = "[mcp_servers.agentmemory]";
+function isWiredText(toml) {
+	return toml.includes(SECTION_HEADER);
+}
+function stripExistingBlock(toml) {
+	const lines = toml.split(/\r?\n/);
+	const out = [];
+	let skipping = false;
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed === SECTION_HEADER || trimmed === "[mcp_servers.agentmemory.env]") {
+			skipping = true;
+			continue;
+		}
+		if (skipping && trimmed.startsWith("[") && trimmed !== "[mcp_servers.agentmemory.env]") skipping = false;
+		if (!skipping) out.push(line);
+	}
+	return out.join("\n").replace(/\n{3,}$/, "\n\n").trimEnd() + "\n";
+}
+const adapter$6 = {
+	name: "codex",
+	displayName: "Codex CLI",
+	docs: "https://github.com/rohitg00/agentmemory#codex-cli-codex-plugin-platform",
+	protocolNote: "→ Using MCP. Hooks are also available — see docs/codex.md.",
+	detect() {
+		return existsSync(CODEX_DIR);
+	},
+	async install(opts) {
+		const exists = existsSync(CODEX_TOML);
+		const current = exists ? readFileSync(CODEX_TOML, "utf-8") : "";
+		const wired = isWiredText(current);
+		if (wired && !opts.force) {
+			logAlreadyWired("Codex CLI", CODEX_TOML);
+			return {
+				kind: "already-wired",
+				mutatedPath: CODEX_TOML
+			};
+		}
+		if (opts.dryRun) {
+			p.log.info(`[dry-run] Would ${wired ? "rewrite" : "append"} [mcp_servers.agentmemory] in ${CODEX_TOML}`);
+			return {
+				kind: "installed",
+				mutatedPath: CODEX_TOML
+			};
+		}
+		let backupPath;
+		if (exists) {
+			backupPath = backupFile(CODEX_TOML, "codex", "toml");
+			logBackup(backupPath);
+		} else mkdirSync(dirname(CODEX_TOML), { recursive: true });
+		const cleaned = wired ? stripExistingBlock(current) : current;
+		writeFileSync(CODEX_TOML, `${cleaned}${cleaned.length === 0 || cleaned.endsWith("\n") ? "" : "\n"}${cleaned.length > 0 ? "\n" : ""}${TOML_BLOCK}`, "utf-8");
+		if (!isWiredText(readFileSync(CODEX_TOML, "utf-8"))) {
+			p.log.error(`Verification failed: ${CODEX_TOML} did not contain ${SECTION_HEADER} after write.`);
+			return {
+				kind: "skipped",
+				reason: "verification-failed"
+			};
+		}
+		logInstalled("Codex CLI", CODEX_TOML);
+		p.log.info("Codex picks up MCP servers on next launch. For the deeper plugin install, run: codex plugin marketplace add rohitg00/agentmemory && codex plugin install agentmemory");
+		return {
+			kind: "installed",
+			mutatedPath: CODEX_TOML,
+			...backupPath !== void 0 && { backupPath }
+		};
+	}
+};
+
+//#endregion
+//#region src/cli/connect/json-mcp-adapter.ts
+function entryMatches(entry) {
+	if (!entry || typeof entry !== "object") return false;
+	const e = entry;
+	if (e["command"] !== "npx") return false;
+	return (Array.isArray(e["args"]) ? e["args"] : []).includes("@agentmemory/mcp");
+}
+function createJsonMcpAdapter(config) {
+	return {
+		name: config.name,
+		displayName: config.displayName,
+		...config.docs !== void 0 && { docs: config.docs },
+		...config.protocolNote !== void 0 && { protocolNote: config.protocolNote },
+		detect() {
+			return existsSync(config.detectDir);
+		},
+		async install(opts) {
+			const existing = readJsonSafe(config.configPath);
+			const next = existing ? { ...existing } : {};
+			const servers = { ...next.mcpServers ?? {} };
+			const alreadyHas = entryMatches(servers["agentmemory"]);
+			if (alreadyHas && !opts.force) {
+				logAlreadyWired(config.displayName, config.configPath);
+				return {
+					kind: "already-wired",
+					mutatedPath: config.configPath
+				};
+			}
+			if (opts.dryRun) {
+				p.log.info(`[dry-run] Would ${alreadyHas ? "overwrite" : "add"} mcpServers.agentmemory in ${config.configPath}`);
+				return {
+					kind: "installed",
+					mutatedPath: config.configPath
+				};
+			}
+			let backupPath;
+			if (existsSync(config.configPath)) {
+				backupPath = backupFile(config.configPath, config.name);
+				logBackup(backupPath);
+			} else mkdirSync(dirname(config.configPath), { recursive: true });
+			servers["agentmemory"] = AGENTMEMORY_MCP_BLOCK;
+			next.mcpServers = servers;
+			writeJsonAtomic(config.configPath, next);
+			if (!entryMatches(readJsonSafe(config.configPath)?.mcpServers?.["agentmemory"])) {
+				p.log.error(`Verification failed: ${config.configPath} did not contain mcpServers.agentmemory after write.`);
+				return {
+					kind: "skipped",
+					reason: "verification-failed"
+				};
+			}
+			logInstalled(config.displayName, config.configPath);
+			return {
+				kind: "installed",
+				mutatedPath: config.configPath,
+				...backupPath !== void 0 && { backupPath }
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/cli/connect/cursor.ts
+const adapter$5 = createJsonMcpAdapter({
+	name: "cursor",
+	displayName: "Cursor",
+	detectDir: join(homedir(), ".cursor"),
+	configPath: join(homedir(), ".cursor", "mcp.json"),
+	docs: "https://github.com/rohitg00/agentmemory#other-agents",
+	protocolNote: "→ Using MCP (the only protocol Cursor speaks). Memory bridge runs at :3111 underneath."
+});
+
+//#endregion
+//#region src/cli/connect/gemini-cli.ts
+const adapter$4 = createJsonMcpAdapter({
+	name: "gemini-cli",
+	displayName: "Gemini CLI",
+	detectDir: join(homedir(), ".gemini"),
+	configPath: join(homedir(), ".gemini", "settings.json"),
+	docs: "https://github.com/rohitg00/agentmemory#other-agents",
+	protocolNote: "→ Using MCP (the only protocol Gemini CLI speaks). Memory bridge runs at :3111 underneath."
+});
+
+//#endregion
+//#region src/cli/connect/hermes.ts
+const HERMES_DIR = join(homedir(), ".hermes");
+const HERMES_CONFIG = join(HERMES_DIR, "config.yaml");
+const DOCS$2 = "https://github.com/rohitg00/agentmemory/tree/main/integrations/hermes";
+const adapter$3 = {
+	name: "hermes",
+	displayName: "Hermes Agent",
+	docs: DOCS$2,
+	protocolNote: "→ Using MCP. Hooks are also available — see docs/hermes.md.",
+	detect() {
+		return existsSync(HERMES_DIR);
+	},
+	async install(_opts) {
+		p.log.warn("Hermes uses YAML config. Automated merge isn't implemented yet — manual install required.");
+		p.note([
+			`Add to ${HERMES_CONFIG}:`,
+			"",
+			"  mcp_servers:",
+			"    agentmemory:",
+			"      command: npx",
+			"      args: [\"-y\", \"@agentmemory/mcp\"]",
+			"",
+			"  memory:",
+			"    provider: agentmemory",
+			"",
+			`Full guide: ${DOCS$2}`
+		].join("\n"), "Hermes manual install");
+		return {
+			kind: "stub",
+			reason: "yaml-merge-not-implemented"
+		};
+	}
+};
+
+//#endregion
+//#region src/cli/connect/openclaw.ts
+const adapter$2 = createJsonMcpAdapter({
+	name: "openclaw",
+	displayName: "OpenClaw",
+	detectDir: join(homedir(), ".openclaw"),
+	configPath: join(homedir(), ".openclaw", "openclaw.json"),
+	docs: "https://github.com/rohitg00/agentmemory/tree/main/integrations/openclaw",
+	protocolNote: "→ Using MCP. Hooks are also available — see docs/openclaw.md."
+});
+
+//#endregion
+//#region src/cli/connect/openhuman.ts
+const OPENHUMAN_DIR = join(homedir(), ".openhuman");
+const DOCS$1 = "https://github.com/tinyhumansai/openhuman";
+const adapter$1 = {
+	name: "openhuman",
+	displayName: "OpenHuman",
+	docs: DOCS$1,
+	protocolNote: "→ Using native hooks (REST API at :3111). MCP not required.",
+	detect() {
+		return existsSync(OPENHUMAN_DIR);
+	},
+	async install(_opts) {
+		p.log.warn("OpenHuman integration is not yet automated. No `integrations/openhuman/` folder exists in the agentmemory repo today.");
+		p.note([
+			"OpenHuman is a Memory-trait host. The expected wiring is the REST",
+			"proxy at http://localhost:3111 plus an OpenHuman-side Memory trait",
+			"impl. Once integrations/openhuman/ lands in agentmemory we'll wire",
+			"this up automatically.",
+			"",
+			`Tracking: ${DOCS$1}`
+		].join("\n"), "OpenHuman manual install");
+		return {
+			kind: "stub",
+			reason: "no-integration-folder-yet"
+		};
+	}
+};
+
+//#endregion
+//#region src/cli/connect/pi.ts
+const PI_DIR = join(homedir(), ".pi");
+const PI_EXT_DIR = join(PI_DIR, "agent", "extensions", "agentmemory");
+const DOCS = "https://github.com/rohitg00/agentmemory/tree/main/integrations/pi";
+const adapter = {
+	name: "pi",
+	displayName: "pi",
+	docs: DOCS,
+	protocolNote: "→ Using native hooks (REST API at :3111). MCP not required.",
+	detect() {
+		return existsSync(PI_DIR);
+	},
+	async install(_opts) {
+		p.log.warn("pi uses a TypeScript extension file. Automated copy + register isn't implemented yet — manual install required.");
+		p.note([
+			"Run these from the agentmemory repo root:",
+			"",
+			`  mkdir -p ${PI_EXT_DIR}`,
+			`  cp integrations/pi/index.ts ${PI_EXT_DIR}/index.ts`,
+			`  cp integrations/pi/security.ts ${PI_EXT_DIR}/security.ts`,
+			"",
+			"Then add to ~/.pi/agent/settings.json:",
+			"  { \"extensions\": [\"~/.pi/agent/extensions/agentmemory\"] }",
+			"",
+			`Full guide: ${DOCS}`
+		].join("\n"), "pi manual install");
+		return {
+			kind: "stub",
+			reason: "ts-extension-copy-not-implemented"
+		};
+	}
+};
+
+//#endregion
+//#region src/cli/connect/index.ts
+var connect_exports = /* @__PURE__ */ __exportAll({
+	ADAPTERS: () => ADAPTERS,
+	knownAgents: () => knownAgents,
+	resolveAdapter: () => resolveAdapter,
+	runAdapter: () => runAdapter,
+	runConnect: () => runConnect
+});
+const ADAPTERS = [
+	adapter$7,
+	adapter$6,
+	adapter$5,
+	adapter$4,
+	adapter$2,
+	adapter$3,
+	adapter,
+	adapter$1
+];
+function resolveAdapter(name) {
+	const lower = name.toLowerCase();
+	return ADAPTERS.find((a) => a.name === lower) ?? null;
+}
+function knownAgents() {
+	return ADAPTERS.map((a) => a.name);
+}
+function parseFlags(args) {
+	const positional = [];
+	let dryRun = false;
+	let force = false;
+	let all = false;
+	for (const a of args) if (a === "--dry-run") dryRun = true;
+	else if (a === "--force") force = true;
+	else if (a === "--all") all = true;
+	else if (!a.startsWith("-")) positional.push(a);
+	return {
+		dryRun,
+		force,
+		all,
+		positional
+	};
+}
+async function runAdapter(adapter, opts) {
+	if (!adapter.detect()) {
+		p.log.warn(`${adapter.displayName}: not detected on this machine (skipping).${adapter.docs ? ` Docs: ${adapter.docs}` : ""}`);
+		return {
+			kind: "skipped",
+			reason: "not-detected"
+		};
+	}
+	p.log.step(`Wiring ${adapter.displayName}…`);
+	if (adapter.protocolNote) p.log.message(adapter.protocolNote);
+	try {
+		return await adapter.install(opts);
+	} catch (err) {
+		p.log.error(`${adapter.displayName}: ${err instanceof Error ? err.message : String(err)}`);
+		return {
+			kind: "skipped",
+			reason: "exception"
+		};
+	}
+}
+async function runConnect(args) {
+	if (platform() === "win32") {
+		p.intro("agentmemory connect");
+		p.log.warn("Windows: automated `connect` is not supported yet. See https://github.com/rohitg00/agentmemory#other-agents for manual install steps.");
+		p.outro("Windows: manual install required — see docs");
+		return;
+	}
+	const { dryRun, force, all, positional } = parseFlags(args);
+	const opts = {
+		dryRun,
+		force
+	};
+	p.intro("agentmemory connect");
+	if (positional.length === 0 && !all) {
+		const detected = ADAPTERS.filter((a) => a.detect());
+		if (detected.length === 0) {
+			p.log.error("No supported agents detected on this machine.");
+			p.outro(`Supported: ${knownAgents().join(", ")}`);
+			process.exit(1);
+		}
+		const picked = await p.multiselect({
+			message: "Wire agentmemory into which agents?",
+			options: detected.map((a) => ({
+				value: a.name,
+				label: a.displayName
+			})),
+			required: true
+		});
+		if (p.isCancel(picked)) {
+			p.cancel("Cancelled.");
+			return;
+		}
+		const results = [];
+		for (const name of picked) {
+			const adapter = resolveAdapter(name);
+			if (!adapter) continue;
+			results.push({
+				name,
+				result: await runAdapter(adapter, opts)
+			});
+		}
+		summarize(results);
+		return;
+	}
+	if (all) {
+		const detected = ADAPTERS.filter((a) => a.detect());
+		if (detected.length === 0) {
+			p.log.error("No supported agents detected on this machine.");
+			process.exit(1);
+		}
+		const results = [];
+		for (const adapter of detected) results.push({
+			name: adapter.name,
+			result: await runAdapter(adapter, opts)
+		});
+		summarize(results);
+		return;
+	}
+	const agentName = positional[0];
+	const adapter = resolveAdapter(agentName);
+	if (!adapter) {
+		p.log.error(`Unknown agent: ${agentName}`);
+		p.outro(`Supported: ${knownAgents().join(", ")}`);
+		process.exit(1);
+	}
+	const result = await runAdapter(adapter, opts);
+	summarize([{
+		name: agentName,
+		result
+	}]);
+	if (result.kind === "skipped" && result.reason !== "not-detected") process.exit(1);
+}
+function summarize(results) {
+	const lines = results.map(({ name, result }) => {
+		switch (result.kind) {
+			case "installed": return `  ✓ ${name}${result.mutatedPath ? ` → ${result.mutatedPath}` : ""}`;
+			case "already-wired": return `  ✓ ${name} (already wired)`;
+			case "stub": return `  ⚠ ${name} (manual install required: ${result.reason})`;
+			case "skipped": return `  ✗ ${name} (skipped: ${result.reason})`;
+		}
+	});
+	p.note(lines.join("\n"), "summary");
+	const stubs = results.filter((r) => r.result.kind === "stub");
+	if (stubs.length > 0) p.log.info(`${stubs.length} agent(s) require manual install — see docs links above.`);
+	p.outro("Restart any wired agent (or open a new session) to pick up agentmemory.");
+}
+
+//#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);
+	}
+	if ((agentsPicked ?? []).length > 0) p.note([
+		"━ how this works ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+		"All selected agents share the same memory at :3111.",
+		"A memory saved by Claude Code is visible to Codex + Cursor instantly.",
+		"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	].join("\n"));
+	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");
+	if (agents.length > 0) await wireSelectedAgents(agents);
+	return {
+		agents,
+		provider
+	};
+}
+async function wireSelectedAgents(agents) {
+	p.note("Wire selected agents now?", "next step");
+	const confirmed = await p.confirm({
+		message: "Run `agentmemory connect <agent>` for each selected agent now? [Y/n]",
+		initialValue: true
+	});
+	if (p.isCancel(confirmed) || confirmed === false) {
+		const cmds = agents.map((a) => `  agentmemory connect ${a}`);
+		p.note(["Wire later with:", ...cmds].join("\n"), "later");
+		return;
+	}
+	const wired = [];
+	const manual = [];
+	const failed = [];
+	for (const name of agents) {
+		const adapter = resolveAdapter(name);
+		if (!adapter) {
+			failed.push({
+				name,
+				reason: "no adapter available"
+			});
+			p.log.warn(`Wiring ${name}… no adapter available (skipped).`);
+			continue;
+		}
+		p.log.step(`Wiring ${name}...`);
+		let result;
+		try {
+			result = await runAdapter(adapter, {
+				dryRun: false,
+				force: false
+			});
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			failed.push({
+				name,
+				reason
+			});
+			p.log.error(`${name}: ${reason}`);
+			continue;
+		}
+		switch (result.kind) {
+			case "installed":
+			case "already-wired":
+				wired.push(name);
+				break;
+			case "stub":
+				manual.push({
+					name,
+					docs: adapter.docs
+				});
+				break;
+			case "skipped":
+				failed.push({
+					name,
+					reason: result.reason
+				});
+				break;
+		}
+	}
+	const summary = [];
+	if (wired.length > 0) summary.push(`Wired: ${wired.join(", ")}.`);
+	if (manual.length > 0 || failed.length > 0) {
+		const parts = [];
+		for (const m of manual) parts.push(`${m.name} (manual install required${m.docs ? ` — see ${m.docs}` : ""})`);
+		for (const f of failed) parts.push(`${f.name} (${f.reason})`);
+		summary.push(`Skipped/failed: ${parts.join(", ")}.`);
+	}
+	if (summary.length === 0) summary.push("No agents were wired.");
+	p.note(summary.join("\n"), "wire summary");
+}
+
+//#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.16";
+
 //#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,19 +1473,32 @@ 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               Stop the running iii-engine started by this CLI
-  mcp                Start standalone MCP server (no engine required)
+  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 shim — opt-in surface for MCP-only clients
+                     (Cursor, Gemini CLI, etc). REST always available at :3111.
   import-jsonl [p]   Import Claude Code JSONL transcripts (default: ~/.claude/projects)
                      --max-files <N> | --max-files=<N>: override scan cap (default 200, max 1000;
                      out-of-range is rejected; for trees >1000 files, batch by subdirectory)
 
 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)
@@ -169,12 +1544,25 @@ function getViewerUrl() {
 	if (envUrl) return envUrl.replace(/\/+$/, "");
 	try {
 		const u = new URL(getBaseUrl());
-		const vPort = (parseInt(u.port || "3111", 10) || 3111) + 2;
+		const vPort = parseInt(process.env["III_VIEWER_PORT"] || "", 10) || (parseInt(u.port || "3111", 10) || 3111) + 2;
 		return `${u.protocol}//${u.hostname}:${vPort}`;
 	} catch {
-		return `http://localhost:${getRestPort() + 2}`;
+		return `http://localhost:${parseInt(process.env["III_VIEWER_PORT"] || "", 10) || getRestPort() + 2}`;
 	}
 }
+function getStreamPort() {
+	return parseInt(process.env["III_STREAM_PORT"] || "", 10) || parseInt(process.env["III_STREAMS_PORT"] || "", 10) || 3112;
+}
+function getEnginePort() {
+	const explicit = parseInt(process.env["III_ENGINE_PORT"] || "", 10);
+	if (explicit) return explicit;
+	const url = process.env["III_ENGINE_URL"];
+	if (url) try {
+		const parsed = new URL(url).port;
+		if (parsed) return parseInt(parsed, 10);
+	} catch {}
+	return 49134;
+}
 async function isEngineRunning() {
 	try {
 		await fetch(`${getBaseUrl()}/`, { signal: AbortSignal.timeout(2e3) });
@@ -240,6 +1628,16 @@ function iiiBinVersion(binPath) {
 		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 v${VERSION} pins v${IIPINNED_VERSION}. Set AGENTMEMORY_III_VERSION=${detected} to silence, or downgrade with: \`${downloadHint}\``);
+}
 function enginePidfilePath() {
 	return join(homedir(), ".agentmemory", "iii.pid");
 }
@@ -300,6 +1698,100 @@ function discoverComposeFile() {
 		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;
+}
+async function maybeOfferGlobalInstall() {
+	if (!isInvokedViaNpx()) return;
+	if (!process.stdin.isTTY) return;
+	if (process.env["CI"]) return;
+	const prefs = readPrefs();
+	if (prefs.skipGlobalInstall || prefs.skipNpxHint) return;
+	const answer = await p.confirm({
+		message: "Install agentmemory globally so the bare `agentmemory` command works in any shell? [Y/n]",
+		initialValue: true
+	});
+	if (p.isCancel(answer)) return;
+	if (answer === false) {
+		writePrefs({ skipGlobalInstall: true });
+		p.log.info("Skipped. Re-run via `npx @agentmemory/agentmemory` or install later with: npm install -g @agentmemory/agentmemory");
+		return;
+	}
+	const npmBin = whichBinary("npm");
+	if (!npmBin) {
+		p.log.warn("npm not found on PATH. Install manually: npm install -g @agentmemory/agentmemory");
+		return;
+	}
+	if (runCommand(npmBin, [
+		"install",
+		"-g",
+		`@agentmemory/agentmemory@${VERSION}`
+	], { label: `Installing @agentmemory/agentmemory@${VERSION} globally` })) {
+		p.log.success("Installed globally. `agentmemory stop` etc. will now work in new shells.");
+		writePrefs({ skipGlobalInstall: true });
+	} else p.log.warn("Global install failed. Try manually: npm install -g @agentmemory/agentmemory");
+}
+function detectIiiConsole() {
+	const onPath = whichBinary("iii-console");
+	if (onPath) return {
+		kind: "installed",
+		binPath: onPath
+	};
+	const fallback = IS_WINDOWS ? join(process.env["USERPROFILE"] ?? "", ".local", "bin", "iii-console.exe") : join(homedir(), ".local", "bin", "iii-console");
+	if (fallback && existsSync(fallback)) return {
+		kind: "installed",
+		binPath: fallback
+	};
+	return { kind: "missing" };
+}
+const III_CONSOLE_INSTALL_CMD = "curl -fsSL https://install.iii.dev/console/main/install.sh | sh";
+async function ensureIiiConsole() {
+	const state = detectIiiConsole();
+	if (state.kind === "installed") return state;
+	if (!process.stdin.isTTY || process.env["CI"]) return state;
+	if (readPrefs().skipConsoleInstall) return state;
+	const answer = await p.confirm({
+		message: "iii console gives engine-level visibility (workers, functions, queues, traces). Install now?",
+		initialValue: true
+	});
+	if (p.isCancel(answer)) return state;
+	if (answer === false) {
+		writePrefs({ skipConsoleInstall: true });
+		return state;
+	}
+	const shBin = whichBinary("sh");
+	const curlBin = whichBinary("curl");
+	if (!shBin || !curlBin) {
+		p.log.warn(`curl or sh not found. Install manually:\n  ${III_CONSOLE_INSTALL_CMD}`);
+		return state;
+	}
+	if (!runCommand(shBin, ["-c", III_CONSOLE_INSTALL_CMD], { label: "Installing iii console" })) {
+		p.log.warn(`iii console install failed. Re-run manually:\n  ${III_CONSOLE_INSTALL_CMD}`);
+		return state;
+	}
+	return detectIiiConsole();
+}
+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();
@@ -389,6 +1881,7 @@ function spawnEngineBackground(bin, spawnArgs, label) {
 	return child;
 }
 function startIiiBin(iiiBin, configPath) {
+	warnIfEngineVersionMismatch(iiiBin);
 	const s = p.spinner();
 	s.start(`Starting iii-engine: ${iiiBin}`);
 	writeEngineState({
@@ -550,16 +2043,69 @@ function installInstructions() {
 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 getEngineHost() {
+	for (const envKey of ["III_ENGINE_URL", "AGENTMEMORY_URL"]) {
+		const raw = process.env[envKey];
+		if (!raw) continue;
+		try {
+			const parsed = new URL(raw);
+			if (parsed.hostname) return parsed.hostname;
+		} catch {}
+	}
+	return "localhost";
+}
+function printReadyHint(consoleState) {
+	const restUrl = getBaseUrl();
+	const viewerUrl = getViewerUrl();
+	const engineHost = getEngineHost();
+	const streamUrl = `ws://${engineHost}:${getStreamPort()}`;
+	const engineUrl = `ws://${engineHost}:${getEnginePort()}`;
+	const consoleLine = consoleState.kind === "installed" ? `iii console  ${consoleState.binPath}  (run: ${consoleState.binPath} -p <port>)` : `iii console  (install: ${III_CONSOLE_INSTALL_CMD})`;
+	const lines = [
+		`REST API     ${restUrl}`,
+		`Viewer       ${viewerUrl}`,
+		`Streams      ${streamUrl}`,
+		`Engine       ${engineUrl}`,
+		consoleLine
+	];
+	p.note(lines.join("\n"), `agentmemory v${VERSION}`);
+	const demoCommand = isInvokedViaNpx() ? "npx @agentmemory/agentmemory demo" : "agentmemory demo";
+	process.stdout.write(`\nTry: ${demoCommand}\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-BBI-ah3h.mjs");
+		if (IS_VERBOSE) p.log.info("Skipping engine check (--no-engine)");
+		await import("./src-3Oy_OOlF.mjs");
+		if (await waitForAgentmemoryReady(15e3)) {
+			const consoleState = await ensureIiiConsole();
+			await maybeOfferGlobalInstall();
+			printReadyHint(consoleState);
+		}
 		return;
 	}
 	if (await isEngineRunning()) {
-		p.log.success("iii-engine is running");
-		await import("./src-BBI-ah3h.mjs");
+		if (IS_VERBOSE) p.log.success("iii-engine is running");
+		warnIfEngineVersionMismatch(whichBinary("iii") ?? fallbackIiiPaths().find((p) => existsSync(p)) ?? null);
+		adoptRunningEngine();
+		await import("./src-3Oy_OOlF.mjs");
+		if (await waitForAgentmemoryReady(15e3)) {
+			const consoleState = await ensureIiiConsole();
+			await maybeOfferGlobalInstall();
+			printReadyHint(consoleState);
+		}
 		return;
 	}
 	if (!await startEngine()) {
@@ -603,7 +2149,13 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-BBI-ah3h.mjs");
+	await import("./src-3Oy_OOlF.mjs");
+	if (await waitForAgentmemoryReady(15e3)) {
+		const consoleState = await ensureIiiConsole();
+		await maybeOfferGlobalInstall();
+		printReadyHint(consoleState);
+	}
+	writePrefs({ skipSplash: true });
 }
 async function apiFetch(base, path, timeoutMs = 5e3) {
 	try {
@@ -717,10 +2269,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({
@@ -728,16 +2413,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;
@@ -745,18 +2426,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,
@@ -772,7 +2449,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,
@@ -788,16 +2465,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."
+	});
+	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"
 	});
-	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.`);
+	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 [
@@ -1178,6 +2975,7 @@ async function runStop() {
 	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}.`);
@@ -1206,8 +3004,9 @@ async function runStop() {
 	}
 	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.`);
+		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);
 		}
 	}
@@ -1235,7 +3034,11 @@ async function runStop() {
 	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
 }
 async function runMcp() {
-	await import("./standalone-Cf5sp0XM.mjs");
+	await import("./standalone-BQOaGF4z.mjs");
+}
+async function runConnectCmd() {
+	const { runConnect } = await Promise.resolve().then(() => connect_exports);
+	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {
 	const VALUE_FLAGS = new Set(["--port", "--tools"]);
@@ -1339,13 +3142,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) => {
@@ -1354,5 +3270,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