Skip to content

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

fix(install): pin iii-engine to v0.11.2 across all install paths (#260)

Rohit Ghumare3b10330c2786
diff --git a/README.md b/README.md
index 8e463090..f079c1ee 100644
--- a/README.md
+++ b/README.md
@@ -413,12 +413,15 @@ npm install && npm run build && npm start
This starts agentmemory with a local `iii-engine` if `iii` is already installed, or falls back to Docker Compose if Docker is available. REST, streams, and the viewer bind to `127.0.0.1` by default.
-Install `iii-engine` manually:
+Install `iii-engine` manually. **agentmemory currently pins `iii-engine` to `v0.11.2`** — `v0.11.6` ships a regression where engine-internal cron/http triggers fail validation and the agentmemory worker drops into an EPIPE reconnect loop. Override with `AGENTMEMORY_III_VERSION=<version>` once compat is verified manually.
-- **macOS / Linux:** `curl -fsSL https://install.iii.dev/iii/main/install.sh | sh`
-- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` from [iii-hq/iii releases](https://github.com/iii-hq/iii/releases/latest), extract `iii.exe`, add to PATH
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** swap `aarch64-apple-darwin` for `x86_64-apple-darwin`
+- **Linux x64:** swap for `x86_64-unknown-linux-gnu`
+- **Linux arm64:** swap for `aarch64-unknown-linux-gnu`
+- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` from [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2), extract `iii.exe`, add to PATH
-Or use Docker (the bundled `docker-compose.yml` pulls `iiidev/iii:latest`). Full docs: [iii.dev/docs](https://iii.dev/docs).
+Or use Docker (the bundled `docker-compose.yml` pulls `iiidev/iii:0.11.2`). Full docs: [iii.dev/docs](https://iii.dev/docs).
### Windows
@@ -427,7 +430,8 @@ agentmemory runs on Windows 10/11, but the Node.js package alone isn't enough
**Option A — Prebuilt Windows binary (recommended):**
```powershell
-# 1. Open https://github.com/iii-hq/iii/releases/latest in your browser
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
+# (we pin to v0.11.2 — v0.11.6 has a regression that breaks agentmemory)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe somewhere on PATH, or place it at:
@@ -435,6 +439,7 @@ agentmemory runs on Windows 10/11, but the Node.js package alone isn't enough
# (agentmemory checks that location automatically)
# 4. Verify:
iii --version
+# Should print: 0.11.2
# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory
diff --git a/docker-compose.yml b/docker-compose.yml
index 655deaf6..65b4b8c8 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,6 +1,14 @@
services:
iii-engine:
- image: iiidev/iii:latest
+ # Pinned to v0.11.2. v0.11.6 has a regression where engine-internal
+ # cron/http trigger registrations fail validation, causing the
+ # agentmemory worker to drop into an EPIPE reconnect loop and BM25
+ # search to return empty after save. Bump only after compat is
+ # verified end-to-end against a fresh agentmemory install.
+ #
+ # Override per-shell or via .env file:
+ # AGENTMEMORY_III_VERSION=0.11.7 docker compose up
+ image: iiidev/iii:${AGENTMEMORY_III_VERSION:-0.11.2}
ports:
- "127.0.0.1:49134:49134"
- "127.0.0.1:3111:3111"
diff --git a/src/cli.ts b/src/cli.ts
index 6548744d..eeacb583 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -18,6 +18,47 @@ const args = process.argv.slice(2);
const IS_WINDOWS = platform() === "win32";
const IS_VERBOSE = args.includes("--verbose") || args.includes("-v");
+// Pinned iii-engine version. The unpinned `install.iii.dev/iii/main/install.sh`
+// script tracks `latest`, which made every fresh agentmemory install pull
+// engine 0.11.6 — and 0.11.6 has a regression where its internal cron/http
+// trigger registrations fail validation, the worker drops into an EPIPE
+// reconnect loop, and BM25 search returns empty after save (visible to users
+// as "demo can't reach worker" and recall always-empty). Override env var
+// AGENTMEMORY_III_VERSION lets early adopters move forward when a fixed
+// engine ships, without us cutting another agentmemory release.
+const IIPINNED_VERSION =
+ process.env["AGENTMEMORY_III_VERSION"] || "0.11.2";
+
+// Map Node platform/arch → the asset name iii-hq/iii ships under
+// https://github.com/iii-hq/iii/releases/download/iii/v<version>/<asset>
+function iiiReleaseAsset(): string | null {
+ const p = platform();
+ const a = process.arch;
+ if (p === "darwin" && a === "arm64")
+ return "iii-aarch64-apple-darwin.tar.gz";
+ if (p === "darwin" && a === "x64")
+ return "iii-x86_64-apple-darwin.tar.gz";
+ if (p === "linux" && a === "x64")
+ return "iii-x86_64-unknown-linux-gnu.tar.gz";
+ if (p === "linux" && a === "arm64")
+ return "iii-aarch64-unknown-linux-gnu.tar.gz";
+ if (p === "linux" && a === "arm")
+ return "iii-armv7-unknown-linux-gnueabihf.tar.gz";
+ if (p === "win32" && a === "x64")
+ return "iii-x86_64-pc-windows-msvc.zip";
+ if (p === "win32" && a === "arm64")
+ return "iii-aarch64-pc-windows-msvc.zip";
+ return null;
+}
+
+function iiiReleaseUrl(): string | null {
+ const asset = iiiReleaseAsset();
+ if (!asset) return null;
+ // Tag name is monorepo-prefixed: `iii/v0.11.2`. Slash is URL-encoded
+ // by GitHub when serving the download path, hence `iii/v...` not `iii%2Fv...`.
+ return `https://github.com/iii-hq/iii/releases/download/iii/v${IIPINNED_VERSION}/${asset}`;
+}
+
function vlog(msg: string): void {
if (IS_VERBOSE) p.log.info(`[verbose] ${msg}`);
}
@@ -291,13 +332,14 @@ async function waitForEngine(timeoutMs: number): Promise<boolean> {
}
function installInstructions(): string[] {
+ const releaseUrl = iiiReleaseUrl();
if (IS_WINDOWS) {
return [
- "agentmemory requires the `iii-engine` runtime. Pick one:",
+ `agentmemory requires the \`iii-engine\` runtime, pinned to v${IIPINNED_VERSION}. Pick one:`,
"",
" A) Download the prebuilt Windows binary:",
- " 1. Open https://github.com/iii-hq/iii/releases/latest",
- " 2. Download iii-x86_64-pc-windows-msvc.zip",
+ ` 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`,
+ ` 2. Download iii-x86_64-pc-windows-msvc.zip`,
" (or iii-aarch64-pc-windows-msvc.zip on ARM)",
" 3. Extract iii.exe and either add its folder to PATH",
" or move it to %USERPROFILE%\\.local\\bin\\iii.exe",
@@ -305,25 +347,31 @@ function installInstructions(): string[] {
"",
" B) Docker Desktop:",
" 1. Install Docker Desktop for Windows",
- " 2. Start Docker Desktop (engine must be running)",
- " 3. Re-run: npx @agentmemory/agentmemory",
+ ` 2. docker pull iiidev/iii:${IIPINNED_VERSION}`,
+ " 3. Start Docker Desktop (engine must be running)",
+ " 4. Re-run: npx @agentmemory/agentmemory",
"",
"Or skip the engine entirely for standalone MCP:",
" npx @agentmemory/agentmemory mcp",
];
}
+ const linuxInstall = releaseUrl
+ ? ` A) mkdir -p ~/.local/bin && curl -fsSL "${releaseUrl}" | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+ : ` A) Manual download from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
return [
- "agentmemory requires the `iii-engine` runtime. Pick one:",
+ `agentmemory requires the \`iii-engine\` runtime, pinned to v${IIPINNED_VERSION}. Pick one:`,
"",
- " A) curl -fsSL https://install.iii.dev/iii/main/install.sh | sh",
- " (installs the prebuilt iii binary into ~/.local/bin/iii)",
+ linuxInstall,
+ ` (installs iii v${IIPINNED_VERSION} into ~/.local/bin/iii)`,
"",
- " B) Docker: install Docker Desktop or docker-ce, then re-run",
+ ` B) Docker: \`docker pull iiidev/iii:${IIPINNED_VERSION}\``,
"",
"Or skip the engine entirely for standalone MCP:",
" npx @agentmemory/agentmemory mcp",
"",
"Docs: https://iii.dev/docs",
+ `Why pinned: agentmemory hits a regression in iii v0.11.6. Override with`,
+ `AGENTMEMORY_III_VERSION=<version> if you've verified compat manually.`,
];
}
@@ -993,15 +1041,43 @@ async function runUpgrade() {
return process.exit(0);
}
if (upgradeEngine === true) {
- const installerOk = runCommand(
- shBin,
- ["-c", "curl -fsSL https://install.iii.dev/iii/main/install.sh | sh"],
- { label: "Upgrading iii-engine via installer", optional: true },
- );
- if (!installerOk) {
+ const releaseUrl = iiiReleaseUrl();
+ const asset = iiiReleaseAsset();
+ const isZipAsset = asset?.endsWith(".zip") === true;
+ if (!releaseUrl) {
p.log.warn(
- "iii-engine installer failed. Fallbacks: Docker (`docker pull iiidev/iii:latest`) or releases at https://github.com/iii-hq/iii/releases/latest.",
+ `iii-engine binary not available for ${platform()}/${process.arch}. Use Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`,
);
+ } else if (IS_WINDOWS || isZipAsset) {
+ // Windows ships a .zip, not a tarball, and the rest of this
+ // branch assumes sh + tar -xz + chmod. Skip the auto-installer
+ // there and point at the manual flow / Docker fallback. Same
+ // guidance as installInstructions().
+ p.log.info(
+ `Skipping auto-install on ${platform()} — the ${asset} asset isn't tar-compatible. Install manually:\n` +
+ ` 1. Download ${releaseUrl}\n` +
+ ` 2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\n` +
+ `Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
+ );
+ } else {
+ // Pinned to IIPINNED_VERSION rather than `install.iii.dev/iii/main`,
+ // which would track `latest` and re-pull the broken 0.11.6 build.
+ const homeDir = homedir();
+ const binDir = join(homeDir, ".local", "bin");
+ const installCmd = [
+ `mkdir -p "${binDir}"`,
+ `curl -fsSL "${releaseUrl}" | tar -xz -C "${binDir}"`,
+ `chmod +x "${binDir}/iii"`,
+ ].join(" && ");
+ const installerOk = runCommand(shBin, ["-c", installCmd], {
+ label: `Installing iii-engine v${IIPINNED_VERSION} (pinned)`,
+ optional: true,
+ });
+ if (!installerOk) {
+ p.log.warn(
+ `iii-engine installer failed. Fallbacks: Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`,
+ );
+ }
}
} else {
p.log.info("Skipped iii-engine installer.");
@@ -1011,8 +1087,8 @@ async function runUpgrade() {
}
if (dockerBin) {
- runCommand(dockerBin, ["pull", "iiidev/iii:latest"], {
- label: "Pulling latest iii Docker image",
+ runCommand(dockerBin, ["pull", `iiidev/iii:${IIPINNED_VERSION}`], {
+ label: `Pulling iii Docker image v${IIPINNED_VERSION} (pinned)`,
optional: true,
});
} else {