diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md index 981c3893d..f368220b3 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 ` or `--instance ` 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 c4ec2c1e0..d04da3712 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` | | 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=` | 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 ``` -`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 1dc2b525c..8d92f8afd 100644 --- a/READMEs/README.de-DE.md +++ b/READMEs/README.de-DE.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` 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 ``` -`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 ff780cbe1..3245e2113 100644 --- a/READMEs/README.es-ES.md +++ b/READMEs/README.es-ES.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` | | 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 ``` -`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 c2b464ecc..b72b503fa 100644 --- a/READMEs/README.fr-FR.md +++ b/READMEs/README.fr-FR.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` | | 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 ``` -`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 412e6f844..00358fad1 100644 --- a/READMEs/README.hi-IN.md +++ b/READMEs/README.hi-IN.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` का उपयोग करें | | 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 ``` -`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 a117b2257..979094f6b 100644 --- a/READMEs/README.ja-JP.md +++ b/READMEs/README.ja-JP.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` を使用 | | 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 ``` -`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 76bcc1d7b..369797c35 100644 --- a/READMEs/README.ko-KR.md +++ b/READMEs/README.ko-KR.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` 사용 | | 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 ``` -`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 bd3777a90..e9bbc32e3 100644 --- a/READMEs/README.pt-BR.md +++ b/READMEs/README.pt-BR.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` | | 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 ``` -`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 2bd659682..804f380c0 100644 --- a/READMEs/README.ru-RU.md +++ b/READMEs/README.ru-RU.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` | | Откат на 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 ``` -`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 c97249acd..28fad8076 100644 --- a/READMEs/README.tr-TR.md +++ b/READMEs/README.tr-TR.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` 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 ``` -`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 cc9a01a15..e711a3673 100644 --- a/READMEs/README.zh-CN.md +++ b/READMEs/README.zh-CN.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` | | 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 ``` -`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 ace349b7e..75b2fc976 100644 --- a/READMEs/README.zh-TW.md +++ b/READMEs/README.zh-TW.md @@ -49,7 +49,6 @@

npm version - npm downloads CI License Stars @@ -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 ` | | 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 ``` -`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 3f6c433ff..48c8d59d5 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 149f806d0..73d536614 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 89257f937..3769815d9 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 89257f937..3769815d9 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 89257f937..3769815d9 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 c96516d07..d26946932 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 3c7cb5375..4e2bc8c4c 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 48f6f09b6..93b907491 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 { 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 )` - : `iii console (install: ${iiiConsoleInstallHint()})`; + `${c.label("iii console")} ${c.dim(consoleState.binPath)} ${c.dim(`(run: ${consoleState.binPath} -p )`)}` + : `${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 { 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 { 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 { } 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 6512c5bd8..0d9412ca6 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 f68da2e31..3348ac226 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): 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): 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): 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 b32bf1f1d..d07dfa969 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 2bf13d547..8ad4ba0ff 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 4233e8a67..1e623eae8 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 28076e09c..5cf108468 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([