agentmemory: Persistent Memory for Coding Agents, Built on the iii Engine

The Problem: Coding Agents Forget Everything Between Sessions

Coding agents like Claude Code, Cursor, and Copilot CLI are powerful within a single session, but they start fresh each time. Every new conversation requires re-explaining project conventions, past decisions, and current state. agentmemory directly targets this problem. It provides a persistent memory layer that stores sessions, facts, and relationships, so agents can recall what happened before. The README frames it as 'Your coding agent remembers everything. No more re-explaining.' That pitch is aimed at developers who use multiple agents and want a shared memory that is not tied to one vendor's cloud. It is also for teams that want memory to live on their own machine, not in a proprietary service.

How It Works: BM25, Local Embeddings, and a Knowledge Graph

agentmemory is built on the iii engine, which the README describes as the 'iii engine' and pins to version v0.11.2. The architecture is a local runtime that exposes REST and MCP HTTP on port 3111, iii streams on 3112, a viewer on 3113, and a worker WebSocket on 49134. The core memory operations are `memory_recall` and `memory_smart_search`. In keyless mode, `memory_recall` uses BM25, a classic keyword search algorithm. `memory_smart_search` can also fuse structural graph matches when graph data already exists, meaning it combines keyword hits with relationships between stored items. For semantic recall without a cloud provider, you can set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env`. This downloads the `Xenova/all-MiniLM-L6-v2` model on first use and runs inference locally. The README warns that the demo's `database performance optimization` query is intentionally semantic and may return zero until an embedding provider is configured. That is a concrete example of the difference between BM25 and semantic search.

Getting Started: One Command, Then a Demo

The canonical install is a single npx command: `npx -y @agentmemory/agentmemory@latest`. The first run is interactive: you pick which agents to wire (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, and others), choose an LLM provider or stay keyless, and it seeds the config, starts the memory server, and offers a global install. After that, you run `npx -y @agentmemory/agentmemory@latest demo` to seed sample sessions and exercise recall. Then you add skills with `npx skills add rohitg00/agentmemory -y`, which installs 17 native skills so your agent knows when to reach for memory. The README also gives an alternative path: hand your coding agent a single instruction to fetch `INSTALL_FOR_AGENTS.md`. That is useful for teams that want the agent to install itself. The CLI exposes `agentmemory connect <agent>` to wire more agents later, with 20 adapters listed.

Keyless Mode vs. Semantic Search: Know the Difference

The most important trade-off is between keyless mode and embedding-based search. Keyless mode disables vector embeddings entirely. `memory_recall` falls back to BM25, which works well for exact keyword matches but fails on semantic queries. The README is explicit: the demo's `database performance optimization` query can return zero until an embedding provider is configured. That is a genuine limitation. If you need to search by meaning, not by keyword, you must either set `EMBEDDING_PROVIDER=local` or use an external LLM provider. Local embeddings require a model download on first use, which may be a problem in offline or air-gapped environments. The README also notes that LLM-written observation compression only starts when `AGENTMEMORY_AUTO_COMPRESS=true` is set. So the out-of-the-box experience is keyword search with no compression. Teams expecting semantic memory out of the box will be disappointed.

Platform Constraints: Windows and Minimal Images

The installation requirements are not trivial. You need Node.js 20 or newer, and on macOS/Linux the automatic iii-engine installation also needs `curl`, a POSIX `sh`, and `tar`. Minimal images like `node:20-slim` may not include those, so a Docker-based setup could fail. Native Windows is the hardest path: you must manually download the pinned iii-engine v0.11.2 ZIP and extract `iii.exe` yourself. The CLI does not auto-extract it. The README suggests WSL2 or Docker Desktop as supported alternatives. This is a real barrier for Windows users who expect a one-command install. The pinned engine version also matters: agentmemory won't attach to a different iii-engine version, so if you already run your own engine, you must stop it and let agentmemory use its pinned one. That is a compatibility constraint that could conflict with other tools.

Data Location and Persistence: Know Where Your Memory Lives

Persistent state is stored in platform-specific directories: `~/Library/Application Support/agentmemory` on macOS, `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` on Linux, and `%APPDATA%\agentmemory` on Windows. You can override this with `--data-dir <path>` or `AGENTMEMORY_DATA_DIR`. The README stresses that you must reuse the same value on every restart, otherwise the memory server may not find your existing data. There is also a backward-compatibility rule: an existing `./data/state_store.db` or `./data/iii-config.yaml` takes precedence over the platform default for instance 0, but an explicit flag or environment override still wins. This is a subtle but important detail. If you move between machines or change your data-dir, you risk losing access to your memory. The viewer on port 3113 is a real-time UI, but the README does not describe its features in detail. The key takeaway is that memory is local and file-based, not a managed cloud service.

Alternatives: Cloud Memory and Other Local Tools

The main alternative to agentmemory is using a vendor-provided memory system, such as the memory features built into Claude Code or Cursor. Those are cloud-backed, which means you do not manage ports, engines, or data directories, but you also do not control the data. Another local alternative is a simple file-based approach, like Karpathy's LLM Wiki pattern, which the README explicitly references as an inspiration. The gist extends that pattern with confidence scoring, lifecycle, knowledge graphs, and hybrid search; agentmemory is the implementation. A developer could also build their own memory layer using a vector database like SQLite with a vector extension, but that would not include the agent adapters or the MCP server. The difference in approach is clear: agentmemory is a full package with a server, an MCP interface, and agent adapters, while a DIY approach gives you full control but requires you to write the integration yourself. For teams that want a ready-made solution with 20 agent adapters, agentmemory is more complete.

Maintenance and License: Apache-2.0 and a Pinned Engine

The project is licensed under Apache-2.0, which is permissive for commercial use, but note that it depends on the iii engine, which is pinned to v0.11.2. This means agentmemory's behavior is tied to that specific engine version. The README states that the worker cannot speak another engine's protocol, so you cannot swap in a newer engine without waiting for agentmemory to update its pin. This is a maintenance cost: you must follow agentmemory releases to get engine updates. The project has a regular release cadence, with v0.9.29 pushed in August 2026, and the repository is active. The README mentions a real-time viewer and a demo, but does not detail upgrade procedures or data migration. You should verify how upgrades handle existing data, especially if you use a custom data-dir. The license is clear, but the dependency on a pinned engine is a constraint that could become a problem if the iii engine evolves separately.

Editorial conclusion

Adopt agentmemory if you use an MCP-capable coding agent and are tired of repeating project context. It is not for you if you need a zero-setup, cloud-hosted memory, or if you cannot meet the Node.js 20 and engine installation requirements. First verify that your agent supports MCP, that you can run the pinned iii-engine v0.11.2 (on Windows, manual extraction is required), and that you are comfortable with the Apache-2.0 license and the data-dir consistency rule. If keyless BM25 is enough, start there; if you need semantic recall, plan for the local embedding model download.

Official sources

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