@agentmemory/agentmemory 0.9.3 → 0.9.5

package/README.md

@@ -3,12 +3,15 @@
 </p>
 
 <p align="center">
-  <strong>Your coding agent remembers everything. No more re-explaining.</strong><br/>
-  Persistent memory for Claude Code, Cursor, Gemini CLI, OpenCode, and any MCP client.
+  <strong>
+    Your coding agent remembers everything. No more re-explaining.
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong></br>
+  Persistent memory for Claude Code, Cursor, Gemini CLI, Codex CLI, pi, OpenCode, and any MCP client.
 </p>
 
 <p align="center">
-  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-825%20stars%20%2F%20110%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 825 stars / 110 forks on the gist" /></a>
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1050%20stars%20%2F%20150%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 1050 stars / 150 forks on the gist" /></a>
 </p>
 
 <p align="center">
@@ -43,7 +46,8 @@
   <a href="#how-it-works">How It Works</a> &bull;
   <a href="#mcp-server">MCP</a> &bull;
   <a href="#real-time-viewer">Viewer</a> &bull;
-  <a href="#iii-console--trace-level-engine-inspection">iii Console</a> &bull;
+  <a href="#iii-console">iii Console</a> &bull;
+  <a href="#powered-by-iii">Powered by iii</a> &bull;
   <a href="#configuration">Config</a> &bull;
   <a href="#api">API</a>
 </p>
@@ -341,7 +345,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
 <summary><b>OpenClaw (paste this prompt)</b></summary>
 
 ```
-Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 50 memory tools:
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 43 memory tools:
 
 {
   "mcpServers": {
@@ -352,7 +356,7 @@ Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separa
   }
 }
 
-Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 4-hook gateway integration, see integrations/openclaw in the agentmemory repo.
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
 ```
 
 Full guide: [`integrations/openclaw/`](integrations/openclaw/)
@@ -363,14 +367,17 @@ Full guide: [`integrations/openclaw/`](integrations/openclaw/)
 <summary><b>Hermes Agent (paste this prompt)</b></summary>
 
 ```
-Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 50 memory tools:
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 43 memory tools:
 
 mcp_servers:
   agentmemory:
     command: npx
     args: ["-y", "@agentmemory/mcp"]
 
-Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/memory/agentmemory.
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
 ```
 
 Full guide: [`integrations/hermes/`](integrations/hermes/)
@@ -386,11 +393,12 @@ Then add the MCP config for your agent:
 | Agent | Setup |
 |---|---|
 | **Cursor** | Add to `~/.cursor/mcp.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}` |
-| **OpenClaw** | Add to MCP config: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}` or use the [gateway plugin](integrations/openclaw/) |
-| **Gemini CLI** | `gemini mcp add agentmemory -- npx -y @agentmemory/mcp` |
-| **Codex CLI** | Add to `.codex/config.yaml`: `mcp_servers: {agentmemory: {command: npx, args: ["-y", "@agentmemory/mcp"]}}` |
+| **OpenClaw** | Add to MCP config: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}` or use the [memory plugin](integrations/openclaw/) |
+| **Gemini CLI** | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` |
+| **Codex CLI** | `codex mcp add agentmemory -- npx -y @agentmemory/mcp` or add `[mcp_servers.agentmemory]` to `.codex/config.toml` |
+| **pi** | Copy [`integrations/pi`](integrations/pi/) to `~/.pi/agent/extensions/agentmemory` and restart pi |
 | **OpenCode** | Add to `opencode.json`: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}` |
-| **Hermes Agent** | Add to `~/.hermes/config.yaml` or use the [memory provider plugin](integrations/hermes/) |
+| **Hermes Agent** | Add to `~/.hermes/config.yaml` with `memory.provider: agentmemory` or use the [memory provider plugin](integrations/hermes/) |
 | **Cline / Goose / Kilo Code** | Add MCP server in settings |
 | **Claude Desktop** | Add to `claude_desktop_config.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}` |
 | **Aider** | REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'` |
@@ -405,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` introduces a new sandbox-everything-via-`iii worker add` model that agentmemory hasn't been refactored for yet. Pin lifts once the refactor lands. Override with `AGENTMEMORY_III_VERSION=<version>` if you've migrated to the sandbox model 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
 
@@ -419,7 +430,9 @@ 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 until agentmemory refactors for the new sandbox
+#     model that engine v0.11.6+ requires)
 # 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:
@@ -427,6 +440,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
@@ -506,7 +520,12 @@ PostToolUse hook fires
   -> Store raw observation
   -> LLM compress -> structured facts + concepts + narrative
   -> Vector embedding (6 providers + local)
-  -> Index in BM25 + vector + knowledge graph
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
 
 SessionStart hook fires
   -> Load project profile (top concepts, files, patterns)
@@ -719,41 +738,57 @@ open http://localhost:3113
 
 The viewer server binds to `127.0.0.1` by default. The REST-served `/agentmemory/viewer` endpoint follows the normal `AGENTMEMORY_SECRET` bearer-token rules. CSP headers use a per-response script nonce and disable inline handler attributes (`script-src-attr 'none'`).
 
-### iii console — trace-level engine inspection
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-viewer.svg"><img src="assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+The viewer at `:3113` shows what your agent **remembered**. The [iii console](https://iii.dev/docs/console) shows what your agent **did** — every memory op as an OpenTelemetry trace, every KV entry editable, every function invocable, every stream tappable. Two windows on the same memory: one product-shaped, one engine-shaped.
+
+Watch a `memory_smart_search` fire and see the BM25 scan → embedding lookup → RRF fusion → reranker as a waterfall. Edit a stuck consolidation timer in the KV browser. Replay a `PostToolUse` hook with a tweaked payload. Pin the WebSocket stream and watch observations land live.
 
-agentmemory runs on the [iii engine](https://iii.dev), so the official [iii console](https://iii.dev/docs/console) gives you OpenTelemetry traces, the raw key/value state store, the stream monitor, and a direct function invoker for every piece of memory machinery. Use it to watch a `memory.search` call hit BM25 → embeddings → reranker in real time, replay a hook invocation, or poke individual functions without going through MCP.
+agentmemory ships this for free because every function, trigger, state scope, and stream is an iii primitive — nothing custom, nothing to instrument.
 
 <p align="center">
-  <img src="assets/iii-console/dashboard.png" alt="iii console dashboard — system counters, application flow, registered triggers, live WebSocket status" width="720" />
+  <img src="assets/iii-console/workers.png" alt="iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
   <br/>
-  <em>Dashboard: functions, triggers, workers, streams, live flow graph. Screenshot from <a href="https://iii.dev/docs/console">iii.dev/docs/console</a>.</em>
+  <em>Workers page: every connected worker — including agentmemory itself — with PID, function count, runtime, and last-seen.</em>
 </p>
 
-**Install once:**
+**Already installed.** The console ships with `iii` — no separate installer.
+
+**Launch alongside agentmemory:**
 
 ```bash
-curl -fsSL https://install.iii.dev/console/main/install.sh | sh
+# agentmemory viewer holds port 3113, so run the console on 3114.
+# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
+iii console --port 3114
 ```
 
-**Launch alongside agentmemory:**
+Then open `http://localhost:3114`. Add `--enable-flow` for the experimental architecture-graph page.
+
+Override engine endpoints only if you've moved them:
 
 ```bash
-# The agentmemory viewer already holds port 3113, so run the console on 3114.
-iii-console --port 3114 --engine-port 3111 --ws-port 3112
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
 ```
 
-Then open `http://localhost:3114`.
-
 **What you can do from the console:**
 
 | Page | Use it to |
 |------|-----------|
-| **Functions** | Invoke any of agentmemory's ~33 functions directly with a JSON payload — handy for testing `memory.recall`, `memory.consolidate`, `graph.query` without wiring a client. |
-| **Triggers** | Replay HTTP triggers (the agentmemory REST endpoints), fire the consolidation cron manually, or emit queue events. |
-| **States** | Browse the KV store — sessions, memory slots, lifecycle timers, embeddings index — and edit values in place. |
-| **Streams** | Watch live memory writes, hook events, and observation updates as they flow through iii's WebSocket stream. |
+| **Workers** | See every connected worker and its live metrics — including the agentmemory worker itself. |
+| **Functions** | Invoke any of agentmemory's functions directly with a JSON payload — handy for testing `memory.recall`, `memory.consolidate`, `graph.query` without wiring a client. |
+| **Triggers** | Replay HTTP, cron, event, and state triggers — fire the consolidation cron manually, retry an HTTP route, emit a state change. |
+| **States** | KV browser with full CRUD — sessions, memory slots, lifecycle timers, embeddings index — edit values in place. |
+| **Streams** | Live WebSocket monitor for memory writes, hook events, and observation updates as they flow through iii streams. |
+| **Queues** | Durable queue topics + dead-letter management. Replay or drop failed embedding / compression jobs. |
 | **Traces** | OpenTelemetry waterfall / flame / service-breakdown views. Filter by `trace_id` to see exactly which functions, DB calls, and embedding requests a single `memory.search` produced. |
-| **Logs** | Structured OTEL logs correlated to trace/span IDs. |
+| **Logs** | Structured OTEL logs filtered and correlated to trace/span IDs. |
+| **Config** | Runtime configuration — see exactly which workers, providers, and ports your engine is running with. |
+| **Flow** | (Optional, `--enable-flow`) Interactive architecture graph of every worker, trigger, and stream. |
 
 <p align="center">
   <img src="assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
@@ -771,6 +806,53 @@ If you want to export to Jaeger/Honeycomb/Grafana Tempo instead, change `exporte
 
 ---
 
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-architecture.svg"><img src="assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory is **already a running [iii](https://iii.dev) instance**. Functions, triggers, KV state, streams, OTEL traces — all of it is iii primitives. You didn't install Postgres, Redis, Express, pm2, or Prometheus, because iii replaces them.
+
+That means one more command extends agentmemory with an entire new capability.
+
+### Extend agentmemory with one command
+
+```bash
+iii worker add iii-pubsub          # fan memory writes out to every connected instance
+iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
+iii worker add iii-queue           # durable retries for embedding + compression jobs
+iii worker add iii-observability   # OTEL traces on every memory op (default on)
+iii worker add iii-sandbox         # run recalled code inside an isolated microVM
+iii worker add iii-database        # swap in a SQL-backed state adapter
+iii worker add mcp                 # generic MCP host alongside the agentmemory MCP
+```
+
+Each `iii worker add` registers new functions and triggers into the same engine agentmemory is already running on. The viewer and console pick them up immediately — no reload, no new integration, no new container.
+
+| `iii worker add` | What you get on top of agentmemory |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Multi-instance memory: every `remember` fans out, every `search` reads the union |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Scheduled lifecycle — nightly consolidation, weekly snapshots, decay on a fixed clock |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Durable retries: failed embedding + compression jobs survive restart, no lost observations |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | OTEL traces, metrics, logs on every function — wired in `iii-config.yaml` from day one |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code that came out of `memory_recall` runs inside a throwaway VM, not your shell |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | SQL-backed state adapter when you outgrow the in-memory KV defaults |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Stand up extra MCP servers next to agentmemory's, share the same engine |
+
+Full registry: [workers.iii.dev](https://workers.iii.dev). Every worker there composes through the same primitives agentmemory uses — and the agentmemory you already have is one of them.
+
+### What iii replaces
+
+| Traditional stack | agentmemory uses |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + in-memory vector index |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker supervision |
+| Prometheus / Grafana | iii OTEL + health monitor |
+| Custom plugin systems | `iii worker add <name>` |
+
+**118 source files · ~21,800 LOC · 800 tests · 123 functions · 34 KV scopes** — all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
+
+---
+
 <h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-config.svg"><img src="assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
 
 ### LLM Providers
@@ -907,25 +989,6 @@ Full endpoint list: [`src/triggers/api.ts`](src/triggers/api.ts)
 
 ---
 
-<h2 id="architecture"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-architecture.svg"><img src="assets/tags/section-architecture.svg" alt="Architecture" height="32" /></picture></h2>
-
-Built on [iii-engine](https://iii.dev)'s three primitives — no Express, no Postgres, no Redis.
-
-**118 source files · ~21,800 LOC · 800 tests · 123 functions · 34 KV scopes**
-
-<details>
-<summary>What iii-engine replaces</summary>
-
-| Traditional stack | agentmemory uses |
-|---|---|
-| Express.js / Fastify | iii HTTP Triggers |
-| SQLite / Postgres + pgvector | iii KV State + in-memory vector index |
-| SSE / Socket.io | iii Streams (WebSocket) |
-| pm2 / systemd | iii-engine worker management |
-| Prometheus / Grafana | iii OTEL + health monitor |
-
-</details>
-
 <h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-development.svg"><img src="assets/tags/section-development.svg" alt="Development" height="32" /></picture></h2>
 
 ```bash

package/dist/cli.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, readlinkSync, statSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { platform } from "node:os";
+import { homedir, platform } from "node:os";
 import * as p from "@clack/prompts";
 import { createHash } from "node:crypto";
 
@@ -81,6 +81,24 @@ 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");
+const IIPINNED_VERSION = process.env["AGENTMEMORY_III_VERSION"] || "0.11.2";
+function iiiReleaseAsset() {
+	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() {
+	const asset = iiiReleaseAsset();
+	if (!asset) return null;
+	return `https://github.com/iii-hq/iii/releases/download/iii/v${IIPINNED_VERSION}/${asset}`;
+}
 function vlog(msg) {
 	if (IS_VERBOSE) p.log.info(`[verbose] ${msg}`);
 }
@@ -98,6 +116,8 @@ Commands:
   upgrade            Upgrade local deps + iii runtime (best effort)
   mcp                Start standalone MCP server (no engine required)
   import-jsonl [p]   Import Claude Code JSONL transcripts (default: ~/.claude/projects)
+                     --max-files <N> | --max-files=<N>: override scan cap (default 200, max 1000;
+                     out-of-range is rejected; for trees >1000 files, batch by subdirectory)
 
 Options:
   --help, -h         Show this help
@@ -286,12 +306,13 @@ async function waitForEngine(timeoutMs) {
 	return false;
 }
 function installInstructions() {
+	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",
@@ -299,24 +320,31 @@ function installInstructions() {
 		"",
 		"  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"
+		"Docs: https://iii.dev/docs",
+		`Why pinned: iii v0.11.6 introduces the new sandbox-everything model`,
+		`(\`iii worker add\` registration). agentmemory still uses the older`,
+		`iii-exec config-file worker model and needs a refactor before it`,
+		`runs cleanly under the new engine. Override with`,
+		`AGENTMEMORY_III_VERSION=<version> when you've migrated manually.`
 	];
 }
 function portInUseDiagnostic(port) {
@@ -326,12 +354,12 @@ async function main() {
 	p.intro("agentmemory");
 	if (skipEngine) {
 		p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-3Snd7D3T.mjs");
+		await import("./src-xYHSzz5S.mjs");
 		return;
 	}
 	if (await isEngineRunning()) {
 		p.log.success("iii-engine is running");
-		await import("./src-3Snd7D3T.mjs");
+		await import("./src-xYHSzz5S.mjs");
 		return;
 	}
 	if (!await startEngine()) {
@@ -375,7 +403,7 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-3Snd7D3T.mjs");
+	await import("./src-xYHSzz5S.mjs");
 }
 async function apiFetch(base, path, timeoutMs = 5e3) {
 	try {
@@ -453,6 +481,42 @@ async function runStatus() {
 function formatChecks(checks) {
 	return checks.map((c) => `${c.ok ? "✓" : "✗"} ${c.name}${c.hint ? `\n   ${c.hint}` : ""}`).join("\n");
 }
+function findLatestDebugLog(debugDir) {
+	const latestLink = join(debugDir, "latest");
+	try {
+		if (existsSync(latestLink)) {
+			const target = readlinkSync(latestLink);
+			const resolved = target.startsWith("/") ? target : join(debugDir, target);
+			if (existsSync(resolved)) return resolved;
+		}
+	} catch {}
+	try {
+		const newest = readdirSync(debugDir).filter((f) => f.endsWith(".txt")).map((f) => ({
+			f,
+			m: statSync(join(debugDir, f)).mtimeMs
+		})).sort((a, b) => b.m - a.m)[0];
+		if (newest) return join(debugDir, newest.f);
+	} catch {}
+}
+function checkClaudeCodeHooks() {
+	const debugDir = join(homedir(), ".claude", "debug");
+	if (!existsSync(debugDir)) return { state: "no-cc-dir" };
+	const logPath = findLatestDebugLog(debugDir);
+	if (!logPath) return { state: "no-debug-log" };
+	let content;
+	try {
+		content = readFileSync(logPath, "utf8");
+	} catch {
+		return { state: "no-debug-log" };
+	}
+	const match = content.match(/Loaded hooks from standard location for plugin agentmemory:\s*(\S+)/);
+	if (match) return {
+		state: "loaded",
+		manifestPath: match[1]
+	};
+	if (content.includes("Loading hooks from plugin: agentmemory")) return { state: "loaded" };
+	return { state: "not-loaded" };
+}
 async function runDoctor() {
 	p.intro("agentmemory doctor");
 	const base = getBaseUrl();
@@ -499,6 +563,28 @@ async function runDoctor() {
 		ok: f.enabled,
 		hint: f.enabled ? void 0 : f.enableHow
 	});
+	const cc = checkClaudeCodeHooks();
+	const ccCheck = (() => {
+		switch (cc.state) {
+			case "loaded": return {
+				ok: true,
+				hint: cc.manifestPath ? `manifest: ${cc.manifestPath}` : void 0
+			};
+			case "not-loaded": return {
+				ok: false,
+				hint: "Plugin enabled but hooks not loaded by Claude Code. Try: /plugin uninstall agentmemory@agentmemory && /plugin install agentmemory@agentmemory, then restart the session. CC must be >= 2.1.x for plugin-hook auto-load."
+			};
+			case "no-debug-log": return {
+				ok: false,
+				hint: "Cannot verify — no Claude Code debug log found. Run once with `claude --debug -p \"x\"`, then re-run doctor."
+			};
+			case "no-cc-dir": return;
+		}
+	})();
+	if (ccCheck) checks.push({
+		name: "Claude Code plugin hooks registered",
+		...ccCheck
+	});
 	checks.push({
 		name: "Knowledge graph populated",
 		ok: graphHas,
@@ -600,6 +686,8 @@ async function seedDemoSession(base, project, session) {
 		const payload = {
 			hookType: "post_tool_use",
 			sessionId: session.id,
+			project,
+			cwd: project,
 			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 			data: {
 				tool_name: obs.toolName,
@@ -744,14 +832,26 @@ async function runUpgrade() {
 			return process.exit(0);
 		}
 		if (upgradeEngine === true) {
-			if (!runCommand(shBin, ["-c", "curl -fsSL https://install.iii.dev/iii/main/install.sh | sh"], {
-				label: "Upgrading iii-engine via installer",
-				optional: true
-			})) 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.");
+			const releaseUrl = iiiReleaseUrl();
+			const asset = iiiReleaseAsset();
+			const isZipAsset = asset?.endsWith(".zip") === true;
+			if (!releaseUrl) p.log.warn(`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) 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)\nOr use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`);
+			else {
+				const binDir = join(homedir(), ".local", "bin");
+				if (!runCommand(shBin, ["-c", [
+					`mkdir -p "${binDir}"`,
+					`curl -fsSL "${releaseUrl}" | tar -xz -C "${binDir}"`,
+					`chmod +x "${binDir}/iii"`
+				].join(" && ")], {
+					label: `Installing iii-engine v${IIPINNED_VERSION} (pinned)`,
+					optional: true
+				})) 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.");
 	} else p.log.warn("curl or sh not found. Skipping iii-engine installer.");
-	if (dockerBin) runCommand(dockerBin, ["pull", "iiidev/iii:latest"], {
-		label: "Pulling latest iii Docker image",
+	if (dockerBin) runCommand(dockerBin, ["pull", `iiidev/iii:${IIPINNED_VERSION}`], {
+		label: `Pulling iii Docker image v${IIPINNED_VERSION} (pinned)`,
 		optional: true
 	});
 	else p.log.info("Docker not found. Skipping Docker image refresh.");
@@ -765,10 +865,38 @@ async function runUpgrade() {
 	].join("\n"), "agentmemory upgrade");
 }
 async function runMcp() {
-	await import("./standalone-BG9uPsDK.mjs");
+	await import("./standalone-BvKacAId.mjs");
 }
 async function runImportJsonl() {
-	const pathArg = args.slice(1).filter((a) => !a.startsWith("-"))[0];
+	const VALUE_FLAGS = new Set(["--port", "--tools"]);
+	let maxFiles;
+	const tail = args.slice(1);
+	const positional = [];
+	for (let i = 0; i < tail.length; i++) {
+		const a = tail[i];
+		if (a === "--max-files") {
+			const raw = tail[i + 1];
+			const parsed = raw !== void 0 ? parseInt(raw, 10) : NaN;
+			if (Number.isInteger(parsed) && parsed > 0) maxFiles = parsed;
+			else if (raw !== void 0) p.log.warn(`Ignoring --max-files ${raw}: expected a positive integer.`);
+			i++;
+			continue;
+		}
+		if (a.startsWith("--max-files=")) {
+			const raw = a.slice(12);
+			const parsed = parseInt(raw, 10);
+			if (Number.isInteger(parsed) && parsed > 0) maxFiles = parsed;
+			else p.log.warn(`Ignoring --max-files=${raw}: expected a positive integer.`);
+			continue;
+		}
+		if (VALUE_FLAGS.has(a)) {
+			i++;
+			continue;
+		}
+		if (a.startsWith("-")) continue;
+		positional.push(a);
+	}
+	const pathArg = positional[0];
 	const port = getRestPort();
 	const base = `http://localhost:${port}`;
 	let probeOk = false;
@@ -790,6 +918,7 @@ async function runImportJsonl() {
 	}
 	const body = {};
 	if (pathArg) body["path"] = pathArg;
+	if (maxFiles !== void 0) body["maxFiles"] = maxFiles;
 	const headers = { "content-type": "application/json" };
 	const secret = process.env["AGENTMEMORY_SECRET"];
 	if (secret) headers["authorization"] = `Bearer ${secret}`;
@@ -821,6 +950,17 @@ async function runImportJsonl() {
 			process.exit(1);
 		}
 		spinner.stop(`imported ${json.imported ?? 0} file(s), ${json.observations ?? 0} observation(s) across ${json.sessionIds?.length || 0} session(s)`);
+		if (json.truncated) {
+			const cap = json.maxFiles ?? 200;
+			const upper = json.maxFilesUpperBound ?? 1e3;
+			const discovered = json.discovered ?? 0;
+			const baseMsg = `Hit the ${cap}-file scan cap; ${discovered - (json.imported ?? 0)} of ${json.traversalCapped ? `${discovered}+ (traversal halted at safety cap)` : String(discovered)} discovered file(s) were skipped.`;
+			if (discovered > upper || json.traversalCapped) p.log.warn(`${baseMsg} Tree exceeds the server's --max-files limit of ${upper}; batch by subdirectory (run import-jsonl once per project under ~/.claude/projects).`);
+			else {
+				const suggested = Math.min(Math.max((discovered || cap) + 100, cap * 2), upper);
+				p.log.warn(`${baseMsg} Re-run with --max-files=${suggested} (max ${upper}) or batch by subdirectory.`);
+			}
+		}
 		if (json.sessionIds && json.sessionIds.length > 0) p.log.info(`View at ${getViewerUrl()} → Replay tab`);
 	} catch (err) {
 		spinner.stop("failed");