Skip to content

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

CLI onboarding UX, colored output, build + docs cleanup (#984)

Rohit Ghumare93ae9bc04f3a
diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md
index 981c3893..f368220b 100644
--- a/INSTALL_FOR_AGENTS.md
+++ b/INSTALL_FOR_AGENTS.md
@@ -12,7 +12,7 @@ Default mode needs no API key and no cloud account. Out of the box it runs hybri
- Node.js >= 20 and npm. Check with `node -v`.
- macOS or Linux for the one-command path. On Windows, use WSL2; native Windows engine setup is manual and `agentmemory connect` is not supported there.
-- Ports 3111 (REST), 3112 (streams), 3113 (viewer), and 49134 (engine) free. Override the whole block with `--port <N>` or `--instance <N>` if any are taken.
+- Ports 3111 (REST), 3112 (streams), 3113 (viewer), and 49134 (engine) free. If any are taken, stop whatever is using them before starting (see Troubleshooting).
## Running non-interactively
@@ -24,7 +24,7 @@ Several commands prompt on a TTY (for example the first-run "install globally?"
npm install -g @agentmemory/agentmemory
```
-If you hit `EACCES` on a system Node install (macOS/Linux), retry with `sudo npm install -g @agentmemory/agentmemory`.
+`npm install -g` already fetches the latest published release. If you hit `EACCES` on a system Node install (macOS/Linux), retry with `sudo npm install -g @agentmemory/agentmemory`.
No-install alternative: skip this step and run the server with `npx -y @agentmemory/agentmemory@latest` everywhere this runbook says `agentmemory`. The `@latest` and `-y` flags matter because npx caches per version and a bare `npx @agentmemory/agentmemory` can serve a stale release.
@@ -46,7 +46,7 @@ The server listens on port 3111 and auto-starts its pinned iii engine on first r
agentmemory &
```
-Or in a dedicated terminal, run `agentmemory` in the foreground. To run a second isolated instance, use `agentmemory --instance 1` (relocates the whole port block to 3211/3212/3213/49234).
+Or run `agentmemory` in the foreground in a dedicated terminal.
Wait until it is reachable, then continue:
@@ -144,9 +144,10 @@ The MCP server exposes 53 tools by default (`--tools all`). Use `--tools core` (
- `command not found: agentmemory`: the global bin is not on `PATH`. Use `npx -y @agentmemory/agentmemory@latest`.
- `EACCES` during global install: retry with `sudo`, or use the npx form.
- Stale npx version: run `npx -y @agentmemory/agentmemory@latest`, or clear the cache with `rm -rf ~/.npm/_npx` (macOS/Linux).
-- Port already in use: another instance or process holds 3111. Stop it, or relocate with `agentmemory --instance 1`.
+- Port already in use: another process holds 3111, 3112, 3113, or 49134. Stop that process, then re-run.
- Server starts but `livez` never returns 200: re-run with `agentmemory --verbose` to see engine stderr.
- Engine version warning on start: harmless. agentmemory uses its own pinned engine in `~/.agentmemory/bin` regardless of any `iii` on `PATH`. Set `AGENTMEMORY_III_VERSION` only to override deliberately.
+- "engine conflict" / another iii engine already running: if a different iii version is already serving the port (common if you run your own iii), agentmemory will not adopt it and stops with an "engine conflict" note. Stop that engine (`agentmemory stop --force`, or however you started it), then re-run `agentmemory` — it installs and runs the pinned engine in `~/.agentmemory/bin`, leaving your own iii untouched.
- Only 7 tools visible in the agent: the MCP shim is in local fallback because it could not reach a server. Start `npx @agentmemory/agentmemory` and ensure `AGENTMEMORY_URL` points at it (default `http://localhost:3111`), then reload MCP.
- Windows: use WSL2 for the path above. Native Windows runs the server but `connect` and the automated engine install are not supported.
diff --git a/README.md b/README.md
index c4ec2c1e..d04da371 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/mcp"><img src="https://img.shields.io/npm/dm/@agentmemory/mcp?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -94,7 +93,7 @@ Fastest path if you use a coding agent: hand it this one instruction and it inst
On Windows the fast path is WSL2. Native Windows engine setup is manual (about 10 to 20 minutes) and `agentmemory connect` is currently unsupported there. See the [Windows notes](#windows) below for the step-by-step.
```bash
-npm install -g @agentmemory/agentmemory # once — bare `agentmemory` on PATH
+npm install -g @agentmemory/agentmemory # once — bare `agentmemory` on PATH
# If you hit EACCES on macOS/Linux system Node installs, retry with:
# sudo npm install -g @agentmemory/agentmemory
agentmemory # start the memory server on :3111
@@ -112,6 +111,8 @@ npx @agentmemory/agentmemory
Heads-up — npx caches per version. If a bare `npx @agentmemory/agentmemory` serves an older release, force the latest with `npx -y @agentmemory/agentmemory@latest`, or clear the cache once with `rm -rf ~/.npm/_npx` (macOS/Linux; on Windows delete `%LOCALAPPDATA%\npm-cache\_npx`). The first npx run from v0.9.16+ prompts to install globally inline so the bare `agentmemory` command works everywhere afterwards.
+Already running your own `iii` engine? agentmemory pins iii-engine v0.11.2 and won't attach to a different version (the worker can't speak another engine's protocol). Stop the other engine, then run `npx -y @agentmemory/agentmemory@latest` — it installs and runs the pinned v0.11.2 in `~/.agentmemory/bin`, leaving your own `iii` untouched.
+
Full options at [Quick Start](#quick-start) below. Agent-specific wiring at [Works with every agent](#works-with-every-agent).
---
@@ -506,7 +507,7 @@ Use the maintenance command when you intentionally want to update your local run
npx @agentmemory/agentmemory upgrade
```
-Warning: this command mutates the current workspace/runtime. It can update JavaScript dependencies, may run `cargo install iii-engine --force`, and may pull Docker images.
+Warning: this command mutates the current workspace/runtime. It can update JavaScript dependencies and pull the pinned `iiidev/iii:0.11.2` Docker image. It never installs an unpinned or newer iii engine.
Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cli.ts:544-595` region).
@@ -518,7 +519,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Claude Code without the plugin install (MCP-standalone path)
-If you wire agentmemory's MCP server through `~/.claude.json` directly instead of using `/plugin install`, Claude Code never resolves `${CLAUDE_PLUGIN_ROOT}` and you have to point hook scripts at absolute paths in `~/.claude/settings.json`. Those paths typically embed the agentmemory version (e.g. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), so the next upgrade silently breaks every hook ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+If you wire agentmemory's MCP server through `~/.claude.json` directly instead of using `/plugin install`, Claude Code never resolves `${CLAUDE_PLUGIN_ROOT}` and you have to point hook scripts at absolute paths in `~/.claude/settings.json`. Those paths typically embed the agentmemory version (e.g. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), so the next upgrade silently breaks every hook.
Workaround:
@@ -684,7 +685,7 @@ The agentmemory entry is the **same MCP server block** across every host that us
| **Aider** | n/a | Talk to the REST API directly: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Any agent (32+)** | n/a | `npx skillkit install agentmemory` auto-detects the host and merges. |
-**Sandboxed MCP clients** (Flatpak / Snap / restrictive containers) that can't reach the host's `localhost`: also set `"AGENTMEMORY_FORCE_PROXY": "1"` in the `env` block, and point `AGENTMEMORY_URL` at a route the sandbox can actually reach (e.g. your LAN IP). See [#234](https://github.com/rohitg00/agentmemory/issues/234) for the diagnostic walkthrough.
+**Sandboxed MCP clients** (Flatpak / Snap / restrictive containers) that can't reach the host's `localhost`: also set `"AGENTMEMORY_FORCE_PROXY": "1"` in the `env` block, and point `AGENTMEMORY_URL` at a route the sandbox can actually reach (e.g. your LAN IP).
### Programmatic access (Python / Rust / Node)
@@ -778,7 +779,7 @@ npx -y @agentmemory/mcp
| 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) |
-> Note: there is no `cargo install iii-engine` — `iii` is not published to crates.io. The only supported install methods are the prebuilt binary above, the upstream `sh` install script (macOS/Linux only), and the Docker image.
+> Note: the iii **engine** is a prebuilt binary, not a cargo crate — don't try to `cargo install` it. (The iii **SDKs** are published on crates.io, npm, and PyPI, but agentmemory doesn't need them.) Supported engine install methods, all pinned to v0.11.2: the prebuilt v0.11.2 binary above, the upstream sh install script **with the version pin** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux), and the Docker image `iiidev/iii:0.11.2`. A bare `install.sh | sh` installs the **latest** engine, which agentmemory does not support — always pass `VERSION=0.11.2`. Easiest of all: just run `npx @agentmemory/agentmemory`, which fetches the pinned engine into `~/.agentmemory/bin` for you.
---
@@ -1229,7 +1230,7 @@ agentmemory auto-detects from your environment. By default, no LLM calls are mad
| OpenRouter | `OPENROUTER_API_KEY` | Any model |
| OpenAI API | `OPENAI_API_KEY` | Default `gpt-4o-mini`, override with `OPENAI_MODEL` |
| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) or `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=<your model>` | Anything OpenAI-API-compatible. Zero cost, runs on your hardware. See [Local models](#local-models-ollama-lm-studio-vllm) below. |
-| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in only. Spawns `@anthropic-ai/claude-agent-sdk` sessions — used to cause unbounded Stop-hook recursion (#149 follow-up) so it is no longer the default. |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in only. Spawns `@anthropic-ai/claude-agent-sdk` sessions — used to cause unbounded Stop-hook recursion so it is no longer the default. |
### Local models (Ollama / LM Studio / vLLM)
@@ -1344,7 +1345,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` reaps both the worker and the engine pidfile cleanly on graceful shutdown (#640, #474). The manual cleanup above is only for the post-crash case where neither pidfile is left behind.
+`agentmemory stop` reaps both the worker and the engine pidfile cleanly on graceful shutdown. The manual cleanup above is only for the post-crash case where neither pidfile is left behind.
### Config File
@@ -1409,7 +1410,7 @@ Create `~/.agentmemory/.env`:
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1443,7 +1444,7 @@ Create `~/.agentmemory/.env`:
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1465,7 +1466,7 @@ Create `~/.agentmemory/.env`:
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.de-DE.md b/READMEs/README.de-DE.md
index 1dc2b525..8d92f8af 100644
--- a/READMEs/README.de-DE.md
+++ b/READMEs/README.de-DE.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ Verwenden Sie den Wartungsbefehl, wenn Sie Ihr lokales Runtime bewusst aktualisi
npx @agentmemory/agentmemory upgrade
```
-Achtung: Dieser Befehl verändert den aktuellen Workspace/Runtime. Er kann JavaScript-Abhängigkeiten aktualisieren, ggf. `cargo install iii-engine --force` ausführen und Docker-Images ziehen.
+Achtung: Dieser Befehl verändert den aktuellen Workspace/Runtime. Er kann JavaScript-Abhängigkeiten aktualisieren und das gepinnte Docker-Image `iiidev/iii:0.11.2` ziehen. Er installiert niemals eine ungepinnte oder neuere iii-Engine.
Implementierungsdetails in `src/cli.ts` (siehe `runUpgrade` rund um den Bereich `src/cli.ts:544-595`).
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Claude Code ohne Plugin-Installation (MCP-Standalone-Pfad)
-Wenn Sie den MCP-Server von agentmemory direkt über `~/.claude.json` verdrahten anstatt über `/plugin install`, löst Claude Code `${CLAUDE_PLUGIN_ROOT}` niemals auf, und Sie müssen Hook-Skripte in `~/.claude/settings.json` auf absolute Pfade zeigen lassen. Diese Pfade enthalten typischerweise die agentmemory-Version (z. B. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), sodass das nächste Upgrade jeden Hook stillschweigend bricht ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+Wenn Sie den MCP-Server von agentmemory direkt über `~/.claude.json` verdrahten anstatt über `/plugin install`, löst Claude Code `${CLAUDE_PLUGIN_ROOT}` niemals auf, und Sie müssen Hook-Skripte in `~/.claude/settings.json` auf absolute Pfade zeigen lassen. Diese Pfade enthalten typischerweise die agentmemory-Version (z. B. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), sodass das nächste Upgrade jeden Hook stillschweigend bricht.
Workaround:
@@ -562,7 +561,7 @@ Der agentmemory-Eintrag ist der **gleiche MCP-Server-Block** für jeden Host, de
| **Aider** | n/v | Sprechen Sie direkt mit der REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Jeder Agent (32+)** | n/v | `npx skillkit install agentmemory` erkennt den Host automatisch und merged. |
-**MCP-Clients in Sandboxen** (Flatpak / Snap / restriktive Container), die den `localhost` des Hosts nicht erreichen können: Setzen Sie zusätzlich `"AGENTMEMORY_FORCE_PROXY": "1"` im `env`-Block und lassen Sie `AGENTMEMORY_URL` auf eine Route zeigen, die die Sandbox tatsächlich erreichen kann (z. B. Ihre LAN-IP). Siehe [#234](https://github.com/rohitg00/agentmemory/issues/234) für den Diagnose-Walkthrough.
+**MCP-Clients in Sandboxen** (Flatpak / Snap / restriktive Container), die den `localhost` des Hosts nicht erreichen können: Setzen Sie zusätzlich `"AGENTMEMORY_FORCE_PROXY": "1"` im `env`-Block und lassen Sie `AGENTMEMORY_URL` auf eine Route zeigen, die die Sandbox tatsächlich erreichen kann (z. B. Ihre LAN-IP).
### Programmatischer Zugriff (Python / Rust / Node)
@@ -656,7 +655,7 @@ npx -y @agentmemory/mcp
| Port-Konflikt | `netstat -ano \| findstr :3111`, um zu sehen, was gebunden ist, dann beenden oder `--port <N>` verwenden |
| Docker-Fallback wird übersprungen, obwohl Docker installiert ist | Stellen Sie sicher, dass Docker Desktop tatsächlich läuft (Taskleisten-Icon) |
-> Hinweis: Es gibt kein `cargo install iii-engine` — `iii` ist nicht auf crates.io veröffentlicht. Die einzigen unterstützten Installationsmethoden sind das vorgebaute Binary oben, das Upstream-`sh`-Installationsskript (nur macOS/Linux) und das Docker-Image.
+> Hinweis: Die iii-**Engine** ist ein vorgebautes Binary, kein Cargo-Crate — versuche nicht, sie per `cargo install` zu installieren. (Die iii-**SDKs** sind auf crates.io, npm und PyPI veröffentlicht, aber agentmemory benötigt sie nicht.) Unterstützte Engine-Installationsmethoden, alle auf v0.11.2 gepinnt: das vorgebaute v0.11.2-Binary oben, das Upstream-`sh`-Installationsskript **mit dem Versions-Pin** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) und das Docker-Image `iiidev/iii:0.11.2`. Ein bloßes `install.sh | sh` installiert die **neueste** Engine, die agentmemory nicht unterstützt — übergib immer `VERSION=0.11.2`. Am einfachsten von allen: Führe einfach `npx @agentmemory/agentmemory` aus, das die gepinnte Engine für dich nach `~/.agentmemory/bin` holt.
---
@@ -1105,7 +1104,7 @@ agentmemory erkennt aus Ihrer Umgebung automatisch. Standardmäßig werden keine
| MiniMax | `MINIMAX_API_KEY` | Anthropic-kompatibel |
| Gemini | `GEMINI_API_KEY` | Aktiviert zusätzlich Embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | Beliebiges Modell |
-| Claude-Abonnement-Fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Nur als Opt-in. Startet `@anthropic-ai/claude-agent-sdk`-Sessions — verursachte früher unbegrenzte Stop-Hook-Rekursion (Folge von #149), daher nicht mehr Standard. |
+| Claude-Abonnement-Fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Nur als Opt-in. Startet `@anthropic-ai/claude-agent-sdk`-Sessions — verursachte früher unbegrenzte Stop-Hook-Rekursion, daher nicht mehr Standard. |
### Kostenbewusste Modellwahl
@@ -1176,7 +1175,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` räumt sowohl den Worker als auch das Engine-Pidfile bei einem geordneten Shutdown sauber auf (#640, #474). Das manuelle Cleanup oben ist nur für den Post-Crash-Fall nötig, in dem kein Pidfile zurückbleibt.
+`agentmemory stop` räumt sowohl den Worker als auch das Engine-Pidfile bei einem geordneten Shutdown sauber auf. Das manuelle Cleanup oben ist nur für den Post-Crash-Fall nötig, in dem kein Pidfile zurückbleibt.
### Konfigurationsdatei
@@ -1241,7 +1240,7 @@ CONSOLIDATION_ENABLED=true
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1275,7 +1274,7 @@ CONSOLIDATION_ENABLED=true
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1297,7 +1296,7 @@ CONSOLIDATION_ENABLED=true
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.es-ES.md b/READMEs/README.es-ES.md
index ff780cbe..3245e211 100644
--- a/READMEs/README.es-ES.md
+++ b/READMEs/README.es-ES.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ Usa el comando de mantenimiento cuando intencionadamente quieras actualizar tu r
npx @agentmemory/agentmemory upgrade
```
-Aviso: este comando muta el workspace/runtime actual. Puede actualizar dependencias de JavaScript, puede ejecutar `cargo install iii-engine --force`, y puede traer imágenes Docker.
+Aviso: este comando muta el workspace/runtime actual. Puede actualizar dependencias de JavaScript y traer la imagen Docker fijada `iiidev/iii:0.11.2`. Nunca instala un motor iii sin fijar ni más nuevo.
Los detalles de implementación están en `src/cli.ts` (ver `runUpgrade` en torno a la región `src/cli.ts:544-595`).
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Claude Code sin instalar el plugin (ruta MCP standalone)
-Si conectas el servidor MCP de agentmemory directamente vía `~/.claude.json` en lugar de usar `/plugin install`, Claude Code nunca resuelve `${CLAUDE_PLUGIN_ROOT}` y tienes que apuntar los scripts de hook a rutas absolutas en `~/.claude/settings.json`. Esas rutas suelen incluir la versión de agentmemory (p. ej. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), por lo que la siguiente actualización rompe silenciosamente todos los hooks ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+Si conectas el servidor MCP de agentmemory directamente vía `~/.claude.json` en lugar de usar `/plugin install`, Claude Code nunca resuelve `${CLAUDE_PLUGIN_ROOT}` y tienes que apuntar los scripts de hook a rutas absolutas en `~/.claude/settings.json`. Esas rutas suelen incluir la versión de agentmemory (p. ej. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), por lo que la siguiente actualización rompe silenciosamente todos los hooks.
Solución:
@@ -562,7 +561,7 @@ La entrada de agentmemory es el **mismo bloque de servidor MCP** en cada host qu
| **Aider** | n/a | Habla directamente con la REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Cualquier agente (32+)** | n/a | `npx skillkit install agentmemory` auto-detecta el host y fusiona. |
-**Clientes MCP en sandbox** (Flatpak / Snap / contenedores restrictivos) que no pueden alcanzar el `localhost` del host: añade también `"AGENTMEMORY_FORCE_PROXY": "1"` al bloque `env`, y apunta `AGENTMEMORY_URL` a una ruta que el sandbox sí pueda alcanzar (p. ej. tu IP de LAN). Consulta [#234](https://github.com/rohitg00/agentmemory/issues/234) para el walkthrough de diagnóstico.
+**Clientes MCP en sandbox** (Flatpak / Snap / contenedores restrictivos) que no pueden alcanzar el `localhost` del host: añade también `"AGENTMEMORY_FORCE_PROXY": "1"` al bloque `env`, y apunta `AGENTMEMORY_URL` a una ruta que el sandbox sí pueda alcanzar (p. ej. tu IP de LAN).
### Acceso programático (Python / Rust / Node)
@@ -656,7 +655,7 @@ npx -y @agentmemory/mcp
| Conflicto de puerto | `netstat -ano \| findstr :3111` para ver qué está vinculado, mátalo o usa `--port <N>` |
| Se omite el fallback a Docker aunque Docker esté instalado | Asegúrate de que Docker Desktop esté efectivamente en ejecución (icono en la bandeja del sistema) |
-> Nota: no existe `cargo install iii-engine` — `iii` no está publicado en crates.io. Los únicos métodos de instalación soportados son el binario preconstruido de arriba, el script `sh` upstream (solo macOS/Linux) y la imagen Docker.
+> Nota: el **motor** iii es un binario preconstruido, no un crate de cargo — no intentes instalarlo con `cargo install`. (Los **SDK** de iii sí están publicados en crates.io, npm y PyPI, pero agentmemory no los necesita.) Métodos de instalación del motor soportados, todos fijados a v0.11.2: el binario preconstruido v0.11.2 de arriba, el script de instalación `sh` upstream **con el pin de versión** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) y la imagen Docker `iiidev/iii:0.11.2`. Un simple `install.sh | sh` instala el motor **más reciente**, que agentmemory no soporta — pasa siempre `VERSION=0.11.2`. Lo más fácil de todo: simplemente ejecuta `npx @agentmemory/agentmemory`, que obtiene el motor fijado en `~/.agentmemory/bin` por ti.
---
@@ -1098,7 +1097,7 @@ agentmemory autodetecta desde tu entorno. Por defecto no se hacen llamadas LLM a
| MiniMax | `MINIMAX_API_KEY` | Compatible con Anthropic |
| Gemini | `GEMINI_API_KEY` | También habilita embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | Cualquier modelo |
-| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Solo opt-in. Lanza sesiones de `@anthropic-ai/claude-agent-sdk` — solía causar recursión sin límite en el Stop-hook (seguimiento de #149), por eso ya no es el comportamiento por defecto. |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Solo opt-in. Lanza sesiones de `@anthropic-ai/claude-agent-sdk` — solía causar recursión sin límite en el Stop-hook, por eso ya no es el comportamiento por defecto. |
### Selección de modelo con conciencia de coste
@@ -1169,7 +1168,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` recoge limpiamente tanto el worker como el pidfile del engine en un shutdown graceful (#640, #474). La limpieza manual de arriba solo aplica al caso post-crash en el que no queda ningún pidfile.
+`agentmemory stop` recoge limpiamente tanto el worker como el pidfile del engine en un shutdown graceful. La limpieza manual de arriba solo aplica al caso post-crash en el que no queda ningún pidfile.
### Fichero de configuración
@@ -1234,7 +1233,7 @@ Crea `~/.agentmemory/.env`:
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1268,7 +1267,7 @@ Crea `~/.agentmemory/.env`:
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1290,7 +1289,7 @@ Crea `~/.agentmemory/.env`:
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.fr-FR.md b/READMEs/README.fr-FR.md
index c2b464ec..b72b503f 100644
--- a/READMEs/README.fr-FR.md
+++ b/READMEs/README.fr-FR.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ Utilisez la commande de maintenance lorsque vous voulez intentionnellement mettr
npx @agentmemory/agentmemory upgrade
```
-Avertissement : cette commande modifie l'espace de travail / runtime courant. Elle peut mettre à jour les dépendances JavaScript, exécuter `cargo install iii-engine --force` et tirer des images Docker.
+Avertissement : cette commande modifie l'espace de travail / runtime courant. Elle peut mettre à jour les dépendances JavaScript et tirer l'image Docker épinglée `iiidev/iii:0.11.2`. Elle n'installe jamais un moteur iii non épinglé ou plus récent.
Détails d'implémentation dans `src/cli.ts` (voir `runUpgrade` autour de la zone `src/cli.ts:544-595`).
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Claude Code sans installation du plugin (chemin MCP-standalone)
-Si vous câblez le serveur MCP d'agentmemory via `~/.claude.json` directement plutôt que via `/plugin install`, Claude Code ne résout jamais `${CLAUDE_PLUGIN_ROOT}` et vous devez pointer les scripts de hooks vers des chemins absolus dans `~/.claude/settings.json`. Ces chemins embarquent typiquement la version d'agentmemory (par ex. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), si bien que la mise à niveau suivante casse silencieusement tous les hooks ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+Si vous câblez le serveur MCP d'agentmemory via `~/.claude.json` directement plutôt que via `/plugin install`, Claude Code ne résout jamais `${CLAUDE_PLUGIN_ROOT}` et vous devez pointer les scripts de hooks vers des chemins absolus dans `~/.claude/settings.json`. Ces chemins embarquent typiquement la version d'agentmemory (par ex. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), si bien que la mise à niveau suivante casse silencieusement tous les hooks.
Contournement :
@@ -562,7 +561,7 @@ L'entrée agentmemory est le **même bloc serveur MCP** pour tous les hôtes uti
| **Aider** | n/a | Parlez directement à l'API REST : `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Tout agent (32+)** | n/a | `npx skillkit install agentmemory` détecte l'hôte automatiquement et fusionne. |
-**Clients MCP en sandbox** (Flatpak / Snap / conteneurs restrictifs) qui ne peuvent pas joindre le `localhost` de l'hôte : définissez également `"AGENTMEMORY_FORCE_PROXY": "1"` dans le bloc `env` et pointez `AGENTMEMORY_URL` vers une route que la sandbox peut effectivement atteindre (par ex. votre IP LAN). Voir [#234](https://github.com/rohitg00/agentmemory/issues/234) pour la démarche de diagnostic.
+**Clients MCP en sandbox** (Flatpak / Snap / conteneurs restrictifs) qui ne peuvent pas joindre le `localhost` de l'hôte : définissez également `"AGENTMEMORY_FORCE_PROXY": "1"` dans le bloc `env` et pointez `AGENTMEMORY_URL` vers une route que la sandbox peut effectivement atteindre (par ex. votre IP LAN).
### Accès programmatique (Python / Rust / Node)
@@ -656,7 +655,7 @@ npx -y @agentmemory/mcp
| Conflit de port | `netstat -ano \| findstr :3111` pour voir ce qui est lié, puis tuez-le ou utilisez `--port <N>` |
| Fallback Docker ignoré bien que Docker soit installé | Assurez-vous que Docker Desktop tourne effectivement (icône de la barre d'état système) |
-> Note : il n'y a pas de `cargo install iii-engine` — `iii` n'est pas publié sur crates.io. Les seules méthodes d'installation supportées sont le binaire précompilé ci-dessus, le script d'installation amont en `sh` (macOS/Linux uniquement) et l'image Docker.
+> Note : le **moteur** iii est un binaire précompilé, pas un crate cargo — n'essayez pas de l'installer avec `cargo install`. (Les **SDK** iii sont bien publiés sur crates.io, npm et PyPI, mais agentmemory n'en a pas besoin.) Méthodes d'installation du moteur supportées, toutes épinglées à v0.11.2 : le binaire précompilé v0.11.2 ci-dessus, le script d'installation `sh` amont **avec l'épingle de version** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) et l'image Docker `iiidev/iii:0.11.2`. Un simple `install.sh | sh` installe le moteur **le plus récent**, que agentmemory ne supporte pas — passez toujours `VERSION=0.11.2`. Le plus simple de tout : exécutez simplement `npx @agentmemory/agentmemory`, qui récupère le moteur épinglé dans `~/.agentmemory/bin` pour vous.
---
@@ -1105,7 +1104,7 @@ agentmemory détecte automatiquement depuis votre environnement. Par défaut, au
| MiniMax | `MINIMAX_API_KEY` | Compatible Anthropic |
| Gemini | `GEMINI_API_KEY` | Active aussi les embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | N'importe quel modèle |
-| Fallback abonnement Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in seulement. Engendre des sessions `@anthropic-ai/claude-agent-sdk` — provoquait une récursion non bornée du Stop-hook (suite de #149), il n'est plus l'option par défaut. |
+| Fallback abonnement Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in seulement. Engendre des sessions `@anthropic-ai/claude-agent-sdk` — provoquait une récursion non bornée du Stop-hook, il n'est plus l'option par défaut. |
### Sélection de modèle attentive au coût
@@ -1176,7 +1175,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` réclame proprement à la fois le worker et le pidfile du moteur en arrêt gracieux (#640, #474). Le nettoyage manuel ci-dessus n'est nécessaire que pour le cas post-crash où aucun pidfile n'est laissé en place.
+`agentmemory stop` réclame proprement à la fois le worker et le pidfile du moteur en arrêt gracieux. Le nettoyage manuel ci-dessus n'est nécessaire que pour le cas post-crash où aucun pidfile n'est laissé en place.
### Fichier de configuration
@@ -1241,7 +1240,7 @@ Créez `~/.agentmemory/.env` :
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1275,7 +1274,7 @@ Créez `~/.agentmemory/.env` :
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1297,7 +1296,7 @@ Créez `~/.agentmemory/.env` :
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.hi-IN.md b/READMEs/README.hi-IN.md
index 412e6f84..00358fad 100644
--- a/READMEs/README.hi-IN.md
+++ b/READMEs/README.hi-IN.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ Imported सेशंस native ones के साथ Replay picker में
npx @agentmemory/agentmemory upgrade
```
-चेतावनी: यह कमांड वर्तमान workspace/runtime को mutate करता है। यह JavaScript निर्भरताएँ update कर सकता है, `cargo install iii-engine --force` चला सकता है, और Docker images खींच सकता है।
+चेतावनी: यह कमांड वर्तमान workspace/runtime को mutate करता है। यह JavaScript निर्भरताएँ update कर सकता है और pinned Docker image `iiidev/iii:0.11.2` खींच सकता है। यह कभी भी unpinned या नया iii engine install नहीं करता।
Implementation विवरण `src/cli.ts` में हैं (`src/cli.ts:544-595` क्षेत्र के आसपास `runUpgrade` देखें)।
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Plugin install के बिना Claude Code (MCP-standalone path)
-अगर आप `/plugin install` का उपयोग करने के बजाय `~/.claude.json` के माध्यम से सीधे agentmemory का MCP सर्वर कनेक्ट करते हैं, तो Claude Code कभी भी `${CLAUDE_PLUGIN_ROOT}` resolve नहीं करता और आपको hook scripts को `~/.claude/settings.json` में absolute paths पर point करना पड़ता है। ये paths आमतौर पर agentmemory version को embed करते हैं (जैसे `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), इसलिए अगला upgrade चुपचाप हर hook को तोड़ देता है ([#508](https://github.com/rohitg00/agentmemory/issues/508))।
+अगर आप `/plugin install` का उपयोग करने के बजाय `~/.claude.json` के माध्यम से सीधे agentmemory का MCP सर्वर कनेक्ट करते हैं, तो Claude Code कभी भी `${CLAUDE_PLUGIN_ROOT}` resolve नहीं करता और आपको hook scripts को `~/.claude/settings.json` में absolute paths पर point करना पड़ता है। ये paths आमतौर पर agentmemory version को embed करते हैं (जैसे `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), इसलिए अगला upgrade चुपचाप हर hook को तोड़ देता है।
Workaround:
@@ -562,7 +561,7 @@ agentmemory entry `mcpServers` shape का उपयोग करने वा
| **Aider** | n/a | REST API से सीधे बात करें: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`। |
| **कोई भी एजेंट (32+)** | n/a | `npx skillkit install agentmemory` host को auto-detect करता है और merge करता है। |
-**Sandboxed MCP क्लाइंट्स** (Flatpak / Snap / प्रतिबंधात्मक containers) जो host के `localhost` तक नहीं पहुँच सकते: `env` block में `"AGENTMEMORY_FORCE_PROXY": "1"` भी set करें, और `AGENTMEMORY_URL` को एक ऐसे route पर point करें जिस तक sandbox वास्तव में पहुँच सकता है (जैसे आपका LAN IP)। Diagnostic walkthrough के लिए [#234](https://github.com/rohitg00/agentmemory/issues/234) देखें।
+**Sandboxed MCP क्लाइंट्स** (Flatpak / Snap / प्रतिबंधात्मक containers) जो host के `localhost` तक नहीं पहुँच सकते: `env` block में `"AGENTMEMORY_FORCE_PROXY": "1"` भी set करें, और `AGENTMEMORY_URL` को एक ऐसे route पर point करें जिस तक sandbox वास्तव में पहुँच सकता है (जैसे आपका LAN IP)।
### Programmatic access (Python / Rust / Node)
@@ -656,7 +655,7 @@ npx -y @agentmemory/mcp
| Port conflict | `netstat -ano \| findstr :3111` से देखें कि क्या bind है, फिर उसे kill करें या `--port <N>` का उपयोग करें |
| Docker installed होने पर भी Docker fallback skip हो रहा है | सुनिश्चित करें कि Docker Desktop वास्तव में चल रहा है (system tray icon) |
-> नोट: कोई `cargo install iii-engine` नहीं है — `iii` crates.io पर publish नहीं है। केवल समर्थित install methods ऊपर prebuilt binary, upstream `sh` install script (केवल macOS/Linux), और Docker image हैं।
+> नोट: iii **engine** एक prebuilt binary है, cargo crate नहीं — इसे `cargo install` से install करने की कोशिश न करें। (iii **SDKs** crates.io, npm, और PyPI पर publish हैं, लेकिन agentmemory को उनकी ज़रूरत नहीं है।) समर्थित engine install methods, सभी v0.11.2 पर pinned: ऊपर वाला prebuilt v0.11.2 binary, version pin **के साथ** upstream `sh` install script `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux), और Docker image `iiidev/iii:0.11.2`। केवल `install.sh | sh` **latest** engine install करता है, जिसे agentmemory support नहीं करता — हमेशा `VERSION=0.11.2` पास करें। सबसे आसान: बस `npx @agentmemory/agentmemory` चलाएँ, जो pinned engine को आपके लिए `~/.agentmemory/bin` में ले आता है।
---
@@ -1108,7 +1107,7 @@ agentmemory आपके environment से auto-detect करता है। D
| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
| Gemini | `GEMINI_API_KEY` | Embeddings भी enable करता है |
| OpenRouter | `OPENROUTER_API_KEY` | कोई भी model |
-| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | केवल opt-in। `@anthropic-ai/claude-agent-sdk` sessions spawn करता है — पहले unbounded Stop-hook recursion का कारण था (#149 follow-up) तो यह अब default नहीं है। |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | केवल opt-in। `@anthropic-ai/claude-agent-sdk` sessions spawn करता है — पहले unbounded Stop-hook recursion का कारण था तो यह अब default नहीं है। |
### Cost-aware model selection
@@ -1179,7 +1178,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` graceful shutdown पर worker और engine pidfile दोनों को साफ़ रूप से reap करता है (#640, #474)। ऊपर का manual cleanup केवल post-crash case के लिए है जहाँ कोई भी pidfile पीछे नहीं छोड़ी गई।
+`agentmemory stop` graceful shutdown पर worker और engine pidfile दोनों को साफ़ रूप से reap करता है। ऊपर का manual cleanup केवल post-crash case के लिए है जहाँ कोई भी pidfile पीछे नहीं छोड़ी गई।
### Config File
@@ -1244,7 +1243,7 @@ CONSOLIDATION_ENABLED=true
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1278,7 +1277,7 @@ CONSOLIDATION_ENABLED=true
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1300,7 +1299,7 @@ CONSOLIDATION_ENABLED=true
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.ja-JP.md b/READMEs/README.ja-JP.md
index a117b225..979094f6 100644
--- a/READMEs/README.ja-JP.md
+++ b/READMEs/README.ja-JP.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.
npx @agentmemory/agentmemory upgrade
```
-警告: このコマンドは現在のワークスペース/ランタイムを変更します。JavaScript 依存を更新したり、`cargo install iii-engine --force` を実行したり、Docker イメージを pull したりすることがあります。
+警告: このコマンドは現在のワークスペース/ランタイムを変更します。JavaScript 依存を更新したり、ピン留めされた Docker イメージ `iiidev/iii:0.11.2` を pull したりすることがあります。ピン留めされていない、あるいは新しい iii エンジンをインストールすることは決してありません。
実装の詳細は `src/cli.ts` を参照(`src/cli.ts:544-595` 付近の `runUpgrade`)。
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### プラグインをインストールしない Claude Code(MCP スタンドアロン)
-`/plugin install` ではなく `~/.claude.json` から直接 agentmemory の MCP サーバーを配線する場合、Claude Code は `${CLAUDE_PLUGIN_ROOT}` を解決しないため、hook スクリプトを `~/.claude/settings.json` の絶対パスに向ける必要があります。これらのパスには通常 agentmemory のバージョン(例: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`)が埋め込まれるため、次のアップグレードで全 hook が静かに壊れます([#508](https://github.com/rohitg00/agentmemory/issues/508))。
+`/plugin install` ではなく `~/.claude.json` から直接 agentmemory の MCP サーバーを配線する場合、Claude Code は `${CLAUDE_PLUGIN_ROOT}` を解決しないため、hook スクリプトを `~/.claude/settings.json` の絶対パスに向ける必要があります。これらのパスには通常 agentmemory のバージョン(例: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`)が埋め込まれるため、次のアップグレードで全 hook が静かに壊れます。
回避策:
@@ -563,7 +562,7 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
| **Aider** | n/a | REST API に直接話しかける: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 |
| **任意のエージェント(32+)** | n/a | `npx skillkit install agentmemory` がホストを自動検出してマージ。 |
-**サンドボックス化された MCP クライアント**(Flatpak / Snap / 制限的なコンテナ)はホストの `localhost` に到達できません: `env` ブロックに `"AGENTMEMORY_FORCE_PROXY": "1"` も設定し、`AGENTMEMORY_URL` をサンドボックスが実際に到達できる経路(例: LAN IP)に向けてください。診断手順は [#234](https://github.com/rohitg00/agentmemory/issues/234) を参照。
+**サンドボックス化された MCP クライアント**(Flatpak / Snap / 制限的なコンテナ)はホストの `localhost` に到達できません: `env` ブロックに `"AGENTMEMORY_FORCE_PROXY": "1"` も設定し、`AGENTMEMORY_URL` をサンドボックスが実際に到達できる経路(例: LAN IP)に向けてください。
### プログラマティックアクセス(Python / Rust / Node)
@@ -657,7 +656,7 @@ npx -y @agentmemory/mcp
| ポート競合 | `netstat -ano \| findstr :3111` でバインドを確認、kill するか `--port <N>` を使用 |
| Docker をインストール済みなのにフォールバックがスキップされる | Docker Desktop が実際に動作している(システムトレイアイコン)ことを確認 |
-> 注意: `cargo install iii-engine` は存在しません — `iii` は crates.io に公開されていません。サポートされるインストール方法は、上記のビルド済みバイナリ、上流の `sh` インストールスクリプト(macOS/Linux のみ)、Docker イメージのみです。
+> 注意: iii **エンジン** はビルド済みバイナリであり、cargo クレートではありません — `cargo install` でインストールしようとしないでください。(iii **SDK** は crates.io、npm、PyPI に公開されていますが、agentmemory には不要です。)サポートされるエンジンのインストール方法はすべて v0.11.2 にピン留めされています: 上記のビルド済み v0.11.2 バイナリ、バージョンピン**付き**の上流 `sh` インストールスクリプト `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh`(macOS/Linux)、および Docker イメージ `iiidev/iii:0.11.2`。単なる `install.sh | sh` は **最新** のエンジンをインストールしますが、agentmemory はそれをサポートしていません — 必ず `VERSION=0.11.2` を渡してください。最も簡単なのは、`npx @agentmemory/agentmemory` を実行するだけです。これがピン留めされたエンジンを `~/.agentmemory/bin` に取得してくれます。
---
@@ -1108,7 +1107,7 @@ agentmemory は環境から自動検出します。デフォルトでは、プ
| MiniMax | `MINIMAX_API_KEY` | Anthropic 互換 |
| Gemini | `GEMINI_API_KEY` | 埋め込みも有効化 |
| OpenRouter | `OPENROUTER_API_KEY` | 任意のモデル |
-| Claude 購読フォールバック | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | オプトインのみ。`@anthropic-ai/claude-agent-sdk` セッションを生成 — 過去に無限の Stop-hook 再帰(#149 のフォローアップ)を引き起こしたため、もはやデフォルトではありません。 |
+| Claude 購読フォールバック | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | オプトインのみ。`@anthropic-ai/claude-agent-sdk` セッションを生成 — 過去に無限の Stop-hook 再帰を引き起こしたため、もはやデフォルトではありません。 |
### コストを意識したモデル選択
@@ -1179,7 +1178,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` は正常終了時に worker と engine の pidfile を綺麗に回収します(#640、#474)。上の手動クリーンアップは、どちらの pidfile も残っていないクラッシュ後の状態を対象とします。
+`agentmemory stop` は正常終了時に worker と engine の pidfile を綺麗に回収します。上の手動クリーンアップは、どちらの pidfile も残っていないクラッシュ後の状態を対象とします。
### 設定ファイル
@@ -1244,7 +1243,7 @@ CONSOLIDATION_ENABLED=true
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1278,7 +1277,7 @@ CONSOLIDATION_ENABLED=true
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1300,7 +1299,7 @@ CONSOLIDATION_ENABLED=true
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.ko-KR.md b/READMEs/README.ko-KR.md
index 76bcc1d7..369797c3 100644
--- a/READMEs/README.ko-KR.md
+++ b/READMEs/README.ko-KR.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.
npx @agentmemory/agentmemory upgrade
```
-경고: 이 명령은 현재 workspace/런타임을 변경합니다. JavaScript 의존성을 업데이트할 수 있으며, `cargo install iii-engine --force`를 실행할 수도 있고, Docker 이미지를 pull할 수도 있습니다.
+경고: 이 명령은 현재 workspace/런타임을 변경합니다. JavaScript 의존성을 업데이트할 수 있으며, 고정된 Docker 이미지 `iiidev/iii:0.11.2`를 pull할 수 있습니다. 고정되지 않았거나 더 새로운 iii 엔진을 설치하는 일은 절대 없습니다.
구현 세부 사항은 `src/cli.ts`에 있습니다 (`runUpgrade`는 `src/cli.ts:544-595` 부근 참고).
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### 플러그인 설치 없이 Claude Code 사용 (MCP-독립형 경로)
-`/plugin install` 대신 `~/.claude.json`을 통해 agentmemory의 MCP 서버를 직접 연결한 경우, Claude Code는 `${CLAUDE_PLUGIN_ROOT}`를 해석하지 못하므로 `~/.claude/settings.json`의 hook 스크립트를 절대 경로로 지정해야 합니다. 이 경로들은 일반적으로 agentmemory 버전을 포함하기 때문에 (예: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), 다음 업그레이드에서 모든 hook이 조용히 깨질 수 있습니다 ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+`/plugin install` 대신 `~/.claude.json`을 통해 agentmemory의 MCP 서버를 직접 연결한 경우, Claude Code는 `${CLAUDE_PLUGIN_ROOT}`를 해석하지 못하므로 `~/.claude/settings.json`의 hook 스크립트를 절대 경로로 지정해야 합니다. 이 경로들은 일반적으로 agentmemory 버전을 포함하기 때문에 (예: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), 다음 업그레이드에서 모든 hook이 조용히 깨질 수 있습니다.
해결책:
@@ -562,7 +561,7 @@ agentmemory 항목은 `mcpServers` 형태를 사용하는 모든 호스트(Curso
| **Aider** | n/a | REST API와 직접 통신: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **모든 에이전트 (32+)** | n/a | `npx skillkit install agentmemory`가 호스트를 자동 감지하고 병합. |
-**샌드박스된 MCP 클라이언트**(Flatpak / Snap / 제한적인 컨테이너 등)가 호스트의 `localhost`에 도달할 수 없는 경우: `env` 블록에 `"AGENTMEMORY_FORCE_PROXY": "1"`도 설정하고, `AGENTMEMORY_URL`을 샌드박스가 실제로 도달 가능한 경로(예: LAN IP)로 지정하십시오. 진단 가이드는 [#234](https://github.com/rohitg00/agentmemory/issues/234)를 참고하십시오.
+**샌드박스된 MCP 클라이언트**(Flatpak / Snap / 제한적인 컨테이너 등)가 호스트의 `localhost`에 도달할 수 없는 경우: `env` 블록에 `"AGENTMEMORY_FORCE_PROXY": "1"`도 설정하고, `AGENTMEMORY_URL`을 샌드박스가 실제로 도달 가능한 경로(예: LAN IP)로 지정하십시오.
### 프로그래매틱 액세스 (Python / Rust / Node)
@@ -656,7 +655,7 @@ npx -y @agentmemory/mcp
| 포트 충돌 | `netstat -ano \| findstr :3111`로 무엇이 바인딩되어 있는지 확인하고 종료하거나 `--port <N>` 사용 |
| Docker가 설치되어 있어도 Docker 폴백을 건너뜀 | Docker Desktop이 실제로 실행 중인지 확인 (시스템 트레이 아이콘) |
-> 참고: `cargo install iii-engine`는 없습니다 — `iii`는 crates.io에 게시되지 않았습니다. 지원되는 설치 방법은 위의 사전 빌드된 바이너리, 업스트림 `sh` 설치 스크립트(macOS/Linux 전용), Docker 이미지뿐입니다.
+> 참고: iii **엔진**은 사전 빌드된 바이너리이며 cargo 크레이트가 아닙니다 — `cargo install`로 설치하려 하지 마세요. (iii **SDK**는 crates.io, npm, PyPI에 게시되어 있지만 agentmemory에는 필요하지 않습니다.) 지원되는 엔진 설치 방법은 모두 v0.11.2에 고정되어 있습니다: 위의 사전 빌드된 v0.11.2 바이너리, 버전 핀**을 포함한** 업스트림 `sh` 설치 스크립트 `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux), 그리고 Docker 이미지 `iiidev/iii:0.11.2`. 그냥 `install.sh | sh`를 실행하면 **최신** 엔진이 설치되는데, agentmemory는 이를 지원하지 않습니다 — 항상 `VERSION=0.11.2`를 전달하세요. 가장 쉬운 방법은 그냥 `npx @agentmemory/agentmemory`를 실행하는 것입니다. 이 명령이 고정된 엔진을 `~/.agentmemory/bin`에 가져다 줍니다.
---
@@ -1089,7 +1088,7 @@ agentmemory는 환경에서 자동 감지합니다. 기본적으로 프로바이
| MiniMax | `MINIMAX_API_KEY` | Anthropic 호환 |
| Gemini | `GEMINI_API_KEY` | 임베딩도 활성화 |
| OpenRouter | `OPENROUTER_API_KEY` | 모든 모델 |
-| Claude subscription 폴백 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 옵트인 전용. `@anthropic-ai/claude-agent-sdk` 세션을 스폰 — 무한 Stop-hook 재귀를 일으킨 전력이 있어서(#149 후속) 더 이상 기본값이 아닙니다. |
+| Claude subscription 폴백 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 옵트인 전용. `@anthropic-ai/claude-agent-sdk` 세션을 스폰 — 무한 Stop-hook 재귀를 일으킨 전력이 있어서 더 이상 기본값이 아닙니다. |
### 비용 인식 모델 선택
@@ -1160,7 +1159,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop`은 정상 종료 시 워커와 엔진 pidfile을 모두 깔끔하게 회수합니다 (#640, #474). 위의 수동 정리는 어떤 pidfile도 남지 않은 크래시 후 케이스에만 해당됩니다.
+`agentmemory stop`은 정상 종료 시 워커와 엔진 pidfile을 모두 깔끔하게 회수합니다. 위의 수동 정리는 어떤 pidfile도 남지 않은 크래시 후 케이스에만 해당됩니다.
### 설정 파일
@@ -1225,7 +1224,7 @@ CONSOLIDATION_ENABLED=true
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1259,7 +1258,7 @@ CONSOLIDATION_ENABLED=true
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1281,7 +1280,7 @@ CONSOLIDATION_ENABLED=true
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.pt-BR.md b/READMEs/README.pt-BR.md
index bd3777a9..e9bbc32e 100644
--- a/READMEs/README.pt-BR.md
+++ b/READMEs/README.pt-BR.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ Use o comando de manutenção quando você intencionalmente quiser atualizar seu
npx @agentmemory/agentmemory upgrade
```
-Aviso: este comando muta o workspace/runtime atual. Pode atualizar dependências JavaScript, pode rodar `cargo install iii-engine --force` e pode puxar imagens Docker.
+Aviso: este comando muta o workspace/runtime atual. Pode atualizar dependências JavaScript e puxar a imagem Docker fixada `iiidev/iii:0.11.2`. Nunca instala um engine iii sem fixação ou mais recente.
Detalhes de implementação estão em `src/cli.ts` (veja `runUpgrade` na região `src/cli.ts:544-595`).
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Claude Code sem instalar o plugin (caminho MCP standalone)
-Se você cabear o servidor MCP do agentmemory via `~/.claude.json` diretamente em vez de usar `/plugin install`, o Claude Code nunca resolve `${CLAUDE_PLUGIN_ROOT}` e você tem que apontar os scripts de hook para caminhos absolutos em `~/.claude/settings.json`. Esses caminhos tipicamente embutem a versão do agentmemory (ex: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), então a próxima atualização quebra silenciosamente todos os hooks ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+Se você cabear o servidor MCP do agentmemory via `~/.claude.json` diretamente em vez de usar `/plugin install`, o Claude Code nunca resolve `${CLAUDE_PLUGIN_ROOT}` e você tem que apontar os scripts de hook para caminhos absolutos em `~/.claude/settings.json`. Esses caminhos tipicamente embutem a versão do agentmemory (ex: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), então a próxima atualização quebra silenciosamente todos os hooks.
Contorno:
@@ -562,7 +561,7 @@ A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todo host que u
| **Aider** | n/a | Fale diretamente com a REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Qualquer agente (32+)** | n/a | `npx skillkit install agentmemory` autodetecta o host e mescla. |
-**Clientes MCP em sandbox** (Flatpak / Snap / contêineres restritivos) que não conseguem alcançar o `localhost` do host: também defina `"AGENTMEMORY_FORCE_PROXY": "1"` no bloco `env`, e aponte `AGENTMEMORY_URL` para uma rota que o sandbox realmente alcance (ex: seu IP de LAN). Veja [#234](https://github.com/rohitg00/agentmemory/issues/234) para o passo a passo de diagnóstico.
+**Clientes MCP em sandbox** (Flatpak / Snap / contêineres restritivos) que não conseguem alcançar o `localhost` do host: também defina `"AGENTMEMORY_FORCE_PROXY": "1"` no bloco `env`, e aponte `AGENTMEMORY_URL` para uma rota que o sandbox realmente alcance (ex: seu IP de LAN).
### Acesso programático (Python / Rust / Node)
@@ -656,7 +655,7 @@ npx -y @agentmemory/mcp
| Conflito de porta | `netstat -ano \| findstr :3111` para ver o que está em bind, mate o processo ou use `--port <N>` |
| Fallback do Docker é pulado mesmo com Docker instalado | Confira se o Docker Desktop está de fato rodando (ícone na bandeja do sistema) |
-> Nota: não existe `cargo install iii-engine` — `iii` não é publicado no crates.io. Os únicos métodos de instalação suportados são o binário pré-compilado acima, o script de instalação `sh` upstream (somente macOS/Linux) e a imagem Docker.
+> Nota: o **engine** iii é um binário pré-compilado, não um crate do cargo — não tente instalá-lo com `cargo install`. (Os **SDKs** do iii são publicados no crates.io, npm e PyPI, mas o agentmemory não precisa deles.) Métodos de instalação do engine suportados, todos fixados em v0.11.2: o binário pré-compilado v0.11.2 acima, o script de instalação `sh` upstream **com a fixação de versão** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) e a imagem Docker `iiidev/iii:0.11.2`. Um simples `install.sh | sh` instala o engine **mais recente**, que o agentmemory não suporta — sempre passe `VERSION=0.11.2`. O mais fácil de tudo: basta rodar `npx @agentmemory/agentmemory`, que busca o engine fixado em `~/.agentmemory/bin` para você.
---
@@ -1098,7 +1097,7 @@ agentmemory autodetecta a partir do seu ambiente. Por padrão, nenhuma chamada L
| MiniMax | `MINIMAX_API_KEY` | Compatível com Anthropic |
| Gemini | `GEMINI_API_KEY` | Também habilita embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | Qualquer modelo |
-| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Apenas opt-in. Cria sessões de `@anthropic-ai/claude-agent-sdk` — costumava causar recursão sem limite no Stop-hook (seguimento do #149), por isso não é mais o padrão. |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Apenas opt-in. Cria sessões de `@anthropic-ai/claude-agent-sdk` — costumava causar recursão sem limite no Stop-hook, por isso não é mais o padrão. |
### Seleção de modelo com consciência de custo
@@ -1169,7 +1168,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` recolhe tanto o worker quanto o pidfile do engine de forma limpa no shutdown graceful (#640, #474). A limpeza manual acima só serve para o caso pós-crash em que nenhum pidfile foi deixado para trás.
+`agentmemory stop` recolhe tanto o worker quanto o pidfile do engine de forma limpa no shutdown graceful. A limpeza manual acima só serve para o caso pós-crash em que nenhum pidfile foi deixado para trás.
### Arquivo de configuração
@@ -1234,7 +1233,7 @@ Crie `~/.agentmemory/.env`:
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1268,7 +1267,7 @@ Crie `~/.agentmemory/.env`:
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1290,7 +1289,7 @@ Crie `~/.agentmemory/.env`:
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.ru-RU.md b/READMEs/README.ru-RU.md
index 2bd65968..804f380c 100644
--- a/READMEs/README.ru-RU.md
+++ b/READMEs/README.ru-RU.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.
npx @agentmemory/agentmemory upgrade
```
-Внимание: команда меняет текущее рабочее окружение / runtime. Она может обновлять JavaScript-зависимости, может запустить `cargo install iii-engine --force`, может стянуть Docker-образы.
+Внимание: команда меняет текущее рабочее окружение / runtime. Она может обновлять JavaScript-зависимости и стянуть закреплённый Docker-образ `iiidev/iii:0.11.2`. Она никогда не устанавливает незакреплённый или более новый движок iii.
Детали реализации — в `src/cli.ts` (см. `runUpgrade` в районе `src/cli.ts:544-595`).
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Claude Code без установки плагина (путь MCP-standalone)
-Если подключать MCP-сервер agentmemory через `~/.claude.json` напрямую, минуя `/plugin install`, Claude Code никогда не разрешит `${CLAUDE_PLUGIN_ROOT}`, и в `~/.claude/settings.json` придётся прописывать абсолютные пути к скриптам хуков. Эти пути обычно включают версию agentmemory (например, `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), так что следующее обновление тихо ломает каждый хук ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+Если подключать MCP-сервер agentmemory через `~/.claude.json` напрямую, минуя `/plugin install`, Claude Code никогда не разрешит `${CLAUDE_PLUGIN_ROOT}`, и в `~/.claude/settings.json` придётся прописывать абсолютные пути к скриптам хуков. Эти пути обычно включают версию agentmemory (например, `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), так что следующее обновление тихо ломает каждый хук.
Обходное решение:
@@ -562,7 +561,7 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
| **Aider** | н/д | Разговаривайте напрямую с REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Любой агент (32+)** | н/д | `npx skillkit install agentmemory` сам определит хост и сольёт настройки. |
-**MCP-клиенты в sandbox** (Flatpak / Snap / ограничивающие контейнеры), которые не могут добраться до `localhost` хоста: дополнительно установите `"AGENTMEMORY_FORCE_PROXY": "1"` в блоке `env` и укажите `AGENTMEMORY_URL` на маршрут, до которого sandbox действительно может дотянуться (например, IP в локальной сети). См. [#234](https://github.com/rohitg00/agentmemory/issues/234) для пошаговой диагностики.
+**MCP-клиенты в sandbox** (Flatpak / Snap / ограничивающие контейнеры), которые не могут добраться до `localhost` хоста: дополнительно установите `"AGENTMEMORY_FORCE_PROXY": "1"` в блоке `env` и укажите `AGENTMEMORY_URL` на маршрут, до которого sandbox действительно может дотянуться (например, IP в локальной сети).
### Программный доступ (Python / Rust / Node)
@@ -656,7 +655,7 @@ npx -y @agentmemory/mcp
| Конфликт порта | `netstat -ano \| findstr :3111`, чтобы понять, что занимает порт, затем убить процесс или использовать `--port <N>` |
| Откат на Docker пропускается, хотя Docker установлен | Убедитесь, что Docker Desktop действительно запущен (иконка в трее) |
-> Примечание: команды `cargo install iii-engine` нет — `iii` не публикуется на crates.io. Поддерживаются только три способа установки: готовый бинарь выше, upstream-`sh`-скрипт (только macOS/Linux) и Docker-образ.
+> Примечание: **движок** iii — это готовый бинарь, а не cargo-крейт, не пытайтесь установить его через `cargo install`. (**SDK** iii опубликованы на crates.io, npm и PyPI, но agentmemory они не нужны.) Поддерживаемые способы установки движка, все закреплены на v0.11.2: готовый бинарь v0.11.2 выше, upstream-`sh`-скрипт **с закреплением версии** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) и Docker-образ `iiidev/iii:0.11.2`. Простой `install.sh | sh` устанавливает **последний** движок, который agentmemory не поддерживает, — всегда передавайте `VERSION=0.11.2`. Самый простой вариант: просто запустите `npx @agentmemory/agentmemory`, который сам загрузит закреплённый движок в `~/.agentmemory/bin`.
---
@@ -1105,7 +1104,7 @@ agentmemory автоопределяет провайдера по окруже
| MiniMax | `MINIMAX_API_KEY` | Совместим с Anthropic |
| Gemini | `GEMINI_API_KEY` | Дополнительно включает эмбеддинги |
| OpenRouter | `OPENROUTER_API_KEY` | Любая модель |
-| Fallback на подписку Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Только по согласию. Запускает сессии `@anthropic-ai/claude-agent-sdk` — раньше приводил к неограниченной рекурсии Stop-хука (продолжение #149), потому больше не по умолчанию. |
+| Fallback на подписку Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Только по согласию. Запускает сессии `@anthropic-ai/claude-agent-sdk` — раньше приводил к неограниченной рекурсии Stop-хука, потому больше не по умолчанию. |
### Выбор модели с учётом стоимости
@@ -1176,7 +1175,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` корректно вычищает и воркер, и pidfile движка при штатном завершении (#640, #474). Ручная очистка выше нужна только в посткрэшевом сценарии, когда ни один pidfile не остался.
+`agentmemory stop` корректно вычищает и воркер, и pidfile движка при штатном завершении. Ручная очистка выше нужна только в посткрэшевом сценарии, когда ни один pidfile не остался.
### Конфигурационный файл
@@ -1241,7 +1240,7 @@ CONSOLIDATION_ENABLED=true
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1275,7 +1274,7 @@ CONSOLIDATION_ENABLED=true
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1297,7 +1296,7 @@ CONSOLIDATION_ENABLED=true
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.tr-TR.md b/READMEs/README.tr-TR.md
index c97249ac..28fad807 100644
--- a/READMEs/README.tr-TR.md
+++ b/READMEs/README.tr-TR.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ Yerel runtime'ınızı bilinçli olarak güncellemek istediğinizde bakım komut
npx @agentmemory/agentmemory upgrade
```
-Uyarı: bu komut mevcut çalışma alanını/runtime'ı değiştirir. JavaScript bağımlılıklarını güncelleyebilir, `cargo install iii-engine --force` çalıştırabilir ve Docker imajlarını çekebilir.
+Uyarı: bu komut mevcut çalışma alanını/runtime'ı değiştirir. JavaScript bağımlılıklarını güncelleyebilir ve sabitlenmiş `iiidev/iii:0.11.2` Docker imajını çekebilir. Asla sabitlenmemiş ya da daha yeni bir iii motoru kurmaz.
Uygulama detayları `src/cli.ts` içinde (`src/cli.ts:544-595` bölgesi civarında `runUpgrade`'a bakın).
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Eklenti kurulumu olmadan Claude Code (MCP-bağımsız yol)
-Eğer `/plugin install` kullanmak yerine agentmemory'nin MCP sunucusunu doğrudan `~/.claude.json` üzerinden bağlarsanız, Claude Code `${CLAUDE_PLUGIN_ROOT}`'u asla çözmez ve hook scriptlerini `~/.claude/settings.json` içinde mutlak yollara işaret etmek zorunda kalırsınız. Bu yollar genellikle agentmemory sürümünü gömer (örn. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), bu yüzden bir sonraki yükseltme her hook'u sessizce kırar ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+Eğer `/plugin install` kullanmak yerine agentmemory'nin MCP sunucusunu doğrudan `~/.claude.json` üzerinden bağlarsanız, Claude Code `${CLAUDE_PLUGIN_ROOT}`'u asla çözmez ve hook scriptlerini `~/.claude/settings.json` içinde mutlak yollara işaret etmek zorunda kalırsınız. Bu yollar genellikle agentmemory sürümünü gömer (örn. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), bu yüzden bir sonraki yükseltme her hook'u sessizce kırar.
Geçici çözüm:
@@ -562,7 +561,7 @@ agentmemory girdisi, `mcpServers` şeklini kullanan her host'ta (Cursor, Claude
| **Aider** | n/a | REST API ile doğrudan konuşun: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Herhangi bir ajan (32+)** | n/a | `npx skillkit install agentmemory` host'u otomatik algılar ve birleştirir. |
-**Sandbox'lı MCP istemcileri** (Flatpak / Snap / kısıtlayıcı container'lar) host'un `localhost`'una erişemez: ayrıca `env` bloğunda `"AGENTMEMORY_FORCE_PROXY": "1"` ayarlayın ve `AGENTMEMORY_URL`'i sandbox'ın gerçekten erişebileceği bir rotaya yönlendirin (örn. LAN IP'niz). Teşhis adım adımı için bkz. [#234](https://github.com/rohitg00/agentmemory/issues/234).
+**Sandbox'lı MCP istemcileri** (Flatpak / Snap / kısıtlayıcı container'lar) host'un `localhost`'una erişemez: ayrıca `env` bloğunda `"AGENTMEMORY_FORCE_PROXY": "1"` ayarlayın ve `AGENTMEMORY_URL`'i sandbox'ın gerçekten erişebileceği bir rotaya yönlendirin (örn. LAN IP'niz).
### Programatik erişim (Python / Rust / Node)
@@ -656,7 +655,7 @@ npx -y @agentmemory/mcp
| Port çakışması | `netstat -ano \| findstr :3111` ile neyin bağlı olduğunu görün, ardından öldürün veya `--port <N>` kullanın |
| Docker kurulu olsa bile Docker fallback atlanıyor | Docker Desktop'ın gerçekten çalıştığından emin olun (sistem tepsisi simgesi) |
-> Not: `cargo install iii-engine` yoktur — `iii` crates.io'da yayımlanmamıştır. Tek desteklenen kurulum yöntemleri yukarıdaki önceden derlenmiş ikilik, upstream `sh` kurulum scripti (yalnızca macOS/Linux) ve Docker imajıdır.
+> Not: iii **motoru** önceden derlenmiş bir ikiliktir, bir cargo crate'i değildir — onu `cargo install` ile kurmaya çalışmayın. (iii **SDK'ları** crates.io, npm ve PyPI'de yayımlanmıştır, ancak agentmemory bunlara ihtiyaç duymaz.) Desteklenen motor kurulum yöntemleri, hepsi v0.11.2'ye sabitlenmiştir: yukarıdaki önceden derlenmiş v0.11.2 ikiliği, sürüm sabitlemesi **ile** upstream `sh` kurulum scripti `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) ve Docker imajı `iiidev/iii:0.11.2`. Yalın bir `install.sh | sh`, agentmemory'nin desteklemediği **en son** motoru kurar — her zaman `VERSION=0.11.2` geçirin. Hepsinden kolayı: sadece `npx @agentmemory/agentmemory` çalıştırın; bu, sabitlenmiş motoru sizin için `~/.agentmemory/bin` dizinine indirir.
---
@@ -1109,7 +1108,7 @@ agentmemory ortamınızdan otomatik algılar. Varsayılan olarak, bir sağlayıc
| MiniMax | `MINIMAX_API_KEY` | Anthropic-uyumlu |
| Gemini | `GEMINI_API_KEY` | Embedding'leri de etkinleştirir |
| OpenRouter | `OPENROUTER_API_KEY` | Herhangi bir model |
-| Claude abonelik fallback'i | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Yalnızca opt-in. `@anthropic-ai/claude-agent-sdk` oturumları doğurur — eskiden sınırsız Stop-hook recursion'ına neden oluyordu (#149 takip), bu yüzden artık varsayılan değil. |
+| Claude abonelik fallback'i | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Yalnızca opt-in. `@anthropic-ai/claude-agent-sdk` oturumları doğurur — eskiden sınırsız Stop-hook recursion'ına neden oluyordu, bu yüzden artık varsayılan değil. |
### Maliyet bilincine sahip model seçimi
@@ -1180,7 +1179,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` graceful shutdown'da hem worker hem de engine pidfile'ını temiz olarak biçer (#640, #474). Yukarıdaki manuel temizlik yalnızca her iki pidfile'ın da geride kalmadığı çökme sonrası durum içindir.
+`agentmemory stop` graceful shutdown'da hem worker hem de engine pidfile'ını temiz olarak biçer. Yukarıdaki manuel temizlik yalnızca her iki pidfile'ın da geride kalmadığı çökme sonrası durum içindir.
### Yapılandırma Dosyası
@@ -1245,7 +1244,7 @@ CONSOLIDATION_ENABLED=true
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1279,7 +1278,7 @@ CONSOLIDATION_ENABLED=true
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1301,7 +1300,7 @@ CONSOLIDATION_ENABLED=true
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.zh-CN.md b/READMEs/README.zh-CN.md
index cc9a01a1..e711a367 100644
--- a/READMEs/README.zh-CN.md
+++ b/READMEs/README.zh-CN.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.
npx @agentmemory/agentmemory upgrade
```
-警告:此命令会变更当前工作空间/运行时。它可能更新 JavaScript 依赖,可能运行 `cargo install iii-engine --force`,也可能拉取 Docker 镜像。
+警告:此命令会变更当前工作空间/运行时。它可能更新 JavaScript 依赖,并拉取固定版本的 Docker 镜像 `iiidev/iii:0.11.2`。它绝不会安装未固定版本或更新的 iii 引擎。
实现细节见 `src/cli.ts`(参考 `src/cli.ts:544-595` 附近的 `runUpgrade`)。
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Claude Code 不安装插件(MCP-standalone 路径)
-如果你直接通过 `~/.claude.json` 连接 agentmemory 的 MCP 服务器而不使用 `/plugin install`,Claude Code 永远不会解析 `${CLAUDE_PLUGIN_ROOT}`,你必须把 hook 脚本指向 `~/.claude/settings.json` 中的绝对路径。这些路径通常会嵌入 agentmemory 版本号(例如 `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`),因此下次升级会静默破坏所有 hooks([#508](https://github.com/rohitg00/agentmemory/issues/508))。
+如果你直接通过 `~/.claude.json` 连接 agentmemory 的 MCP 服务器而不使用 `/plugin install`,Claude Code 永远不会解析 `${CLAUDE_PLUGIN_ROOT}`,你必须把 hook 脚本指向 `~/.claude/settings.json` 中的绝对路径。这些路径通常会嵌入 agentmemory 版本号(例如 `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`),因此下次升级会静默破坏所有 hooks。
变通方法:
@@ -563,7 +562,7 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
| **Aider** | n/a | 直接调用 REST API:`curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 |
| **任何代理 (32+)** | n/a | `npx skillkit install agentmemory` 自动检测宿主并合并。 |
-**沙盒化的 MCP 客户端**(Flatpak / Snap / 受限容器)无法访问宿主的 `localhost`:还要在 `env` 块中设置 `"AGENTMEMORY_FORCE_PROXY": "1"`,并把 `AGENTMEMORY_URL` 指向沙盒确实能到达的路由(例如你的 LAN IP)。诊断步骤见 [#234](https://github.com/rohitg00/agentmemory/issues/234)。
+**沙盒化的 MCP 客户端**(Flatpak / Snap / 受限容器)无法访问宿主的 `localhost`:还要在 `env` 块中设置 `"AGENTMEMORY_FORCE_PROXY": "1"`,并把 `AGENTMEMORY_URL` 指向沙盒确实能到达的路由(例如你的 LAN IP)。
### 程序化访问(Python / Rust / Node)
@@ -657,7 +656,7 @@ npx -y @agentmemory/mcp
| 端口冲突 | `netstat -ano \| findstr :3111` 查看占用,然后 kill 或用 `--port <N>` |
| Docker 已安装但仍跳过回退 | 确保 Docker Desktop 确实在运行(系统托盘图标) |
-> 注意:没有 `cargo install iii-engine` — `iii` 未发布到 crates.io。唯一受支持的安装方式是上面的预构建二进制、上游 `sh` 安装脚本(仅 macOS/Linux)和 Docker 镜像。
+> 注意:iii **引擎** 是预构建的二进制文件,而非 cargo crate — 不要尝试用 `cargo install` 安装它。(iii 的 **SDK** 确实已发布到 crates.io、npm 和 PyPI,但 agentmemory 并不需要它们。)受支持的引擎安装方式均固定为 v0.11.2:上面的预构建 v0.11.2 二进制、**带版本固定** 的上游 `sh` 安装脚本 `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh`(macOS/Linux),以及 Docker 镜像 `iiidev/iii:0.11.2`。直接运行 `install.sh | sh` 会安装 **最新** 引擎,而 agentmemory 不支持该版本 — 请务必传入 `VERSION=0.11.2`。最简单的方式:直接运行 `npx @agentmemory/agentmemory`,它会为你把固定版本的引擎获取到 `~/.agentmemory/bin`。
---
@@ -1106,7 +1105,7 @@ agentmemory 从你的环境自动检测。默认情况下,除非你配置提供
| MiniMax | `MINIMAX_API_KEY` | Anthropic 兼容 |
| Gemini | `GEMINI_API_KEY` | 同时启用嵌入 |
| OpenRouter | `OPENROUTER_API_KEY` | 任意模型 |
-| Claude 订阅回退 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 仅按需启用。会派生 `@anthropic-ai/claude-agent-sdk` 会话 — 曾导致无限 Stop-hook 递归(#149 后续)故不再默认。 |
+| Claude 订阅回退 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 仅按需启用。会派生 `@anthropic-ai/claude-agent-sdk` 会话 — 曾导致无限 Stop-hook 递归故不再默认。 |
### 成本感知的模型选择
@@ -1177,7 +1176,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` 在优雅关闭时干净地回收 worker 和 engine pidfile(#640、#474)。上面的手动清理仅针对崩溃后两个 pidfile 都未留下的情况。
+`agentmemory stop` 在优雅关闭时干净地回收 worker 和 engine pidfile。上面的手动清理仅针对崩溃后两个 pidfile 都未留下的情况。
### 配置文件
@@ -1242,7 +1241,7 @@ CONSOLIDATION_ENABLED=true
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1276,7 +1275,7 @@ CONSOLIDATION_ENABLED=true
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1298,7 +1297,7 @@ CONSOLIDATION_ENABLED=true
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/READMEs/README.zh-TW.md b/READMEs/README.zh-TW.md
index ace349b7..75b2fc97 100644
--- a/READMEs/README.zh-TW.md
+++ b/READMEs/README.zh-TW.md
@@ -49,7 +49,6 @@
<p align="center">
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
- <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
@@ -422,7 +421,7 @@ npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.
npx @agentmemory/agentmemory upgrade
```
-警告:此指令會變更目前工作區/執行階段。它可能更新 JavaScript 相依、可能執行 `cargo install iii-engine --force`、也可能拉取 Docker 鏡像。
+警告:此指令會變更目前工作區/執行階段。它可能更新 JavaScript 相依,並拉取固定版本的 Docker 鏡像 `iiidev/iii:0.11.2`。它絕不會安裝未固定版本或更新的 iii 引擎。
實作細節見 `src/cli.ts`(參考 `src/cli.ts:544-595` 附近的 `runUpgrade`)。
@@ -434,7 +433,7 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
#### Claude Code 不安裝外掛(MCP-standalone 路徑)
-若你直接透過 `~/.claude.json` 連接 agentmemory 的 MCP 伺服器而非使用 `/plugin install`,Claude Code 永遠不會解析 `${CLAUDE_PLUGIN_ROOT}`,你必須把 hook 腳本指向 `~/.claude/settings.json` 中的絕對路徑。這些路徑通常會嵌入 agentmemory 版本號(例如 `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`),因此下次升級會靜默破壞所有 hooks([#508](https://github.com/rohitg00/agentmemory/issues/508))。
+若你直接透過 `~/.claude.json` 連接 agentmemory 的 MCP 伺服器而非使用 `/plugin install`,Claude Code 永遠不會解析 `${CLAUDE_PLUGIN_ROOT}`,你必須把 hook 腳本指向 `~/.claude/settings.json` 中的絕對路徑。這些路徑通常會嵌入 agentmemory 版本號(例如 `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`),因此下次升級會靜默破壞所有 hooks。
變通方法:
@@ -563,7 +562,7 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
| **Aider** | n/a | 直接呼叫 REST API:`curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 |
| **任何代理(32+)** | n/a | `npx skillkit install agentmemory` 自動偵測宿主並合併。 |
-**沙箱化的 MCP 用戶端**(Flatpak / Snap / 受限容器)無法存取宿主的 `localhost`:還要在 `env` 區塊中設定 `"AGENTMEMORY_FORCE_PROXY": "1"`,並把 `AGENTMEMORY_URL` 指向沙箱確實能到達的路由(例如你的 LAN IP)。診斷步驟見 [#234](https://github.com/rohitg00/agentmemory/issues/234)。
+**沙箱化的 MCP 用戶端**(Flatpak / Snap / 受限容器)無法存取宿主的 `localhost`:還要在 `env` 區塊中設定 `"AGENTMEMORY_FORCE_PROXY": "1"`,並把 `AGENTMEMORY_URL` 指向沙箱確實能到達的路由(例如你的 LAN IP)。
### 程式化存取(Python / Rust / Node)
@@ -657,7 +656,7 @@ npx -y @agentmemory/mcp
| 連接埠衝突 | `netstat -ano \| findstr :3111` 查看佔用,然後 kill 或用 `--port <N>` |
| Docker 已安裝但仍跳過回退 | 確保 Docker Desktop 確實在執行(系統匣圖示) |
-> 注意:沒有 `cargo install iii-engine` — `iii` 未發布到 crates.io。唯一受支援的安裝方式是上述預建二進位、上游 `sh` 安裝指令稿(僅 macOS/Linux)和 Docker 鏡像。
+> 注意:iii **引擎** 是預建的二進位檔,而非 cargo crate — 請勿嘗試以 `cargo install` 安裝它。(iii 的 **SDK** 確實已發布到 crates.io、npm 和 PyPI,但 agentmemory 並不需要它們。)受支援的引擎安裝方式皆固定為 v0.11.2:上述預建的 v0.11.2 二進位、**帶版本固定** 的上游 `sh` 安裝指令稿 `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh`(macOS/Linux),以及 Docker 鏡像 `iiidev/iii:0.11.2`。直接執行 `install.sh | sh` 會安裝 **最新** 引擎,而 agentmemory 並不支援該版本 — 請務必傳入 `VERSION=0.11.2`。最簡單的方式:直接執行 `npx @agentmemory/agentmemory`,它會為你把固定版本的引擎取得到 `~/.agentmemory/bin`。
---
@@ -1106,7 +1105,7 @@ agentmemory 從你的環境自動偵測。預設情況下,除非你設定提供
| MiniMax | `MINIMAX_API_KEY` | Anthropic 相容 |
| Gemini | `GEMINI_API_KEY` | 同時啟用嵌入 |
| OpenRouter | `OPENROUTER_API_KEY` | 任意模型 |
-| Claude 訂閱回退 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 僅按需啟用。會衍生 `@anthropic-ai/claude-agent-sdk` 會話 — 曾導致無限 Stop-hook 遞迴(#149 後續)故不再預設。 |
+| Claude 訂閱回退 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 僅按需啟用。會衍生 `@anthropic-ai/claude-agent-sdk` 會話 — 曾導致無限 Stop-hook 遞迴故不再預設。 |
### 成本感知的模型選擇
@@ -1177,7 +1176,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```
-`agentmemory stop` 在優雅關閉時乾淨地回收 worker 和 engine pidfile(#640、#474)。上述手動清理僅針對當機後兩個 pidfile 都未留下的情況。
+`agentmemory stop` 在優雅關閉時乾淨地回收 worker 和 engine pidfile。上述手動清理僅針對當機後兩個 pidfile 都未留下的情況。
### 設定檔
@@ -1242,7 +1241,7 @@ CONSOLIDATION_ENABLED=true
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
-# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (auto-detected, or override)
@@ -1276,7 +1275,7 @@ CONSOLIDATION_ENABLED=true
# III_REST_PORT=3111
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default (#138). When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1298,7 +1297,7 @@ CONSOLIDATION_ENABLED=true
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
-# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
diff --git a/deploy/coolify/Dockerfile b/deploy/coolify/Dockerfile
index 3f6c433f..48c8d59d 100644
--- a/deploy/coolify/Dockerfile
+++ b/deploy/coolify/Dockerfile
@@ -4,7 +4,7 @@ FROM iiidev/iii:${III_VERSION} AS iii-image
FROM node:22-slim
-ARG AGENTMEMORY_VERSION=0.9.12
+ARG AGENTMEMORY_VERSION=0.9.27
ARG III_VERSION=0.11.2
ARG III_SDK_VERSION=0.11.2
diff --git a/deploy/coolify/docker-compose.yml b/deploy/coolify/docker-compose.yml
index 149f806d..73d53661 100644
--- a/deploy/coolify/docker-compose.yml
+++ b/deploy/coolify/docker-compose.yml
@@ -4,7 +4,7 @@ services:
context: .
dockerfile: Dockerfile
args:
- AGENTMEMORY_VERSION: "0.9.12"
+ AGENTMEMORY_VERSION: "0.9.27"
III_VERSION: "0.11.2"
III_SDK_VERSION: "0.11.2"
restart: unless-stopped
diff --git a/deploy/fly/Dockerfile b/deploy/fly/Dockerfile
index 89257f93..3769815d 100644
--- a/deploy/fly/Dockerfile
+++ b/deploy/fly/Dockerfile
@@ -4,7 +4,7 @@ FROM iiidev/iii:${III_VERSION} AS iii-image
FROM node:22-slim
-ARG AGENTMEMORY_VERSION=0.9.12
+ARG AGENTMEMORY_VERSION=0.9.27
ARG III_VERSION=0.11.2
ARG III_SDK_VERSION=0.11.2
diff --git a/deploy/railway/Dockerfile b/deploy/railway/Dockerfile
index 89257f93..3769815d 100644
--- a/deploy/railway/Dockerfile
+++ b/deploy/railway/Dockerfile
@@ -4,7 +4,7 @@ FROM iiidev/iii:${III_VERSION} AS iii-image
FROM node:22-slim
-ARG AGENTMEMORY_VERSION=0.9.12
+ARG AGENTMEMORY_VERSION=0.9.27
ARG III_VERSION=0.11.2
ARG III_SDK_VERSION=0.11.2
diff --git a/deploy/render/Dockerfile b/deploy/render/Dockerfile
index 89257f93..3769815d 100644
--- a/deploy/render/Dockerfile
+++ b/deploy/render/Dockerfile
@@ -4,7 +4,7 @@ FROM iiidev/iii:${III_VERSION} AS iii-image
FROM node:22-slim
-ARG AGENTMEMORY_VERSION=0.9.12
+ARG AGENTMEMORY_VERSION=0.9.27
ARG III_VERSION=0.11.2
ARG III_SDK_VERSION=0.11.2
diff --git a/deploy/render/render.yaml b/deploy/render/render.yaml
index c96516d0..d2694693 100644
--- a/deploy/render/render.yaml
+++ b/deploy/render/render.yaml
@@ -15,7 +15,7 @@ services:
- key: PORT
value: "3111"
- key: AGENTMEMORY_VERSION
- value: "0.9.12"
+ value: "0.9.27"
- key: III_VERSION
value: "0.11.2"
- key: III_SDK_VERSION
diff --git a/package.json b/package.json
index 3c7cb537..4e2bc8c4 100644
--- a/package.json
+++ b/package.json
@@ -65,6 +65,7 @@
"@clack/prompts": "^1.2.0",
"dotenv": "^17.4.2",
"iii-sdk": "0.11.2",
+ "picocolors": "^1.1.1",
"zod": "^4.0.0"
},
"optionalDependencies": {
diff --git a/src/cli.ts b/src/cli.ts
index 48f6f09b..93b90749 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -21,6 +21,22 @@ import { join, dirname, delimiter as PATH_DELIMITER } from "node:path";
import { fileURLToPath } from "node:url";
import { homedir, platform } from "node:os";
import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+// Semantic color helpers. clack strips ANSI for box-width math
+// (stripVTControlCharacters + string-width), so coloring inside p.note
+// keeps borders aligned. Centralized here so the palette stays consistent
+// across every command's output.
+const c = {
+ url: pc.cyan,
+ ok: pc.green,
+ warn: pc.yellow,
+ err: pc.red,
+ cmd: (s: string) => pc.bold(pc.cyan(s)),
+ label: pc.bold,
+ dim: pc.dim,
+ accent: (s: string) => pc.bold(pc.yellow(s)),
+};
import { generateId } from "./state/schema.js";
import {
buildDiagnostics,
@@ -223,7 +239,7 @@ if (portIdx !== -1 && args[portIdx + 1]) {
// `--instance N` picks a 100-port block off the 3111 base so multiple
// agentmemory daemons can coexist on one host without env-var
-// gymnastics (#750). `--instance 0` keeps the canonical 3111/3112/3113/49134
+// gymnastics. `--instance 0` keeps the canonical 3111/3112/3113/49134
// quartet; `--instance 1` → 3211/3212/3213/49234; etc. REST acts as the
// anchor — streams/viewer/engine derive from it via fixed offsets below
// unless an env explicitly pins each one.
@@ -306,7 +322,7 @@ function getViewerUrl(): string {
// engine docs use post-0.11) and `III_STREAMS_PORT` (the name our
// own config.ts has used since 0.7) so a single source of truth in
// either form lights up the ready panel. Falls back to REST+1 so
-// `--port 3211` auto-picks 3212 instead of colliding on 3112 (#750).
+// `--port 3211` auto-picks 3212 instead of colliding on 3112.
function getStreamPort(): number {
return (
parseInt(process.env["III_STREAM_PORT"] || "", 10) ||
@@ -318,7 +334,7 @@ function getStreamPort(): number {
// Bridge WebSocket port — the iii engine's internal worker bus.
// Defaults derived from REST as REST+46023 so the canonical 3111
// anchor yields 49134 and `--port 3211` auto-picks 49234 without a
-// second-instance collision (#750). Overridable via
+// second-instance collision. Overridable via
// `III_ENGINE_PORT` or the legacy `III_ENGINE_URL=ws://host:port`.
function getEnginePort(): number {
const explicit = parseInt(process.env["III_ENGINE_PORT"] || "", 10);
@@ -370,7 +386,7 @@ function findIiiConfig(): string {
// Precedence (user-overridable wins): explicit env > project cwd >
// ~/.agentmemory/ > bundled. The bundled config used to win
// unconditionally, so users hitting the observability log-feedback
- // loop (#519) had no way to drop a tamer config in place without
+ // loop had no way to drop a tamer config in place without
// editing node_modules.
const envPath = process.env["AGENTMEMORY_III_CONFIG"];
const candidates = [
@@ -405,7 +421,7 @@ function whichBinary(name: string): string | null {
// Private install location agentmemory manages itself. Sits under the
// agentmemory state dir (~/.agentmemory/bin) so the pinned engine stays
-// isolated from a user-managed iii on PATH or in ~/.local/bin. #752: a
+// isolated from a user-managed iii on PATH or in ~/.local/bin. A
// fresh box with iii 0.16.1 already on PATH refused to boot because the
// hard-pin enforcer told users to overwrite their global install with
// v0.11.2. Private install resolves the conflict without touching their
@@ -530,7 +546,7 @@ function clearEnginePidfile(): void {
} catch {}
}
-// Worker pidfile (#640, #474): the agentmemory worker process
+// Worker pidfile: the agentmemory worker process
// (`node dist/index.mjs`) is spawned by iii-exec inside the engine. When
// `agentmemory stop` kills only the engine pid, the worker can survive
// (detached spawn, signal not propagated, or kept alive by a wrapper
@@ -685,7 +701,7 @@ function detectIiiConsole(): IiiConsoleState {
// install.iii.dev/iii/main/install.sh: `engine_version="${VERSION:-}"`).
// Pin to IIPINNED_VERSION so a fresh boot can never pull a newer iii
// console that talks a different protocol than our pinned engine
-// (root cause of #712-class drift).
+// (root cause of protocol drift).
const III_CONSOLE_INSTALL_CMD =
`curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=${IIPINNED_VERSION} sh`;
@@ -766,7 +782,7 @@ function adoptRunningEngine(): void {
});
}
if (enginePid && !existingPid) {
- p.log.info(`Attached to existing iii-engine (pid ${enginePid})`);
+ p.log.info(c.ok(`Attached to existing iii-engine (pid ${enginePid})`));
}
} catch (err) {
vlog(`adoptRunningEngine: ${err instanceof Error ? err.message : String(err)}`);
@@ -889,7 +905,7 @@ function startIiiBin(iiiBin: string, configPath: string): boolean {
s.start(`Starting iii-engine: ${iiiBin}`);
writeEngineState({ kind: "native", configPath, binPath: iiiBin });
spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
- s.stop("iii-engine process started");
+ s.stop(c.ok("iii-engine process started"));
return true;
}
@@ -922,7 +938,7 @@ async function startEngine(): Promise<boolean> {
if (iiiBin && configPath) {
if (iiiBin !== pathIii) {
- p.log.info(`Using iii at: ${iiiBin} (v${IIPINNED_VERSION})`);
+ p.log.info(`Using iii at: ${c.dim(iiiBin)} (v${c.accent(IIPINNED_VERSION)})`);
process.env["PATH"] = `${dirname(iiiBin)}${PATH_DELIMITER}${process.env["PATH"] ?? ""}`;
}
return startIiiBin(iiiBin, configPath);
@@ -1148,20 +1164,20 @@ function printReadyHint(consoleState: IiiConsoleState): void {
// the detected binary path so `(run: ...)` is executable as-
// is, even when the binary isn't on PATH under the bare
// name `iii-console`.
- `iii console ${consoleState.binPath} (run: ${consoleState.binPath} -p <port>)`
- : `iii console (install: ${iiiConsoleInstallHint()})`;
+ `${c.label("iii console")} ${c.dim(consoleState.binPath)} ${c.dim(`(run: ${consoleState.binPath} -p <port>)`)}`
+ : `${c.label("iii console")} ${c.dim(`(install: ${iiiConsoleInstallHint()})`)}`;
const lines = [
- `REST API ${restUrl}`,
- `Viewer ${viewerUrl}`,
- `Streams ${streamUrl}`,
- `Engine ${engineUrl}`,
+ `${c.label("REST API")} ${c.url(restUrl)}`,
+ `${c.label("Viewer")} ${c.url(viewerUrl)}`,
+ `${c.label("Streams")} ${c.url(streamUrl)}`,
+ `${c.label("Engine")} ${c.url(engineUrl)}`,
consoleLine,
];
// p.note renders a bordered panel with a title — same affordance
// used elsewhere in this CLI for "Troubleshooting" / "Setup
// required" blocks, so the visual language stays consistent.
- p.note(lines.join("\n"), `agentmemory v${VERSION}`);
+ p.note(lines.join("\n"), `agentmemory v${c.accent(VERSION)}`);
// Pick a runnable form for the suggested next-step. Users invoked
// via `npx` don't have the bare `agentmemory` command on PATH yet
@@ -1171,7 +1187,7 @@ function printReadyHint(consoleState: IiiConsoleState): void {
const demoCommand = isInvokedViaNpx()
? "npx @agentmemory/agentmemory demo"
: "agentmemory demo";
- process.stdout.write(`\nTry: ${demoCommand}\n`);
+ process.stdout.write(`\n${c.dim("Try:")} ${c.cmd(demoCommand)}\n`);
}
async function main() {
@@ -1222,24 +1238,58 @@ async function main() {
whichBinary("iii") ??
fallbackIiiPaths().find((p) => existsSync(p)) ??
null;
- if (attachedBin) {
- const detected = iiiBinVersion(attachedBin);
- if (detected && detected !== IIPINNED_VERSION) {
- p.log.warn(
- `iii on PATH is v${detected} (from ${attachedBin}) but agentmemory v${VERSION} pins v${IIPINNED_VERSION}. ` +
- `agentmemory will use its own pinned engine in ~/.agentmemory/bin and leaves ${attachedBin} untouched. ` +
- `If you want agentmemory to track a different engine, set AGENTMEMORY_III_VERSION=${detected}.`,
- );
+ const detected = attachedBin ? iiiBinVersion(attachedBin) : null;
+
+ // Fail closed: only adopt the running engine when we can positively
+ // confirm it is the pinned version. An unknown version (detected === null,
+ // e.g. the binary can't be version-probed) is treated as incompatible —
+ // adopting a foreign or unverifiable engine hangs the worker in a
+ // WebSocket reconnect loop. Worst case here is a re-run that reinstalls
+ // the pinned engine, never a silent loop.
+ if (detected === IIPINNED_VERSION) {
+ adoptRunningEngine();
+ await import("./index.js");
+ if (await waitForAgentmemoryReady(15000)) {
+ const consoleState = await ensureIiiConsole();
+ await maybeOfferGlobalInstall();
+ printReadyHint(consoleState);
}
+ return;
}
- adoptRunningEngine();
- await import("./index.js");
- if (await waitForAgentmemoryReady(15000)) {
- const consoleState = await ensureIiiConsole();
- await maybeOfferGlobalInstall();
- printReadyHint(consoleState);
- }
- return;
+
+ const detectedLabel = detected ? `v${detected}` : "an unverified version";
+
+ // An incompatible engine owns the port. Adopting it hangs the worker in a
+ // WebSocket reconnect loop (it can't speak that engine's protocol), so stop
+ // with the simplest honest remedy. A normal user has no other engine and
+ // never sees this; only someone running their own iii does, and for them
+ // "stop it, then run normally" is the fix. We do not suggest a different
+ // engine version: agentmemory only supports v${IIPINNED_VERSION}.
+ const base = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";
+ p.log.error(
+ `Another iii-engine (${detectedLabel}) is running on port ${getEnginePort()}, and agentmemory needs its own pinned v${IIPINNED_VERSION}.`,
+ );
+ p.note(
+ [
+ `agentmemory only supports iii-engine v${IIPINNED_VERSION}. It will not adopt or change the running engine (${detectedLabel}).`,
+ "",
+ c.label("Switch to the pinned engine in two steps:"),
+ "",
+ ` 1. Stop the running engine:`,
+ ` ${c.cmd(`${base} stop --force`)}`,
+ ` ${c.dim(`(or stop your own iii however you started it — agentmemory leaves your global iii untouched)`)}`,
+ "",
+ ` 2. Start agentmemory. It downloads and runs the pinned`,
+ ` v${IIPINNED_VERSION} into ~/.agentmemory/bin automatically:`,
+ ` ${c.cmd(base)}`,
+ "",
+ c.dim(`Step 2 needs no manual install. To install iii v${IIPINNED_VERSION} yourself (replaces your global iii), curl:`),
+ ` ${c.cmd(III_CONSOLE_INSTALL_CMD)}`,
+ ` ${c.dim("or download the release:")} ${c.url(`https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`)}`,
+ ].join("\n"),
+ "engine conflict",
+ );
+ process.exit(1);
}
const started = await startEngine();
@@ -1305,7 +1355,7 @@ async function main() {
process.exit(1);
}
- s.stop("iii-engine is ready");
+ s.stop(c.ok("iii-engine is ready"));
await import("./index.js");
if (await waitForAgentmemoryReady(15000)) {
const consoleState = await ensureIiiConsole();
@@ -1381,7 +1431,7 @@ async function runStatus() {
p.log.success(`Connected — v${version} at ${base}`);
const lines = [
- `Health: ${status === "healthy" ? "✓ healthy" : status}`,
+ `Health: ${status === "healthy" ? pc.green("✓ healthy") : pc.yellow(status)}`,
`Sessions: ${sessions}`,
`Observations: ${obsCount}`,
`Memories: ${memCount}`,
@@ -1389,7 +1439,7 @@ async function runStatus() {
`Circuit: ${cb}`,
`Heap: ${heapMB} MB`,
`Uptime: ${uptime}s`,
- `Viewer: ${getViewerUrl()}`,
+ `Viewer: ${c.url(getViewerUrl())}`,
];
if (obsCount > 0) {
@@ -1400,10 +1450,10 @@ async function runStatus() {
}
if (flagsRes) {
- const provider = flagsRes.provider === "llm" ? "✓ llm" : "✗ noop (no key)";
- const embed = flagsRes.embeddingProvider === "embeddings" ? "✓ embeddings" : "bm25-only";
+ const provider = flagsRes.provider === "llm" ? pc.green("✓ llm") : pc.yellow("✗ noop (no key)");
+ const embed = flagsRes.embeddingProvider === "embeddings" ? pc.green("✓ embeddings") : pc.dim("bm25-only");
const flagRows = (flagsRes.flags || []).map((f: { key: string; enabled: boolean; label: string }) =>
- ` ${f.enabled ? "✓" : "✗"} ${f.key.padEnd(32)} ${f.label}`
+ ` ${f.enabled ? pc.green("✓") : pc.dim("✗")} ${pc.bold(f.key.padEnd(32))} ${f.label}`
);
lines.push("");
lines.push(`Provider: ${provider}`);
@@ -1433,7 +1483,7 @@ type DoctorCheck = { name: string; ok: boolean; hint?: string };
function formatChecks(checks: DoctorCheck[]): string {
return checks
- .map((c) => `${c.ok ? "✓" : "✗"} ${c.name}${c.hint ? `\n ${c.hint}` : ""}`)
+ .map((c) => `${c.ok ? pc.green("✓") : pc.red("✗")} ${c.name}${c.hint ? `\n ${c.hint}` : ""}`)
.join("\n");
}
@@ -2233,17 +2283,17 @@ async function runDemoBody(base: string) {
`Project: ${demoProject}`,
`Sessions: ${sessions.length} seeded (${totalObs} observations)`,
"",
- "Search results:",
+ c.label("Search results:"),
...results.flatMap((r) => [
- ` "${r.query}"`,
- ` → ${r.hits} hit(s), top: ${r.topTitle.slice(0, 60)}`,
+ ` ${c.label(`"${r.query}"`)}`,
+ ` ${c.dim("→")} ${c.ok(`${r.hits} hit(s)`)}, top: ${r.topTitle.slice(0, 60)}`,
]),
"",
- `Notice: searching "database performance optimization"`,
- `found the N+1 query fix — keyword matching can't do that.`,
+ c.accent(`Notice: searching "database performance optimization"`),
+ c.accent(`found the N+1 query fix — keyword matching can't do that.`),
"",
- `Viewer: ${getViewerUrl()}`,
- `Clean up with: curl -X DELETE "${base}/agentmemory/sessions?project=${demoProject}"`,
+ `Viewer: ${c.url(getViewerUrl())}`,
+ `Clean up with: ${c.dim(`curl -X DELETE "${base}/agentmemory/sessions?project=${demoProject}"`)}`,
];
p.note(lines.join("\n"), "demo complete");
@@ -2264,7 +2314,7 @@ function runCommand(
});
if (result.status === 0) {
- spinner.stop(`${options.label} ✓`);
+ spinner.stop(`${options.label} ${pc.green("✓")}`);
return true;
}
@@ -2278,7 +2328,7 @@ function runCommand(
return false;
}
- spinner.stop(`${options.label} ✗`);
+ spinner.stop(`${options.label} ${pc.red("✗")}`);
p.log.error(msg.slice(0, 300));
return false;
}
@@ -2484,7 +2534,7 @@ async function runStop(): Promise<void> {
const portPids = findEnginePidsByPort(port);
const pidfilePid = readEnginePidfile();
- // #640 + #474: read the worker pid up front so the engine-down branch
+ // read the worker pid up front so the engine-down branch
// can still reap an orphaned worker process (the common failure mode
// where a wrapper script kept the worker alive across engine restarts).
const workerPid = readWorkerPidfile();
@@ -2546,7 +2596,7 @@ async function runStop(): Promise<void> {
if (pidfilePid) candidates.add(pidfilePid);
for (const pid of portPids) candidates.add(pid);
- // #640 + #474: stop must also reap the agentmemory worker process
+ // stop must also reap the agentmemory worker process
// (`node dist/index.mjs`). If only the engine is killed, the worker can
// survive (detached spawn / signal not propagated) and reconnect to the
// next engine as a duplicate registration. workerPid was read above so
@@ -2562,7 +2612,7 @@ async function runStop(): Promise<void> {
}
let allStopped = true;
- // #843: stop worker first, then engine. The worker's shutdown
+ // stop worker first, then engine. The worker's shutdown
// handler calls indexPersistence.save() -> kv.set() -> iii state::set
// to flush BM25/vector snapshots + audit rows. Killing iii first
// leaves those writes with no engine to land on, and the index +
diff --git a/src/cli/connect/index.ts b/src/cli/connect/index.ts
index 6512c5bd..0d9412ca 100644
--- a/src/cli/connect/index.ts
+++ b/src/cli/connect/index.ts
@@ -1,5 +1,6 @@
import { platform } from "node:os";
import * as p from "@clack/prompts";
+import pc from "picocolors";
import type { ConnectAdapter, ConnectOptions, ConnectResult } from "./types.js";
import { adapter as antigravity } from "./antigravity.js";
import { adapter as claudeCode } from "./claude-code.js";
@@ -177,13 +178,13 @@ function summarize(
const lines = results.map(({ name, result }) => {
switch (result.kind) {
case "installed":
- return ` ✓ ${name}${result.mutatedPath ? ` → ${result.mutatedPath}` : ""}`;
+ return ` ${pc.green("✓")} ${pc.bold(name)}${result.mutatedPath ? ` ${pc.dim("→")} ${pc.cyan(result.mutatedPath)}` : ""}`;
case "already-wired":
- return ` ✓ ${name} (already wired)`;
+ return ` ${pc.green("✓")} ${pc.bold(name)} ${pc.dim("(already wired)")}`;
case "stub":
- return ` ⚠ ${name} (manual install required: ${result.reason})`;
+ return ` ${pc.yellow("⚠")} ${pc.bold(name)} ${pc.yellow(`(manual install required: ${result.reason})`)}`;
case "skipped":
- return ` ✗ ${name} (skipped: ${result.reason})`;
+ return ` ${pc.red("✗")} ${pc.bold(name)} ${pc.dim(`(skipped: ${result.reason})`)}`;
}
});
p.note(lines.join("\n"), "summary");
diff --git a/src/config.ts b/src/config.ts
index f68da2e3..3348ac22 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -1,6 +1,7 @@
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";
+import pc from "picocolors";
import type {
AgentMemoryConfig,
ProviderConfig,
@@ -126,15 +127,11 @@ function detectProvider(env: Record<string, string>): ProviderConfig {
const allowAgentSdk = env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true";
if (!allowAgentSdk) {
process.stderr.write(
- "[agentmemory] No LLM provider key found " +
- "(ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, MINIMAX_API_KEY, OPENAI_API_KEY). " +
- "LLM-backed compression and summarization are DISABLED — using no-op provider. " +
- "This is the safe default: the agent-sdk fallback used to spawn Claude Agent SDK " +
- "child sessions which inherit Claude Code's plugin hooks and cause infinite Stop-hook " +
- "recursion (#149 follow-up). To opt in to the agent-sdk fallback anyway, set both " +
- "AGENTMEMORY_AUTO_COMPRESS=true AND AGENTMEMORY_ALLOW_AGENT_SDK=true — but be aware " +
- "it will burn your Claude Pro allocation and may still recurse if you use it from " +
- "inside Claude Code itself.\n",
+ pc.dim(
+ "[agentmemory] No LLM provider key set — running zero-LLM (BM25 + on-device embeddings). " +
+ "Set ANTHROPIC_API_KEY (or GEMINI/OPENAI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env for LLM compression and summaries. " +
+ "Agent-SDK fallback stays off by default to avoid a Stop-hook recursion loop; opt in with AGENTMEMORY_AUTO_COMPRESS=true + AGENTMEMORY_ALLOW_AGENT_SDK=true.\n",
+ ),
);
return {
provider: "noop",
@@ -146,7 +143,7 @@ function detectProvider(env: Record<string, string>): ProviderConfig {
process.stderr.write(
"[agentmemory] WARNING: agent-sdk fallback enabled via AGENTMEMORY_ALLOW_AGENT_SDK=true. " +
"This spawns @anthropic-ai/claude-agent-sdk child sessions that can trigger the Stop-hook " +
- "recursion loop (#149 follow-up). A SDK-child env marker is set to block re-entry, " +
+ "recursion loop. A SDK-child env marker is set to block re-entry, " +
"but prefer setting a real API key in ~/.agentmemory/.env instead.\n",
);
return {
@@ -164,7 +161,7 @@ export function loadConfig(): AgentMemoryConfig {
// Port quartet: REST is the anchor; streams/engine derive from it
// unless individually overridden. Default anchor 3111 yields the
// canonical 3112 streams / 49134 engine pair, but `III_REST_PORT=3211`
- // auto-picks 3212 + 49234 so a second instance doesn't collide (#750).
+ // auto-picks 3212 + 49234 so a second instance doesn't collide.
const restPort = parseInt(env["III_REST_PORT"] || "3111", 10) || 3111;
const streamsPort =
parseInt(env["III_STREAM_PORT"] || env["III_STREAMS_PORT"] || "", 10) ||
@@ -336,7 +333,7 @@ export function getGraphBatchSize(): number {
return safeParseInt(getMergedEnv()["GRAPH_EXTRACTION_BATCH_SIZE"], 10);
}
-// #771: window for the smart-search followup-rate diagnostic. A second
+// window for the smart-search followup-rate diagnostic. A second
// search arriving within this many seconds (with disjoint results)
// counts as a "follow-up" — a directional signal that the first result
// set didn't satisfy. Long values overcount (legitimate refinement
@@ -376,7 +373,7 @@ function hasLLMProviderConfigured(env: Record<string, string | undefined>): bool
);
}
-// Per-observation LLM compression is OFF by default as of 0.8.8 (see #138).
+// Per-observation LLM compression is OFF by default as of 0.8.8.
// When disabled, observations are captured and indexed via a synthetic
// (zero-LLM) compression path so recall/search still works. Users who want
// richer LLM-generated summaries can set AGENTMEMORY_AUTO_COMPRESS=true in
@@ -387,7 +384,7 @@ export function isAutoCompressEnabled(): boolean {
}
// Hook-level context injection into Claude Code's conversation is OFF by
-// default as of 0.8.10 (see #143). When disabled, pre-tool-use and
+// default as of 0.8.10. When disabled, pre-tool-use and
// session-start hooks still POST observations for background capture, but
// never write context to stdout — so Claude Code doesn't inject an extra
// ~4000-char blob into every tool turn. 0.8.8 stopped the agentmemory-side
@@ -446,7 +443,7 @@ export function loadFallbackConfig(): FallbackConfig {
"[agentmemory] Ignoring FALLBACK_PROVIDERS entry 'agent-sdk' " +
"(AGENTMEMORY_ALLOW_AGENT_SDK is not 'true'). The agent-sdk " +
"fallback can spawn Claude Agent SDK child sessions that trigger " +
- "the Stop-hook recursion loop (#149 follow-up). Opt in explicitly " +
+ "the Stop-hook recursion loop. Opt in explicitly " +
"with AGENTMEMORY_ALLOW_AGENT_SDK=true if this is intentional.\n",
);
return false;
diff --git a/src/functions/image-quota-cleanup.ts b/src/functions/image-quota-cleanup.ts
index b32bf1f1..d07dfa96 100644
--- a/src/functions/image-quota-cleanup.ts
+++ b/src/functions/image-quota-cleanup.ts
@@ -4,7 +4,6 @@ import { StateKV } from "../state/kv.js";
import { readdir, stat } from "node:fs/promises";
import { join } from "node:path";
import { IMAGES_DIR, getMaxBytes, deleteImage } from "../utils/image-store.js";
-import { getImageRefCount } from "./image-refs.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { logger } from "../logger.js";
@@ -56,6 +55,7 @@ export function registerImageQuotaCleanup(sdk: ISdk, kv: StateKV): void {
await withKeyedLock(`imgRef:${f.filePath}`, async () => {
let refCount: number;
try {
+ const { getImageRefCount } = await import("./image-refs.js");
refCount = await getImageRefCount(kv, f.filePath);
} catch (err) {
// Fail-closed: if we cannot determine refCount we must NOT
diff --git a/src/functions/observe.ts b/src/functions/observe.ts
index 2bf13d54..8ad4ba0f 100644
--- a/src/functions/observe.ts
+++ b/src/functions/observe.ts
@@ -10,6 +10,7 @@ import { buildSyntheticCompression } from "./compress-synthetic.js";
import { getSearchIndex, vectorIndexAddGuarded } from "./search.js";
import { getAgentId } from "../config.js";
import { logger } from "../logger.js";
+import { saveImageToDisk } from "../utils/image-store.js";
export function extractImage(d: unknown): string | undefined {
if (!d) return undefined;
@@ -151,7 +152,6 @@ export function registerObserveFunction(
}
if (pendingImageData && (pendingImageData.startsWith("data:image/") || pendingImageData.startsWith("iVBORw0KGgo") || pendingImageData.startsWith("/9j/"))) {
- const { saveImageToDisk } = await import("../utils/image-store.js");
const { filePath, bytesWritten } = await saveImageToDisk(pendingImageData);
raw.imageData = filePath;
const { incrementImageRef } = await import("./image-refs.js");
@@ -180,13 +180,19 @@ export function registerObserveFunction(
} catch (error) {
if (raw.imageData) {
- const { deleteImage } = await import("../utils/image-store.js");
- const { deletedBytes } = await deleteImage(raw.imageData);
- if (deletedBytes > 0) {
- sdk.trigger({
- function_id: "mem::disk-size-delta",
- payload: { deltaBytes: -deletedBytes },
- action: TriggerAction.Void(),
+ // Roll back the ref taken above. decrementImageRef deletes the file
+ // only when no other observation still references it (deduped images
+ // survive) and emits the disk-size delta itself — deleting the file
+ // directly here would orphan shared images and leave a stale ref.
+ // If the rollback itself fails, log it but still surface the
+ // original write error (the more useful failure to diagnose).
+ try {
+ const { decrementImageRef } = await import("./image-refs.js");
+ await decrementImageRef(kv, sdk, raw.imageData);
+ } catch (rollbackError) {
+ logger.error("Failed to roll back image ref after observation write failure", {
+ imageRef: raw.imageData,
+ error: rollbackError instanceof Error ? rollbackError.message : String(rollbackError),
});
}
}
@@ -274,7 +280,7 @@ export function registerObserveFunction(
});
}
- // Per-observation LLM compression is opt-in as of 0.8.8 (#138).
+ // Per-observation LLM compression is opt-in as of 0.8.8.
// Default path: build a zero-LLM synthetic compression so recall
// and BM25 search still work without burning the user's Claude
// token allocation on every tool invocation.
diff --git a/src/index.ts b/src/index.ts
index 4233e8a6..1e623eae 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -276,21 +276,21 @@ async function main() {
if (isAutoCompressEnabled()) {
bootLog(
- `WARNING: AGENTMEMORY_AUTO_COMPRESS=true — every PostToolUse observation will be sent to your LLM provider for compression. This spends API tokens proportional to your session tool-use frequency (see #138). Set AGENTMEMORY_AUTO_COMPRESS=false to disable.`,
+ `WARNING: AGENTMEMORY_AUTO_COMPRESS=true — every PostToolUse observation will be sent to your LLM provider for compression. This spends API tokens proportional to your session tool-use frequency. Set AGENTMEMORY_AUTO_COMPRESS=false to disable.`,
);
} else {
bootLog(
- `Auto-compress: OFF (default, #138) — observations indexed via zero-LLM synthetic compression. Set AGENTMEMORY_AUTO_COMPRESS=true to opt-in to LLM-powered summaries (uses your API key).`,
+ `Auto-compress: OFF (default) — observations indexed via zero-LLM synthetic compression. Set AGENTMEMORY_AUTO_COMPRESS=true to opt-in to LLM-powered summaries (uses your API key).`,
);
}
if (isContextInjectionEnabled()) {
bootLog(
- `WARNING: AGENTMEMORY_INJECT_CONTEXT=true — the PreToolUse and SessionStart hooks will inject up to ~4000 chars of memory context into every tool turn. On Claude Pro this burns session tokens proportional to your tool-call frequency (see #143). Set AGENTMEMORY_INJECT_CONTEXT=false to disable.`,
+ `WARNING: AGENTMEMORY_INJECT_CONTEXT=true — the PreToolUse and SessionStart hooks will inject up to ~4000 chars of memory context into every tool turn. On Claude Pro this burns session tokens proportional to your tool-call frequency. Set AGENTMEMORY_INJECT_CONTEXT=false to disable.`,
);
} else {
bootLog(
- `Context injection: OFF (default, #143) — hooks capture observations but do not inject context into Claude Code's conversation. Set AGENTMEMORY_INJECT_CONTEXT=true to opt-in (warning: expect your Claude Pro allocation to drain faster).`,
+ `Context injection: OFF (default) — hooks capture observations but do not inject context into Claude Code's conversation. Set AGENTMEMORY_INJECT_CONTEXT=true to opt-in (warning: expect your Claude Pro allocation to drain faster).`,
);
}
@@ -498,7 +498,7 @@ async function main() {
}
if (backfilled > 0) {
bootLog(
- `Backfilled ${backfilled} memories into BM25 (legacy gap before #257)`,
+ `Backfilled ${backfilled} memories into BM25 (legacy index gap)`,
);
indexPersistence.scheduleSave();
}
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 28076e09..5cf10846 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -19,22 +19,29 @@ const hookEntries = [
const shared = {
format: ["esm"] as const,
target: "node20" as const,
- inlineOnly: false as const,
- // Keep as node_modules imports. We never import onnxruntime-{node,web}
- // directly; they come in transitively through @xenova/transformers, which
- // is lazy-loaded from src/providers/embedding/{clip,local}.ts and
- // src/state/reranker.ts. Bundling inlines relative paths like
+ // Keep these as node_modules imports (deps.neverBundle). We never import
+ // onnxruntime-{node,web} directly; they come in transitively through
+ // @xenova/transformers, which is lazy-loaded from
+ // src/providers/embedding/{clip,local}.ts and src/state/reranker.ts.
+ // Bundling inlines relative paths like
// `../bin/napi-v3/darwin/arm64/onnxruntime_binding.node` that no longer
- // resolve from dist/. All three are declared as optionalDependencies in
+ // resolve from dist/. All are declared as optionalDependencies in
// package.json so users can install them only when they enable local
// embeddings / CLIP / reranker.
- external: [
- "@xenova/transformers",
- "onnxruntime-node",
- "onnxruntime-web",
- "@anthropic-ai/claude-agent-sdk",
- "@anthropic-ai/sdk",
- ] as const,
+ deps: {
+ neverBundle: [
+ "@xenova/transformers",
+ "onnxruntime-node",
+ "onnxruntime-web",
+ "@anthropic-ai/claude-agent-sdk",
+ "@anthropic-ai/sdk",
+ ],
+ },
+ // Each entry is its own build, so the per-entry dts/deps timing notice
+ // fires ~30 times and drowns the real output. It is informational only.
+ inputOptions: {
+ checks: { pluginTimings: false },
+ },
};
export default defineConfig([