Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

fix(cli): surface real engine startup errors, Windows support (#127)

Rohit Ghumare4beb35ab9e48
diff --git a/README.md b/README.md
index 50b9cc66..9b647b81 100644
--- a/README.md
+++ b/README.md
@@ -377,6 +377,47 @@ This starts agentmemory with a local `iii-engine` if `iii` is already installed,
Install `iii-engine` manually with `cargo install iii-engine` or follow [iii.dev docs](https://iii.dev/docs).
+### Windows
+
+agentmemory runs on Windows 10/11, but the Node.js package alone isn't enough — you also need the `iii-engine` runtime (a separate Rust binary) as a background process. Pick one of:
+
+**Option A — Rust toolchain (recommended):**
+
+```powershell
+# 1. Install rustup: https://rustup.rs/
+# 2. Restart your shell so cargo is on PATH
+cargo install iii-engine
+
+# 3. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory
+```
+
+**Option B — Docker Desktop:**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure it says "Engine running"
+# 3. Run agentmemory — it will auto-start the bundled compose file:
+npx -y @agentmemory/agentmemory
+```
+
+**Option C — standalone MCP only (no engine):** if you only need the MCP tools for your agent and don't need the REST API / viewer / cron jobs, skip the engine entirely:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# or via the shim package:
+npx -y agentmemory-mcp
+```
+
+**Diagnostics for Windows:** if `npx @agentmemory/agentmemory` fails, re-run with `--verbose` to see the actual engine stderr. Common failure modes:
+
+| Symptom | Fix |
+|---|---|
+| `iii-engine process started` then `did not become ready within 15s` | Engine crashed on startup — re-run with `--verbose`, check stderr |
+| `Could not start iii-engine` | Neither `iii.exe` nor Docker is installed. See Option A or B above |
+| Port conflict | `netstat -ano \| findstr :3111` to see what's bound, then kill it or use `--port <N>` |
+| Docker fallback skipped even though Docker is installed | Make sure Docker Desktop is actually running (system tray icon) |
+
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-why.svg"><img src="assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
diff --git a/src/cli.ts b/src/cli.ts
index 48de10ed..def5a1cb 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -1,14 +1,21 @@
#!/usr/bin/env node
-import { spawn, execFileSync } from "node:child_process";
+import { spawn, execFileSync, type ChildProcess } from "node:child_process";
import { existsSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, delimiter as PATH_DELIMITER } from "node:path";
import { fileURLToPath } from "node:url";
+import { platform } from "node:os";
import * as p from "@clack/prompts";
import { generateId } from "./state/schema.js";
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");
+
+function vlog(msg: string): void {
+ if (IS_VERBOSE) p.log.info(`[verbose] ${msg}`);
+}
if (args.includes("--help") || args.includes("-h")) {
console.log(`
@@ -24,6 +31,7 @@ Commands:
Options:
--help, -h Show this help
+ --verbose, -v Show engine stderr and diagnostic info on startup
--tools all|core Tool visibility (default: core = 7 tools)
--no-engine Skip auto-starting iii-engine
--port <N> Override REST port (default: 3111)
@@ -78,7 +86,7 @@ function findIiiConfig(): string {
}
function whichBinary(name: string): string | null {
- const cmd = process.platform === "win32" ? "where" : "which";
+ const cmd = IS_WINDOWS ? "where" : "which";
try {
return execFileSync(cmd, [name], { encoding: "utf-8" }).trim().split("\n")[0];
} catch {
@@ -86,47 +94,112 @@ function whichBinary(name: string): string | null {
}
}
+function fallbackIiiPaths(): string[] {
+ if (IS_WINDOWS) {
+ const userProfile = process.env["USERPROFILE"] || "";
+ const localAppData = process.env["LOCALAPPDATA"] || "";
+ return [
+ join(userProfile, ".cargo", "bin", "iii.exe"),
+ join(localAppData, "cargo", "bin", "iii.exe"),
+ join(userProfile, ".local", "bin", "iii.exe"),
+ ].filter(Boolean);
+ }
+ return [
+ join(process.env["HOME"] || "", ".cargo", "bin", "iii"),
+ join(process.env["HOME"] || "", ".local", "bin", "iii"),
+ "/usr/local/bin/iii",
+ ];
+}
+
+type StartupFailure = {
+ kind: "no-engine" | "no-docker-compose" | "engine-crashed" | "docker-crashed";
+ stderr?: string;
+ binary?: string;
+};
+
+let startupFailure: StartupFailure | null = null;
+
+// Spawn a background engine and collect any startup stderr for a short
+// window. The process is unref'd so the CLI parent can exit cleanly; we
+// only care about stderr that shows up BEFORE the health check succeeds,
+// which is what surfaces early crash/config-parse errors on all platforms.
+function spawnEngineBackground(
+ bin: string,
+ spawnArgs: string[],
+ label: string,
+): ChildProcess {
+ vlog(`spawn: ${bin} ${spawnArgs.join(" ")}`);
+ const child = spawn(bin, spawnArgs, {
+ detached: true,
+ stdio: ["ignore", "ignore", "pipe"],
+ windowsHide: true,
+ });
+ const stderrChunks: Buffer[] = [];
+ let stderrBytes = 0;
+ const MAX_STDERR_CAPTURE = 16 * 1024;
+ child.stderr?.on("data", (chunk: Buffer) => {
+ if (stderrBytes >= MAX_STDERR_CAPTURE) return;
+ const slice = chunk.subarray(0, MAX_STDERR_CAPTURE - stderrBytes);
+ stderrChunks.push(slice);
+ stderrBytes += slice.length;
+ });
+ child.on("exit", (code, signal) => {
+ if (code !== 0 && code !== null) {
+ const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+ startupFailure = {
+ kind: label.includes("Docker") ? "docker-crashed" : "engine-crashed",
+ stderr: stderr.trim() || `process exited with code ${code}${signal ? ` (${signal})` : ""}`,
+ binary: bin,
+ };
+ vlog(`engine exited early: code=${code} signal=${signal}`);
+ if (IS_VERBOSE && stderr.trim()) {
+ p.log.error(`engine stderr:\n${stderr}`);
+ }
+ }
+ });
+ child.unref();
+ return child;
+}
+
async function startEngine(): Promise<boolean> {
const configPath = findIiiConfig();
let iiiBin = whichBinary("iii");
+ vlog(`iii binary: ${iiiBin ?? "(not on PATH)"}, config: ${configPath || "(not found)"}`);
if (iiiBin && configPath) {
const s = p.spinner();
s.start(`Starting iii-engine: ${iiiBin}`);
- const child = spawn(iiiBin, ["--config", configPath], {
- detached: true,
- stdio: "ignore",
- });
- child.unref();
+ spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
s.stop("iii-engine process started");
return true;
}
const dockerBin = whichBinary("docker");
- const dockerCompose = join(__dirname, "..", "docker-compose.yml");
- const dcExists = existsSync(dockerCompose) || existsSync(join(process.cwd(), "docker-compose.yml"));
+ vlog(`docker binary: ${dockerBin ?? "(not on PATH)"}`);
+ const dockerComposeCandidates = [
+ join(__dirname, "..", "docker-compose.yml"),
+ join(__dirname, "docker-compose.yml"),
+ join(process.cwd(), "docker-compose.yml"),
+ ];
+ const composeFile = dockerComposeCandidates.find((c) => existsSync(c));
+ vlog(`docker-compose.yml: ${composeFile ?? "(not found)"}`);
- if (dockerBin && dcExists) {
- const composeFile = existsSync(dockerCompose) ? dockerCompose : join(process.cwd(), "docker-compose.yml");
+ if (dockerBin && composeFile) {
const s = p.spinner();
s.start("Starting iii-engine via Docker...");
- const child = spawn(dockerBin, ["compose", "-f", composeFile, "up", "-d"], {
- detached: true,
- stdio: "ignore",
- });
- child.unref();
+ spawnEngineBackground(
+ dockerBin,
+ ["compose", "-f", composeFile, "up", "-d"],
+ "iii-engine via Docker",
+ );
s.stop("Docker compose started");
return true;
}
- const iiiPaths = [
- join(process.env["HOME"] || "", ".local", "bin", "iii"),
- "/usr/local/bin/iii",
- ];
- for (const iiiPath of iiiPaths) {
+ for (const iiiPath of fallbackIiiPaths()) {
if (existsSync(iiiPath)) {
p.log.info(`Found iii at: ${iiiPath}`);
- process.env["PATH"] = `${dirname(iiiPath)}:${process.env["PATH"]}`;
+ process.env["PATH"] = `${dirname(iiiPath)}${PATH_DELIMITER}${process.env["PATH"] ?? ""}`;
iiiBin = iiiPath;
break;
}
@@ -135,15 +208,16 @@ async function startEngine(): Promise<boolean> {
if (iiiBin && configPath) {
const s = p.spinner();
s.start(`Starting iii-engine: ${iiiBin}`);
- const child = spawn(iiiBin, ["--config", configPath], {
- detached: true,
- stdio: "ignore",
- });
- child.unref();
+ spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
s.stop("iii-engine process started");
return true;
}
+ if (!iiiBin && (!dockerBin || !composeFile)) {
+ startupFailure = { kind: "no-engine" };
+ } else if (!composeFile && dockerBin) {
+ startupFailure = { kind: "no-docker-compose" };
+ }
return false;
}
@@ -156,6 +230,44 @@ async function waitForEngine(timeoutMs: number): Promise<boolean> {
return false;
}
+function installInstructions(): string[] {
+ if (IS_WINDOWS) {
+ return [
+ "agentmemory requires the `iii-engine` runtime. Pick one:",
+ "",
+ " A) Rust toolchain (recommended):",
+ " 1. Install rustup: https://rustup.rs/",
+ " 2. Restart your shell so cargo is on PATH",
+ " 3. cargo install iii-engine",
+ "",
+ " B) Docker Desktop:",
+ " 1. Install Docker Desktop for Windows",
+ " 2. Start Docker Desktop (make sure the engine is running)",
+ " 3. Re-run: npx @agentmemory/agentmemory",
+ "",
+ "Or skip the engine entirely for standalone MCP:",
+ " npx @agentmemory/agentmemory mcp",
+ ];
+ }
+ return [
+ "agentmemory requires the `iii-engine` runtime. Pick one:",
+ "",
+ " A) cargo install iii-engine",
+ " (install rustup first if needed: https://rustup.rs/)",
+ "",
+ " B) Docker: install Docker Desktop or docker-ce, then re-run",
+ "",
+ "Or skip the engine entirely for standalone MCP:",
+ " npx @agentmemory/agentmemory mcp",
+ ];
+}
+
+function portInUseDiagnostic(port: number): string {
+ return IS_WINDOWS
+ ? ` netstat -ano | findstr :${port}`
+ : ` lsof -i :${port} # or: ss -tlnp | grep :${port}`;
+}
+
async function main() {
p.intro("agentmemory");
@@ -174,21 +286,15 @@ async function main() {
const started = await startEngine();
if (!started) {
p.log.error("Could not start iii-engine.");
- p.note(
- [
- "Install iii-engine (pick one):",
- " cargo install iii-engine",
- " See: https://iii.dev/docs",
+ const lines = installInstructions();
+ if (startupFailure?.kind === "no-docker-compose") {
+ lines.unshift(
+ "Docker is installed but docker-compose.yml is missing from this",
+ "install. Re-install with: npm install -g @agentmemory/agentmemory",
"",
- "Or use Docker:",
- " docker pull iiidev/iii:latest",
- "",
- "Docs: https://iii.dev/docs",
- "",
- "Or skip with: agentmemory --no-engine",
- ].join("\n"),
- "Setup required",
- );
+ );
+ }
+ p.note(lines.join("\n"), "Setup required");
process.exit(1);
}
@@ -199,7 +305,41 @@ async function main() {
if (!ready) {
const port = getRestPort();
s.stop("iii-engine did not become ready within 15s");
- p.log.error(`Check that ports ${port}, ${port + 1}, 49134 are available.`);
+
+ if (startupFailure?.kind === "engine-crashed" || startupFailure?.kind === "docker-crashed") {
+ p.log.error("The iii-engine process crashed on startup.");
+ if (startupFailure.binary) {
+ p.log.info(`Binary: ${startupFailure.binary}`);
+ }
+ if (startupFailure.stderr) {
+ p.note(startupFailure.stderr, "engine stderr");
+ } else {
+ p.log.info("No stderr was captured. Re-run with --verbose for more detail.");
+ }
+ p.note(
+ [
+ "Common causes:",
+ " - iii-engine version mismatch (try: cargo install iii-engine --force)",
+ " - Docker Desktop not running (if you're using the Docker path)",
+ " - Port already in use (see below)",
+ ].join("\n"),
+ "Troubleshooting",
+ );
+ } else {
+ p.log.error("The engine process started but the REST API never responded.");
+ p.note(
+ [
+ `Check whether port ${port} is already bound by another process:`,
+ portInUseDiagnostic(port),
+ "",
+ "If it is, free the port or override: agentmemory --port <N>",
+ "",
+ "If it isn't, a firewall may be blocking 127.0.0.1:" + port + ".",
+ "Re-run with --verbose to see engine stderr.",
+ ].join("\n"),
+ "Troubleshooting",
+ );
+ }
process.exit(1);
}