#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix(cli): surface real engine startup errors, Windows support (#127)
Rohit Ghumare4beb35ab9e48
diff --git a/README.md b/README.mdindex 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.tsindex 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);}