@agentmemory/agentmemory 0.9.15 → 0.9.17

package/dist/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } 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";
@@ -8,6 +9,23 @@ 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",
@@ -304,7 +322,7 @@ function envPath(home) {
 function preferencesPath(home) {
 	return join(home, ".agentmemory", "preferences.json");
 }
-function backupsDir(home) {
+function backupsDir$1(home) {
 	return join(home, ".agentmemory", "backups");
 }
 function dataDir(home) {
@@ -380,9 +398,9 @@ function buildRemovePlan(ctx, options) {
 	plan.push({
 		id: "backups",
 		description: "Delete backups/ directory (connect manifest + backups)",
-		path: backupsDir(home),
+		path: backupsDir$1(home),
 		alwaysAsk: false,
-		applicable: !options.keepData && pathExists(backupsDir(home)),
+		applicable: !options.keepData && pathExists(backupsDir$1(home)),
 		sizeBytes: -1
 	});
 	if (connectManifest?.installed?.length) for (const entry of connectManifest.installed) plan.push({
@@ -448,12 +466,12 @@ function getTerminalWidth() {
 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}`));
@@ -489,6 +507,8 @@ const DEFAULTS = {
 	lastProvider: null,
 	skipSplash: false,
 	skipNpxHint: false,
+	skipGlobalInstall: false,
+	skipConsoleInstall: false,
 	firstRunAt: null
 };
 function prefsDir() {
@@ -543,6 +563,541 @@ function isFirstRun() {
 	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));
@@ -722,6 +1277,12 @@ async function runOnboarding() {
 		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 }) => ({
@@ -752,11 +1313,82 @@ async function runOnboarding() {
 		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
@@ -801,7 +1433,7 @@ function bootLog(msg) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.9.15";
+const VERSION = "0.9.17";
 
 //#endregion
 //#region src/cli.ts
@@ -857,7 +1489,8 @@ Commands:
                      --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)
+  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)
@@ -911,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) });
@@ -990,7 +1636,7 @@ function warnIfEngineVersionMismatch(iiiBinPath) {
 	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}\``);
+	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");
@@ -1059,20 +1705,75 @@ function isInvokedViaNpx() {
 	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() {
+async function maybeOfferGlobalInstall() {
 	if (!isInvokedViaNpx()) return;
-	if (shouldSkipNpxHint()) return;
-	p.log.info("Tip: install globally for the bare `agentmemory` command:\n  npm install -g @agentmemory/agentmemory");
+	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 {
@@ -1350,9 +2051,34 @@ async function waitForAgentmemoryReady(timeoutMs) {
 	}
 	return false;
 }
-function printReadyHint() {
-	const hint = `Memory ready on :${getRestPort()} · viewer on ${getViewerUrl()} · try: agentmemory demo`;
-	process.stdout.write("\n" + hint + "\n");
+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() {
 	if (IS_RESET) resetPrefs();
@@ -1362,17 +2088,24 @@ async function main() {
 	if (firstRun || IS_RESET) await runOnboarding();
 	if (skipEngine) {
 		if (IS_VERBOSE) p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-BGcqJR1a.mjs");
-		if (await waitForAgentmemoryReady(15e3)) printReadyHint();
+		await import("./src-TiNuQ3Ub.mjs");
+		if (await waitForAgentmemoryReady(15e3)) {
+			const consoleState = await ensureIiiConsole();
+			await maybeOfferGlobalInstall();
+			printReadyHint(consoleState);
+		}
 		return;
 	}
 	if (await isEngineRunning()) {
 		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();
+		await import("./src-TiNuQ3Ub.mjs");
+		if (await waitForAgentmemoryReady(15e3)) {
+			const consoleState = await ensureIiiConsole();
+			await maybeOfferGlobalInstall();
+			printReadyHint(consoleState);
+		}
 		return;
 	}
 	if (!await startEngine()) {
@@ -1416,9 +2149,12 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	maybeEmitNpxHint();
-	await import("./src-BGcqJR1a.mjs");
-	if (await waitForAgentmemoryReady(15e3)) printReadyHint();
+	await import("./src-TiNuQ3Ub.mjs");
+	if (await waitForAgentmemoryReady(15e3)) {
+		const consoleState = await ensureIiiConsole();
+		await maybeOfferGlobalInstall();
+		printReadyHint(consoleState);
+	}
 	writePrefs({ skipSplash: true });
 }
 async function apiFetch(base, path, timeoutMs = 5e3) {
@@ -2298,10 +3034,10 @@ async function runStop() {
 	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
 }
 async function runMcp() {
-	await import("./standalone-BQOaGF4z.mjs");
+	await import("./standalone-BIXq6S80.mjs");
 }
 async function runConnectCmd() {
-	const { runConnect } = await import("./connect-hRTF7E2c.mjs");
+	const { runConnect } = await Promise.resolve().then(() => connect_exports);
 	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {