What causes "iii-engine binary not found locally." in rohitg00/agentmemory?

Answer the prompt with "install" (recommended) to install iii v (~6MB, ~5s) to ~/.agentmemory/bin.

iii-engine binary not found locally.

Error message

iii-engine binary not found locally.

What it means

When the CLI needs the pinned iii-engine but finds no local binary, it decides what to do based on interactivity: non-interactive environments auto-install silently, but in an interactive TTY it warns "iii-engine binary not found locally." and presents a prompt offering to install the pinned version to ~/.agentmemory/bin (leaving any user-managed iii untouched). This is the warning printed just before that interactive prompt.

Source

Thrown at src/cli.ts:1707

  // Wrong-version iii on PATH is a configuration trap: any prompt would
  // confuse the user since they already "have iii installed". Skip the
  // prompt and auto-install pinned engine to the private location.
  const pathIiiMismatch = pathIii !== null && resolveCompatibleIii(pathIii) === null;

  if (dockerOptIn && dockerBin && composeFile) {
    choice = "docker";
  } else if (pathIiiMismatch) {
    choice = "install";
    const detected = iiiBinVersion(pathIii!);
    p.log.info(
      `iii on PATH is v${detected ?? "unknown"} but agentmemory pins v${IIPINNED_VERSION}. ` +
        `Installing pinned engine to ~/.agentmemory/bin (leaves your existing iii untouched).`,
    );
  } else if (!interactive) {
    choice = "install";
    p.log.info("Non-interactive environment detected — auto-installing iii-engine.");
  } else {
    p.log.warn(`iii-engine binary not found locally.`);
    const options: { value: Choice; label: string; hint?: string }[] = [
      {
        value: "install",
        label: `Install iii v${IIPINNED_VERSION} to ~/.agentmemory/bin (~6MB, ~5s)`,
        hint: "recommended",
      },
    ];
    if (dockerBin && composeFile) {
      options.push({ value: "docker", label: "Use Docker compose", hint: "advanced" });
    }
    options.push({ value: "manual", label: "Show manual install steps and exit" });

    const picked = await p.select<Choice>({
      message: "How would you like to start iii-engine?",
      options,
      initialValue: "install",
    });
    if (p.isCancel(picked)) {

View on GitHub (pinned to e04ba88819)

Solutions

Answer the prompt with "install" (recommended) to install iii v<pinned> (~6MB, ~5s) to ~/.agentmemory/bin.
If you already manage iii yourself, choose the option to use your existing binary — though the hard-pinned version must match.
Pre-install manually: `npm install -g @agentmemory/agentmemory` setups or download from the iii GitHub releases and put it on PATH.
Re-run `agentmemory start`; after installation the warning disappears.

Example fix

// before: fresh machine, no engine
$ agentmemory start  # iii-engine binary not found locally.
// after: accept recommended install
? Choose: Install iii v<pinned> to ~/.agentmemory/bin (recommended)  ✔

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from "node:fs";
import { execFileSync } from "node:child_process";
function engineAvailable(): boolean {
  try { execFileSync("which", ["iii"], { stdio: "ignore" }); return true; } catch {}
  return existsSync(join(homedir(), ".agentmemory", "bin"));
}
if (!engineAvailable()) console.warn("Run `agentmemory start` interactively once to install the engine.");

Try / catch

try {
  await startEngine();
} catch (e) {
  if (String(e).includes("iii-engine")) {
    console.error("Engine missing; run `agentmemory start` in a TTY and choose install.");
  } else throw e;
}

Prevention

Run `agentmemory start` once interactively on a new machine to install the pinned engine.
Avoid deleting ~/.agentmemory/bin when cleaning state.
In CI, rely on the non-interactive auto-install path or pre-install the engine in the image.
If you manage iii yourself, ensure its version matches the pin the CLI enforces.

When it happens

Trigger: Engine detection finds no iii-engine binary (neither on PATH nor at the private ~/.agentmemory/bin path) and the process is interactive — typically the first `agentmemory start` on a fresh machine, or after the private install was deleted.

Common situations: Fresh developer workstations; containers without the engine; users who cleared ~/.agentmemory; switching machines or profiles; CI environments that skipped the non-interactive auto-install flag.

Related errors

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/4d0e66c9d993a490. Report an issue: GitHub.