![\"agentmemory:](\"assets/banner.png\")
\n\n \n
\n \n Your coding agent remembers everything. No more re-explaining.\n Built on iii engine\n
\n Persistent memory for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client.\n
\n 🇬🇧 English •\n 🇨🇳 简体中文 •\n 🇹🇼 繁體中文 •\n 🇯🇵 日本語 •\n 🇰🇷 한국어 •\n 🇵🇹 Português •\n 🇧🇷 Português (Brasil) •\n 🇪🇸 Español •\n 🇩🇪 Deutsch •\n 🇫🇷 Français •\n 🇮🇹 Italiano •\n 🇳🇱 Nederlands •\n 🇵🇱 Polski •\n 🇨🇿 Čeština •\n 🇷🇴 Română •\n 🇭🇺 Magyar •\n 🇬🇷 Ελληνικά •\n 🇸🇪 Svenska •\n 🇩🇰 Dansk •\n 🇳🇴 Norsk •\n 🇫🇮 Suomi •\n 🇷🇺 Русский •\n 🇺🇦 Українська •\n 🇹🇷 Türkçe •\n 🇮🇱 עברית •\n 🇸🇦 العربية •\n 🇮🇳 हिन्दी •\n 🇧🇩 বাংলা •\n 🇵🇰 اردو •\n 🇹🇭 ไทย •\n 🇻🇳 Tiếng Việt •\n 🇮🇩 Bahasa Indonesia •\n 🇵🇭 Tagalog\n
\n\n\n \n
\n ![\"Design](\"https://img.shields.io/badge/Viral%20GitHub%20Gist-1.6k%20stars%20%2F%20230%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a\"){kind=icon}
\n The gist extends Karpathy's LLM Wiki pattern with confidence scoring, lifecycle, knowledge graphs, and hybrid search: agentmemory is the implementation.\n
\n\n\n ![\"npm](\"https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm\")
![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github\")
![\"License\"](\"https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge\")
![\"Stars\"](\"https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github\")
\n ![\"95.2%](\"assets/tags/light/stat-recall.svg\")
![\"92%](\"assets/tags/light/stat-tokens.svg\")
![\"54](\"assets/tags/light/stat-tools.svg\")
![\"12](\"assets/tags/light/stat-hooks.svg\")
![\"0](\"assets/tags/light/stat-deps.svg\")
![\"2,500+](\"assets/tags/light/stat-tests.svg\")
\n ![\"agentmemory](\"assets/demo.gif\")
\n
\n Install •\n Quick Start •\n Benchmarks •\n vs Competitors •\n Agents •\n How It Works •\n MCP •\n Viewer •\n Powered by iii •\n Config •\n API\n
\n\n---\n\n## Install\n\nRequirements:\n\n- Node.js 20 or newer with npm and npx (`node -v`, `npm -v`, and `npx -v`).\n- macOS/Linux automatic iii-engine installation also needs `curl`, a POSIX `sh`, and `tar`. Minimal images such as `node:20-slim` may not include them.\n- Native Windows requires the pinned iii-engine v0.22.1 `iii.exe` to be installed manually. WSL2 or Docker Desktop are the other supported paths.\n\nCanonical fresh-install command:\n\n```bash\nnpx -y @agentmemory/agentmemory@latest\n```\n\nThe first run is an interactive setup: pick the agents to wire (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), pick an LLM provider or stay keyless, and it seeds the config, starts the memory server and its pinned iii engine, and offers to install globally so the bare `agentmemory` command works everywhere afterward. `-y` accepts npx's package prompt and `@latest` avoids a stale cached release. A provider makes LLM features available, but LLM-written observation compression starts only when `AGENTMEMORY_AUTO_COMPRESS=true` is also set.\n\nKeyless mode disables vector embeddings. `memory_recall` (the `mem::search` path) uses BM25, while `memory_smart_search` can also fuse structural graph matches 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`; inference runs locally after that initial model download.\n\nThe local runtime 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 lives in `~/Library/Application Support/agentmemory` on macOS, `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` on Linux, and `%APPDATA%\\agentmemory` on Windows. Use `--data-dir![\"Works](\"assets/tags/light/section-agents.svg\")
\n![\"Claude](\"https://github.com/anthropics.png?size=120\") \nClaude Code \nnative plugin + 12 hooks + MCP\n | \n\n![\"Codex](\"https://github.com/openai.png?size=120\") \nCodex CLI \nnative plugin + 6 hooks + MCP\n | \n\n![\"GitHub](\"https://svgl.app/library/github_dark.svg\") \nGitHub Copilot CLI \nMCP + plugin hooks/skills\n | \n\n![\"Cursor\"](\"https://svgl.app/library/cursor_dark.svg\") \nCursor \nnative plugin + 7 hooks + MCP\n | \n\n![\"OpenCode\"](\"https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png\") \nOpenCode \ncapture plugin + MCP\n | \n
\n![\"Devin\"](\"https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/devin.png\") \nDevin \n6 hooks + skills + MCP\n | \n\n![\"OpenClaw\"](\"https://github.com/openclaw.png?size=120\") \nOpenClaw \nnative plugin + MCP\n | \n\n![\"Hermes\"](\"https://github.com/NousResearch.png?size=120\") \nHermes \nnative plugin + MCP\n | \n\n![\"pi\"](\"assets/agents/pi.svg\") \npi \nnative plugin + MCP\n | \n\n![\"OpenHuman\"](\"https://github.com/tinyhumansai.png?size=120\") \nOpenHuman \nnative Memory trait backend\n | \n
\n![\"Gemini](\"https://github.com/google-gemini.png?size=120\") \nGemini CLI \nMCP server\n | \n\n![\"Antigravity\"](\"https://svgl.app/library/antigravity.svg\") \nAntigravity \nMCP + hooks\n | \n\n \nClaude Desktop \nMCP server\n | \n\n![\"Warp\"](\"https://svgl.app/library/warp.svg\") \nWarp \nconnect + MCP + skills\n | \n\n![\"Zed\"](\"https://svgl.app/library/zed-logo_dark.svg\"){kind=logo} \nZed \nMCP server\n | \n
\n![\"Cline\"](\"https://github.com/cline.png?size=120\") \nCline \nMCP server\n | \n\n![\"Continue\"](\"https://github.com/continuedev.png?size=120\") \nContinue \nMCP server\n | \n\n![\"Droid\"](\"https://www.factory.ai/favicon.svg\") \nDroid \nMCP server\n | \n\n \nKiro \nMCP server\n | \n\n![\"Qwen](\"https://svgl.app/library/qwen_dark.svg\") \nQwen Code \nMCP server\n | \n
\n![\"DeepSeek](\"https://svgl.app/library/deepseek.svg\") \nDeepSeek Harness \nMCP server\n | \n\n![\"Roo](\"https://github.com/RooCodeInc.png?size=120\") \nRoo Code \nMCP server\n | \n\n![\"Kilo](\"https://github.com/Kilo-Org.png?size=120\") \nKilo Code \nMCP server\n | \n\n![\"Goose\"](\"https://github.com/block.png?size=120\") \nGoose \nMCP server\n | \n\n![\"Aider\"](\"https://github.com/Aider-AI.png?size=120\") \nAider \nREST API\n | \n
\n Works with any agent that speaks MCP or HTTP. One server, memories shared across all of them.\n
\n\n---\n\nYou explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences. Built-in memory (CLAUDE.md, .cursorrules) caps out at 200 lines and goes stale. agentmemory fixes this. It silently captures what your agent does, compresses it into searchable memory, and injects the right context when the next session starts. One command. Works across agents.\n\n**What changes:** Session 1 you set up JWT auth. Session 2 you ask for rate limiting. The agent already knows your auth uses jose middleware in `src/middleware/auth.ts`, your tests cover token validation, and you chose jose over jsonwebtoken for Edge compatibility, with no re-explaining and no copy-pasting.\n\n```bash\nnpx -y @agentmemory/agentmemory@latest\n```\n\nBy default, agentmemory stores iii-engine state outside the repository you start it from: `~/Library/Application Support/agentmemory` on macOS, `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` on Linux, and `%APPDATA%\\agentmemory` on Windows. An existing legacy `./data/state_store.db` or `./data/iii-config.yaml` is reused for instance 0 before that platform default. To choose a location explicitly, pass `--data-dir![\"Benchmarks\"](\"assets/tags/light/section-benchmarks.svg\")
| \n\n### Retrieval Accuracy\n\n**coding-agent-life-v1** (in-house corpus, sandbox-reproducible)\n\n| Adapter | P@5 | R@5 | Top-5 hit rate | p50 latency |\n|---|---|---|---|---|\n| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |\n| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |\n\n100% top-5 hit rate at the **P@5 math ceiling** for this corpus (0.240, see scorecard). Hybrid retrieves every gold session; grep misses 1 of 2 gold on the multi-session temporal query. Lift is **recall + temporal**, not aggregate precision. This benchmark is small and gold-sparse; the larger LongMemEval-S below differentiates better. Full per-type breakdown + correction note: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](docs/benchmarks/2026-05-20-coding-agent-life-v1.md).\n\n**LongMemEval-S** (ICLR 2025, 500 questions)\n\n| System | R@5 | R@10 | MRR |\n|---|---|---|---|\n| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |\n| BM25-only fallback | 86.2% | 94.6% | 71.5% |\n\n | \n\n\n### Token Savings\n\n| Approach | Tokens/yr | Cost/yr |\n|---|---|---|\n| Paste full context | 19.5M+ | Impossible (exceeds window) |\n| LLM-summarized | ~650K | ~$500 |\n| **agentmemory** | **~170K** | **~$10** |\n| agentmemory + local embeddings | ~170K | **$0** |\n\n | \n
![\"vs](\"assets/tags/light/section-competitors.svg\")
| \n | agentmemory | \nmem0 (63K ⭐) | \nLetta / MemGPT (24K ⭐) | \nKhoj (36K ⭐) | \nsupermemory (29K ⭐) | \nTencentDB Agent Memory (22K ⭐) | \nMemPalace (54K ⭐) | \noracleagentmemory | \nHippo | \nBuilt-in (CLAUDE.md) | \n
|---|---|---|---|---|---|---|---|---|---|---|
| Type | \nMemory engine + MCP server | \nMemory layer API | \nFull agent runtime | \nPersonal AI | \nMemory API + app | \nTeam memory hub (LLM proxy) | \nVector memory (OSS) | \nMemory engine (Oracle DB) | \nMemory system | \nStatic file | \n
| Retrieval R@5 | \n95.2% | \n68.5% (LoCoMo) | \n83.2% (LoCoMo) | \nN/A | \nSelf-reported | \nPersonaMem 76% (self-reported) | \n~96.6% (self-reported) | \n94.4% (self-reported) | \nN/A | \nN/A (grep) | \n
| Auto-capture | \n12 hooks (zero manual effort) | \nManual add() calls | \nAgent self-edits | \nManual | \nAPI-side extraction | \nProxy interception (base-URL swap) | \nManual | \nAPI extraction | \nManual | \nManual editing | \n
| Search | \nBM25 + Vector + Graph (RRF fusion) | \nVector + Graph | \nVector (archival) | \nSemantic | \nVector + RAG | \n4 asset types (Chat / Skill / Wiki / CodeGraph) | \nVector-only | \nVector + semantic | \nDecay-weighted | \nLoads everything into context | \n
| Multi-agent | \nMCP + REST + leases + signals | \nAPI (no coordination) | \nWithin Letta runtime only | \nNo | \nNo | \nTeam roles + shared assets | \nNo | \nScoped only | \nMulti-agent shared | \nPer-agent files | \n
| Framework lock-in | \nNone (any MCP client) | \nNone | \nHigh (must use Letta) | \nStandalone | \nNone | \nProxy fronts every model call | \nNone | \nOracle Database | \nNone | \nPer-agent format | \n
| External deps | \nNone (SQLite + iii-engine) | \nQdrant / pgvector | \nPostgres + vector DB | \nMultiple | \nManaged cloud | \nDocker stack (Core + Hub + Proxy) | \nVector store | \nOracle AI Database | \nNone | \nNone | \n
| Memory lifecycle | \n4-tier consolidation + decay + auto-forget | \nPassive extraction | \nAgent-managed | \nManual | \nAuto-forget | \nManual review; auto-routing in progress | \nNone | \nNot stated | \nDecay + consolidation | \nManual pruning | \n
| Token efficiency | \n~1,900 tokens/session ($10/yr) | \nVaries by integration | \nCore memory in context | \nVaries | \nCloud pricing | \nNot stated | \nNo token budget | \nLLM-backed (varies) | \nVaries | \n22K+ tokens at 240 obs | \n
| Real-time viewer | \nYes (port 3113) | \nCloud dashboard | \nCloud dashboard | \nWeb UI | \nCloud dashboard | \nHub web UI | \nNo | \nNo | \nNo | \nNo | \n
| Self-hosted | \nYes (default) | \nOptional | \nOptional | \nYes | \nNo (cloud-only) | \nYes (Docker) | \nYes | \nYes (Oracle DB) | \nYes | \nYes | \n
benchmark/COMPARISON.md). The mem0 and Letta figures are their published LoCoMo numbers (a different dataset); the MemPalace, supermemory, TencentDB (PersonaMem), and oracleagentmemory figures are vendor self-reported claims we have not independently reproduced (oracleagentmemory's run used GPT-5.5 against an Oracle AI Database). Shown side by side for ballpark only, not a head-to-head on identical data. Star counts are approximate and drift over time.\n\n**Newer entrants** worth knowing, compared in depth in [`benchmark/COMPARISON.md`](benchmark/COMPARISON.md):\n\n| System | ⭐ | Angle |\n|--------|---|-------|\n| Zep / Graphiti | 30K | Temporal knowledge graph; strongest published temporal-query results (LongMemEval 63.8%), but graph builds asynchronously so fresh facts can lag |\n| Cognee | 30K | Document-to-knowledge-graph ingestion, Python-only, built for structured entity extraction rather than session capture |\n\nNone of these auto-capture from coding-agent hooks, ship a local-first viewer, or run keyless — the combination agentmemory is built around.\n\n---\n\n![\"Quick](\"assets/tags/light/section-quickstart.svg\")
\n ![\"Deploy](\"https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white\"){kind=icon}
![\"Deploy](\"https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white\"){kind=icon}
![\"Why](\"assets/tags/light/section-why.svg\")
![\"How](\"assets/tags/light/section-how.svg\")
![\"Search\"](\"assets/tags/light/section-search.svg\")