agentmemory is a persistent memory system for AI coding agents, with the goal of solving the problem that coding agents need to re-interpret architecture, rediscover defects, and re-teach preferences in every session. Traditional built-in memory such as CLAUDE.md and .cursorrules is limited to about 200 lines and easily becomes outdated. agentmemory improves on this by automatically capturing agent behavior, compressing it into retrievable memory, and injecting the correct context at the start of the next session. The project is built on the iii engine, and the current version targets iii-sdk 0.22.1 and pins iii-engine v0.22.1.
Purpose and main capabilities agentmemory can be used to provide persistent memory across sessions for a variety of programming agents. It supports Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any client that supports MCP. All agents share the same memory server. It provides capabilities such as silently capturing agent operations, compressing them into searchable memory, and injecting context at session startup. It also provides a memory viewer, replay timeline, import of legacy Claude Code JSONL transcripts, skill injection, and other features. According to the materials, it includes 9 callable skills such as /recall, /remember, /session-history, /forget, /recap, /handoff, /lesson, /commit-context, /commit-history, as well as 8 reference skills loaded on demand.
Usage Installation requires Node.js 20 or newer, along with npm and npx. Automatic installation of the iii engine on macOS/Linux also requires curl, POSIX sh, and tar. Native Windows requires manually installing the pinned version iii-engine v0.22.1 iii.exe; WSL2 or Docker Desktop are other supported paths. The standard fresh installation command is npx -y @agentmemory/agentmemory@latest. The first run is an interactive setup: choose the agents to connect, choose an LLM provider or remain keyless, seed the configuration, start the memory server and itspinned iii engine, and optionally install globally. y accepts the npx package prompt, and @latest avoids using an old cached version. LLM features can be used after setting a provider, but LLM-written observation compression only starts when AGENTMEMORY_AUTO_COMPRESS=true is also set. Keyless mode disables vector embeddings; memory_recall (the mem::search path) uses BM25, and memory_smart_search can also fuse structural graph matching when graph data already exists. For free on-device semantic recall, set EMBEDDING_PROVIDER=local in ~/.agentmemory/.env and restart. The first embedding request downloads Xenova/all-MiniLM-L6-v2, after which inference runs locally.
Local operation uses four ports: 3111 for REST/MCP HTTP, 3112 for iii streams, 3113 for the viewer, and 49134 for the iii worker WebSocket. Persistent iii state is stored by platform at ~/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, and reuse the same value on every restart. For backward compatibility, existing ./data/state_store.db or ./data/iii-config.yaml files take precedence over platform defaults for instance 0; explicit flags or environment overrides still take precedence. More agents can be connected at any time with agentmemory connect <agent>, supporting 20 adapters. The Windows quick path is WSL2; native Windows engine setup requires manually downloading the pinned v0.22.1 ZIP and extracting iii.exe, and the CLI will not automatically extract it. Docker Desktop is also supported.
Daily use and maintenance Every session can be replayed. Open the viewer and select Repplay tag, you can drag the timeline to view discrete events such as prompts, tool calls, tool results, and responses, supporting play/pause, 0.5x to 4x speed control, and keyboard shortcuts. After importing legacy Claude Code JSONL transcripts, the imported sessions appear alongside native sessions in the Replay selector, routed underneath through the mem::replay::load, mem::replay::sessions, and mem::replay::import-jsonl iii functions. Each imported transcript is indexed for search, tagged with the source channel import, and mined for session crystals and lessons. Note: Claude Code's cleanupPeriodDays (located in ~/.claude/settings.json, default 30) automatically deletes JSONL transcripts older than that window. If you import months-old history on a new installation, content older than 30 days has already disappeared before the first import. You can run a cron for import-jsonl, increase cleanupPeriodDays, or hook in automatic capture. The upgrade/maintenance commands are used to intentionally update the local runtime, will change the current workspace/runtime, may update JavaScript dependencies and pull the locked iiidev/iii:0.22.1 Docker image, and never install an unlocked or updated version of the iii engine.
Benchmarks and Comparisons The project provides retrieval accuracy benchmarks. coding-agent-life-v1 is an internal corpus, reproducible in a sandbox, reported to achieve a P@5 hit rate of 100% against that corpus's mathematical ceiling (0.240, see the scorecard). Hybrid retrieval retrieves every gold-standard session; grep misses 1 of 2 gold standards in multi-session temporal queries. The improvement is in recall + time, not aggregate precision. This benchmark is small and the gold standard is sparse; the larger LongMemEval-S discriminates better. LongMemEval-S is 500 questions from ICLR 2025, with the embedding model all-MiniLM-L6-v2 (local, free, no API key required). Full reports are in benchmark/LONGMEMEVAL.md, benchmark/QUALITY.md, benchmark/SCALE.md. For competitor comparisons, see benchmark/COMPARISON.md,covering agentmemory and mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo, and others. Benchmark note: only agentmemory's R@5 is its own measurement result (LongMemEval-S, reproducible from benchmark/COMPARISON.md). mem0's and Letta's numbers are the LoCoMo numbers they published (a different dataset); MemPalace's, supermemory's, TencentDB's (PersonaMem), and oracleagentmemory's numbers are vendor self-reported claims, not yet independently reproduced (oracleagentmemory's run uses GPT-5.5 against Oracle AI Database). The side-by-side presentation is for rough reference only, not a head-to-head on the same data. Star counts are approximate and drift over time.
Compatibility and Limitations This version targets iii-sdk 0.22.1 and locks iii-engine v0.22.1, and will not attach to a different version. agentmemory works with any agent that supports hooks, MCP, or a REST API. The Codex plugin and the Claude Code plugin come from the same plugin/ directory, registering the bundled stdio MCP bridge, 6 lifecycle hooks, and skills; Codex's hook engine injects CLAUDE_PLUGIN_ROOT into the hook subprocess, so the same hook scripts work across both hosts without duplication. The Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude Code-only and are not registered for Codex. Native plugin hook dispatch has been verified in Codex CLI 0.150.1. Desktop behavior depends on its bundled runtime; before enabling workarounds, check /hooks and confirm captured events. If the host requires global hooks, you can mirror the commands into ~/.codex/hooks.json. Claude Code recommends using the /plugin install path. If directlyConnect to agentmemory's MCP server via ~/.claude.json; Claude Code will never resolve ${CLAUDE_PLUGIN_ROOT}, so hook scripts must be pointed to absolute paths in ~/.claude/settings.json; these paths typically embed the agentmemory version, and the next upgrade will silently break every hook. After upgrading agentmemory, rerun the command to refresh the paths. For remote or protected deployments, AGENTMEMORY_URL and AGENTMEMORY_SECRET can be set.
The project has 5000+ Stars on GitHub and uses a free model. The above is the information explicitly provided in the materials; other features, fees, prices, platforms, effects, or usage steps are not provided at this time.
