@agentmemory/agentmemory 0.9.28 → 0.9.29

package/dist/.env.example

@@ -26,22 +26,24 @@
 # The detection order is OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY
 # → GEMINI_API_KEY → OPENROUTER_API_KEY → noop.
 
-# OPENAI_API_KEY=sk-...                          # Used for OpenAI-compatible embeddings today. PR #307 will extend this to chat completions (DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama via `/v1`).
+# OPENAI_API_KEY=sk-...                          # Activates both the OpenAI-compatible LLM provider (DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama via `/v1`) and OpenAI embeddings. Set OPENAI_API_KEY_FOR_LLM=false to scope it to embeddings only.
 # OPENAI_BASE_URL=https://api.openai.com         # Override for OpenAI-compatible providers
+# OPENAI_MODEL=gpt-5.6-luna                      # Default OpenAI-compatible chat model
+# OPENAI_API_KEY_FOR_LLM=false                   # Skip OpenAI auto-detection for LLM; key stays active for embeddings
 
 # ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_MODEL=claude-sonnet-4-20250514       # Default Anthropic model
+# ANTHROPIC_MODEL=claude-sonnet-5                # Default Anthropic model
 # ANTHROPIC_BASE_URL=https://api.anthropic.com   # Override for Anthropic-compatible proxies / Azure AI Foundry
 
 # GEMINI_API_KEY=...                             # Either env name works; GEMINI_API_KEY takes precedence
 # GOOGLE_API_KEY=...                             # Alias for GEMINI_API_KEY when set alone (emits a one-time stderr hint)
-# GEMINI_MODEL=gemini-2.5-flash                  # Default Gemini model (auto-detected GA model)
+# GEMINI_MODEL=gemini-3.7-flash                  # Default Gemini model (current stable Flash)
 
 # OPENROUTER_API_KEY=sk-or-...
-# OPENROUTER_MODEL=anthropic/claude-sonnet-4-20250514
+# OPENROUTER_MODEL=anthropic/claude-sonnet-5
 
 # MINIMAX_API_KEY=...
-# MINIMAX_MODEL=MiniMax-M2.7
+# MINIMAX_MODEL=MiniMax-M3
 
 # MAX_TOKENS=4096                                # Cap LLM completion tokens for compression / summarise calls
 
@@ -111,6 +113,13 @@
 # CONSOLIDATION_DECAY_DAYS=30                    # Age (days) after which non-reinforced memories decay during consolidation
 # GRAPH_EXTRACTION_ENABLED=true                  # Extract concept-graph edges on remember; powers the graph-traversal recall path
 # GRAPH_EXTRACTION_BATCH_SIZE=8                  # Memories per graph-extraction batch
+
+# Local reasoning models only: set to 1 to ask the model to skip its
+# hidden thinking pass during graph extraction. Extraction runs several
+# times faster; relation quality can drop slightly. Leave unset to let
+# the model think (default).
+# AGENTMEMORY_LLM_NOTHINK=1
+
 # AGENTMEMORY_REFLECT=true                       # Periodically auto-synthesize lessons from memories
 # AGENTMEMORY_DROP_STALE_INDEX=true              # Drop on-disk BM25 / vector index on startup if dim guard fires (#248). Recovery toggle for stuck-state debugging.
 # AGENTMEMORY_IMAGE_EMBEDDINGS=true              # Enable image embeddings when an image provider is present (experimental).
@@ -119,7 +128,7 @@
 # 6. CLI / runtime knobs
 # -----------------------------------------------------------------------------
 
-# AGENTMEMORY_TOOLS=all                          # core (7 tools, default) | all (51 tools) — surface exposed to MCP clients
+# AGENTMEMORY_TOOLS=core                         # all (54 tools, default) | core (8 tools): surface exposed to MCP clients
 # AGENTMEMORY_SLOTS=memory                       # Comma-separated plugin slot names the CLI should claim
 # AGENTMEMORY_DEBUG=1                            # Trace MCP shim probe + standalone fallback decisions to stderr
 # AGENTMEMORY_FORCE_PROXY=1                      # Skip the MCP shim livez probe and trust AGENTMEMORY_URL (for sandboxed MCP clients that can't reach localhost)

package/dist/cli.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";iBAqRsB,kBAAA,CAAA,GAAsB,OAAA"}
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";iBAoSsB,kBAAA,CAAA,GAAsB,OAAA"}

package/dist/cli.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { a as runAdapter, i as resolveAdapter, r as knownAgents, t as ADAPTERS } from "./connect-JnsJXc68.mjs";
-import { i as generateId } from "./schema-CNiCWzV9.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, t as ESSENTIAL_TOOLS } from "./tools-registry-D3NEoe5m.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 { appendFileSync, 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 { 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";
@@ -525,7 +525,7 @@ const PROVIDERS = [
 	},
 	{
 		value: "minimax",
-		label: "MiniMax — minimax-m1",
+		label: "MiniMax — MiniMax-M3",
 		envKey: "MINIMAX_API_KEY"
 	},
 	{
@@ -765,6 +765,87 @@ 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,
@@ -784,6 +865,7 @@ 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);
@@ -867,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}).
@@ -905,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"];
@@ -999,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 {
@@ -1175,8 +1285,8 @@ async function maybeOfferGlobalInstall() {
 	if (runCommand(npmBin, [
 		"install",
 		"-g",
-		`@agentmemory/agentmemory@0.9.28`
-	], { label: `Installing @agentmemory/agentmemory@0.9.28 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");
@@ -1231,6 +1341,13 @@ 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",
@@ -1352,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: ${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) {
@@ -1371,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,6 +1665,12 @@ function printReadyHint(consoleState) {
 	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();
@@ -1552,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-CzgoepGU.mjs");
+		await import("./src-G7yt8gGm.mjs");
 		if (await waitForAgentmemoryReady(15e3)) {
 			const consoleState = await ensureIiiConsole();
 			await maybeOfferGlobalInstall();
@@ -1567,7 +1693,7 @@ async function main() {
 		const detected = attachedBin ? iiiBinVersion(attachedBin) : null;
 		if (detected === IIPINNED_VERSION) {
 			adoptRunningEngine();
-			await import("./src-CzgoepGU.mjs");
+			await import("./src-G7yt8gGm.mjs");
 			if (await waitForAgentmemoryReady(15e3)) {
 				const consoleState = await ensureIiiConsole();
 				await maybeOfferGlobalInstall();
@@ -1638,7 +1764,7 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop(c.ok("iii-engine is ready"));
-	await import("./src-CzgoepGU.mjs");
+	await import("./src-G7yt8gGm.mjs");
 	if (await waitForAgentmemoryReady(15e3)) {
 		const consoleState = await ensureIiiConsole();
 		await maybeOfferGlobalInstall();
@@ -2286,7 +2412,7 @@ async function startServerForDemo() {
 			process.exit(1);
 		}
 	}
-	await import("./src-CzgoepGU.mjs");
+	await import("./src-G7yt8gGm.mjs");
 	if (!await waitForAgentmemoryReady(15e3)) {
 		p.log.error("agentmemory worker did not become ready within 15s.");
 		process.exit(1);
@@ -2346,6 +2472,7 @@ async function runDemoBody(base) {
 	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)`,
@@ -2353,8 +2480,11 @@ async function runDemoBody(base) {
 		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)}`]),
 		"",
-		c.accent(`Notice: searching "database performance optimization"`),
-		c.accent(`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:        ${c.url(getViewerUrl())}`,
 		`Clean up with: ${c.dim(`curl -X DELETE "${base}/agentmemory/sessions?project=${demoProject}"`)}`
@@ -2476,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");
@@ -2510,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");
@@ -2594,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);
@@ -2612,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);
@@ -2619,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-YsZFFQBM.mjs");
+	await import("./standalone-BqNJDJ04.mjs");
 }
 async function runConnectCmd() {
-	const { runConnect } = await import("./connect-JnsJXc68.mjs").then((n) => n.n);
+	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 = [];
@@ -2838,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,
@@ -2849,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);
 });