agentmemory

Your coding agent remembers everything. No more re-explaining. Built on iii engine
Persistent memory for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client.

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Türkçe | Русский | हिन्दी | Português | Français | Deutsch

The gist extends Karpathy's LLM Wiki pattern with confidence scoring, lifecycle, knowledge graphs, and hybrid search: agentmemory is the implementation.

Install • Quick Start • Benchmarks • vs Competitors • Agents • How It Works • MCP • Viewer • iii Console • Powered by iii • Config • API

Install

Fastest path if you use a coding agent: hand it this one instruction and it installs, wires, and verifies agentmemory end to end.

Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md

On Windows the fast path is WSL2. Native Windows engine setup is manual (about 10 to 20 minutes) and agentmemory connect is currently unsupported there. See the Windows notes below for the step-by-step.

npm install -g @agentmemory/agentmemory          # once — bare `agentmemory` on PATH
# If you hit EACCES on macOS/Linux system Node installs, retry with:
# sudo npm install -g @agentmemory/agentmemory
agentmemory                                      # start the memory server on :3111
agentmemory demo                                 # seed sample sessions + prove recall
agentmemory demo --serve                         # one command: boot server, run demo, tear down (no second terminal)
agentmemory connect claude-code                  # wire MCP into your agent (also: copilot-cli, codex, cursor, gemini-cli, ...)
npx skills add rohitg00/agentmemory -y           # install 15 native skills (8 you can invoke, 7 reference) so your agent knows when to use the tools

Or via npx (no install):

npx @agentmemory/agentmemory

Heads-up — npx caches per version. If a bare npx @agentmemory/agentmemory serves an older release, force the latest with npx -y @agentmemory/agentmemory@latest, or clear the cache once with rm -rf ~/.npm/_npx (macOS/Linux; 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.

Full options at Quick Start below. Agent-specific wiring at Works with every agent.

agentmemory works with any agent that supports hooks, MCP, or REST API. All agents share the same memory server.

Claude Code native plugin + 12 hooks + MCP	Codex CLI native plugin + 6 hooks + MCP	GitHub Copilot CLI MCP + plugin hooks/skills	OpenClaw native plugin + MCP	Hermes native plugin + MCP	pi native plugin + MCP	OpenHuman native Memory trait backend	Cursor MCP server	Gemini CLI MCP server
OpenCode 22 hooks + MCP + plugin	Cline MCP server	Goose MCP server	Kilo Code MCP server	Aider REST API	Claude Desktop MCP server	Windsurf MCP server	Roo Code MCP server
Warp connect + MCP + skills

_{Works with any agent that speaks MCP or HTTP. One server, memories shared across all of them.}

You 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.

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. No re-explaining. No copy-pasting. The agent just knows.

npx @agentmemory/agentmemory

Latest release notes: CHANGELOG.md.

Embedding model: all-MiniLM-L6-v2 (local, free, no API key). Full reports: benchmark/LONGMEMEVAL.md, benchmark/QUALITY.md, benchmark/SCALE.md. Competitor comparison: benchmark/COMPARISON.md covering agentmemory vs mem0, Letta, Khoj, supermemory, MemPalace, Hippo.

Reproduce locally: eval/README.md — adapter-pluggable harness for LongMemEval _s (public 500-Q) + coding-agent-life-v1 (in-house 15-session corpus). Grep / vector / agentmemory adapters score side-by-side, NDJSON output, published scorecards land in docs/benchmarks/.

Pairs with codegraph, Understand Anything, and Graphify. Code-graph indexing, multi-agent build pipelines, and broader knowledge graphs across docs / PDFs / images / videos. agentmemory remembers the work; those three projects light up the rest of the context layer. Recipes + question-routing table: docs/recipes/pairings.md.

_{Benchmark note: only agentmemory's R@5 is our own measured result (LongMemEval-S, reproducible from benchmark/COMPARISON.md). The mem0 and Letta figures are their published LoCoMo numbers (a different dataset); the MemPalace, supermemory, 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.}

Compatibility: this release targets stable iii-sdk ^0.11.0 and iii-engine v0.11.x.

Try it in 30 seconds

# Terminal 1: start the server
npx @agentmemory/agentmemory

# Terminal 2: seed sample data and see recall in action
npx @agentmemory/agentmemory demo

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.

Open http://localhost:3113 to watch the memory build live.

Recommended: install globally

npx caches per-version. If you ran npx @agentmemory/[email protected] last week, a bare npx @agentmemory/agentmemory may serve the stale 0.9.14 from ~/.npm/_npx/, not the latest release. Install once and the bare agentmemory command works everywhere:

npm install -g @agentmemory/agentmemory
# If you hit EACCES on macOS/Linux system Node installs, retry with:
# sudo npm install -g @agentmemory/agentmemory
agentmemory                    # start the server (same as the npx form)
agentmemory stop               # tear it down
agentmemory remove             # uninstall everything we created
agentmemory connect claude-code   # wire one agent
agentmemory doctor             # interactive diagnostics + fix prompts

From 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:

npx -y @agentmemory/agentmemory@latest                 # forces latest from npm (cross-platform)
rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # macOS/Linux only (POSIX shell)

On Windows / 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.

Session Replay

Every 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/pause, speed control (0.5×–4×), and keyboard shortcuts (space to toggle, arrows to step).

Already have older Claude Code JSONL transcripts you want to bring in?

# Import everything under the default ~/.claude/projects
npx @agentmemory/agentmemory import-jsonl

# Or import a single file
npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl

Imported 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.

Heads-up if you rely on import-jsonl as your primary capture path: Claude Code's cleanupPeriodDays (in ~/.claude/settings.json, default 30) auto-deletes JSONL transcripts older than that window from ~/.claude/projects/. If you install agentmemory fresh on a months-old Claude Code history, anything older than 30 days is already gone before the first import. Either run import-jsonl on a cron, raise cleanupPeriodDays to something higher, or wire the auto-capture hooks (the default plugin install path) so each turn lands in agentmemory while the session is live and the JSONL cleanup stops mattering.

Upgrade / Maintenance

Use the maintenance command when you intentionally want to update your local runtime:

npx @agentmemory/agentmemory upgrade

Warning: this command mutates the current workspace/runtime. It can update JavaScript dependencies, may run cargo install iii-engine --force, and may pull Docker images.

Implementation details live in src/cli.ts (see runUpgrade around the src/cli.ts:544-595 region).

Claude Code (one block, paste it)

Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.

Claude Code without the plugin install (MCP-standalone path)

If you wire agentmemory's MCP server through ~/.claude.json directly instead of using /plugin install, Claude Code never resolves ${CLAUDE_PLUGIN_ROOT} and you have to point hook scripts at absolute paths in ~/.claude/settings.json. Those paths typically embed the agentmemory version (e.g. ~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…), so the next upgrade silently breaks every hook (#508).

Workaround:

agentmemory connect claude-code --with-hooks

This merges the same hook commands into ~/.claude/settings.json with absolute paths resolved to the bundled plugin/ directory of the currently installed @agentmemory/agentmemory package. Re-run the command after upgrading agentmemory to refresh the paths. User entries in the same file are preserved; only previous agentmemory entries are replaced. Using the /plugin install path remains the recommended approach. For remote or protected deployments, launch Claude Code with AGENTMEMORY_URL and AGENTMEMORY_SECRET set. The plugin passes both values through to its bundled MCP server; when AGENTMEMORY_URL is empty, the MCP shim uses http://localhost:3111.

Codex CLI (Codex plugin platform)

# 1. start the memory server in a separate terminal
npx @agentmemory/agentmemory

# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory

The Codex plugin ships from the same plugin/ directory as the Claude Code plugin. It registers:

• @agentmemory/mcp as an MCP server (proxies all 53 tools when AGENTMEMORY_URL points at a running agentmemory server; falls back to 7 tools locally when no server is reachable)
• 6 lifecycle hooks: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop
• 8 invocable skills: /recall, /remember, /session-history, /forget, /recap, /handoff, /commit-context, /commit-history, plus 7 reference skills the agent loads on demand (MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide)

Codex's hook engine injects CLAUDE_PLUGIN_ROOT into hook subprocesses (per codex-rs/hooks/src/engine/discovery.rs), so the same hook scripts work across both hosts without duplication. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude-Code-only and are not registered for Codex.

Codex Desktop: plugin hooks currently silent (workaround available)

CodexHooks and PluginHooks are both stable + default-enabled in codex-rs/features/src/lib.rs, but Codex Desktop builds currently do not dispatch plugin-local hooks.json (openai/codex#16430). MCP tools still work; only the lifecycle observations are missing.

Until upstream lands the fix, mirror the same hook commands into the global ~/.codex/hooks.json:

agentmemory connect codex --with-hooks

This adds an idempotent block to ~/.codex/hooks.json referencing absolute paths to the bundled scripts (no ${CLAUDE_PLUGIN_ROOT} expansion needed at user-scope). Re-run the same command after upgrading agentmemory to refresh paths. User entries in the same file are preserved; only previous agentmemory entries are replaced.

GitHub Copilot CLI

# MCP-only wiring
agentmemory connect copilot-cli

# Full hooks/skills plugin from the GitHub subdir
copilot plugin install rohitg00/agentmemory:plugin

agentmemory connect copilot-cli merges mcpServers.agentmemory into ~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json when COPILOT_HOME is set) and preserves existing servers. This adapter is Windows-safe even though other connect adapters still require manual Windows setup. Copilot picks up the MCP server on next launch or after /mcp. Install the plugin as well when you want the full hook/skill experience.

Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 53 memory tools:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.

Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 53 memory tools:

mcp_servers:
  agentmemory:
    command: npx
    args: ["-y", "@agentmemory/mcp"]

memory:
  provider: agentmemory

Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost: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/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.

Other agents

Start the memory server: npx @agentmemory/agentmemory

Native skills via npx skills add (50+ agents)

agentmemory ships 15 skills in the Claude-Code-style <dir>/SKILL.md format: 8 invocable action skills (remember, recall, recap, handoff, forget, commit-context, commit-history, session-history) and 7 reference skills the agent loads on demand (agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-config, agentmemory-agents, agentmemory-hooks, agentmemory-architecture, write-agentmemory-skill). The reference skills carry data tables generated from source, so they never drift. The skills CLI by vercel-labs auto-installs them into the calling agent's native skill directory across 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, and more):

npx skills add rohitg00/agentmemory -y          # auto-detects the calling agent
npx skills add rohitg00/agentmemory -y -a warp  # explicit agent
npx skills add rohitg00/agentmemory -y -a '*'   # install to every installed agent

This is complementary to agentmemory connect <agent>:

• agentmemory connect <agent> writes the MCP server config so the tools are available.
• npx skills add rohitg00/agentmemory installs the skills so the agent knows when to call them.

For the few agents the skills CLI doesn't cover yet (Zed v1.3.x and below), drop the 15 SKILL.md files under the agent's native skill directory yourself — same format works everywhere.

Standard MCP block

The 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):

"agentmemory": {
  "command": "npx",
  "args": ["-y", "@agentmemory/mcp"],
  "env": {
    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
  }
}

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": { ... } }. The ${VAR} placeholders inherit AGENTMEMORY_URL / AGENTMEMORY_SECRET from the shell at MCP-server launch — unset vars pass empty strings and the shim falls back to http://localhost:3111. One wired entry covers both local and remote (k8s / reverse-proxied) deployments.

Sandboxed MCP clients (Flatpak / Snap / 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 for the diagnostic walkthrough.

Programmatic access (Python / Rust / Node)

agentmemory 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://localhost:49134 — no separate REST client per language.

pip install iii-sdk         # Python
cargo add iii-sdk           # Rust
npm  install iii-sdk        # Node

from iii import register_worker

iii = register_worker("ws://localhost:49134")
iii.connect()

iii.trigger({
    "function_id": "mem::smart-search",
    "payload": {"project": "demo", "query": "how do tokens refresh"},
})

Worked example: examples/python/ (quickstart + observation/recall flow). REST on :3111 remains available for hosts without an iii runtime.

From source

git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start

This 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.

Install 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=<version> if you've migrated to the sandbox model manually.

• macOS arm64: mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii
• macOS x64: swap aarch64-apple-darwin for x86_64-apple-darwin
• Linux x64: swap for x86_64-unknown-linux-gnu
• Linux arm64: swap for aarch64-unknown-linux-gnu
• Windows: download iii-x86_64-pc-windows-msvc.zip from iii-hq/iii releases v0.11.2, extract iii.exe, add to PATH

Or use Docker (the bundled docker-compose.yml pulls iiidev/iii:0.11.2). Full docs: iii.dev/docs.

Windows

agentmemory runs on Windows 10/11, 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/winget package today, so Windows users have two paths:

Option A — Prebuilt Windows binary (recommended):

# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
#     model that engine v0.11.6+ requires)
# 2. Download iii-x86_64-pc-windows-msvc.zip
#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe somewhere on PATH, or place it at:
#    %USERPROFILE%\.local\bin\iii.exe
#    (agentmemory checks that location automatically)
# 4. Verify:
iii --version
# Should print: 0.11.2

# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory

Option B — Docker Desktop:

# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Run agentmemory — it will auto-start the bundled compose file:
npx -y @agentmemory/agentmemory

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:

npx -y @agentmemory/agentmemory mcp
# or via the shim package:
npx -y @agentmemory/mcp

Diagnostics for Windows: if npx @agentmemory/agentmemory fails, re-run with --verbose to see the actual engine stderr. Common failure modes:

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/Linux only), and the Docker image.

Deploy

One-click templates for managed hosts. Each one ships a self-contained Dockerfile that pulls @agentmemory/agentmemory from npm and copies the iii engine binary in from the official iiidev/iii Docker Hub image — no pre-built agentmemory image required. Persistent storage mounts at /data; the first-boot entrypoint overwrites the npm-bundled iii config (which binds 127.0.0.1) with a deploy-tuned one that binds 0.0.0.0 and uses absolute /data paths, generates the HMAC secret, then drops privileges from root to node via gosu before exec'ing the agentmemory CLI.

Render'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/render/ to point at the in-repo blueprint manually.

Full setup details (HMAC capture, viewer SSH tunnel, rotation, backup, cost floors) live in deploy/:

• deploy/fly — single machine with auto_stop_machines = "stop"; cheapest idle.
• deploy/railway — Hobby plan flat fee, volume in the dashboard.
• deploy/render — Blueprint flow, automatic disk snapshots on paid plans.
• deploy/coolify — self-hosted on your own VPS via Coolify; same Docker Compose stack, you own the host and the data.

Only port 3111 is published. The viewer on 3113 stays bound to loopback inside the container — every template's README documents the SSH-tunnel pattern for reaching it.

Every 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.

Session 1: "Add auth to the API"
  Agent writes code, runs tests, fixes bugs
  agentmemory silently captures every tool use
  Session ends -> observations compressed into structured memory

Session 2: "Now add rate limiting"
  Agent already knows:
    - Auth uses JWT middleware in src/middleware/auth.ts
    - Tests in test/auth.test.ts cover token validation
    - You chose jose over jsonwebtoken for Edge compatibility
  Zero re-explaining. Starts working immediately.

vs built-in agent memory

Every 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.

Memory Pipeline

PostToolUse hook fires
  -> SHA-256 dedup (5min window)
  -> Privacy filter (strip secrets, API keys)
  -> Store raw observation
  -> LLM compress -> structured facts + concepts + narrative
  -> Vector embedding (6 providers + local)
  -> Index in BM25 + vector

Stop / SessionEnd hook fires
  -> Summarize session
  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)

SessionStart hook fires
  -> Load project profile (top concepts, files, patterns)
  -> Hybrid search (BM25 + vector + graph)
  -> Token budget (default: 2000 tokens)
  -> Inject into conversation

4-Tier Memory Consolidation

Inspired by how human brains process memory — not unlike sleep consolidation.

Memories decay over time (Ebbinghaus curve). Frequently accessed memories strengthen. Stale memories auto-evict. Contradictions are detected and resolved.

What Gets Captured

| Hook | Captures |

…view the full README on GitHub.