[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11465":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":9,"totalLinesOfCode":9,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":9,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":37,"readmeContent":38,"aiSummary":39,"trendingCount":16,"starSnapshotCount":16,"syncStatus":40,"lastSyncTime":41,"discoverSource":42},11465,"agentmemory","rohitg00\u002Fagentmemory","rohitg00","#1 Persistent memory for AI coding agents based on real-world benchmarks",null,"https:\u002F\u002Fgithub.com\u002Frohitg00\u002Fagentmemory","TypeScript",22362,1843,61,127,0,135,1203,7459,743,44.8,false,"main",[5,25,26,27,28,29,30,31,32,33,34,35,36],"agents","ai","claude","claudecode","codex","copilot","cursor","genai","harness","hermes","memory","openclaw","2026-06-12 02:02:31","\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fbanner.png\" alt=\"agentmemory — Persistent memory for AI coding agents\" width=\"720\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>\n    Your coding agent remembers everything. No more re-explaining.\n    Built on \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fiii-hq\u002Fiii\">iii engine\u003C\u002Fa>\n  \u003C\u002Fstrong>\u003Cbr\u002F>\n  Persistent memory for Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client.\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F25123\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Ftrendshift.io\u002Fapi\u002Fbadge\u002Frepositories\u002F25123\" alt=\"rohitg00\u002Fagentmemory | Trendshift\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fwww.star-history.com\u002F?repos=rohitg00%2Fagentmemory&type=date&legend=top-left\">\n    \u003Cpicture>\n      \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=rohitg00\u002Fagentmemory&type=date&theme=dark&legend=top-left\" \u002F>\n      \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=rohitg00\u002Fagentmemory&type=date&legend=top-left\" \u002F>\n      \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=rohitg00\u002Fagentmemory&type=date&legend=top-left\" \u002F>\n    \u003C\u002Fpicture>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgist.github.com\u002Frohitg00\u002F2067ab416f7bbe447c1977edaaa681e2\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FViral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a\" alt=\"Design doc: 1200 stars \u002F 172 forks on the gist\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cem>The gist extends Karpathy's LLM Wiki pattern with confidence scoring, lifecycle, knowledge graphs, and hybrid search: agentmemory is the implementation.\u003C\u002Fem>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@agentmemory\u002Fagentmemory\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@agentmemory\u002Fagentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm\" alt=\"npm version\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Frohitg00\u002Fagentmemory\u002Factions\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Frohitg00\u002Fagentmemory\u002Fci.yml?label=tests&style=for-the-badge&logo=github\" alt=\"CI\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Frohitg00\u002Fagentmemory\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Frohitg00\u002Fagentmemory?color=blue&style=for-the-badge\" alt=\"License\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Frohitg00\u002Fagentmemory\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Frohitg00\u002Fagentmemory?style=for-the-badge&color=yellow&logo=github\" alt=\"Stars\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fstat-recall.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fstat-recall.svg\" alt=\"95.2% retrieval R@5\" height=\"38\" \u002F>\u003C\u002Fpicture>\n  \u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fstat-tokens.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fstat-tokens.svg\" alt=\"92% fewer tokens\" height=\"38\" \u002F>\u003C\u002Fpicture>\n  \u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fstat-tools.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fstat-tools.svg\" alt=\"51 MCP tools\" height=\"38\" \u002F>\u003C\u002Fpicture>\n  \u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fstat-hooks.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fstat-hooks.svg\" alt=\"12 auto hooks\" height=\"38\" \u002F>\u003C\u002Fpicture>\n  \u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fstat-deps.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fstat-deps.svg\" alt=\"0 external DBs\" height=\"38\" \u002F>\u003C\u002Fpicture>\n  \u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fstat-tests.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fstat-tests.svg\" alt=\"950+ tests passing\" height=\"38\" \u002F>\u003C\u002Fpicture>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fdemo.gif\" alt=\"agentmemory demo\" width=\"720\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#install\">Install\u003C\u002Fa> •\n  \u003Ca href=\"#quick-start\">Quick Start\u003C\u002Fa> •\n  \u003Ca href=\"#benchmarks\">Benchmarks\u003C\u002Fa> •\n  \u003Ca href=\"#vs-competitors\">vs Competitors\u003C\u002Fa> •\n  \u003Ca href=\"#works-with-every-agent\">Agents\u003C\u002Fa> •\n  \u003Ca href=\"#how-it-works\">How It Works\u003C\u002Fa> •\n  \u003Ca href=\"#mcp-server\">MCP\u003C\u002Fa> •\n  \u003Ca href=\"#real-time-viewer\">Viewer\u003C\u002Fa> •\n  \u003Ca href=\"#iii-console\">iii Console\u003C\u002Fa> •\n  \u003Ca href=\"#powered-by-iii\">Powered by iii\u003C\u002Fa> •\n  \u003Ca href=\"#configuration\">Config\u003C\u002Fa> •\n  \u003Ca href=\"#api\">API\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## Install\n\n```bash\nnpm install -g @agentmemory\u002Fagentmemory     # once — bare `agentmemory` on PATH\nagentmemory                                  # start the memory server on :3111\nagentmemory demo                             # seed sample sessions + prove recall\nagentmemory connect claude-code              # wire your agent (also: codex, cursor, gemini-cli, ...)\n```\n\nOr via `npx` (no install):\n\n```bash\nnpx @agentmemory\u002Fagentmemory\n```\n\nHeads-up — npx caches per version. If a bare `npx @agentmemory\u002Fagentmemory` serves an older release, force the latest with `npx -y @agentmemory\u002Fagentmemory@latest`, or clear the cache once with `rm -rf ~\u002F.npm\u002F_npx` (macOS\u002FLinux; on Windows delete `%LOCALAPPDATA%\\npm-cache\\_npx`). The first npx run from v0.9.16+ prompts to install globally inline so the bare `agentmemory` command works everywhere afterwards.\n\nFull options at [Quick Start](#quick-start) below. Agent-specific wiring at [Works with every agent](#works-with-every-agent).\n\n---\n\n\u003Ch2 id=\"works-with-every-agent\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-agents.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-agents.svg\" alt=\"Works with every agent\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\nagentmemory works with any agent that supports hooks, MCP, or REST API. All agents share the same memory server.\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fclaude.com\u002Fproduct\u002Fclaude-code\">\u003Cimg src=\"https:\u002F\u002Fmatthiasroder.com\u002Fcontent\u002Fimages\u002F2026\u002F01\u002FClaude.png?size=120\" alt=\"Claude Code\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Claude Code\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>native plugin + 12 hooks + MCP\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fopenai.png?size=120\" alt=\"Codex CLI\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Codex CLI\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>native plugin + 6 hooks + MCP\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"integrations\u002Fopenclaw\u002F\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fopenclaw.png?size=120\" alt=\"OpenClaw\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>OpenClaw\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>native plugin + MCP\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"integrations\u002Fhermes\u002F\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002FNousResearch.png?size=120\" alt=\"Hermes\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Hermes\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>native plugin + MCP\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"integrations\u002Fpi\u002F\">\u003Cimg src=\"assets\u002Fagents\u002Fpi.svg\" alt=\"pi\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>pi\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>native plugin + MCP\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Ftinyhumansai\u002Fopenhuman\">\u003Cimg src=\"https:\u002F\u002Fraw.githubusercontent.com\u002Ftinyhumansai\u002Fopenhuman\u002Fmain\u002Fapp\u002Fsrc-tauri\u002Ficons\u002F128x128.png\" alt=\"OpenHuman\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>OpenHuman\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>native Memory trait backend\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fcursor.com\">\u003Cimg src=\"https:\u002F\u002Fwww.freelogovectors.net\u002Fwp-content\u002Fuploads\u002F2025\u002F06\u002Fcursor-logo-freelogovectors.net_.png\" alt=\"Cursor\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Cursor\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>MCP server\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fgoogle-gemini.png?size=120\" alt=\"Gemini CLI\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Gemini CLI\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>MCP server\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fopencode-ai\u002Fopencode\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fopencode-ai.png?size=120\" alt=\"OpenCode\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>OpenCode\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>MCP server\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fcline\u002Fcline\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fcline.png?size=120\" alt=\"Cline\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Cline\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>MCP server\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fblock\u002Fgoose\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fblock.png?size=120\" alt=\"Goose\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Goose\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>MCP server\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002FKilo-Org\u002Fkilocode\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002FKilo-Org.png?size=120\" alt=\"Kilo Code\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Kilo Code\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>MCP server\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAider-AI\u002Faider\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002FAider-AI.png?size=120\" alt=\"Aider\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Aider\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>REST API\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fclaude.ai\u002Fdownload\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fanthropics.png?size=120\" alt=\"Claude Desktop\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Claude Desktop\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>MCP server\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fwindsurf.com\">\u003Cimg src=\"https:\u002F\u002Fexafunction.github.io\u002Fpublic\u002Fbrand\u002Fwindsurf-black-symbol.svg?size=120\" alt=\"Windsurf\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Windsurf\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>MCP server\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003Ctd align=\"center\" width=\"12.5%\">\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002FRooCodeInc\u002FRoo-Code\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002FRooCodeInc.png?size=120\" alt=\"Roo Code\" width=\"48\" height=\"48\" \u002F>\u003C\u002Fa>\u003Cbr\u002F>\n\u003Cstrong>Roo Code\u003C\u002Fstrong>\u003Cbr\u002F>\n\u003Csub>MCP server\u003C\u002Fsub>\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n\u003Cp align=\"center\">\n  \u003Csub>Works with \u003Cstrong>any\u003C\u002Fstrong> agent that speaks MCP or HTTP. One server, memories shared across all of them.\u003C\u002Fsub>\n\u003C\u002Fp>\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\u002Fmiddleware\u002Fauth.ts`, your tests cover token validation, and you chose jose over jsonwebtoken for Edge compatibility. No re-explaining. No copy-pasting. The agent just *knows*.\n\n```bash\nnpx @agentmemory\u002Fagentmemory\n```\n\n> **New in v0.9.0** — Landing site at [agent-memory.dev](https:\u002F\u002Fagent-memory.dev), filesystem connector (`@agentmemory\u002Ffs-watcher`), standalone MCP now proxies to the running server so hooks and the viewer agree, audit policy codified across every delete path, health stops flagging `memory_critical` on tiny Node processes. Full notes in [CHANGELOG.md](CHANGELOG.md#090--2026-04-18).\n\n---\n\n\u003Ch2 id=\"benchmarks\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-benchmarks.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-benchmarks.svg\" alt=\"Benchmarks\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd width=\"50%\">\n\n### Retrieval Accuracy\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\u003C\u002Ftd>\n\u003Ctd width=\"50%\">\n\n### Token Savings\n\n| Approach | Tokens\u002Fyr | Cost\u002Fyr |\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\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n> Embedding model: `all-MiniLM-L6-v2` (local, free, no API key). Full reports: [`benchmark\u002FLONGMEMEVAL.md`](benchmark\u002FLONGMEMEVAL.md), [`benchmark\u002FQUALITY.md`](benchmark\u002FQUALITY.md), [`benchmark\u002FSCALE.md`](benchmark\u002FSCALE.md). Competitor comparison: [`benchmark\u002FCOMPARISON.md`](benchmark\u002FCOMPARISON.md) — agentmemory vs mem0, Letta, Khoj, claude-mem, Hippo.\n\n---\n\n\u003Ch2 id=\"vs-competitors\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-competitors.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-competitors.svg\" alt=\"vs Competitors\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\n\u003Ctable>\n\u003Ctr>\n\u003Cth width=\"20%\">\u003C\u002Fth>\n\u003Cth width=\"20%\">agentmemory\u003C\u002Fth>\n\u003Cth width=\"20%\">mem0 (53K ⭐)\u003C\u002Fth>\n\u003Cth width=\"20%\">Letta \u002F MemGPT (22K ⭐)\u003C\u002Fth>\n\u003Cth width=\"20%\">Built-in (CLAUDE.md)\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Type\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Memory engine + MCP server\u003C\u002Ftd>\n\u003Ctd>Memory layer API\u003C\u002Ftd>\n\u003Ctd>Full agent runtime\u003C\u002Ftd>\n\u003Ctd>Static file\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Retrieval R@5\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>\u003Cstrong>95.2%\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>68.5% (LoCoMo)\u003C\u002Ftd>\n\u003Ctd>83.2% (LoCoMo)\u003C\u002Ftd>\n\u003Ctd>N\u002FA (grep)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Auto-capture\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>12 hooks (zero manual effort)\u003C\u002Ftd>\n\u003Ctd>Manual \u003Ccode>add()\u003C\u002Fcode> calls\u003C\u002Ftd>\n\u003Ctd>Agent self-edits\u003C\u002Ftd>\n\u003Ctd>Manual editing\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Search\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>BM25 + Vector + Graph (RRF fusion)\u003C\u002Ftd>\n\u003Ctd>Vector + Graph\u003C\u002Ftd>\n\u003Ctd>Vector (archival)\u003C\u002Ftd>\n\u003Ctd>Loads everything into context\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Multi-agent\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>MCP + REST + leases + signals\u003C\u002Ftd>\n\u003Ctd>API (no coordination)\u003C\u002Ftd>\n\u003Ctd>Within Letta runtime only\u003C\u002Ftd>\n\u003Ctd>Per-agent files\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Framework lock-in\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>None (any MCP client)\u003C\u002Ftd>\n\u003Ctd>None\u003C\u002Ftd>\n\u003Ctd>High (must use Letta)\u003C\u002Ftd>\n\u003Ctd>Per-agent format\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>External deps\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>None (SQLite + iii-engine)\u003C\u002Ftd>\n\u003Ctd>Qdrant \u002F pgvector\u003C\u002Ftd>\n\u003Ctd>Postgres + vector DB\u003C\u002Ftd>\n\u003Ctd>None\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Memory lifecycle\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>4-tier consolidation + decay + auto-forget\u003C\u002Ftd>\n\u003Ctd>Passive extraction\u003C\u002Ftd>\n\u003Ctd>Agent-managed\u003C\u002Ftd>\n\u003Ctd>Manual pruning\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Token efficiency\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>~1,900 tokens\u002Fsession ($10\u002Fyr)\u003C\u002Ftd>\n\u003Ctd>Varies by integration\u003C\u002Ftd>\n\u003Ctd>Core memory in context\u003C\u002Ftd>\n\u003Ctd>22K+ tokens at 240 obs\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Real-time viewer\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Yes (port 3113)\u003C\u002Ftd>\n\u003Ctd>Cloud dashboard\u003C\u002Ftd>\n\u003Ctd>Cloud dashboard\u003C\u002Ftd>\n\u003Ctd>No\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Self-hosted\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Yes (default)\u003C\u002Ftd>\n\u003Ctd>Optional\u003C\u002Ftd>\n\u003Ctd>Optional\u003C\u002Ftd>\n\u003Ctd>Yes\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n---\n\n\u003Ch2 id=\"quick-start\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-quickstart.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-quickstart.svg\" alt=\"Quick Start\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\nCompatibility: this release targets stable `iii-sdk` `^0.11.0` and iii-engine v0.11.x.\n\n### Try it in 30 seconds\n\n```bash\n# Terminal 1: start the server\nnpx @agentmemory\u002Fagentmemory\n\n# Terminal 2: seed sample data and see recall in action\nnpx @agentmemory\u002Fagentmemory demo\n```\n\n`demo` seeds 3 realistic sessions (JWT auth, N+1 query fix, rate limiting) and runs semantic searches against them. You'll see it find \"N+1 query fix\" when you search \"database performance optimization\" — keyword matching can't do that.\n\nOpen `http:\u002F\u002Flocalhost:3113` to watch the memory build live.\n\n### Recommended: install globally\n\n`npx` caches per-version. If you ran `npx @agentmemory\u002Fagentmemory@0.9.14` last week, a bare `npx @agentmemory\u002Fagentmemory` may serve the stale 0.9.14 from `~\u002F.npm\u002F_npx\u002F`, not the latest release. Install once and the bare `agentmemory` command works everywhere:\n\n```bash\nnpm install -g @agentmemory\u002Fagentmemory\nagentmemory                    # start the server (same as the npx form)\nagentmemory stop               # tear it down\nagentmemory remove             # uninstall everything we created\nagentmemory connect claude-code   # wire one agent\nagentmemory doctor             # interactive diagnostics + fix prompts\n```\n\nFrom v0.9.16 onward, the first npx run prompts you to install globally inline — answer `Y` once and you're set. If you skip, fall back to either of these for a fresh fetch:\n\n```bash\nnpx -y @agentmemory\u002Fagentmemory@latest                 # forces latest from npm (cross-platform)\nrm -rf ~\u002F.npm\u002F_npx && npx @agentmemory\u002Fagentmemory     # macOS\u002FLinux only (POSIX shell)\n```\n\nOn Windows \u002F PowerShell, the equivalent cache clear is `Remove-Item -Recurse -Force \"$env:LOCALAPPDATA\\npm-cache\\_npx\"` — the `npx -y ...@latest` form above is the cross-platform option.\n\n### Session Replay\n\nEvery session agentmemory records is replayable. Open the viewer, pick the **Replay** tab, and scrub through the timeline: prompts, tool calls, tool results, and responses render as discrete events with play\u002Fpause, speed control (0.5×–4×), and keyboard shortcuts (space to toggle, arrows to step).\n\nAlready have older Claude Code JSONL transcripts you want to bring in?\n\n```bash\n# Import everything under the default ~\u002F.claude\u002Fprojects\nnpx @agentmemory\u002Fagentmemory import-jsonl\n\n# Or import a single file\nnpx @agentmemory\u002Fagentmemory import-jsonl ~\u002F.claude\u002Fprojects\u002F-my-project\u002Fabc123.jsonl\n```\n\nImported sessions show up in the Replay picker alongside native ones. Under the hood each entry routes through the `mem::replay::load`, `mem::replay::sessions`, and `mem::replay::import-jsonl` iii functions — no side-channel servers.\n\n### Upgrade \u002F Maintenance\n\nUse the maintenance command when you intentionally want to update your local runtime:\n\n```bash\nnpx @agentmemory\u002Fagentmemory upgrade\n```\n\nWarning: this command mutates the current workspace\u002Fruntime. It can update JavaScript dependencies, may run `cargo install iii-engine --force`, and may pull Docker images.\n\nImplementation details live in `src\u002Fcli.ts` (see `runUpgrade` around the `src\u002Fcli.ts:544-595` region).\n\n### Claude Code (one block, paste it)\n\n```\nInstall agentmemory: run `npx @agentmemory\u002Fagentmemory` in a separate terminal to start the memory server. Then run `\u002Fplugin marketplace add rohitg00\u002Fagentmemory` and `\u002Fplugin install agentmemory` — the plugin registers all 12 hooks, 4 skills, AND auto-wires the `@agentmemory\u002Fmcp` stdio server via its `.mcp.json`, so you get 51 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http:\u002F\u002Flocalhost:3111\u002Fagentmemory\u002Fhealth`. The real-time viewer is at http:\u002F\u002Flocalhost:3113.\n```\n\n### Codex CLI (Codex plugin platform)\n\n```bash\n# 1. start the memory server in a separate terminal\nnpx @agentmemory\u002Fagentmemory\n\n# 2. register the agentmemory marketplace and install the plugin\ncodex plugin marketplace add rohitg00\u002Fagentmemory\ncodex plugin install agentmemory\n```\n\nThe Codex plugin ships from the same `plugin\u002F` directory as the Claude Code plugin. It registers:\n\n- `@agentmemory\u002Fmcp` as an MCP server (proxies all 51 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable)\n- 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`\n- 4 skills: `\u002Frecall`, `\u002Fremember`, `\u002Fsession-history`, `\u002Fforget`\n\nCodex's hook engine injects `CLAUDE_PLUGIN_ROOT` into hook subprocesses (per [`codex-rs\u002Fhooks\u002Fsrc\u002Fengine\u002Fdiscovery.rs`](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex\u002Fblob\u002Fmain\u002Fcodex-rs\u002Fhooks\u002Fsrc\u002Fengine\u002Fdiscovery.rs)), so the same hook scripts work across both hosts without duplication. Subagent \u002F SessionEnd \u002F Notification \u002F TaskCompleted \u002F PostToolUseFailure events are Claude-Code-only and are not registered for Codex.\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>OpenClaw (paste this prompt)\u003C\u002Fb>\u003C\u002Fsummary>\n\n```\nInstall agentmemory for OpenClaw. Run `npx @agentmemory\u002Fagentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 51 memory tools:\n\n{\n  \"mcpServers\": {\n    \"agentmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentmemory\u002Fmcp\"],\n      \"env\": {\n        \"AGENTMEMORY_URL\": \"http:\u002F\u002Flocalhost:3111\"\n      }\n    }\n  }\n}\n\nRestart OpenClaw. Verify with `curl http:\u002F\u002Flocalhost:3111\u002Fagentmemory\u002Fhealth`. Open http:\u002F\u002Flocalhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations\u002Fopenclaw` to `~\u002F.openclaw\u002Fextensions\u002Fagentmemory` and enable `plugins.slots.memory = \"agentmemory\"` in `~\u002F.openclaw\u002Fopenclaw.json`.\n```\n\nFull guide: [`integrations\u002Fopenclaw\u002F`](integrations\u002Fopenclaw\u002F)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Hermes Agent (paste this prompt)\u003C\u002Fb>\u003C\u002Fsummary>\n\n```\nInstall agentmemory for Hermes. Run `npx @agentmemory\u002Fagentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~\u002F.hermes\u002Fconfig.yaml so Hermes can use agentmemory as an MCP server with all 51 memory tools:\n\nmcp_servers:\n  agentmemory:\n    command: npx\n    args: [\"-y\", \"@agentmemory\u002Fmcp\"]\n\nmemory:\n  provider: agentmemory\n\nVerify with `curl http:\u002F\u002Flocalhost:3111\u002Fagentmemory\u002Fhealth`. Open http:\u002F\u002Flocalhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations\u002Fhermes from the agentmemory repo to ~\u002F.hermes\u002Fplugins\u002Fagentmemory.\n```\n\nFull guide: [`integrations\u002Fhermes\u002F`](integrations\u002Fhermes\u002F)\n\n\u003C\u002Fdetails>\n\n### Other agents\n\nStart the memory server: `npx @agentmemory\u002Fagentmemory`\n\nThe agentmemory entry is the **same MCP server block** across every host that uses the `mcpServers` shape (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):\n\n```json\n\"agentmemory\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@agentmemory\u002Fmcp\"],\n  \"env\": {\n    \"AGENTMEMORY_URL\": \"http:\u002F\u002Flocalhost:3111\"\n  }\n}\n```\n\n**Merge this entry into the existing `mcpServers` object** in the host's config file — don't replace the file. If the file already has other servers, add `agentmemory` next to them as another key inside `mcpServers`. If `mcpServers` is missing entirely, paste the block inside `{ \"mcpServers\": { ... } }`.\n\n| Agent | Config file | Notes |\n|---|---|---|\n| **Cursor** | `~\u002F.cursor\u002Fmcp.json` | Merge into `mcpServers`. One-click deeplink also available on the website. |\n| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Merge into `mcpServers`. Restart Claude Desktop after editing. |\n| **Cline \u002F Roo Code \u002F Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Same `mcpServers` block. |\n| **Windsurf** | `~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json` | Same `mcpServers` block. |\n| **Gemini CLI** | `~\u002F.gemini\u002Fsettings.json` | `gemini mcp add agentmemory npx -y @agentmemory\u002Fmcp --scope user` (auto-merges). |\n| **OpenClaw** | OpenClaw MCP config | Same `mcpServers` block, or use the deeper [memory plugin](integrations\u002Fopenclaw\u002F). |\n| **Codex CLI (MCP only)** | `.codex\u002Fconfig.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory\u002Fmcp`, or add `[mcp_servers.agentmemory]` manually. |\n| **Codex CLI (full plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00\u002Fagentmemory` then `codex plugin install agentmemory`. Registers MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 skills. |\n| **OpenCode** | `opencode.json` | Different shape — top-level `mcp` key, command as array: `{\"mcp\": {\"agentmemory\": {\"type\": \"local\", \"command\": [\"npx\", \"-y\", \"@agentmemory\u002Fmcp\"], \"enabled\": true}}}`. |\n| **pi** | `~\u002F.pi\u002Fagent\u002Fextensions\u002Fagentmemory` | Copy [`integrations\u002Fpi`](integrations\u002Fpi\u002F) and restart pi. |\n| **Hermes Agent** | `~\u002F.hermes\u002Fconfig.yaml` | Use the deeper [memory provider plugin](integrations\u002Fhermes\u002F) with `memory.provider: agentmemory`. |\n| **Goose** | Goose MCP settings UI | Same `mcpServers` block. |\n| **Aider** | n\u002Fa | Talk to the REST API directly: `curl -X POST http:\u002F\u002Flocalhost:3111\u002Fagentmemory\u002Fsmart-search -d '{\"query\": \"auth\"}'`. |\n| **Any agent (32+)** | n\u002Fa | `npx skillkit install agentmemory` auto-detects the host and merges. |\n\n**Sandboxed MCP clients** (Flatpak \u002F Snap \u002F restrictive containers) that can't reach the host's `localhost`: also set `\"AGENTMEMORY_FORCE_PROXY\": \"1\"` in the `env` block, and point `AGENTMEMORY_URL` at a route the sandbox can actually reach (e.g. your LAN IP). See [#234](https:\u002F\u002Fgithub.com\u002Frohitg00\u002Fagentmemory\u002Fissues\u002F234) for the diagnostic walkthrough.\n\n### Programmatic access (Python \u002F Rust \u002F Node)\n\nagentmemory registers its core operations as iii functions (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Any language with an iii SDK can call them directly over `ws:\u002F\u002Flocalhost:49134` — no separate REST client per language.\n\n```bash\npip install iii-sdk         # Python\ncargo add iii-sdk           # Rust\nnpm  install iii-sdk        # Node\n```\n\n```python\nfrom iii import register_worker\n\niii = register_worker(\"ws:\u002F\u002Flocalhost:49134\")\niii.connect()\n\niii.trigger({\n    \"function_id\": \"mem::smart-search\",\n    \"payload\": {\"project\": \"demo\", \"query\": \"how do tokens refresh\"},\n})\n```\n\nWorked example: [`examples\u002Fpython\u002F`](examples\u002Fpython\u002F) (quickstart + observation\u002Frecall flow). REST on `:3111` remains available for hosts without an iii runtime.\n\n### From source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Frohitg00\u002Fagentmemory.git && cd agentmemory\nnpm install && npm run build && npm start\n```\n\nThis starts agentmemory with a local `iii-engine` if `iii` is already installed, or falls back to Docker Compose if Docker is available. REST, streams, and the viewer bind to `127.0.0.1` by default.\n\nInstall `iii-engine` manually. **agentmemory currently pins `iii-engine` to `v0.11.2`** — `v0.11.6` introduces a new sandbox-everything-via-`iii worker add` model that agentmemory hasn't been refactored for yet. Pin lifts once the refactor lands. Override with `AGENTMEMORY_III_VERSION=\u003Cversion>` if you've migrated to the sandbox model manually.\n\n- **macOS arm64:** `mkdir -p ~\u002F.local\u002Fbin && curl -fsSL https:\u002F\u002Fgithub.com\u002Fiii-hq\u002Fiii\u002Freleases\u002Fdownload\u002Fiii\u002Fv0.11.2\u002Fiii-aarch64-apple-darwin.tar.gz | tar -xz -C ~\u002F.local\u002Fbin && chmod +x ~\u002F.local\u002Fbin\u002Fiii`\n- **macOS x64:** swap `aarch64-apple-darwin` for `x86_64-apple-darwin`\n- **Linux x64:** swap for `x86_64-unknown-linux-gnu`\n- **Linux arm64:** swap for `aarch64-unknown-linux-gnu`\n- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` from [iii-hq\u002Fiii releases v0.11.2](https:\u002F\u002Fgithub.com\u002Fiii-hq\u002Fiii\u002Freleases\u002Ftag\u002Fiii%2Fv0.11.2), extract `iii.exe`, add to PATH\n\nOr use Docker (the bundled `docker-compose.yml` pulls `iiidev\u002Fiii:0.11.2`). Full docs: [iii.dev\u002Fdocs](https:\u002F\u002Fiii.dev\u002Fdocs).\n\n### Windows\n\nagentmemory runs on Windows 10\u002F11, but the Node.js package alone isn't enough — you also need the `iii-engine` runtime (a separate native binary) as a background process. The official upstream installer is a `sh` script and there is no PowerShell installer or scoop\u002Fwinget package today, so Windows users have two paths:\n\n**Option A — Prebuilt Windows binary (recommended):**\n\n```powershell\n# 1. Open https:\u002F\u002Fgithub.com\u002Fiii-hq\u002Fiii\u002Freleases\u002Ftag\u002Fiii%2Fv0.11.2 in your browser\n#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox\n#     model that engine v0.11.6+ requires)\n# 2. Download iii-x86_64-pc-windows-msvc.zip\n#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)\n# 3. Extract iii.exe somewhere on PATH, or place it at:\n#    %USERPROFILE%\\.local\\bin\\iii.exe\n#    (agentmemory checks that location automatically)\n# 4. Verify:\niii --version\n# Should print: 0.11.2\n\n# 5. Then run agentmemory as usual:\nnpx -y @agentmemory\u002Fagentmemory\n```\n\n**Option B — Docker Desktop:**\n\n```powershell\n# 1. Install Docker Desktop for Windows\n# 2. Start Docker Desktop and make sure the engine is running\n# 3. Run agentmemory — it will auto-start the bundled compose file:\nnpx -y @agentmemory\u002Fagentmemory\n```\n\n**Option C — standalone MCP only (no engine):** if you only need the MCP tools for your agent and don't need the REST API, viewer, or cron jobs, skip the engine entirely:\n\n```powershell\nnpx -y @agentmemory\u002Fagentmemory mcp\n# or via the shim package:\nnpx -y @agentmemory\u002Fmcp\n```\n\n**Diagnostics for Windows:** if `npx @agentmemory\u002Fagentmemory` fails, re-run with `--verbose` to see the actual engine stderr. Common failure modes:\n\n| Symptom | Fix |\n|---|---|\n| `iii-engine process started` then `did not become ready within 15s` | Engine crashed on startup — re-run with `--verbose`, check stderr |\n| `Could not start iii-engine` | Neither `iii.exe` nor Docker is installed. See Option A or B above |\n| Port conflict | `netstat -ano \\| findstr :3111` to see what's bound, then kill it or use `--port \u003CN>` |\n| Docker fallback skipped even though Docker is installed | Make sure Docker Desktop is actually running (system tray icon) |\n\n> Note: there is no `cargo install iii-engine` — `iii` is not published to crates.io. The only supported install methods are the prebuilt binary above, the upstream `sh` install script (macOS\u002FLinux only), and the Docker image.\n\n---\n\n\u003Ch2 id=\"deploy\">Deploy\u003C\u002Fh2>\n\nOne-click templates for managed hosts. Each one ships a self-contained\nDockerfile that pulls `@agentmemory\u002Fagentmemory` from npm and copies\nthe iii engine binary in from the official `iiidev\u002Fiii` Docker Hub\nimage — no pre-built agentmemory image required. Persistent storage\nmounts at `\u002Fdata`; the first-boot entrypoint overwrites the\nnpm-bundled iii config (which binds `127.0.0.1`) with a deploy-tuned\none that binds `0.0.0.0` and uses absolute `\u002Fdata` paths, generates\nthe HMAC secret, then drops privileges from `root` to `node` via\n`gosu` before exec'ing the agentmemory CLI.\n\n\u003Cp>\n  \u003Ca href=\"https:\u002F\u002Ffly.io\u002Flaunch?repo=https:\u002F\u002Fgithub.com\u002Frohitg00\u002Fagentmemory&path=deploy\u002Ffly\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDeploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white\" alt=\"Deploy to fly.io\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Frailway.com\u002Fnew\u002Ftemplate?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDeploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white\" alt=\"Deploy to Railway\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\nRender's one-click deploy button requires `render.yaml` at the repository root, which we deliberately keep clean. Use the Render Blueprint flow documented in [`deploy\u002Frender\u002F`](.\u002Fdeploy\u002Frender\u002FREADME.md) to point at the in-repo blueprint manually.\n\nFull setup details (HMAC capture, viewer SSH tunnel, rotation, backup,\ncost floors) live in [`deploy\u002F`](.\u002Fdeploy\u002FREADME.md):\n\n- [`deploy\u002Ffly`](.\u002Fdeploy\u002Ffly\u002FREADME.md) — single machine with\n  `auto_stop_machines = \"stop\"`; cheapest idle.\n- [`deploy\u002Frailway`](.\u002Fdeploy\u002Frailway\u002FREADME.md) — Hobby plan flat fee,\n  volume in the dashboard.\n- [`deploy\u002Frender`](.\u002Fdeploy\u002Frender\u002FREADME.md) — Blueprint flow,\n  automatic disk snapshots on paid plans.\n- [`deploy\u002Fcoolify`](.\u002Fdeploy\u002Fcoolify\u002FREADME.md) — self-hosted on your\n  own VPS via [Coolify](https:\u002F\u002Fcoolify.io\u002Fself-hosted); same Docker\n  Compose stack, you own the host and the data.\n\nOnly port `3111` is published. The viewer on `3113` stays bound to\nloopback inside the container — every template's README documents the\nSSH-tunnel pattern for reaching it.\n\n---\n\n\u003Ch2 id=\"why-agentmemory\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-why.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-why.svg\" alt=\"Why agentmemory\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\nEvery coding agent forgets everything when the session ends. You waste the first 5 minutes of every session re-explaining your stack. agentmemory runs in the background and eliminates that entirely.\n\n```\nSession 1: \"Add auth to the API\"\n  Agent writes code, runs tests, fixes bugs\n  agentmemory silently captures every tool use\n  Session ends -> observations compressed into structured memory\n\nSession 2: \"Now add rate limiting\"\n  Agent already knows:\n    - Auth uses JWT middleware in src\u002Fmiddleware\u002Fauth.ts\n    - Tests in test\u002Fauth.test.ts cover token validation\n    - You chose jose over jsonwebtoken for Edge compatibility\n  Zero re-explaining. Starts working immediately.\n```\n\n### vs built-in agent memory\n\nEvery AI coding agent ships with built-in memory — Claude Code has `MEMORY.md`, Cursor has notepads, Cline has memory bank. These work like sticky notes. agentmemory is the searchable database behind the sticky notes.\n\n| | Built-in (CLAUDE.md) | agentmemory |\n|---|---|---|\n| Scale | 200-line cap | Unlimited |\n| Search | Loads everything into context | BM25 + vector + graph (top-K only) |\n| Token cost | 22K+ at 240 observations | ~1,900 tokens (92% less) |\n| Cross-agent | Per-agent files | MCP + REST (any agent) |\n| Coordination | None | Leases, signals, actions, routines |\n| Observability | Read files manually | Real-time viewer on :3113 |\n\n---\n\n\u003Ch2 id=\"how-it-works\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-how.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-how.svg\" alt=\"How It Works\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\n### Memory Pipeline\n\n```\nPostToolUse hook fires\n  -> SHA-256 dedup (5min window)\n  -> Privacy filter (strip secrets, API keys)\n  -> Store raw observation\n  -> LLM compress -> structured facts + concepts + narrative\n  -> Vector embedding (6 providers + local)\n  -> Index in BM25 + vector\n\nStop \u002F SessionEnd hook fires\n  -> Summarize session\n  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)\n  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)\n\nSessionStart hook fires\n  -> Load project profile (top concepts, files, patterns)\n  -> Hybrid search (BM25 + vector + graph)\n  -> Token budget (default: 2000 tokens)\n  -> Inject into conversation\n```\n\n### 4-Tier Memory Consolidation\n\nInspired by how human brains process memory — not unlike sleep consolidation.\n\n| Tier | What | Analogy |\n|------|------|---------|\n| **Working** | Raw observations from tool use | Short-term memory |\n| **Episodic** | Compressed session summaries | \"What happened\" |\n| **Semantic** | Extracted facts and patterns | \"What I know\" |\n| **Procedural** | Workflows and decision patterns | \"How to do it\" |\n\nMemories decay over time (Ebbinghaus curve). Frequently accessed memories strengthen. Stale memories auto-evict. Contradictions are detected and resolved.\n\n### What Gets Captured\n\n| Hook | Captures |\n|------|----------|\n| `SessionStart` | Project path, session ID |\n| `UserPromptSubmit` | User prompts (privacy-filtered) |\n| `PreToolUse` | File access patterns + enriched context |\n| `PostToolUse` | Tool name, input, output |\n| `PostToolUseFailure` | Error context |\n| `PreCompact` | Re-injects memory before compaction |\n| `SubagentStart\u002FStop` | Sub-agent lifecycle |\n| `Stop` | End-of-session summary |\n| `SessionEnd` | Session complete marker |\n\n### Key Capabilities\n\n| Capability | Description |\n|---|---|\n| **Automatic capture** | Every tool use recorded via hooks — zero manual effort |\n| **Semantic search** | BM25 + vector + knowledge graph with RRF fusion |\n| **Memory evolution** | Versioning, supersession, relationship graphs |\n| **Auto-forgetting** | TTL expiry, contradiction detection, importance eviction |\n| **Privacy first** | API keys, secrets, `\u003Cprivate>` tags stripped before storage |\n| **Self-healing** | Circuit breaker, provider fallback chain, health monitoring |\n| **Claude bridge** | Bi-directional sync with MEMORY.md |\n| **Knowledge graph** | Entity extraction + BFS traversal |\n| **Team memory** | Namespaced shared + private across team members |\n| **Citation provenance** | Trace any memory back to source observations |\n| **Git snapshots** | Version, rollback, and diff memory state |\n\n---\n\n\u003Ch2 id=\"search\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-search.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-search.svg\" alt=\"Search\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\nTriple-stream retrieval combining three signals:\n\n| Stream | What it does | When |\n|---|---|---|\n| **BM25** | Stemmed keyword matching with synonym expansion | Always on |\n| **Vector** | Cosine similarity over dense embeddings | Embedding provider configured |\n| **Graph** | Knowledge graph traversal via entity matching | Entities detected in query |\n\nFused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 results per session).\n\nBM25 tokenizes Greek, Cyrillic, Hebrew, Arabic, and accented Latin out of the box. For Chinese \u002F Japanese \u002F Korean memories, install the optional segmenters (`npm install @node-rs\u002Fjieba tiny-segmenter`) to split CJK runs into word-level tokens; without them, agentmemory soft-falls to whole-run tokenization and prints a one-time hint on stderr.\n\n### Embedding providers\n\nagentmemory auto-detects your provider. For best results, install local embeddings (free):\n\n```bash\nnpm install @xenova\u002Ftransformers\n```\n\n| Provider | Model | Cost | Notes |\n|---|---|---|---|\n| **Local (recommended)** | `all-MiniLM-L6-v2` | Free | Offline, +8pp recall over BM25-only |\n| Gemini | `gemini-embedding-001` | Free tier | 100+ languages, 768\u002F1536\u002F3072 dims (MRL), 2048-token input. Replaces `text-embedding-004` ([deprecated, shutdown Jan 14, 2026](https:\u002F\u002Fai.google.dev\u002Fgemini-api\u002Fdocs\u002Fdeprecations)) |\n| OpenAI | `text-embedding-3-small` | $0.02\u002F1M | Highest quality |\n| Voyage AI | `voyage-code-3` | Paid | Optimized for code |\n| Cohere | `embed-english-v3.0` | Free trial | General purpose |\n| OpenRouter | Any model | Varies | Multi-model proxy |\n\n---\n\n\u003Ch2 id=\"mcp-server\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-mcp.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-mcp.svg\" alt=\"MCP Server\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\n51 tools, 6 resources, 3 prompts, and 4 skills — the most comprehensive MCP memory toolkit for any agent.\n\n> **MCP shim vs full server:** the published `@agentmemory\u002Fmcp` package is a thin shim. It exposes the full 51-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag — setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor \u002F OpenCode \u002F Gemini CLI, start `npx @agentmemory\u002Fagentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http:\u002F\u002Flocalhost:3111`.\n\n### 51 Tools\n\n\u003Cdetails>\n\u003Csummary>Core tools (always available)\u003C\u002Fsummary>\n\n| Tool | Description |\n|------|-------------|\n| `memory_recall` | Search past observations |\n| `memory_compress_file` | Compress markdown files while preserving structure |\n| `memory_save` | Save an insight, decision, or pattern |\n| `memory_patterns` | Detect recurring patterns |\n| `memory_smart_search` | Hybrid semantic + keyword search |\n| `memory_file_history` | Past observations about specific files |\n| `memory_sessions` | List recent sessions |\n| `memory_timeline` | Chronological observations |\n| `memory_profile` | Project profile (concepts, files, patterns) |\n| `memory_export` | Export all memory data |\n| `memory_relations` | Query relationship graph |\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Extended tools (51 total — set AGENTMEMORY_TOOLS=all)\u003C\u002Fsummary>\n\n| Tool | Description |\n|------|-------------|\n| `memory_patterns` | Detect recurring patterns |\n| `memory_timeline` | Chronological observations |\n| `memory_relations` | Query relationship graph |\n| `memory_graph_query` | Knowledge graph traversal |\n| `memory_consolidate` | Run 4-tier consolidation |\n| `memory_claude_bridge_sync` | Sync with MEMORY.md |\n| `memory_team_share` | Share with team members |\n| `memory_team_feed` | Recent shared items |\n| `memory_audit` | Audit trail of operations |\n| `memory_governance_delete` | Delete with audit trail |\n| `memory_snapshot_create` | Git-versioned snapshot |\n| `memory_action_create` | Create work items with dependencies |\n| `memory_action_update` | Update action status |\n| `memory_frontier` | Unblocked actions ranked by priority |\n| `memory_next` | Single most important next action |\n| `memory_lease` | Exclusive action leases (multi-agent) |\n| `memory_routine_run` | Instantiate workflow routines |\n| `memory_signal_send` | Inter-agent messaging |\n| `memory_signal_read` | Read messages with receipts |\n| `memory_checkpoint` | External condition gates |\n| `memory_mesh_sync` | P2P sync between instances |\n| `memory_sentinel_create` | Event-driven watchers |\n| `memory_sentinel_trigger` | Fire sentinels externally |\n| `memory_sketch_create` | Ephemeral action graphs |\n| `memory_sketch_promote` | Promote to permanent |\n| `memory_crystallize` | Compact action chains |\n| `memory_diagnose` | Health checks |\n| `memory_heal` | Auto-fix stuck state |\n| `memory_facet_tag` | Dimension:value tags |\n| `memory_facet_query` | Query by facet tags |\n| `memory_verify` | Trace provenance |\n\n\u003C\u002Fdetails>\n\n### 6 Resources · 3 Prompts · 4 Skills\n\n| Type | Name | Description |\n|------|------|-------------|\n| Resource | `agentmemory:\u002F\u002Fstatus` | Health, session count, memory count |\n| Resource | `agentmemory:\u002F\u002Fproject\u002F{name}\u002Fprofile` | Per-project intelligence |\n| Resource | `agentmemory:\u002F\u002Fmemories\u002Flatest` | Latest 10 active memories |\n| Resource | `agentmemory:\u002F\u002Fgraph\u002Fstats` | Knowledge graph statistics |\n| Prompt | `recall_context` | Search + return context messages |\n| Prompt | `session_handoff` | Handoff data between agents |\n| Prompt | `detect_patterns` | Analyze recurring patterns |\n| Skill | `\u002Frecall` | Search memory |\n| Skill | `\u002Fremember` | Save to long-term memory |\n| Skill | `\u002Fsession-history` | Recent session summaries |\n| Skill | `\u002Fforget` | Delete observations\u002Fsessions |\n\n### Standalone MCP\n\nRun without the full server — for any MCP client. Either of these works:\n\n```bash\nnpx -y @agentmemory\u002Fagentmemory mcp   # canonical (always available)\nnpx -y @agentmemory\u002Fmcp                # shim package alias\n```\n\nOr add to your agent's MCP config:\n\nMost agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):\n```json\n{\n  \"mcpServers\": {\n    \"agentmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentmemory\u002Fmcp\"],\n      \"env\": {\n        \"AGENTMEMORY_URL\": \"http:\u002F\u002Flocalhost:3111\"\n      }\n    }\n  }\n}\n```\n\nMerge the `agentmemory` entry into your host's existing `mcpServers` object rather than replacing the file. For sandboxed clients that can't reach the host's `localhost`, add `\"AGENTMEMORY_FORCE_PROXY\": \"1\"` to the env block and set `AGENTMEMORY_URL` to a route the sandbox can reach.\n\nOpenCode (`opencode.json`):\n```json\n{\n  \"mcp\": {\n    \"agentmemory\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@agentmemory\u002Fmcp\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n---\n\n\u003Ch2 id=\"real-time-viewer\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-viewer.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-viewer.svg\" alt=\"Real-Time Viewer\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\nAuto-starts on port `3113`. Live observation stream, session explorer, memory browser, knowledge graph visualization, and health dashboard.\n\n```bash\nopen http:\u002F\u002Flocalhost:3113\n```\n\nThe viewer server binds to `127.0.0.1` by default. The REST-served `\u002Fagentmemory\u002Fviewer` endpoint follows the normal `AGENTMEMORY_SECRET` bearer-token rules. CSP headers use a per-response script nonce and disable inline handler attributes (`script-src-attr 'none'`).\n\n---\n\n\u003Ch2 id=\"iii-console\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-viewer.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-viewer.svg\" alt=\"iii Console\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\nThe viewer at `:3113` shows what your agent **remembered**. The [iii console](https:\u002F\u002Fiii.dev\u002Fdocs\u002Fconsole) shows what your agent **did** — every memory op as an OpenTelemetry trace, every KV entry editable, every function invocable, every stream tappable. Two windows on the same memory: one product-shaped, one engine-shaped.\n\nWatch a `memory_smart_search` fire and see the BM25 scan → embedding lookup → RRF fusion → reranker as a waterfall. Edit a stuck consolidation timer in the KV browser. Replay a `PostToolUse` hook with a tweaked payload. Pin the WebSocket stream and watch observations land live.\n\nagentmemory ships this for free because every function, trigger, state scope, and stream is an iii primitive — nothing custom, nothing to instrument.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fiii-console\u002Fworkers.png\" alt=\"iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata\" width=\"720\" \u002F>\n  \u003Cbr\u002F>\n  \u003Cem>Workers page: every connected worker — including agentmemory itself — with PID, function count, runtime, and last-seen.\u003C\u002Fem>\n\u003C\u002Fp>\n\n**Already installed.** The console ships with `iii` — no separate installer.\n\n**Launch alongside agentmemory:**\n\n```bash\n# agentmemory viewer holds port 3113, so run the console on 3114.\n# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.\niii console --port 3114\n```\n\nThen open `http:\u002F\u002Flocalhost:3114`. Add `--enable-flow` for the experimental architecture-graph page.\n\nOverride engine endpoints only if you've moved them:\n\n```bash\niii console --port 3114 \\\n  --engine-port 3111 \\\n  --ws-port 3112 \\\n  --bridge-port 49134\n```\n\n**What you can do from the console:**\n\n| Page | Use it to |\n|------|-----------|\n| **Workers** | See every connected worker and its live metrics — including the agentmemory worker itself. |\n| **Functions** | Invoke any of agentmemory's functions directly with a JSON payload — handy for testing `memory.recall`, `memory.consolidate`, `graph.query` without wiring a client. |\n| **Triggers** | Replay HTTP, cron, event, and state triggers — fire the consolidation cron manually, retry an HTTP route, emit a state change. |\n| **States** | KV browser with full CRUD — sessions, memory slots, lifecycle timers, embeddings index — edit values in place. |\n| **Streams** | Live WebSocket monitor for memory writes, hook events, and observation updates as they flow through iii streams. |\n| **Queues** | Durable queue topics + dead-letter management. Replay or drop failed embedding \u002F compression jobs. |\n| **Traces** | OpenTelemetry waterfall \u002F flame \u002F service-breakdown views. Filter by `trace_id` to see exactly which functions, DB calls, and embedding requests a single `memory.search` produced. |\n| **Logs** | Structured OTEL logs filtered and correlated to trace\u002Fspan IDs. |\n| **Config** | Runtime configuration — see exactly which workers, providers, and ports your engine is running with. |\n| **Flow** | (Optional, `--enable-flow`) Interactive architecture graph of every worker, trigger, and stream. |\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fiii-console\u002Ftraces-waterfall.png\" alt=\"iii console trace waterfall view showing per-span duration\" width=\"720\" \u002F>\n  \u003Cbr\u002F>\n  \u003Cem>Traces: waterfall \u002F flame \u002F service breakdown for every memory operation.\u003C\u002Fem>\n\u003C\u002Fp>\n\n**Traces are already on:**\n\n`iii-config.yaml` ships with the `iii-observability` worker enabled (`exporter: memory`, `sampling_ratio: 1.0`, metrics + logs). No extra config needed — the moment agentmemory starts, every memory operation emits a trace span and a structured log the console can read.\n\nIf you want to export to Jaeger\u002FHoneycomb\u002FGrafana Tempo instead, change `exporter: memory` to `exporter: otlp` and set the collector endpoint per iii's observability docs.\n\n> **Heads-up:** no auth is enforced on the console itself — keep it bound to `127.0.0.1` (the default) and never expose it publicly.\n\n---\n\n\u003Ch2 id=\"powered-by-iii\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-architecture.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-architecture.svg\" alt=\"Powered by iii\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\nagentmemory is **already a running [iii](https:\u002F\u002Fiii.dev) instance**. Functions, triggers, KV state, streams, OTEL traces — all of it is iii primitives. You didn't install Postgres, Redis, Express, pm2, or Prometheus, because iii replaces them.\n\nThat means one more command extends agentmemory with an entire new capability.\n\n### Extend agentmemory with one command\n\n```bash\niii worker add iii-pubsub          # fan memory writes out to every connected instance\niii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation\niii worker add iii-queue           # durable retries for embedding + compression jobs\niii worker add iii-observability   # OTEL traces on every memory op (default on)\niii worker add iii-sandbox         # run recalled code inside an isolated microVM\niii worker add iii-database        # swap in a SQL-backed state adapter\niii worker add mcp                 # generic MCP host alongside the agentmemory MCP\n```\n\nEach `iii worker add` registers new functions and triggers into the same engine agentmemory is already running on. The viewer and console pick them up immediately — no reload, no new integration, no new container.\n\n| `iii worker add` | What you get on top of agentmemory |\n|---|---|\n| [`iii-pubsub`](https:\u002F\u002Fworkers.iii.dev\u002Fworkers\u002Fiii-pubsub) | Multi-instance memory: every `remember` fans out, every `search` reads the union |\n| [`iii-cron`](https:\u002F\u002Fworkers.iii.dev\u002Fworkers\u002Fiii-cron) | Scheduled lifecycle — nightly consolidation, weekly snapshots, decay on a fixed clock |\n| [`iii-queue`](https:\u002F\u002Fworkers.iii.dev\u002Fworkers\u002Fiii-queue) | Durable retries: failed embedding + compression jobs survive restart, no lost observations |\n| [`iii-observability`](https:\u002F\u002Fworkers.iii.dev\u002Fworkers\u002Fiii-observability) | OTEL traces, metrics, logs on every function — wired in `iii-config.yaml` from day one |\n| [`iii-sandbox`](https:\u002F\u002Fworkers.iii.dev\u002Fworkers\u002Fiii-sandbox) | Code that came out of `memory_recall` runs inside a throwaway VM, not your shell |\n| [`iii-database`](https:\u002F\u002Fworkers.iii.dev\u002Fworkers\u002Fiii-database) | SQL-backed state adapter when you outgrow the in-memory KV defaults |\n| [`mcp`](https:\u002F\u002Fworkers.iii.dev\u002Fworkers\u002Fmcp) | Stand up extra MCP servers next to agentmemory's, share the same engine |\n\nFull registry: [workers.iii.dev](https:\u002F\u002Fworkers.iii.dev). Every worker there composes through the same primitives agentmemory uses — and the agentmemory you already have is one of them.\n\n### What iii replaces\n\n| Traditional stack | agentmemory uses |\n|---|---|\n| Express.js \u002F Fastify | iii HTTP Triggers |\n| SQLite \u002F Postgres + pgvector | iii KV State + in-memory vector index |\n| SSE \u002F Socket.io | iii Streams (WebSocket) |\n| pm2 \u002F systemd | iii engine worker supervision |\n| Prometheus \u002F Grafana | iii OTEL + health monitor |\n| Custom plugin systems | `iii worker add \u003Cname>` |\n\n**118 source files · ~21,800 LOC · 950+ tests · 123 functions · 34 KV scopes** — all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.\n\n---\n\n\u003Ch2 id=\"configuration\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-config.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-config.svg\" alt=\"Configuration\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\n### LLM Providers\n\nagentmemory auto-detects from your environment. No API key needed if you have a Claude subscription.\n\n| Provider | Config | Notes |\n|----------|--------|-------|\n| **No-op (default)** | No config needed | LLM-backed compress\u002Fsummarize is DISABLED. Synthetic BM25 compression + recall still work. See `AGENTMEMORY_ALLOW_AGENT_SDK` below if you used to rely on the Claude-subscription fallback. |\n| Anthropic API | `ANTHROPIC_API_KEY` | Per-token billing |\n| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |\n| Gemini | `GEMINI_API_KEY` | Also enables embeddings |\n| OpenRouter | `OPENROUTER_API_KEY` | Any model |\n| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in only. Spawns `@anthropic-ai\u002Fclaude-agent-sdk` sessions — used to cause unbounded Stop-hook recursion (#149 follow-up) so it is no longer the default. |\n\n### Environment Variables\n\nCreate `~\u002F.agentmemory\u002F.env`:\n\n```env\n# LLM provider (pick one — default is the no-op provider: no LLM calls)\n# ANTHROPIC_API_KEY=sk-ant-...\n# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy \u002F Azure\n# GEMINI_API_KEY=...\n# OPENROUTER_API_KEY=...\n# MINIMAX_API_KEY=...\n# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the\n#                                          # OpenAI LLM provider (here) AND the OpenAI\n#                                          # embedding provider (further below). Set\n#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it\n#                                          # to embeddings only.\n# OPENAI_BASE_URL=https:\u002F\u002Fapi.openai.com   # Optional: override for Azure \u002F vLLM \u002F LM Studio \u002F proxies\n#                                          # Azure: https:\u002F\u002F\u003Cresource>.openai.azure.com\u002Fopenai\u002Fdeployments\u002F\u003Cdeployment>\n#                                          # Auto-detected from `.openai.azure.com` hostname; uses\n#                                          # api-key header + api-version query param.\n# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param\n# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model\n# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch\n#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS\n#                                          # for back-compat with v0.9.17. New configs should\n#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.\n# OPENAI_REASONING_EFFORT=none             # Optional: \"low\" | \"medium\" | \"high\" | \"none\"\n#                                          # Honored only by OpenAI's reasoning models (o1, o3,\n#                                          # gpt-*-reasoning) and providers that mirror that\n#                                          # schema (Ollama Cloud thinking models). Standard\n#                                          # chat models reject this field with 400. Set to\n#                                          # \"none\" for thinking models that return reasoning\n#                                          # but no content.\n# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection\n#                                          # for LLM (useful if you only want OpenAI for embeddings)\n# Opt-in Claude-subscription fallback (spawns @anthropic-ai\u002Fclaude-agent-sdk);\n# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):\n# AGENTMEMORY_ALLOW_AGENT_SDK=true\n\n# Embedding provider (auto-detected, or override)\n# EMBEDDING_PROVIDER=local\n# VOYAGE_API_KEY=...\n# OPENAI_API_KEY=sk-...\n# OPENAI_BASE_URL=https:\u002F\u002Fapi.openai.com   # Override for Azure \u002F vLLM \u002F LM Studio \u002F proxies\n# OPENAI_EMBEDDING_MODEL=text-embedding-3-small\n# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table\n\n# Outbound LLM \u002F embedding timeout\n# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every\n                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,\n                                          # OpenAI LLM, OpenAI\u002FCohere\u002FVoyage\u002FOpenRouter\n                                          # embedding). For the OpenAI LLM path, the\n                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)\n                                          # takes precedence when set, for back-compat\n                                          # with v0.9.17.\n                                          # Increase for slow networks or large batch calls;\n                                          # decrease to fail-fast on rate-limit holds.\n\n# Search tuning\n# BM25_WEIGHT=0.4\n# VECTOR_WEIGHT=0.6\n# TOKEN_BUDGET=2000\n\n# Auth\n# AGENTMEMORY_SECRET=your-secret\n\n# Ports (defaults: 3111 API, 3113 viewer)\n# III_REST_PORT=3111\n\n# Features\n# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,\n                                   # every PostToolUse hook calls your\n                                   # LLM provider to compress the\n                                   # observation — expect significant\n                                   # token spend on active sessions.\n# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned\n                                   # memory slots — persona,\n                                   # user_preferences, tool_guidelines,\n                                   # project_context, guidance,\n                                   # pending_items, session_patterns,\n                                   # self_notes. Size-limited; agent\n                                   # edits via memory_slot_* tools.\n                                   # Pinned slots addressable for\n                                   # SessionStart injection.\n# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.\n                                   # Stop hook fires mem::slot-reflect:\n                                   # scans recent observations, auto-\n                                   # appends TODOs to pending_items,\n                                   # counts patterns in\n                                   # session_patterns, records touched\n                                   # files in project_context. Fire-\n                                   # and-forget; does not block.\n# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:\n                                   # - SessionStart may inject ~1-2K\n                                   #   chars of project context into\n                                   #   the first turn of each session\n                                   #   (this is what actually reaches\n                                   #   the model — Claude Code treats\n                                   #   SessionStart stdout as context)\n                                   # - PreToolUse fires \u002Fagentmemory\u002Fenrich\n                                   #   on every file-touching tool call\n                                   #   (resource cleanup, not a token\n                                   #   fix — PreToolUse stdout is debug\n                                   #   log only per Claude Code docs)\n                                   # Observations are still captured via\n                                   # PostToolUse regardless of this flag.\n# GRAPH_EXTRACTION_ENABLED=false\n# CONSOLIDATION_ENABLED=true\n# LESSON_DECAY_ENABLED=true\n# OBSIDIAN_AUTO_EXPORT=false\n# AGENTMEMORY_EXPORT_ROOT=~\u002F.agentmemory\n# CLAUDE_MEMORY_BRIDGE=false\n# SNAPSHOT_ENABLED=false\n\n# Team\n# TEAM_ID=\n# USER_ID=\n# TEAM_MODE=private\n\n# Tool visibility: \"core\" (8 tools) or \"all\" (51 tools)\n# AGENTMEMORY_TOOLS=core\n```\n\n---\n\n\u003Ch2 id=\"api\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-api.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-api.svg\" alt=\"API\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\n121 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer \u003Csecret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.\n\n\u003Cdetails>\n\u003Csummary>Key endpoints\u003C\u002Fsummary>\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `\u002Fagentmemory\u002Fhealth` | Health check (always public) |\n| `POST` | `\u002Fagentmemory\u002Fsession\u002Fstart` | Start session + get context |\n| `POST` | `\u002Fagentmemory\u002Fsession\u002Fend` | End session |\n| `POST` | `\u002Fagentmemory\u002Fobserve` | Capture observation |\n| `POST` | `\u002Fagentmemory\u002Fsmart-search` | Hybrid search |\n| `POST` | `\u002Fagentmemory\u002Fcontext` | Generate context |\n| `POST` | `\u002Fagentmemory\u002Fremember` | Save to long-term memory |\n| `POST` | `\u002Fagentmemory\u002Fforget` | Delete observations |\n| `POST` | `\u002Fagentmemory\u002Fenrich` | File context + memories + bugs |\n| `GET` | `\u002Fagentmemory\u002Fprofile` | Project profile |\n| `GET` | `\u002Fagentmemory\u002Fexport` | Export all data |\n| `POST` | `\u002Fagentmemory\u002Fimport` | Import from JSON |\n| `POST` | `\u002Fagentmemory\u002Fgraph\u002Fquery` | Knowledge graph query |\n| `POST` | `\u002Fagentmemory\u002Fteam\u002Fshare` | Share with team |\n| `GET` | `\u002Fagentmemory\u002Faudit` | Audit trail |\n\nFull endpoint list: [`src\u002Ftriggers\u002Fapi.ts`](src\u002Ftriggers\u002Fapi.ts)\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Ch2 id=\"development\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-development.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-development.svg\" alt=\"Development\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\n```bash\nnpm run dev               # Hot reload\nnpm run build             # Production build\nnpm test                  # 950+ tests\nnpm run test:integration  # API tests (requires running services)\n```\n\n**Prerequisites:** Node.js >= 20, [iii-engine](https:\u002F\u002Fiii.dev\u002Fdocs) or Docker\n\n\u003Ch2 id=\"license\">\u003Cpicture>\u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Ftags\u002Flight\u002Fsection-license.svg\">\u003Cimg src=\"assets\u002Ftags\u002Fsection-license.svg\" alt=\"License\" height=\"32\" \u002F>\u003C\u002Fpicture>\u003C\u002Fh2>\n\n[Apache-2.0](LICENSE)\n","agentmemory 是一个为AI编码助手提供持久记忆功能的项目，基于真实世界的基准测试。它支持Claude Code、Cursor、Gemini CLI等多种AI代理工具，通过集成信心评分、生命周期管理、知识图谱和混合搜索等技术特性，确保了高效的上下文理解和信息检索能力。使用TypeScript编写，能够显著减少重复解释工作，提高开发效率。适用于需要长期记忆支持的各种AI辅助编程场景，如代码生成、调试及维护等任务。",2,"2026-06-11 03:31:54","trending"]