0.9.21 — 2026-05-19

Quality + integration wave. Headline: native OpenCode plugin with full Claude Code hook parity (#237 by @cl0ckt0wer). Ten more PRs alongside: memory_recall returning the wrong shape, env-file AGENTMEMORY_DROP_STALE_INDEX silently ignored, hook scripts crashing on Windows usernames with spaces, viewer search inputs interrupting CJK IME composition, large sessions silently failing at the LLM context limit, lessons invisible to smart-search, Hermes plugin manifest missing hooks, cli onboarding crashing in non-TTY contexts, rebuildIndex blocking boot on large corpora, 25h embed-loop bottleneck during rebuild, and the v0.9.19 iii-console installer workaround can come out now that upstream is fixed.

Added

• OpenCode plugin with 22 auto-capture hooks (PR #237 by @cl0ckt0wer, closes #236 + #244). Complete OpenCode plugin in plugin/opencode/ matching Claude Code hook parity. Covers session lifecycle (8 hooks), messages (3), tool lifecycle (2), part tracking, permissions, task tracking, plus a two-layer enrichment pipeline (memory context on first turn, file enrichment on subsequent turns) and two slash commands (/recall, /remember). Full gap analysis in plugin/opencode/README.md.

Fixed

• memory_recall endpoint + format/token_budget forwarding (PR #516 by @serhiizghama, closes #507 + #440). MCP memory_recall always returned compact mode and dropped format + token_budget params. Two root causes fixed: standalone shim routed through /agentmemory/smart-search instead of /agentmemory/search, and the local-fallback path didn't read either param. Now routes correctly, forwards both params end-to-end, defaults format to "full" matching the MCP schema.

• env-file AGENTMEMORY_DROP_STALE_INDEX flag now honored (PR #461 by @honor2030, closes #456). Setting the flag in ~/.agentmemory/.env was silently ignored because the boot path read process.env directly. New isDropStaleIndexEnabled() helper reads merged env. Combined with #455 + #469 reports, this is the unblock path for the stale-index server-crash recovery loop.

• Windows hook scripts quote plugin paths correctly (PR #487 by @honor2030, closes #477). Hook command strings referenced ${CLAUDE_PLUGIN_ROOT}/scripts/*.mjs without quotes — Windows users with spaces in their username had every hook crash. Quotes added + regression test.

• Viewer search inputs honor IME composition (PR #517 by @jonathanzhan1975). CJK users typing in the viewer's search inputs hit mid-character interruption — every keystroke fired the oninput= re-render handler, breaking IME composition mid-syllable. New bindImeSafeSearch helper defers re-render until compositionend.

• Chunk large sessions to fit LLM context window (PR #472 by @efenex). Sessions with >7000 observations silently failed at the LLM provider's context limit — the consolidation pipeline silently skipped the session. New chunking splits oversized sessions across multiple compress calls + restitches the narrative via a REDUCE_SYSTEM prompt. Legacy single-call path preserved when obs count is under the chunk size. Backfill script under scripts/ for users hitting the pre-fix bug.

• Surface lessons in smart-search + diagnose tally (PR #473 by @efenex). Closes the lesson round-trip with #458 (lessons auto-injected into mem::context): lessons are now also returned alongside hybrid search results in a separate lessons field on smart-search, and the diagnose health surface tallies per-store counts so the trust-shock pattern (save succeeds, recall empty, diagnose says 0) goes away.

• Declare all Hermes plugin hooks (PR #486 by @honor2030). The Hermes plugin.yaml manifest only declared 3 of the 6 implemented hooks. All 6 now declared (prefetch, sync_turn, on_session_end, on_pre_compress, on_memory_write, system_prompt_block).

• rebuildIndex non-blocking on boot (PR #500 by @efenex). Boot path previously await-ed rebuildIndex(kv), so the viewer + later boot steps stalled — on large corpora this was 25h+ of blocked startup. Replaced with void rebuildIndex(kv).then(...).catch(...) so the rebuild runs in the background.

• Batched embed calls in rebuildIndex (25h → 3h on large corpora) (PR #504 by @efenex). The rebuild loop made one embed call per observation, paying full HTTP RTT per item. New vectorIndexAddBatchGuarded helper batches embeds (default 32, configurable via REBUILD_EMBED_BATCH_SIZE) and try/catches per-item failures. Measured 25h → 3h on a 250k-observation corpus.

• CLI skips onboarding prompts without a tty (PR #491 by @honor2030). Onboarding prompts crashed in non-interactive contexts (CI, docker run -d, piped input). New guard short-circuits with sensible defaults when stdin/stdout aren't TTYs or CI=1.

Changed

• Drop iii-console installer --next workaround (PR #546). v0.9.19 routed first-run iii-console install through bash -s -- --next to dodge an upstream tag-prefix bug at iii-hq/iii#1652. Upstream iii-hq/iii#1660 shipped 2026-05-19; install.iii.dev/console/main/install.sh is a CDN proxy serving upstream main HEAD so the fix is live without an iii release tag. Reverted to canonical bare curl ... | sh.

Infrastructure

• 95 test files (was 92), 1067 tests pass (was 1038) on chore(release): v0.9.21.
• Bundles 11 PRs: 1 contributor feature + 9 bug fixes across MCP / hooks / viewer / summarize / lessons / Hermes / rebuildIndex / CLI + 1 upstream-installer revert.
• New contributors landing first PRs this release: @cl0ckt0wer, @serhiizghama, @jonathanzhan1975.

0.9.20 — 2026-05-18

Hotfix: revert the Codex Stop → session-end chain shipped in v0.9.19.

Fixed

• Revert Codex Stop hook session-end chain (PR #501 by @Rex57, reverts v0.9.19's #495, re-opens #493). Post-merge field-testing surfaced the underlying issue: Codex Stop fires before the overall conversation is truly finished — multiple Stops bracket each assistant turn within one session. Chaining session-end.mjs from Stop marked sessions completed too early, with later observations still arriving against an endedAt-stamped record. Restored to summarize-only Stop; the SessionEnd-shaped solution stays open as #493.

0.9.19 — 2026-05-18

Feature + hardening wave. Sessions now link to the git commits they shipped (forward + reverse lookup, REST + MCP surfaces). OpenAI provider transport collapses into one shared module with auto-detected Azure URL style (legacy /openai/deployments/<dep> and v1 /openai/v1 both supported). Graph retrieval switches from BFS to Dijkstra over the weighted edge graph. Codex Stop hook chains session-end. Plugin MCP server inherits AGENTMEMORY_URL / AGENTMEMORY_SECRET from the shell. Point fix routes the bundled iii-console installer around an upstream tag-prefix bug. 1007+ tests pass.

Added

• Session-to-commit linking (PR #498). New KV.commits namespace keyed by full SHA holds CommitLink records (sha, shortSha, branch, repo, message, author, authoredAt, files, sessionIds). Session.commitShas[] provides the forward back-reference. REST: POST /agentmemory/session/commit upserts links (merges sessionIds on re-link, preserves linkedAt); GET /agentmemory/commits/:sha and GET /agentmemory/commits round-trip. MCP: memory_commit_lookup and memory_commits tools. Post-commit hook auto-captures the link on every commit in the working directory. Closes the loop on "what session wrote this code" / "what commits did this session ship" without leaving agentmemory.

• Azure OpenAI v1 URL pattern auto-detection (PR #462, closes #371). Both the LLM and embedding providers now route through _openai-shared.ts and auto-detect Azure URL style:

  • OPENAI_BASE_URL=https://r.openai.azure.com/openai/deployments/<dep> → legacy URL pattern, api-version query param via OPENAI_API_VERSION (default 2024-08-01-preview).
  • OPENAI_BASE_URL=https://r.openai.azure.com (bare host, or /openai, or /openai/v1) → v1 GA pattern, /openai/v1/<route>, deployment name carried in the request body as model.
  • Net effect: Azure embeddings work for the first time (LLM-side Azure shipped in v0.9.17; embedding was still hardcoded to /v1/embeddings + Bearer). Closes #199 (consolidation) as superseded.

Changed

• Graph retrieval: BFS → Dijkstra over weighted edges (PR #463, closes #328 filed by @Tanmay-008 with benchmark numbers showing the BFS edge-count semantics + O(n) Array.shift() profile). Memory graph edges carry weights 0.1–1.0; BFS visited by edge-count regardless, so a one-hop weak edge ranked the same as a two-hop strong chain. Dijkstra over cost = 1/max(weight, 0.01) selects weight-optimal paths instead. Adjacency map built once in O(V+E) and min-heap dequeue at O(log V) replace the prior O(V·E) + O(n) Array.shift() profile. maxDepth semantics preserved (still edge-count bound). The startNode path is excluded from returned paths so the dedicated score=1.0 fallback loop in searchByEntities fires as designed (regression catch from the inline review).

• Codex Stop hook chains session-end (PR #495 by @Rex57, fixes #493 also filed by @Rex57). hooks.codex.json Stop now runs stop.mjs followed by session-end.mjs. Codex doesn't ship a separate SessionEnd lifecycle event, so the session would otherwise stay open after the user terminated the Codex session. Tests assert both commands appear in the Stop chain.

• Plugin MCP entry inherits shell env via passthrough (PR #460, closes #375 filed by @anthony-spruyt). plugin/.mcp.json and AGENTMEMORY_MCP_BLOCK (the template agentmemory connect <agent> writes into ~/.claude.json, ~/.cursor/mcp.json, etc.) now declare env: { AGENTMEMORY_URL: "${AGENTMEMORY_URL}", AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET}" }. The MCP host substitutes shell values at server launch. When the vars are unset, the host passes empty strings; the standalone shim's process.env["AGENTMEMORY_URL"] || "http://localhost:3111" falls back to localhost. One wired entry now covers both local and remote (k8s / reverse-proxied) deployments without /doctor "duplicate server" warnings.

Fixed

• ensureIiiConsole() install path (src/cli.ts). The upstream install.iii.dev/console/main/install.sh script's jq predicate filters releases with startswith("v") while iii-hq/iii tags as iii/v0.12.0. The script bails with no stable iii release found on every fresh install. Switched the install command to curl ... | bash -s -- --next until upstream patches the script — the --next codepath uses a regex on -next. without the buggy startswith constraint, so it succeeds against the same tag set. Inline comment documents the upstream bug + revert condition.

Infrastructure

• 91 test files, 1007 tests pass on chore(release): v0.9.19.
• Bundles five PRs (#460, #462, #463, #495, #498) plus the inline iii-console installer workaround into one patch release.

[0.9.18] — 2026-05-17

Hardening + DX wave. Five fixes land together: lessons now flow into the auto-inject context payload (closes a half-finished loop from earlier releases — see #381 / #457), the viewer drops data: from its img-src CSP by self-hosting its favicon, the filesystem watcher redacts PEM private-key blocks and standalone JWTs before transport, the mcp-standalone livez probe gets a dependency-injection seam that kills a flaky test, and the OpenAI timeout precedence is documented + tightened (strict integer parse, OPENAI_TIMEOUT_MS keeps its v0.9.17 meaning as an alias of the global AGENTMEMORY_LLM_TIMEOUT_MS). 1007/1007 tests pass.

Added

• Lessons auto-injected into mem::context payload (PR #458, closes #457, surfaced in discussion #381). Lessons were generated + stored but only retrievable via an explicit memory_lesson_recall MCP call — agents rarely thought to invoke it, so the loop was half-done. mem::context now reads KV.lessons alongside slots + profile, ranks by (project-relevance × confidence) (project-scoped lessons get a 1.5× boost), filters tombstoned + cross-project entries, caps at top-10, and emits a ## Lessons Learned block competing fairly for the token budget. Block recency tracks the most-recent lastReinforcedAt || updatedAt, so hot lessons survive when budget tightens.

• Self-hosted viewer favicon (PR #452, closes #447). The viewer's inline-SVG data: favicon (added in #313) required data: in img-src — a broader allowance than the viewer actually needed. The favicon now lives at /favicon.svg served by the viewer with Content-Type: image/svg+xml and Cache-Control: public, max-age=3600; build script copies the asset into dist/viewer/ alongside index.html. CSP reverts to bare img-src 'self'.

Changed

• OPENAI_TIMEOUT_MS is now an alias of AGENTMEMORY_LLM_TIMEOUT_MS (PR #453, closes #446). v0.9.17 shipped OPENAI_TIMEOUT_MS as the OpenAI-scoped knob, then PR #379 introduced the global AGENTMEMORY_LLM_TIMEOUT_MS shared across all raw-fetch providers. The OpenAI provider now resolves them in precedence order: OPENAI_TIMEOUT_MS → AGENTMEMORY_LLM_TIMEOUT_MS → 60_000ms default. v0.9.17 configs keep working unchanged; new configs should prefer the global. The provider's request also moved onto the shared fetchWithTimeout helper that owns AbortController + clearTimeout cleanup for every raw-fetch path (minimax, openrouter, gemini, embedding providers).

• Strict integer parse for timeout env vars (PR #453, CodeRabbit catch). parsePositiveInt rejects values like "30ms", "1_000", "60s", "30abc", "-30", "0" via /^\d+$/ (after trim) instead of letting parseInt's lenience silently swallow trailing units / underscores / signs as a number. Malformed values fall back to the 60s default with no surprise truncation.

Fixed

• Filesystem watcher redacts PEM private-key blocks + standalone JWTs in previews (PR #450, closes #448). Continues the redaction surface opened in PR #332. PEM blocks (-----BEGIN ... PRIVATE KEY----- through -----END ... PRIVATE KEY-----, including encrypted, RSA, EC, DSA, OpenSSH, PGP variants) get a state-machine pass that replaces the whole block with a single [REDACTED ... PRIVATE KEY] marker; standalone JWT-shaped tokens (three base64url segments separated by dots, length ≥ ~32 chars) are masked to their last 4 chars. Both run before any transport-layer write.

• mcp-standalone livez probe DI seam kills the test flake (PR #451, closes #449). The standalone shim's livez probe used a fixed fetch against localhost:3111 which made the test suite depend on no other agentmemory instance running on the host. New setLivezProbe() injection seam lets tests provide a deterministic probe; default behaviour for production users is unchanged.

Infrastructure

• 91 test files (was 90), 1007 tests (was 992). New test/context-lessons.test.ts (8 cases) covers lessons-auto-inject inclusion, empty-state no-op, project ranking, cross-project isolation, soft-delete skip, top-10 cap, confidence rendering, optional context string append.

• Bundled the four follow-up issues filed during the v0.9.17 audit wave (#446, #447, #448, #449) plus the cross-project lesson-injection gap surfaced in discussion #381 into a single patch release — no behaviour changes for existing users beyond the hardening above.

OpenAI-compatible LLM provider lands the universal-adapter shape — one config (OPENAI_API_KEY + OPENAI_BASE_URL + OPENAI_MODEL) covers OpenAI, Azure OpenAI (auto-detected from hostname), DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama (via /v1), and any future endpoint mirroring POST /v1/chat/completions. Worker telemetry now pins a stable project_name so engine metrics + traces attribute cleanly. agent-memory.dev Compare section no longer wraps awkwardly.

Added

• OpenAI-compatible LLM provider (#307, @fatinghenji). Closes #185, #232 (Ollama works via OPENAI_BASE_URL=http://localhost:11434/v1), #312, supersedes #240.

• Azure OpenAI auto-detection. .openai.azure.com hostname → swaps Authorization: Bearer for api-key, drops /v1 path prefix, appends api-version=<version> query (default 2024-08-01-preview, override via OPENAI_API_VERSION).

• OPENAI_TIMEOUT_MS env var. AbortController-bounded fetch, default 60s, clear timeout error with the env-var hint. Other raw-fetch providers tracked in #373.

• OPENAI_REASONING_EFFORT passthrough. Forwarded as reasoning_effort on the request body for OpenAI reasoning models (o1, o3, gpt-*-reasoning) and providers that mirror that schema. Standard chat models reject the field with 400 — README documents the caveat. Falls back to message.reasoning when message.content is empty (Ollama Cloud thinking-model shape).

Changed

• telemetry.project_name pinned to "agentmemory" (#426). iii-sdk auto-detection produces inconsistent identifiers per host (agentmemory, node, npm, occasionally the user's home dir basename via npx). Pinning gives every install the same stable identifier in engine metrics + traces. Also pins language and framework.

• OPENAI_API_KEY_FOR_LLM=false opt-out. detectLlmProviderKind now mirrors detectProvider's existing gate — users who set OPENAI_API_KEY only for embeddings won't see the LLM auto-activate. README leads with an explicit shared-use callout.

• Compare section (#427). Title AGENTMEMORY VS. THE FIELD. → VS. THE FIELD. (eyebrow already says VS.). text-wrap: balance globally on .section-title. NATIVE PLUGINS cell 6 (Claude/Codex/OpenClaw/Hermes/pi/OpenHuman) → 6 (names already shown in Agents grid). Row grid rebalanced + word-break: break-word + 24px padding so cells like YES (APACHE-2.0) have breathing room.

Install

npm install -g @agentmemory/agentmemory@0.9.17
agentmemory

Try with any OpenAI-compatible endpoint:

# Standard OpenAI
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

# DeepSeek
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_MODEL=deepseek-chat

# Local Ollama
OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=llama3.1:8b

# Azure (auto-detected by hostname)
OPENAI_API_KEY=...
OPENAI_BASE_URL=https://my-resource.openai.azure.com/openai/deployments/gpt-4o
OPENAI_API_VERSION=2024-08-01-preview

Full changelog: https://github.com/rohitg00/agentmemory/blob/main/CHANGELOG.md#0917--2026-05-16

Two waves: (1) DevEx polish on top of v0.9.15 — 5-port ready panel, iii console install, interactive global-install prompt, onboarding now actually wires the agents you select, MCP reworded as opt-in. (2) Marketing site refresh — new AS FEATURED IN bar (AlphaSignal · Agentic AI Foundation · Trendshift) + Agents/Compare/CommandCenter/Hero updated for the v0.9.15 surface.

Added

• 5-port ready panel (#410). Single clack note replaces the old single-line ready hint. Lists REST / Viewer / Streams / Engine / iii console — all derived from configured env vars (AGENTMEMORY_URL, III_*_PORT, III_ENGINE_URL), not hardcoded localhost.

• iii console install probe + auto-install (#410). ensureIiiConsole() detects the binary on PATH or ~/.local/bin/iii-console. If missing on a TTY, prompts to run curl -fsSL https://install.iii.dev/console/main/install.sh | sh. Console is first-class.

• Interactive global-install prompt (#410). First npx run asks Install agentmemory globally so agentmemory works in any shell? [Y/n]. Yes runs npm install -g @agentmemory/agentmemory@<VERSION> inline. No writes skipGlobalInstall: true to preferences. Fixes the v0.9.15 footgun where agentmemory stop in a new shell hit command not found.

• Onboarding wires selected agents inline (#408). After the multi-select step, asks Wire these agents now? [Y/n] and dispatches each through the same runAdapter the explicit agentmemory connect uses. Successes + failures bucketed in a summary block.

• Memory-share callout (#408). Between multi-select and provider step: All selected agents share the same memory at :3111. A memory saved by Claude Code is visible to Codex + Cursor instantly.

• AS FEATURED IN bar on agent-memory.dev (#415). New FeaturedIn component between Hero and Stats. Three cards with real brand marks: AlphaSignal (180K subs), Agentic AI Foundation (Linux Foundation backed), Trendshift (live badge endpoint).

Changed

• MCP messaging reworded as opt-in (#409). Endpoints summary now reads REST first (REST API: 121 endpoints at ...) with a second line for MCP (MCP surface (opt-in via npx @agentmemory/mcp): 51 tools · 6 resources · 3 prompts). Each connect adapter prints a protocol-note line explaining which surface it's wiring.

• CLI --help mcp description (#409). Now reads Start standalone MCP shim — opt-in surface for MCP-only clients (Cursor, Gemini CLI, etc). REST always available at :3111.

• Engine version-mismatch warning (#410). Was hardcoded v0.9.14+. Now uses ${VERSION} so the string never lies post-release.

• CommandCenter — iii console (#415). OPTIONAL → FIRST-CLASS. Bullet counts bumped to 121 HTTP endpoints to match generated-meta.json.

• Compare table (#415). MCP TOOLS 44 → 51. New REST ENDPOINTS (121) and NATIVE PLUGINS (6 first-party agents) rows.

• Agents grid (#415). FOUR → SIX first-party (added pi + OpenHuman). Codex CLI now reads NATIVE PLUGIN (has hooks).

• Hero CTA (#415). START IN 60 SECONDS → START IN 30 SECONDS.

Fixed

• CLI no longer kills its own parent process. lsof -i :PORT -t returns client PIDs alongside the LISTEN-socket owner — including the CLI's keep-alive fetch. Now restricts to -sTCP:LISTEN and filters process.pid.

• Splash banner ASCII (#411). Broken middle glyphs (_ _ instead of _ __ around the 'n') replaced with verified figlet agentmemory standard-font output. 70 cols × 6 rows.

• README install hoisted to top (#411). Install section moved from line 306 to the top under the nav anchors. 4-line block leading with npm install -g. Quick Start kept below.

Install

npx @agentmemory/agentmemory@0.9.16
# or — recommended:
npm install -g @agentmemory/agentmemory@0.9.16
agentmemory

Full changelog: https://github.com/rohitg00/agentmemory/blob/main/CHANGELOG.md#0916--2026-05-15

DevEx overhaul. Four PRs landed simultaneously rebuilding the first-run experience to SkillKit-grade polish.

Added

• Splash banner + onboarding wizard (#403). Terminal-width-aware ASCII (full at ≥120 cols, compact at 80–119, single-line below 80). First-run flow: multi-select 8 native-plugin agents + 8 MCP-server agents, single-select LLM provider (Anthropic / OpenAI / Gemini / OpenRouter / MiniMax / BM25-only), seeds ~/.agentmemory/.env with the chosen provider's *_API_KEY= line commented.

• ~/.agentmemory/preferences.json (#403). Schema-versioned JSON with smart defaults. Atomic write. Future runs skip the splash.

• agentmemory connect <agent> (#402). Automates native-plugin install for claude-code, codex, cursor, gemini-cli, openclaw end-to-end. Stubs for hermes, pi, openhuman. Each adapter: detect → backup → merge → verify → idempotent on re-run. Supports --dry-run, --force, --all, interactive picker.

• agentmemory remove (#406). Tears down everything we installed: pidfile, state, preferences, backups, ~/.local/bin/iii (only when it matches our installed version), agent connections. Asks separately for .env and memory data dir. Two confirmations by default.

• agentmemory doctor v2 (#406). Interactive Fix/Skip/More/Quit per finding. New flags: --all (auto-fix every finding, for CI), --dry-run.

• agentmemory stop --force (#405). Bypasses Docker-compose heuristic refusal so engines started before v0.9.14 can be torn down without lsof | xargs kill.

• --reset flag. Wipes preferences, re-runs onboarding.

• --verbose / AGENTMEMORY_VERBOSE=1. Restores the pre-v0.9.15 25-line [agentmemory] X engine-boot log stream when debugging.

Changed

• First-run output trimmed from 30+ lines to ~10. The [agentmemory] Worker v0.9.x boot log stream is buffered behind a bootLog shim and only surfaces with --verbose.

• isEngineRunning() short-circuit now adopts the engine (#405). When the CLI finds an existing engine on :3111, it writes ~/.agentmemory/iii.pid and ~/.agentmemory/engine-state.json if neither exists. Closes the migration gap where pre-v0.9.14 engines could not be stopped via agentmemory stop.

• Viewer port auto-bump (#405). :3113 taken → retry 3114 → 3115 → ... up to 3122 before failing loud. Pre-fix was silent skip.

• Engine version-mismatch warning (#405). iii on PATH != IIPINNED_VERSION (v0.11.2) now warns loud with override path. Pre-fix was silent acceptance — v0.11.6 on PATH led to undebuggable EPIPE loops.

• npx PATH hint (#405). Runs invoked via npx get one extra line after engine ready: Tip: install globally for the bare \agentmemory` command: npm install -g @agentmemory/agentmemory. Suppressible via preferences.skipNpxHint`.

Install

npx @agentmemory/agentmemory@0.9.15
# or
npm install -g @agentmemory/agentmemory@0.9.15
agentmemory

Full changelog: https://github.com/rohitg00/agentmemory/blob/main/CHANGELOG.md#0915--2026-05-15

CLI bootstrap rework so npx @agentmemory/agentmemory stops failing on Rancher Desktop and other Docker-shim daemons. The native iii-engine binary is now the first-class start path; Docker becomes opt-in. Also ships agentmemory stop so engines started in the background can be torn down without lsof | xargs kill. README agents grid reorders OpenHuman next to the other native-integration agents.

Added

• agentmemory stop command (#396). Reads ~/.agentmemory/iii.pid first, falls back to lsof -i :PORT -sTCP:LISTEN -t, sends SIGTERM, waits 3s, escalates to SIGKILL. State file (~/.agentmemory/engine-state.json) records whether the engine was started natively or via docker compose up -d, so stop runs docker compose -f <file> down for Docker engines instead of signaling the host's Docker socket proxy by accident.

• AGENTMEMORY_USE_DOCKER=1 env var. Opt-in path for users who want the bundled docker-compose.yml to keep handling iii-engine lifecycle. Without it, the CLI prefers the native binary in ~/.local/bin/iii.

Changed

• startEngine() fallback order rewritten (#396). New tier order: (1) iii on PATH, (2) ~/.local/bin/iii or fallback paths, (3) interactive clack p.select with three choices — auto-install the pinned v0.11.2 binary, use Docker compose, or print manual install instructions and exit, (4) Docker compose only via explicit opt-in or the post-install failure fallback, (5) fail-loud with install instructions. CI / non-TTY environments auto-pick install. The Docker fallback was tier 2 and silently fired on every cold start; on Rancher Desktop docker compose up -d returns 0 even when the daemon's pull silently fails, which produced "engine started but REST never responded" misdiagnoses.

• Installer logic extracted from runUpgrade into runIiiInstaller(). Both first-run and agentmemory upgrade now share the same pinned-v0.11.2 curl-and-tar path.

• README agents grid reordered (#397). Row 1 is now Claude Code → Codex CLI → OpenClaw → Hermes → pi → OpenHuman → Cursor → Gemini CLI.

Fixed

• CLI no longer kills its own parent process. lsof -i :PORT -t returns every PID with an active TCP connection to the port, including the CLI's own keep-alive fetch() from isEngineRunning(). Without a LISTEN filter, agentmemory stop would SIGKILL itself — exit code 137, state files never cleaned up. Now filters to -sTCP:LISTEN and drops process.pid from the candidate set.

• agentmemory stop no longer clears the pidfile when a stale process holds the port. Pre-fix behaviour cleared the pidfile and printed "Nothing to stop" — the next run would silently start a second engine on a port that the first engine still owns. Now preserves the pidfile and surfaces the live PIDs.

• Docker-started engines stop safely. Pre-fix code called findEnginePidsByPort and signaled whatever held :3111. When the engine was started via docker compose up -d, that's the host's Docker socket proxy, not the engine — killing it took down Docker Desktop networking for every other container. The new state file lets runStop detect Docker-managed engines and run docker compose down instead.

Install

npx @agentmemory/agentmemory@0.9.14

Or pin in package.json:

"@agentmemory/agentmemory": "0.9.14"

Full changelog: https://github.com/rohitg00/agentmemory/blob/main/CHANGELOG.md#0914--2026-05-15

Six PRs landed since v0.9.12 — .env.example discovery shipped (#372), CJK BM25 tokenizer landed (#344 / PR #362), benchmark/load-100k.ts load harness landed (#346 / PR #363), one-click deploy templates for fly.io / Railway / Render / Coolify added (#343 / PR #361), Gemini provider defaults moved to current GA models (#246 + #368 / PR #370), and the in-tree Python ecosystem story switched from a duplicate REST client to a one-page iii-sdk example (#342 / PR #364). Plus 14 Dependabot security advisories closed via Next.js + PostCSS bumps.

Contributors

Huge thanks to three external contributors this release:

• @fatinghenji — pre-cleanup work on the OpenAI-compatible LLM provider (PR #240 / PR #307); the universal-adapter shape will land in the next minor once branch maintenance catches up
• @AmmarSaleh50 — Gemini embedding migration with L2-norm + 768-dim plumbing (PR #246, folded into PR #370)
• @yut304 — Gemini LLM default deprecation fix (PR #368, folded into PR #370)

Added

.env.example at repo root + bundled in the npm tarball (#383, closes #372, #47, #293, partial #233)

Every env var actually read by src/ is now documented in one place, grouped by surface: LLM provider, embedding provider, auth, search tuning, behaviour flags, CLI runtime, ports, iii engine pin, Claude Code bridge, Obsidian export. Every line is commented out by default so the file ships as a config template, not a config. The npm package now lists .env.example in its files field so npm i -g @agentmemory/agentmemory carries it.

New agentmemory init CLI command copies the bundled template to ~/.agentmemory/.env if absent; refuses to overwrite an existing config and prints a diff command pointing at the latest template. The exists-check + copy is now a single atomic copyFile(template, target, COPYFILE_EXCL) so two parallel init runs cannot race.

New scripts/check-env-example.mjs CI sync-checker walks every .ts / .mts / .mjs / .js file under src/ and fails CI when the runtime reads an env var the template doesn't document (or vice versa). Plugged into .github/workflows/ci.yml after npm test. Initial bootstrap: 60 keys in sync.

CJK tokenizer for BM25 search (#362, closes #344)

New src/state/cjk-segmenter.ts detects CJK input by Unicode block and routes to @node-rs/jieba (Chinese, native, no model download), tiny-segmenter (Japanese, pure JS, ~25 KB), or rule-based syllable-block split (Korean). Both segmenters declared in optionalDependencies so the base install stays lean; soft-fail with a one-time stderr hint when the dep is missing. Order-preserving single-pass tokenization across mixed CJK + non-CJK runs — regression test for "abc 메모리 def 项目 ghi" returns ["abc","메모리","def","项目","ghi"].

benchmark/load-100k.ts load harness (#363, closes #346)

Hand-rolled, dependency-free harness that seeds N synthetic memories against a local daemon at http://localhost:3111 and records p50 / p90 / p99 latency + throughput for POST /agentmemory/remember, POST /agentmemory/smart-search, and GET /agentmemory/memories?latest=true across the matrix N ∈ {1k, 10k, 100k} × concurrency C ∈ {1, 10, 100}. Content drawn from a seedable mulberry32 PRNG so re-running against the same build produces the same seed corpus. Results land in benchmark/results/load-100k-<short-git-sha>.json. Wired as npm run bench:load.

One-click deploy templates: fly.io / Railway / Render / Coolify (#361, closes #343)

Each template under deploy/<platform>/ ships a multi-stage Dockerfile that COPY --from=iiidev/iii:0.11.2s the engine binary into a node:22-slim runtime, npm-installs @agentmemory/agentmemory under /opt/agentmemory with iii-sdk pinned via package.json overrides (avoids the caret-resolves-to-0.11.6 drift), and runs an entrypoint that rewrites the bundled iii-config.yaml to bind 0.0.0.0 + use absolute /data paths, chowns the platform-mounted volume to node:node via gosu, generates a first-boot HMAC secret, and exec's the agentmemory CLI as the unprivileged node user under tini (with TINI_SUBREAPER=1). Verified end-to-end on fly.io (machine in iad, 1 GB volume, healthcheck passing). Coolify template uses expose: instead of ports: so Traefik handles TLS termination + domain routing.

examples/python/ quickstart via iii-sdk (#364, closes #342)

Quickstart + observation/recall flow showing iii-sdk (Python) calling mem::remember / mem::smart-search / mem::context directly over ws://localhost:49134. Replaces a duplicate-transport Python REST client (initial PR #360, closed) with a single-SDK story — the same iii-sdk install (pip install iii-sdk / cargo add iii-sdk / npm install iii-sdk) talks to every agentmemory function from any language.

Changed

Gemini provider defaults bumped to current GA models (#370, closes #368, #246)

LLM default gemini-2.0-flash → gemini-2.5-flash (the gemini-flash-latest moving alias was rejected — production behaviour should be deterministic from a release perspective).

Embedding default text-embedding-004 → gemini-embedding-001 (the previous default is deprecated and shuts down 2026-01-14 per ai.google.dev/gemini-api/docs/deprecations). Three implementation details ride along:

1. URL path :batchEmbedContent → :batchEmbedContents (plural — the new model's batch endpoint).
2. Every request now sends outputDimensionality: 768 so the returned vectors match GeminiEmbeddingProvider.dimensions = 768 and the index-restore dim guard from #248 — no reindex needed for existing users.
3. Returned vectors are L2-normalized before the result-array push because gemini-embedding-001 does not normalize by default unlike text-embedding-004 — without this the downstream cosine-similarity math silently collapses recall. l2Normalize warns once on a zero-norm embedding so operators can correlate index quality dips with upstream regressions.

Security

14 open Dependabot advisories closed via Next.js + PostCSS bumps (#348)

13 Next.js advisories closed: middleware/proxy bypass, SSRF on WebSocket upgrades, DoS via connection exhaustion, CSP-nonce XSS, image-opt DoS, RSC cache poisoning, beforeInteractive XSS, and segment-prefetch routes — by bumping the website's Next.js to ^16.2.6. The PostCSS XSS-via-unescaped-</style> advisory closed by pinning to ^8.5.10 via overrides in website/package.json. Verified npm audit --omit=dev returns 0 and npm run build clean on Next 16.2.6.

Dependabot now runs weekly against six update streams (npm × 5 paths + github-actions) per the new .github/dependabot.yml.

Install / upgrade

npm i -g @agentmemory/agentmemory@0.9.13
# or
npx @agentmemory/agentmemory@0.9.13

# MCP standalone shim
npx -y @agentmemory/mcp@0.9.13

# After install:
npx @agentmemory/agentmemory init   # copy bundled .env.example to ~/.agentmemory/.env

Full changelog: v0.9.12...v0.9.13

Four landed PRs since v0.9.11 — one type-correctness fix, one search-quality fix (BM25 unicode + vector-index live-write), one viewer hardening (CSP-clean fonts + load-error surface), and one integrations security hardening (bearer token over plaintext HTTP).

Contributors

Huge thanks to four external contributors this release:

• @mvanhorn — plaintext-bearer-auth guard across Hermes (Python), OpenClaw (mjs), and pi (TypeScript) plus the AGENTMEMORY_REQUIRE_HTTPS=1 escalation knob (#315)
• @nik1t7n — original repro for the BM25 non-ASCII tokenizer bug + vector-index-never-populated trace (#295)
• @hem57 — Windows repro screenshot + browser-console CSP-violation trace that pinned down the viewer "stuck Loading" path (#323)
• @cl0ckt0wer — precise file:line trace for the duplicate RetentionScore.source declaration (#277)

Fixed

BM25 tokenizer now indexes non-ASCII; vector index now actually populated at runtime (#327, closes #295)

Two bugs in one PR:

BM25 tokenizer regex stripped every non-ASCII character. src/state/search-index.ts used \w (JS \w is ASCII-only), so non-English search returned empty results across the board — Greek, accented Latin, Hebrew, Arabic, Cyrillic. Regex replaced with /[^\p{L}\p{N}\s/.\\-_]/gu (Unicode letters/numbers, preserves underscore for memory_recall-style identifiers, keeps existing path/separator handling).

VectorIndex.add() had zero callers anywhere in src/. The vector index was loaded from disk at startup and never updated at runtime, so hybrid search returned stale results forever. New vectorIndexAddGuarded() helper in src/functions/search.ts wires vectorIndex.add() into remember.ts, observe.ts synthetic-compression branch, compress.ts post-LLM compression, and the cold-start rebuildIndex() walk — with a per-write dimension guard (symmetric to the persistence-load guard from #248), 16k-char input clipping (so an oversized memory can't 400 the embed call), and consistent stderr logging that no longer swallows embed failures.

migrateVectorIndex() utility re-embeds every memory + per-session observation against a new provider when dimensions change; per-session try/catch isolation so one bad session can't abort the whole migration; structured failedSessions[] result with a "<sessions-list-failed>" sentinel that distinguishes a catastrophic list-failure from per-session failures.

Soft-fail throughout: a downed embedder never breaks an upstream save. Live-tested end-to-end against Greek fixtures (thanks @nik1t7n for the original repro).

CJK caveat preserved: this fix recovers Greek, Cyrillic, accented Latin, Hebrew, Arabic, and other space-delimited scripts. CJK languages without spaces between characters still tokenize as a single sentence-long token — separate concern, needs a segmenter (PR #224 area).

Integrations now warn when sending the bearer token over plaintext HTTP (#315, closes #275)

Symmetric guard across all three plugin runtimes (Python / mjs / TypeScript): a request that would attach Authorization: Bearer <secret> to a http://<non-loopback>:port URL now logs a one-time stderr warning telling the operator the token is observable on the wire.

Loopback hosts (localhost, 127.0.0.1, ::1) and https:// URLs are exempt.

New env knob AGENTMEMORY_REQUIRE_HTTPS=1 escalates the warning to a hard refusal — the plugin throws before any request is sent, so a misconfigured deployment can fail loudly instead of leaking the bearer once.

Edge cases verified by 13 tests: IPv6 [::1] loopback (loopback), RFC1918 LAN IPs (192.168.x.x / 10.x.x.x warn — NOT loopback by design), lookalike hostnames (localhost.evil.com warns), no-secret short-circuit (guard never fires when no bearer would be sent), https-with-secret silent. Thanks @mvanhorn.

Viewer dashboard no longer sticks on "Loading dashboard…" (#335, closes #323)

Two narrow fixes from @hem57's Windows repro:

1. Removed the <link rel="stylesheet"> to fonts.googleapis.com. The viewer's strict CSP (default-src 'none', style-src 'unsafe-inline', font-src 'self') blocks external stylesheet origins by design, so every page load logged a CSP violation for the font CSS and another for each blocked font file. System-font fallbacks were already declared on every --font-* CSS variable so dropping the external <link> is a clean swap.

2. Wrapped loadDashboard() body in a try/catch that renders the error inline ("Dashboard failed to load: <reason>") instead of leaving the placeholder text up forever. Future "stuck Loading" reports now come with concrete error messages instead of just a screenshot of the placeholder.

RetentionScore type no longer declares source twice (#326, closes #277)

src/types.ts:835 and :842 both declared source?: "episodic" | "semantic" on RetentionScore. TypeScript silently accepts duplicate property declarations when the types are identical, so the build never errored — but the documented JSDoc on the first declaration (the #124 back-compat note explaining undefined should probe both scopes) was effectively shadowed by the duplicate. Removed the second declaration; grep confirmed no caller writes source twice on the same row, so the cleanup is a pure type-correctness fix with no runtime change. Thanks @cl0ckt0wer.

Changed

• @agentmemory/mcp package version bumped 0.9.11 → 0.9.12 to lockstep with the main package.

Install / upgrade

npm i -g @agentmemory/agentmemory@0.9.12
# or
npx @agentmemory/agentmemory

# MCP standalone shim
npx -y @agentmemory/mcp

Full changelog: v0.9.11...v0.9.12