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

[rohitg00]

Why

iii-engine v0.11.6 ships a regression where its internal cron/http trigger registrations fail the engine's own new validators at boot. Result for end users: every fresh agentmemory install pulls v0.11.6 (because all paths resolve latest / main), and the worker drops into an EPIPE reconnect loop. memory_save returns 200 with a memory ID, but memory_smart_search and memory_recall always return empty

Reproducer (verified locally on macOS arm64 with iii v0.11.6):

$ curl -X POST :3111/agentmemory/remember -d '{"content":"alpha bravo","type":"fact"}'
{"success":true,"memory":{"id":"mem_..."}}

$ curl -X POST :3111/agentmemory/search -d '{"query":"alpha bravo"}'
{"format":"full","results":[],"tokens_used":0}     # broken

Engine boot log:

[ERROR] iii::workers::cron::cron Cron expression is not set for trigger 2e5afd82-...
[ERROR] iii::trigger Error registering trigger — error: Cron expression is required
[ERROR] iii::trigger Error registering trigger — error: api_path is required for http triggers
[ERROR] agentmemory [iii] Failed to send message: write EPIPE   # ~10/sec, indefinitely

The trigger UUIDs are stable across fresh state dirs — these are the engine's own internal registrations failing its own new validation, not anything agentmemory registers.

What changes

Until the engine fix lands upstream, every agentmemory install path now resolves to v0.11.2 (last known-good engine version):

Path	Before	After
src/cli.ts auto-installer	curl install.iii.dev/iii/main/install.sh | sh (tracks latest)	curl github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-<arch>.tar.gz | tar -xz -C ~/.local/bin
src/cli.ts Docker fallback	docker pull iiidev/iii:latest	docker pull iiidev/iii:0.11.2
src/cli.ts install instructions	linked releases/latest	link releases/tag/iii%2Fv0.11.2
docker-compose.yml	image: iiidev/iii:latest	image: iiidev/iii:0.11.2
README.md install section	one-liner curl pipe	per-arch tarball commands + pin rationale

Escape hatch

AGENTMEMORY_III_VERSION=0.11.7 npx @agentmemory/agentmemory upgrade

Lets early adopters pull a newer engine when one ships, without us cutting another agentmemory release. Default stays pinned.

What's NOT in this PR

• No engine version bump path automation. When the engine fix ships (likely v0.11.7), bump IIPINNED_VERSION in src/cli.ts, the README, and docker-compose.yml and ship a follow-up.
• No iii-sdk pin change. The npm SDK doesn't break — the engine binary does.

Test plan

• Type-check clean (npx tsc --noEmit — no new errors from changed files).
• Build clean (npm run build).
• Verified the pinned tarball URL resolves and extracts a working binary:

  $ /tmp/iii --version
  0.11.2
  

• dist contains only pinned URLs — grep finds no leftover iiidev/iii:latest or install.iii.dev/iii/main/install.sh.
• CI on this PR (Vercel preview deploy will fail with the usual "Authorization required" — known limitation on forks, ignore).

Follow-up

File against iii-hq/iii for the engine-internal trigger validation regression. Smoking gun: engine rejects its own cron triggers at UUIDs 2e5afd82-... and 00c616c5-... that are stable across fresh state — these are hardcoded in the engine, not user-registered. Worth flagging upstream so the fix lands and we can unpin.

Summary by CodeRabbit

• Documentation

  • Improved installation instructions with platform-specific download steps and explicit verification of the pinned runtime (v0.11.2).
  • Documented a v0.11.6 regression and how to override the pinned version via an environment variable.

• New Features

  • CLI now installs/upgrades using the pinned runtime release and reports fallbacks when pinned assets aren’t available.

• Chores

  • Container configuration and install guidance updated to use the pinned engine version.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentmemory	Ready	Preview, Comment	May 9, 2026 3:07pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1aa3f73d-e9a5-41bb-953c-1ee83ee30465

📥 Commits

Reviewing files that changed from the base of the PR and between f04f53f and da272c4.

📒 Files selected for processing (3)

• README.md
• docker-compose.yml
• src/cli.ts

✅ Files skipped from review due to trivial changes (2)

• docker-compose.yml
• README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• src/cli.ts

---

📝 Walkthrough

Walkthrough

This PR pins the iii-engine runtime to v0.11.2 across CLI installation/upgrade flows, README documentation, and docker-compose; adds platform-aware GitHub asset selection and a AGENTMEMORY_III_VERSION override; and documents a v0.11.6 regression.

Changes

iii-engine Version Pinning

Layer / File(s)	Summary
Version Configuration and Platform Mapping src/cli.ts	Introduces IIPINNED_VERSION constant (default 0.11.2), environment override via AGENTMEMORY_III_VERSION, and helper functions that map the current OS/CPU architecture to GitHub release asset names and construct pinned download URLs.
Installation Documentation and CLI Guidance README.md, src/cli.ts	README.md and installInstructions() now document pinned v0.11.2 installation with a v0.11.6 regression warning, optional override env var, and platform-specific download links pointing to the pinned GitHub release instead of the generic install script or latest tag.
Docker Service Configuration docker-compose.yml	The iii-engine service image is pinned to iiidev/iii:${AGENTMEMORY_III_VERSION:-0.11.2} instead of latest, with inline comments explaining the v0.11.6 regression and when the image tag should be bumped.
Upgrade Command Implementation src/cli.ts	The upgrade command now constructs pinned release URLs, skips auto-install for non-tar/Windows zip assets, downloads/extracts pinned tarballs into ~/.local/bin when available, logs fallbacks to Docker/manual when unavailable, and pulls the pinned Docker image tag during refresh.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• rohitg00/agentmemory#174: Modifies src/cli.ts upgrade/install behavior; related to installer flow changes.
• rohitg00/agentmemory#128: Updates CLI installation/upgrade logic and README install instructions in the same areas.
• rohitg00/agentmemory#175: Related CLI install/upgrade hardening; touches similar upgrade paths.

Poem

🐰 I pin the engine, neat and small,

v0.11.2 stands firm for all.
Downloads suited to each OS and arch,
Warnings tucked in the README’s march,
A rabbit hops forward—no more “latest” fall.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the primary change: pinning iii-engine to v0.11.2 across all install paths. It is directly supported by changes across README.md, docker-compose.yml, and src/cli.ts.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/pin-iii-engine-0.11.2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docker-compose.yml`:
- Line 8: The docker-compose image is hardcoded to iiidev/iii:0.11.2 so
AGENTMEMORY_III_VERSION is ignored; change the image line to reference the
environment variable (e.g. image: iiidev/iii:${AGENTMEMORY_III_VERSION:-0.11.2})
so AGENTMEMORY_III_VERSION can override the tag while preserving the current
default, and ensure the variable is documented or provided via .env or
environment when running the compose command.

In `@src/cli.ts`:
- Around line 358-365: The current linuxInstall command (constructed where
releaseUrl is used to build the one-liner in cli.ts) pipes curl into tar but
doesn't ensure ~/.local/bin exists; update the template string referenced by
linuxInstall so it first creates the directory (e.g., prepend "mkdir -p
~/.local/bin &&") before the tar extraction and keep the existing chmod step and
use of IIPINNED_VERSION and releaseUrl unchanged; ensure both the
releaseUrl-true branch (the curl|tar one-liner) and any place that constructs
the same install string use the mkdir -p addition.
- Around line 1044-1066: The Windows ZIP asset is being piped into tar -xz and
chmod'd which will fail; update the installer branch in the iiiReleaseUrl()
handling to detect Windows (platform() or process.platform === 'win32') or the
asset suffix (iiiReleaseAsset() endsWith ".zip") and either skip the tarball
installer on Windows (fall back to Docker/manual instructions) or run a
ZIP-aware install flow: fetch the .zip, extract the iii.exe (or rename it) into
the binDir (instead of using tar and chmod), and ensure the code paths using
homedir(), binDir, installCmd, runCommand, shBin and IIPINNED_VERSION handle the
alternate zip/unzip command or skip gracefully so Windows users do not hit the
tar-based failure.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2e1fb810-cb62-443e-8aff-d72c6294231e

📥 Commits

Reviewing files that changed from the base of the PR and between 1a03538 and f04f53f.

📒 Files selected for processing (3)

• README.md
• docker-compose.yml
• src/cli.ts

[rohitg00]

Pushed da272c4 to address all three findings.

#	Finding	Verdict	Fix
1	docker-compose hardcoded 0.11.2, ignored AGENTMEMORY_III_VERSION	Valid	image: iiidev/iii:\${AGENTMEMORY_III_VERSION:-0.11.2} — escape hatch now actually works for compose users
2	Displayed Linux install command lacked mkdir -p ~/.local/bin	Valid (display-only)	Prepended to installInstructions() linuxInstall and to README per-arch lines. The programmatic runUpgrade install path already had mkdir -p "${binDir}" at line 1055, no change needed there
3	Windows ZIP piped through tar -xz would fail	Valid	Added IS_WINDOWS || isZipAsset guard before the tarball branch — logs manual-install + Docker-fallback guidance instead, mirrors what installInstructions() already shows for Windows

Skipped: none — all three were valid as written.

Validation

• npx tsc --noEmit — no new errors from changed files (the one remaining port unused is pre-existing on main).
• npm run build clean.
• Compose interpolation verified end-to-end:

  $ AGENTMEMORY_III_VERSION=0.11.7 docker compose config | grep image:
      image: iiidev/iii:0.11.7
  
  $ docker compose config | grep image:
      image: iiidev/iii:0.11.2
  

PR head: da272c4. Ready for re-review / merge.