agentmemory: persistent memory for coding agents, pinned to one iii-engine version

The re-explaining problem agentmemory targets

Every coding agent starts each session with an empty head. You explain the architecture on Monday, switch to Cursor on Tuesday, and explain it again. The README frames the project around exactly that: your coding agent remembers everything, no more re-explaining. The intended user is someone who runs more than one agent against the same codebase and wants the observations from one session to be available in the next, regardless of which client is driving.

The list of supported clients is the real scope statement: Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client. That is a broad surface, and the repository backs it with 20 adapters reachable through agentmemory connect <agent>. If you use a single agent and never switch, the value is smaller: you are adding a daemon and a data directory to solve a problem one long-running session mostly avoids.

How the memory layer is put together

agentmemory is not a standalone database. It is a worker on top of the iii engine, and the package description says it is powered by iii-engine's three primitives. The local runtime exposes four ports: 3111 for REST and MCP HTTP, 3112 for iii streams, 3113 for the viewer, and 49134 for the iii worker WebSocket. Memory therefore flows through the engine rather than through a process the CLI owns directly.

Persistent state lives outside the repository by default: ~/Library/Application Support/agentmemory on macOS, $XDG_DATA_HOME/agentmemory or ~/.local/share/agentmemory on Linux, and %APPDATA%\agentmemory on Windows. Two overrides exist, --data-dir <path> and AGENTMEMORY_DATA_DIR, and the README is explicit that you must reuse the same value on every restart. There is also a backward-compatibility rule worth knowing before you migrate anything: an existing ./data/state_store.db or ./data/iii-config.yaml takes precedence over the platform default for instance 0, and an explicit flag or environment override still wins over both.

Recall behaviour depends on what you have configured. In keyless mode vector embeddings are disabled, so memory_recall, which the README maps to the mem::search path, uses BM25. memory_smart_search can additionally fuse structural graph matches when graph data already exists. Setting a provider key does not by itself turn on LLM-written observation compression; that path also requires AGENTMEMORY_AUTO_COMPRESS=true.

Installing agentmemory and proving recall works

The canonical fresh-install command is a single npx invocation. Requirements are Node.js 20 or newer with npm and npx. On macOS and Linux the automatic iii-engine installation additionally needs curl, a POSIX sh, and tar, which the README notes minimal images such as node:20-slim may lack.

npx -y @agentmemory/agentmemory@latest

The first run is interactive. It asks which agents to wire, asks for an LLM provider or lets you stay keyless, seeds the config, starts the memory server and its pinned iii engine, and offers a global install so the bare agentmemory command works afterward. The -y flag accepts npx's package prompt and @latest avoids a stale cached release.

Once the daemon is up, seed sample data and exercise recall, then install the agent-side skills:

npx -y @agentmemory/agentmemory@latest demo
npx skills add rohitg00/agentmemory -y

The demo seeds sample sessions and runs queries. According to the README, keyword searches should hit in default keyless mode through BM25, while the demo's database performance optimization query is intentionally semantic and can return zero until an embedding provider is configured. That is the first thing to verify on your machine, because it tells you whether you are running the keyless path or a semantic one.

For free on-device semantic recall, set one variable in the env file and restart:

# in ~/.agentmemory/.env
EMBEDDING_PROVIDER=local

The first embedding request downloads Xenova/all-MiniLM-L6-v2; inference runs locally after that initial download. If you would rather have an agent perform the whole setup, the README points at INSTALL_FOR_AGENTS.md and gives the one-line instruction to retrieve and follow it.

The iii-engine version pin is the sharpest constraint

The compose file is unusually direct about compatibility. The iii-engine service is pinned to v0.11.2, described as the last engine that runs agentmemory's current direct-registration worker cleanly. v0.11.6 introduces a new model that registers everything as a sandboxed worker through iii worker add, and the comment states agentmemory has not been refactored for it. The stated failure mode is not subtle: the architectural mismatch surfaces as EPIPE reconnect loops and empty search after save. If you already run your own iii engine, the README says agentmemory will not attach to a different version because the worker cannot speak another engine's protocol.

Docker adds a second constraint that catches people who assume a named volume just works. The iii-engine image is distroless and runs as UID 65532 with no chown of its own, while Docker creates named volumes as root with mode 755. A one-shot iii-init container runs at compose-up to chown and chmod /data. The comment explains what happens without it: the engine silently buffers in RAM and state evaporates on every restart. There are escape hatches, AGENTMEMORY_DOCKER_UID, AGENTMEMORY_DOCKER_GID and AGENTMEMORY_DOCKER_SKIP_CHOWN, but skipping the chown is a deliberate choice you should make with the consequence in mind.

Native Windows is the third rough edge. The fast path is WSL2, and native Windows requires the pinned v0.11.2 ZIP to be downloaded and iii.exe extracted manually, because the CLI does not auto-extract it. Docker Desktop is the other supported route.

Where agentmemory is the wrong tool

It is a local daemon with a data directory on your filesystem, and nothing in the README describes a hosted or multi-tenant mode. If your agents run in ephemeral cloud containers, the memory store dies with the container unless you mount a persistent volume and keep the same data directory value across restarts. If you need several users or machines sharing one memory service with access control, this is not that product.

Keyless operation is a genuine strength and also a boundary. Without a provider key, LLM-backed summarisation, reflection and consolidation are disabled. You still get indexing through zero-LLM synthetic compression and BM25 recall, but any query that depends on meaning rather than keyword overlap can return nothing, which the README concedes for the demo's semantic query. If semantic recall is the whole point for you, budget for either a provider key or the local embedding model download.

Finally, the version pin means you cannot simply track the newest iii engine. Teams that treat engine upgrades as routine maintenance will hit the EPIPE and empty-search behaviour described in the compose file before they hit anything else.

agentmemory compared with mem0 and claude-mem

The closest comparison in search interest is mem0, and the difference is architectural rather than cosmetic. mem0 is a memory layer you call from application code, typically as a service or library your own software integrates. agentmemory inverts that: it is a local worker on the iii engine that plugs into agents you already run through MCP and per-agent adapters, so the integration point is the agent's tool surface rather than your application's code. If you are building a product with memory as a feature, the mem0 shape fits better. If you are a developer trying to make Cursor and Codex CLI share context, agentmemory's shape fits better.

claude-mem is the other frequently paired comparison, and the name signals the difference: a memory layer tied to one client versus one that lists Claude Code alongside Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi and OpenCode in the same breath. The trade is focus against reach. A single-client tool can tune itself to that client's hooks and context format; agentmemory has to keep 20 adapters behaving the same way, and its own README's emphasis on connect <agent> and the skills package suggests that adapter breadth is where the maintenance weight sits.

Maintenance, licence and what an upgrade actually costs

The last push to the default branch was on 2026-08-16, the same day as the v0.9.29 release. The two releases before that landed on 2026-07-19 and 2026-06-07, so the recent cadence is roughly monthly. The repository is not archived.

Upgrade cost is dominated by the engine pin, not by the npm version. Bumping the agentmemory package is the easy part; the compose file warns that the engine should be bumped only after agentmemory is refactored to register as a sandboxed worker. There is an override, AGENTMEMORY_III_VERSION, which the compose file shows being used to run 0.11.7, but the surrounding comment makes clear that this is a test, not a supported configuration. The release notes do not describe a rollback path for a data directory written by a newer engine, so back up the data directory before experimenting with the version variable.

The project is Apache-2.0, which permits commercial use and modification and includes a patent grant. That is the licence text, not legal advice; if you redistribute agentmemory inside a product, read the LICENSE file in the repository and the attribution requirements yourself. Note also that the package depends on the iii engine, which is a separate image with its own terms, and the compose file pins a specific tag of it.

Editorial conclusion

Adopt agentmemory if you drive several coding agents and keep re-explaining the same project context, and you are willing to run a local daemon on ports 3111 to 3113 plus 49134. Skip it if you need a hosted, multi-tenant memory service, if your agents run only in the cloud, or if you cannot pin iii-engine v0.11.2, since the compose file states v0.11.6 changes the worker registration model and surfaces as EPIPE reconnect loops and empty search after save. Before wiring anything, run the demo command and confirm the keyword queries hit; if the semantic query returns zero, that is the documented keyless behaviour, and you decide whether to set EMBEDDING_PROVIDER=local.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes