@agentmemory/agentmemory 0.9.27 → 0.9.29

package/dist/cli.mjs

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { i as generateId } from "./schema-CNiCWzV9.mjs";
-import { n as resolveAdapter, r as runAdapter } from "./connect-bmZ5eqYN.mjs";
-import { r as setBootVerbose } from "./logger-yHTcEBAI.mjs";
-import { t as VERSION } from "./version-9DNrRyph.mjs";
+import { a as runAdapter, i as resolveAdapter, r as knownAgents, t as ADAPTERS } from "./connect-Qaeq15TQ.mjs";
+import { i as generateId } from "./schema-BFZhNTF7.mjs";
+import { r as setBootVerbose } from "./logger-BEB7pCI9.mjs";
+import { i as VERSION, n as getAllTools, p as hydrateProcessEnvFromFile, t as ESSENTIAL_TOOLS } from "./tools-registry-BV_2bu7z.mjs";
 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 { delimiter, dirname, join } from "node:path";
+import { appendFileSync, closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir, platform } from "node:os";
 import * as p from "@clack/prompts";
+import pc from "picocolors";
 import { copyFile, mkdir } from "node:fs/promises";
 //#region src/cli/doctor-diagnostics.ts
 /** Common placeholder values shipped in .env.example. */
@@ -436,7 +437,8 @@ const DEFAULTS = {
 	skipNpxHint: false,
 	skipGlobalInstall: false,
 	skipConsoleInstall: false,
-	firstRunAt: null
+	firstRunAt: null,
+	injectContextChosen: false
 };
 function prefsDir() {
 	return join(homedir(), ".agentmemory");
@@ -492,95 +494,14 @@ function isFirstRun() {
 //#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: "copilot-cli",
-		label: "GitHub Copilot CLI",
-		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 AGENT_GLYPH = {
+	"claude-code": "⟁",
+	"copilot-cli": "◈",
+	codex: "◎",
+	cursor: "◫",
+	"gemini-cli": "✦",
+	opencode: "⬡"
+};
 const PROVIDERS = [
 	{
 		value: "anthropic",
@@ -604,7 +525,7 @@ const PROVIDERS = [
 	},
 	{
 		value: "minimax",
-		label: "MiniMax — minimax-m1",
+		label: "MiniMax — MiniMax-M3",
 		envKey: "MINIMAX_API_KEY"
 	},
 	{
@@ -613,16 +534,20 @@ const PROVIDERS = [
 		envKey: null
 	}
 ];
+const PROVIDER_COST_HINTS = {
+	anthropic: "rough cost: a fast Haiku-class model keeps compress/consolidate at fractions of a cent per session.",
+	openai: "rough cost: a mini-class model keeps compress/consolidate at fractions of a cent per session.",
+	gemini: "rough cost: a Flash-class model keeps compress/consolidate at fractions of a cent per session.",
+	openrouter: "rough cost: pick a small model; spend tracks your chosen model's per-token price.",
+	minimax: "rough cost: scales with the MiniMax model price per token."
+};
 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"
-	}))];
+	const options = ADAPTERS.map((a) => ({
+		value: a.name,
+		label: `${AGENT_GLYPH[a.name] ?? "◇"} ${a.displayName}`,
+		hint: a.category === "native" ? "native plugin" : "MCP server"
+	}));
+	return [...options.filter((o) => o.hint === "native plugin"), ...options.filter((o) => o.hint === "MCP server")];
 }
 function getInitialAgentValues(env = process.env) {
 	if (env["COPILOT_CLI"] === "1" || env["COPILOT_AGENT_SESSION_ID"]) return ["copilot-cli"];
@@ -715,7 +640,12 @@ async function runOnboarding() {
 	}
 	const provider = providerPicked === "skip" ? null : providerPicked;
 	const agents = agentsPicked ?? [];
+	if (provider) {
+		const hint = PROVIDER_COST_HINTS[provider];
+		if (hint) p.log.info(hint);
+	}
 	const envPath = await seedEnvFile(provider);
+	await maybePromptContextInjection(envPath);
 	writePrefs({
 		lastAgent: agents[0] ?? null,
 		lastAgents: agents,
@@ -737,6 +667,33 @@ async function runOnboarding() {
 		provider
 	};
 }
+function enableInjectContextInEnv(envPath) {
+	if (!envPath || !existsSync(envPath)) return false;
+	try {
+		const current = readFileSync(envPath, "utf-8");
+		if (/^\s*AGENTMEMORY_INJECT_CONTEXT\s*=\s*true\b/m.test(current)) return true;
+		appendFileSync(envPath, `${current.length > 0 && !current.endsWith("\n") ? "\n" : ""}AGENTMEMORY_INJECT_CONTEXT=true\n`, { mode: 384 });
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function maybePromptContextInjection(envPath) {
+	if (readPrefs().injectContextChosen) return;
+	const enable = await p.confirm({
+		message: "Enable automatic context injection so the agent recalls past sessions without being asked? [y/N]",
+		initialValue: false
+	});
+	if (p.isCancel(enable)) {
+		p.cancel("Setup cancelled. Re-run any time with: agentmemory --reset");
+		process.exit(0);
+	}
+	p.log.info("Cost note: injection spends session tokens proportional to tool-call frequency. Default is off.");
+	writePrefs({ injectContextChosen: true });
+	if (enable === true) if (enableInjectContextInEnv(envPath)) p.log.success("Context injection enabled (AGENTMEMORY_INJECT_CONTEXT=true).");
+	else p.log.warn("Could not update ~/.agentmemory/.env. Set AGENTMEMORY_INJECT_CONTEXT=true there to enable it.");
+	else p.log.info("Context injection left off. Set AGENTMEMORY_INJECT_CONTEXT=true later to enable.");
+}
 async function wireSelectedAgents(agents) {
 	p.note("Wire selected agents now?", "next step");
 	const confirmed = await p.confirm({
@@ -808,13 +765,107 @@ async function wireSelectedAgents(agents) {
 	p.note(summary.join("\n"), "wire summary");
 }
 //#endregion
+//#region src/cli-data-dir.ts
+function argValue(args, name) {
+	const equals = `${name}=`;
+	const inline = args.find((arg) => arg.startsWith(equals));
+	if (inline) return inline.slice(equals.length);
+	const idx = args.indexOf(name);
+	if (idx !== -1) return args[idx + 1];
+}
+function expandHome(pathValue, home) {
+	if (pathValue === "~") return home;
+	if (pathValue.startsWith("~/") || pathValue.startsWith("~\\")) return join(home, pathValue.slice(2));
+	return pathValue;
+}
+function absoluteDataDir(pathValue, cwd, home) {
+	const expanded = expandHome(pathValue, home);
+	return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+}
+function platformDefaultDataDir(env, home, nodePlatform, useXdg = true) {
+	if (nodePlatform === "darwin") return join(home, "Library", "Application Support", "agentmemory");
+	if (nodePlatform === "win32") {
+		const appData = env["APPDATA"];
+		return appData ? join(appData, "agentmemory") : join(home, ".agentmemory");
+	}
+	const xdgDataHome = env["XDG_DATA_HOME"];
+	if (useXdg && xdgDataHome && isAbsolute(xdgDataHome)) return join(xdgDataHome, "agentmemory");
+	return join(home, ".local", "share", "agentmemory");
+}
+function nearestGitParent(pathValue) {
+	let current = pathValue;
+	while (true) {
+		if (existsSync(join(current, ".git"))) return current;
+		const parent = dirname(current);
+		if (parent === current) return void 0;
+		current = parent;
+	}
+}
+function isWithin(parent, child) {
+	const pathFromParent = relative(parent, child);
+	return pathFromParent === "" || pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent);
+}
+function resolveDataDir(options = {}) {
+	const args = options.args ?? process.argv.slice(2);
+	const env = options.env ?? process.env;
+	const cwd = options.cwd ?? process.cwd();
+	const home = options.home ?? homedir();
+	const nodePlatform = options.platform ?? platform();
+	const parsedInstance = parseInt(argValue(args, "--instance") ?? "0", 10);
+	const instance = parsedInstance > 0 && parsedInstance <= 50 ? parsedInstance : 0;
+	const forInstance = (dataDir) => instance ? join(dataDir, `instance-${instance}`) : dataDir;
+	const flagValue = argValue(args, "--data-dir");
+	if (flagValue) return {
+		dataDir: forInstance(absoluteDataDir(flagValue, cwd, home)),
+		source: "flag"
+	};
+	const envValue = env["AGENTMEMORY_DATA_DIR"];
+	if (envValue) return {
+		dataDir: forInstance(absoluteDataDir(envValue, cwd, home)),
+		source: "env"
+	};
+	const legacyDir = resolve(cwd, "data");
+	const hasLegacyStore = existsSync(join(legacyDir, "state_store.db")) || existsSync(join(legacyDir, "iii-config.yaml"));
+	if (instance === 0 && hasLegacyStore) return {
+		dataDir: legacyDir,
+		source: "default"
+	};
+	const defaultDir = platformDefaultDataDir(env, home, nodePlatform);
+	const gitParent = nearestGitParent(cwd);
+	if (gitParent && isWithin(gitParent, defaultDir)) {
+		const relocated = platformDefaultDataDir(env, home, nodePlatform, false);
+		if (relocated !== defaultDir) return {
+			dataDir: forInstance(relocated),
+			source: "default",
+			relocatedFrom: defaultDir
+		};
+	}
+	return {
+		dataDir: forInstance(defaultDir),
+		source: "default"
+	};
+}
+//#endregion
 //#region src/cli.ts
+const c = {
+	url: pc.cyan,
+	ok: pc.green,
+	warn: pc.yellow,
+	err: pc.red,
+	cmd: (s) => pc.bold(pc.cyan(s)),
+	label: pc.bold,
+	dim: pc.dim,
+	accent: (s) => pc.bold(pc.yellow(s))
+};
+const ALL_TOOLS_COUNT = getAllTools().length;
+const CORE_TOOLS_COUNT = getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name)).length;
 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") || process.env["AGENTMEMORY_VERBOSE"] === "1" || process.env["AGENTMEMORY_VERBOSE"] === "true";
 setBootVerbose(IS_VERBOSE);
 const IS_RESET = args.includes("--reset");
+hydrateProcessEnvFromFile();
 if (args.includes("--version") || args.includes("-V")) {
 	process.stdout.write(`${VERSION}\n`);
 	process.exit(0);
@@ -840,6 +891,19 @@ function iiiReleaseUrl() {
 function vlog(msg) {
 	if (IS_VERBOSE) p.log.info(`[verbose] ${msg}`);
 }
+function wrapList(items, indent, width = 78) {
+	const lines = [];
+	let line = "";
+	for (const item of items) {
+		const joined = line ? `${line}, ${item}` : item;
+		if (line && indent + joined.length > width) {
+			lines.push(`${line},`);
+			line = item;
+		} else line = joined;
+	}
+	lines.push(line);
+	return lines.join(`\n${" ".repeat(indent)}`);
+}
 if (args.includes("--help") || args.includes("-h")) {
 	console.log(`
 agentmemory — persistent memory for AI coding agents
@@ -849,9 +913,8 @@ 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,
-                     copilot-cli, codex, cursor, gemini-cli, openclaw,
-                     hermes, pi, openhuman).
+  connect [agent]    Wire agentmemory into an installed agent
+                     (${wrapList(knownAgents(), 21)}).
                      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
@@ -860,7 +923,9 @@ Commands:
                      --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
+  demo [--serve]     Seed sample sessions and show recall in action.
+                     --serve boots the server, runs the demo, and stops it
+                     in one command (no second terminal).
   upgrade            Upgrade local deps + iii runtime (best effort)
   stop [--force]     Stop the running iii-engine started by this CLI.
                      --force bypasses the Docker-heuristic guard and signals
@@ -876,7 +941,7 @@ Options:
   --help, -h         Show this help
   --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: all = 51 tools; core = 8 essentials)
+  --tools all|core   Tool visibility (default: all = ${ALL_TOOLS_COUNT} tools; core = ${CORE_TOOLS_COUNT} essentials)
   --no-engine        Skip auto-starting iii-engine
   --port <N>         Override REST port (default: 3111). Streams (N+1), viewer
                      (N+2), and iii engine (N+46023) auto-derive from N so a
@@ -884,10 +949,12 @@ Options:
   --instance <N>     Shortcut for --port (3111 + N*100) to run multiple
                      daemons side-by-side without env gymnastics.
                      --instance 1 -> 3211/3212/3213/49234, etc. (max N=50)
+  --data-dir <path>  Store iii-engine state outside the current repo
 
 Environment:
   AGENTMEMORY_URL              Full REST base URL (e.g. http://localhost:3111).
                                Honored by status, doctor, and MCP shim commands.
+  AGENTMEMORY_DATA_DIR         State directory fallback when --data-dir is not set.
   AGENTMEMORY_USE_DOCKER=1     Prefer the bundled docker-compose path over the
                                native iii-engine binary on first run.
   AGENTMEMORY_III_VERSION      Override pinned iii-engine version (default ${IIPINNED_VERSION}).
@@ -907,7 +974,11 @@ Quick start:
 	process.exit(0);
 }
 const toolsIdx = args.indexOf("--tools");
-if (toolsIdx !== -1 && args[toolsIdx + 1]) process.env["AGENTMEMORY_TOOLS"] = args[toolsIdx + 1];
+if (toolsIdx !== -1 && args[toolsIdx + 1]) {
+	const toolsMode = args[toolsIdx + 1];
+	if (toolsMode !== "all" && toolsMode !== "core") p.log.warn(`Unknown --tools value "${toolsMode}" (valid: all, core); falling back to all.`);
+	process.env["AGENTMEMORY_TOOLS"] = toolsMode;
+}
 const portIdx = args.indexOf("--port");
 if (portIdx !== -1 && args[portIdx + 1]) process.env["III_REST_PORT"] = args[portIdx + 1];
 const instanceIdx = args.indexOf("--instance");
@@ -918,6 +989,8 @@ if (instanceIdx !== -1 && args[instanceIdx + 1]) {
 		if (!process.env["III_REST_PORT"]) process.env["III_REST_PORT"] = String(base);
 	}
 }
+const dataDirResolution = resolveDataDir({ args });
+if (dataDirResolution.source !== "default") process.env["AGENTMEMORY_DATA_DIR"] = dataDirResolution.dataDir;
 const skipEngine = args.includes("--no-engine");
 function getRestPort() {
 	const url = process.env["AGENTMEMORY_URL"];
@@ -1012,6 +1085,30 @@ function findIiiConfig() {
 	for (const c of candidates) if (existsSync(c)) return c;
 	return "";
 }
+function yamlSingleQuoted(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function renderIiiConfig(template, dataDir) {
+	return template.replace("file_path: ./data/state_store.db", `file_path: ${yamlSingleQuoted(join(dataDir, "state_store.db"))}`).replace("file_path: ./data/stream_store", `file_path: ${yamlSingleQuoted(join(dataDir, "stream_store"))}`);
+}
+function writeRuntimeIiiConfig(configPath, dataDir) {
+	mkdirSync(dataDir, { recursive: true });
+	const runtimeConfigPath = join(dataDir, "iii-config.yaml");
+	writeFileSync(runtimeConfigPath, renderIiiConfig(readFileSync(configPath, "utf8"), dataDir));
+	return runtimeConfigPath;
+}
+function warnIfRelocatedDataDir() {
+	if (!dataDirResolution.relocatedFrom) return;
+	try {
+		mkdirSync(dataDirResolution.dataDir, { recursive: true });
+		const marker = join(dataDirResolution.dataDir, ".cwd-relocation-warning");
+		if (existsSync(marker)) return;
+		p.log.warn(`Default data dir ${dataDirResolution.relocatedFrom} is inside a git worktree; using ${dataDirResolution.dataDir} instead.`);
+		writeFileSync(marker, (/* @__PURE__ */ new Date()).toISOString());
+	} catch {
+		p.log.warn(`Default data dir ${dataDirResolution.relocatedFrom} is inside a git worktree; using ${dataDirResolution.dataDir} instead.`);
+	}
+}
 function whichBinary(name) {
 	const cmd = IS_WINDOWS ? "where" : "which";
 	try {
@@ -1188,8 +1285,8 @@ async function maybeOfferGlobalInstall() {
 	if (runCommand(npmBin, [
 		"install",
 		"-g",
-		`@agentmemory/agentmemory@0.9.27`
-	], { label: `Installing @agentmemory/agentmemory@0.9.27 globally` })) {
+		`@agentmemory/agentmemory@0.9.29`
+	], { label: `Installing @agentmemory/agentmemory@0.9.29 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");
@@ -1244,13 +1341,20 @@ function adoptRunningEngine() {
 		const existingPid = readEnginePidfile();
 		if (existingState && existingPid) return;
 		const enginePid = findEnginePidsByPort(getRestPort())[0];
+		if (enginePid) {
+			const comm = pidCommand(enginePid);
+			if (isForeignPortHolder(comm)) {
+				vlog(`adoptRunningEngine: refusing to adopt pid ${enginePid} (${comm}) — not the iii engine binary`);
+				return;
+			}
+		}
 		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})`);
+		if (enginePid && !existingPid) p.log.info(c.ok(`Attached to existing iii-engine (pid ${enginePid})`));
 	} catch (err) {
 		vlog(`adoptRunningEngine: ${err instanceof Error ? err.message : String(err)}`);
 	}
@@ -1352,7 +1456,7 @@ function startIiiBin(iiiBin, configPath) {
 		binPath: iiiBin
 	});
 	spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
-	s.stop("iii-engine process started");
+	s.stop(c.ok("iii-engine process started"));
 	return true;
 }
 function pickCompatibleIii(candidates) {
@@ -1365,17 +1469,19 @@ function pickCompatibleIii(candidates) {
 }
 async function startEngine() {
 	const configPath = findIiiConfig();
+	warnIfRelocatedDataDir();
+	const runtimeConfigPath = configPath ? writeRuntimeIiiConfig(configPath, dataDirResolution.dataDir) : "";
 	const pathIii = whichBinary("iii");
-	vlog(`iii binary: ${pathIii ?? "(not on PATH)"}, config: ${configPath || "(not found)"}`);
+	vlog(`iii binary: ${pathIii ?? "(not on PATH)"}, config: ${runtimeConfigPath || "(not found)"}`);
 	const fallbacks = fallbackIiiPaths().filter((p) => existsSync(p));
 	for (const f of fallbacks) vlog(`fallback iii at ${f} reports version: ${iiiBinVersion(f) ?? "unknown"}`);
 	let iiiBin = pickCompatibleIii([pathIii, ...fallbacks]);
-	if (iiiBin && configPath) {
+	if (iiiBin && runtimeConfigPath) {
 		if (iiiBin !== pathIii) {
-			p.log.info(`Using iii at: ${iiiBin} (v${IIPINNED_VERSION})`);
+			p.log.info(`Using iii at: ${c.dim(iiiBin)} (v${c.accent(IIPINNED_VERSION)})`);
 			process.env["PATH"] = `${dirname(iiiBin)}${delimiter}${process.env["PATH"] ?? ""}`;
 		}
-		return startIiiBin(iiiBin, configPath);
+		return startIiiBin(iiiBin, runtimeConfigPath);
 	}
 	if (pathIii && !iiiBin) vlog(`iii on PATH is v${iiiBinVersion(pathIii) ?? "unknown"}, pin is v${IIPINNED_VERSION}. Will install pinned engine to ${privateIiiPath()}.`);
 	if (!configPath) {
@@ -1384,6 +1490,7 @@ async function startEngine() {
 	}
 	const dockerBin = whichBinary("docker");
 	vlog(`docker binary: ${dockerBin ?? "(not on PATH)"}`);
+	mkdirSync(dataDirResolution.dataDir, { recursive: true });
 	const composeFile = [
 		join(__dirname, "..", "docker-compose.yml"),
 		join(__dirname, "docker-compose.yml"),
@@ -1545,19 +1652,25 @@ function printReadyHint(consoleState) {
 	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: ${iiiConsoleInstallHint()})`;
+	const consoleLine = consoleState.kind === "installed" ? `${c.label("iii console")}  ${c.dim(consoleState.binPath)}  ${c.dim(`(run: ${consoleState.binPath} -p <port>)`)}` : `${c.label("iii console")}  ${c.dim(`(install: ${iiiConsoleInstallHint()})`)}`;
 	const lines = [
-		`REST API     ${restUrl}`,
-		`Viewer       ${viewerUrl}`,
-		`Streams      ${streamUrl}`,
-		`Engine       ${engineUrl}`,
+		`${c.label("REST API")}     ${c.url(restUrl)}`,
+		`${c.label("Viewer")}       ${c.url(viewerUrl)}`,
+		`${c.label("Streams")}      ${c.url(streamUrl)}`,
+		`${c.label("Engine")}       ${c.url(engineUrl)}`,
 		consoleLine
 	];
-	p.note(lines.join("\n"), `agentmemory v${VERSION}`);
+	p.note(lines.join("\n"), `agentmemory v${c.accent(VERSION)}`);
 	const demoCommand = isInvokedViaNpx() ? "npx @agentmemory/agentmemory demo" : "agentmemory demo";
-	process.stdout.write(`\nTry: ${demoCommand}\n`);
+	process.stdout.write(`\n${c.dim("Try:")} ${c.cmd(demoCommand)}\n`);
 }
 async function main() {
+	try {
+		if ((await fetch(`${getBaseUrl()}/agentmemory/livez`, { signal: AbortSignal.timeout(1500) })).ok) {
+			p.log.error(`agentmemory is already running on port ${getRestPort()}. Starting a second instance here would corrupt the running daemon's REST routing. Use the REST API (or the MCP tools) against the running instance, run a different --instance, or stop it first with \`agentmemory stop\`.`);
+			process.exit(1);
+		}
+	} catch {}
 	if (IS_RESET) resetPrefs();
 	const firstRun = isFirstRun();
 	const prefs = readPrefs();
@@ -1565,7 +1678,7 @@ 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-MOg2zKJs.mjs");
+		await import("./src-G7yt8gGm.mjs");
 		if (await waitForAgentmemoryReady(15e3)) {
 			const consoleState = await ensureIiiConsole();
 			await maybeOfferGlobalInstall();
@@ -1577,21 +1690,38 @@ async function main() {
 		if (IS_VERBOSE) p.log.success("iii-engine is running");
 		const persisted = readEngineState();
 		const attachedBin = (persisted?.kind === "native" && persisted.binPath && existsSync(persisted.binPath) ? persisted.binPath : null) ?? whichBinary("iii") ?? fallbackIiiPaths().find((p) => existsSync(p)) ?? null;
-		if (attachedBin) {
-			const detected = iiiBinVersion(attachedBin);
-			if (detected && detected !== IIPINNED_VERSION) {
-				p.log.error(`Attached iii-engine appears to be v${detected} (from ${attachedBin}) but agentmemory v${VERSION} hard-pins v${IIPINNED_VERSION}. Engine API drift causes runtime failures (e.g. state::list-not-found on v0.13.0+). Stop the running engine (\`agentmemory stop --force\`) and re-run \`agentmemory\` to install the pinned engine into ~/.agentmemory/bin without touching ${attachedBin}. Or set AGENTMEMORY_III_VERSION=${detected} to override at your own risk.`);
-				process.exit(1);
+		const detected = attachedBin ? iiiBinVersion(attachedBin) : null;
+		if (detected === IIPINNED_VERSION) {
+			adoptRunningEngine();
+			await import("./src-G7yt8gGm.mjs");
+			if (await waitForAgentmemoryReady(15e3)) {
+				const consoleState = await ensureIiiConsole();
+				await maybeOfferGlobalInstall();
+				printReadyHint(consoleState);
 			}
+			return;
 		}
-		adoptRunningEngine();
-		await import("./src-MOg2zKJs.mjs");
-		if (await waitForAgentmemoryReady(15e3)) {
-			const consoleState = await ensureIiiConsole();
-			await maybeOfferGlobalInstall();
-			printReadyHint(consoleState);
-		}
-		return;
+		const detectedLabel = detected ? `v${detected}` : "an unverified version";
+		const base = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";
+		p.log.error(`Another iii-engine (${detectedLabel}) is running on port ${getEnginePort()}, and agentmemory needs its own pinned v${IIPINNED_VERSION}.`);
+		p.note([
+			`agentmemory only supports iii-engine v${IIPINNED_VERSION}. It will not adopt or change the running engine (${detectedLabel}).`,
+			"",
+			c.label("Switch to the pinned engine in two steps:"),
+			"",
+			`  1. Stop the running engine:`,
+			`       ${c.cmd(`${base} stop --force`)}`,
+			`     ${c.dim(`(or stop your own iii however you started it — agentmemory leaves your global iii untouched)`)}`,
+			"",
+			`  2. Start agentmemory. It downloads and runs the pinned`,
+			`     v${IIPINNED_VERSION} into ~/.agentmemory/bin automatically:`,
+			`       ${c.cmd(base)}`,
+			"",
+			c.dim(`Step 2 needs no manual install. To install iii v${IIPINNED_VERSION} yourself (replaces your global iii), curl:`),
+			`     ${c.cmd(III_CONSOLE_INSTALL_CMD)}`,
+			`     ${c.dim("or download the release:")} ${c.url(`https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`)}`
+		].join("\n"), "engine conflict");
+		process.exit(1);
 	}
 	if (!await startEngine()) {
 		p.log.error("Could not start iii-engine.");
@@ -1633,8 +1763,8 @@ async function main() {
 		}
 		process.exit(1);
 	}
-	s.stop("iii-engine is ready");
-	await import("./src-MOg2zKJs.mjs");
+	s.stop(c.ok("iii-engine is ready"));
+	await import("./src-G7yt8gGm.mjs");
 	if (await waitForAgentmemoryReady(15e3)) {
 		const consoleState = await ensureIiiConsole();
 		await maybeOfferGlobalInstall();
@@ -1692,7 +1822,7 @@ async function runStatus() {
 		const pctSaved = estFullTokens > 0 ? Math.round(tokensSaved / estFullTokens * 100) : 0;
 		p.log.success(`Connected — v${version} at ${base}`);
 		const lines = [
-			`Health:       ${status === "healthy" ? "✓ healthy" : status}`,
+			`Health:       ${status === "healthy" ? pc.green("✓ healthy") : pc.yellow(status)}`,
 			`Sessions:     ${sessions}`,
 			`Observations: ${obsCount}`,
 			`Memories:     ${memCount}`,
@@ -1700,7 +1830,7 @@ async function runStatus() {
 			`Circuit:      ${cb}`,
 			`Heap:         ${heapMB} MB`,
 			`Uptime:       ${uptime}s`,
-			`Viewer:       ${getViewerUrl()}`
+			`Viewer:       ${c.url(getViewerUrl())}`
 		];
 		if (obsCount > 0) {
 			lines.push("");
@@ -1709,9 +1839,9 @@ async function runStatus() {
 			lines.push(`  Injected:     ~${estInjectedTokens.toLocaleString()} tokens`);
 		}
 		if (flagsRes) {
-			const provider = flagsRes.provider === "llm" ? "✓ llm" : "✗ noop (no key)";
-			const embed = flagsRes.embeddingProvider === "embeddings" ? "✓ embeddings" : "bm25-only";
-			const flagRows = (flagsRes.flags || []).map((f) => `  ${f.enabled ? "✓" : "✗"} ${f.key.padEnd(32)} ${f.label}`);
+			const provider = flagsRes.provider === "llm" ? pc.green("✓ llm") : pc.yellow("✗ noop (no key)");
+			const embed = flagsRes.embeddingProvider === "embeddings" ? pc.green("✓ embeddings") : pc.dim("bm25-only");
+			const flagRows = (flagsRes.flags || []).map((f) => `  ${f.enabled ? pc.green("✓") : pc.dim("✗")} ${pc.bold(f.key.padEnd(32))} ${f.label}`);
 			lines.push("");
 			lines.push(`Provider:     ${provider}`);
 			lines.push(`Embeddings:   ${embed}`);
@@ -1732,7 +1862,7 @@ async function runStatus() {
 	}
 }
 function formatChecks(checks) {
-	return checks.map((c) => `${c.ok ? "✓" : "✗"} ${c.name}${c.hint ? `\n   ${c.hint}` : ""}`).join("\n");
+	return checks.map((c) => `${c.ok ? pc.green("✓") : pc.red("✗")} ${c.name}${c.hint ? `\n   ${c.hint}` : ""}`).join("\n");
 }
 function findLatestDebugLog(debugDir) {
 	const latestLink = join(debugDir, "latest");
@@ -2268,15 +2398,63 @@ async function runInit() {
 	].join("\n"), "Next steps");
 	p.outro(`Edit ${target} and you're set.`);
 }
+async function startServerForDemo() {
+	if (await isAgentmemoryReady()) return async () => {};
+	const startedEngine = !await isEngineRunning();
+	if (startedEngine) {
+		if (!await startEngine()) {
+			p.log.error("Could not start iii-engine for the demo.");
+			p.note(installInstructions().join("\n"), "Setup required");
+			process.exit(1);
+		}
+		if (!await waitForEngine(15e3)) {
+			p.log.error("iii-engine did not become ready within 15s.");
+			process.exit(1);
+		}
+	}
+	await import("./src-G7yt8gGm.mjs");
+	if (!await waitForAgentmemoryReady(15e3)) {
+		p.log.error("agentmemory worker did not become ready within 15s.");
+		process.exit(1);
+	}
+	return async () => {
+		if (!startedEngine) return;
+		const port = getRestPort();
+		const state = readEngineState();
+		if (state?.kind === "docker") {
+			await stopDockerEngine(state.composeFile, port).catch(() => {});
+			return;
+		}
+		const pids = new Set(findEnginePidsByPort(port));
+		const pidfilePid = readEnginePidfile();
+		if (pidfilePid) pids.add(pidfilePid);
+		for (const pid of pids) await signalAndWait(pid, "SIGTERM", 3e3).catch(() => {});
+		clearEnginePidfile();
+		clearEngineState();
+		clearWorkerPidfile();
+	};
+}
 async function runDemo() {
 	const port = getRestPort();
 	const base = `http://localhost:${port}`;
 	p.intro("agentmemory demo");
-	if (!await isAgentmemoryReady()) {
+	const serve = args.includes("--serve");
+	let teardown = async () => {};
+	if (serve) teardown = await startServerForDemo();
+	else if (!await isAgentmemoryReady()) {
 		p.log.error(`agentmemory worker not reachable on port ${port} (livez probe failed). Something may be on the port but it isn't serving /agentmemory/*.`);
 		p.log.info("Start it with: npx @agentmemory/agentmemory");
+		p.log.info("Or run a one-command demo with: npx @agentmemory/agentmemory demo --serve");
 		process.exit(1);
 	}
+	try {
+		await runDemoBody(base);
+	} finally {
+		await teardown();
+	}
+	if (serve) process.exit(0);
+}
+async function runDemoBody(base) {
 	const demoProject = "/tmp/agentmemory-demo";
 	const sessions = buildDemoSessions();
 	const sSeed = p.spinner();
@@ -2294,18 +2472,22 @@ async function runDemo() {
 	const results = [];
 	for (const query of queries) results.push(await runDemoSearch(base, query));
 	sQuery.stop("Search complete");
+	const semanticHits = results.find((r) => r.query === "database performance optimization")?.hits ?? 0;
 	const lines = [
 		`Project:       ${demoProject}`,
 		`Sessions:      ${sessions.length} seeded (${totalObs} observations)`,
 		"",
-		"Search results:",
-		...results.flatMap((r) => [`  "${r.query}"`, `    → ${r.hits} hit(s), top: ${r.topTitle.slice(0, 60)}`]),
+		c.label("Search results:"),
+		...results.flatMap((r) => [`  ${c.label(`"${r.query}"`)}`, `    ${c.dim("→")} ${c.ok(`${r.hits} hit(s)`)}, top: ${r.topTitle.slice(0, 60)}`]),
 		"",
-		`Notice: searching "database performance optimization"`,
-		`found the N+1 query fix — keyword matching can't do that.`,
+		...semanticHits > 0 ? [c.accent(`Notice: searching "database performance optimization"`), c.accent(`found the N+1 query fix — keyword matching can't do that.`)] : [
+			c.dim(`Note: "database performance optimization" found nothing —`),
+			c.dim(`semantic recall needs an embedding provider key (e.g.`),
+			c.dim(`OPENAI_API_KEY or GEMINI_API_KEY in ~/.agentmemory/.env).`)
+		],
 		"",
-		`Viewer:        ${getViewerUrl()}`,
-		`Clean up with: curl -X DELETE "${base}/agentmemory/sessions?project=${demoProject}"`
+		`Viewer:        ${c.url(getViewerUrl())}`,
+		`Clean up with: ${c.dim(`curl -X DELETE "${base}/agentmemory/sessions?project=${demoProject}"`)}`
 	];
 	p.note(lines.join("\n"), "demo complete");
 	p.log.success("agentmemory is working. Point your agent at it and get back to coding.");
@@ -2319,7 +2501,7 @@ function runCommand(command, commandArgs, options = { label: "command" }) {
 		encoding: "utf-8"
 	});
 	if (result.status === 0) {
-		spinner.stop(`${options.label} ✓`);
+		spinner.stop(`${options.label} ${pc.green("✓")}`);
 		return true;
 	}
 	const stderr = (result.stderr || "").toString().trim();
@@ -2330,7 +2512,7 @@ function runCommand(command, commandArgs, options = { label: "command" }) {
 		p.log.warn(msg.slice(0, 300));
 		return false;
 	}
-	spinner.stop(`${options.label} ✗`);
+	spinner.stop(`${options.label} ${pc.red("✗")}`);
 	p.log.error(msg.slice(0, 300));
 	return false;
 }
@@ -2424,6 +2606,38 @@ async function signalAndWait(pid, initialSignal, timeoutMs) {
 	await new Promise((r) => setTimeout(r, 200));
 	return !pidAlive(pid);
 }
+async function stopWorkerPid(pid, graceMs) {
+	const s = p.spinner();
+	s.start(`Stopping agentmemory worker (pid ${pid})... [flushing state]`);
+	const ok = await signalAndWait(pid, "SIGTERM", graceMs);
+	s.stop(ok ? `Stopped worker pid ${pid}` : `Failed to stop worker pid ${pid}`);
+	return ok;
+}
+function pidCommand(pid) {
+	if (IS_WINDOWS) return "";
+	try {
+		return execFileSync("ps", [
+			"-p",
+			String(pid),
+			"-o",
+			"comm="
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return "";
+	}
+}
+function isForeignPortHolder(comm) {
+	if (!comm) return false;
+	const base = comm.split("/").pop() || comm;
+	return base !== "iii" && !base.startsWith("iii-");
+}
 function findEnginePidsByPort(port) {
 	if (IS_WINDOWS) return [];
 	const lsof = whichBinary("lsof");
@@ -2458,17 +2672,35 @@ async function stopDockerEngine(composeFile, port) {
 		p.log.error(`Engine state references ${composeFile}, but the file is gone. Stop it manually:\n  docker compose down  (from the dir holding the original docker-compose.yml)`);
 		process.exit(1);
 	}
+	const workerPid = readWorkerPidfile();
+	let workerStopped = true;
+	if (workerPid) workerStopped = await stopWorkerPid(workerPid, 5e3);
+	let composeText = "";
+	try {
+		composeText = readFileSync(composeFile, "utf-8");
+	} catch {
+		composeText = "";
+	}
+	const ownServices = ["iii-engine", "iii-init"].filter((svc) => new RegExp(`^\\s+${svc}:`, "m").test(composeText));
+	if (ownServices.length === 0) {
+		p.log.error(`${composeFile} does not define the agentmemory services (iii-engine/iii-init). Refusing to run an unscoped \`docker compose down\` against it — that would tear down every service in the file.\n\nStop the engine service manually:\n  docker compose -f ${composeFile} stop <service>`);
+		process.exit(1);
+	}
 	const ok = runCommand(dockerBin, [
 		"compose",
 		"-f",
 		composeFile,
-		"down"
-	], { label: `docker compose -f ${composeFile} down` });
-	clearEnginePidfile();
-	clearEngineState();
-	clearWorkerPidfile();
-	if (!ok) {
-		p.log.error(`docker compose down failed. The engine may still be running on :${port}. Inspect with:\n  docker compose -f ${composeFile} ps`);
+		"rm",
+		"-s",
+		"-f",
+		...ownServices
+	], { label: `docker compose -f ${composeFile} rm -s -f ${ownServices.join(" ")}` });
+	if (workerStopped) clearWorkerPidfile();
+	if (ok) {
+		clearEnginePidfile();
+		clearEngineState();
+	} else {
+		p.log.error(`docker compose rm failed. The engine may still be running on :${port}. Inspect with:\n  docker compose -f ${composeFile} ps`);
 		process.exit(1);
 	}
 	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
@@ -2542,15 +2774,18 @@ async function runStop() {
 		process.exit(1);
 	}
 	let allStopped = true;
-	for (const pid of workerCandidates) {
-		const s = p.spinner();
-		s.start(`Stopping agentmemory worker (pid ${pid})... [flushing state]`);
-		const ok = await signalAndWait(pid, "SIGTERM", 5e3);
-		s.stop(ok ? `Stopped worker pid ${pid}` : `Failed to stop worker pid ${pid}`);
-		if (!ok) allStopped = false;
-	}
+	for (const pid of workerCandidates) if (!await stopWorkerPid(pid, 5e3)) allStopped = false;
+	const skippedForeign = [];
 	for (const pid of candidates) {
 		if (workerCandidates.has(pid)) continue;
+		const comm = pidCommand(pid);
+		if (!force && isForeignPortHolder(comm)) {
+			skippedForeign.push({
+				pid,
+				comm
+			});
+			continue;
+		}
 		const s = p.spinner();
 		s.start(`Stopping iii-engine (pid ${pid})...`);
 		const ok = await signalAndWait(pid, "SIGTERM", 3e3);
@@ -2560,6 +2795,11 @@ async function runStop() {
 	clearEnginePidfile();
 	clearEngineState();
 	clearWorkerPidfile();
+	if (skippedForeign.length > 0) {
+		const list = skippedForeign.map((sf) => `  pid ${sf.pid}  ${sf.comm}`).join("\n");
+		p.log.error(`Refused to signal process(es) holding :${port} that are not the iii engine:\n${list}\n\nIf the engine runs in Docker, stop it there:\n  docker compose ps && docker compose rm -s -f <service>\n\nOr re-run with --force to signal them anyway.`);
+		process.exit(1);
+	}
 	if (!allStopped) {
 		p.log.error("One or more processes survived SIGKILL. Investigate with `ps`.");
 		process.exit(1);
@@ -2567,14 +2807,18 @@ async function runStop() {
 	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
 }
 async function runMcp() {
-	await import("./standalone-BORXC71-.mjs");
+	await import("./standalone-BqNJDJ04.mjs");
 }
 async function runConnectCmd() {
-	const { runConnect } = await import("./connect-bmZ5eqYN.mjs").then((n) => n.t);
+	const { runConnect } = await import("./connect-Qaeq15TQ.mjs").then((n) => n.n);
 	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {
-	const VALUE_FLAGS = new Set(["--port", "--tools"]);
+	const VALUE_FLAGS = new Set([
+		"--port",
+		"--tools",
+		"--data-dir"
+	]);
 	let maxFiles;
 	const tail = args.slice(1);
 	const positional = [];
@@ -2786,7 +3030,7 @@ async function runRemove() {
 	}
 	p.outro("Done. agentmemory cleanly removed. The npm package itself: npm uninstall -g @agentmemory/agentmemory");
 }
-({
+const commands = {
 	init: runInit,
 	connect: runConnectCmd,
 	status: runStatus,
@@ -2797,7 +3041,13 @@ async function runRemove() {
 	remove: runRemove,
 	mcp: runMcp,
 	"import-jsonl": runImportJsonl
-}[args[0] ?? ""] ?? main)().catch((err) => {
+};
+const first = args[0] ?? "";
+async function unknownCommand() {
+	p.log.error(`Unknown command: ${first}. Supported: ${Object.keys(commands).join(", ")}. Run \`agentmemory\` with no arguments to start the memory server, or \`agentmemory --help\` for usage.`);
+	process.exit(1);
+}
+(commands[first] ?? (first && !first.startsWith("-") ? unknownCommand : main))().catch((err) => {
 	p.log.error(err instanceof Error ? err.message : String(err));
 	process.exit(1);
 });