Your coding agent remembers everything. No more re-explaining.
Persistent memory for Claude Code, Cursor, Gemini CLI, OpenCode, and any MCP client.

Quick Start • Why • Agents • How It Works • Search • Memory Evolution • MCP • Viewer • Configuration • API

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.

95.2% retrieval accuracy on LongMemEval (ICLR 2025). 43 MCP tools. 12 hooks. Real-time viewer. Works with Claude Code, Cursor, Gemini CLI, OpenCode, and any MCP client. 646 tests. Zero external DB dependencies.

npx @agentmemory/agentmemory   # installs iii-engine if missing, starts everything

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` to register all 12 hooks, 4 skills, and 43 MCP tools. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.

That's it. Paste the block above into Claude Code. The agent handles installation, engine startup, plugin registration, and verification.

Start the memory server first: npx @agentmemory/agentmemory

Every coding agent forgets everything when the session ends. You waste the first 5 minutes of every session re-explaining your stack, your conventions, your recent decisions. 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
    - The rate limit discussion from last week's debugging session
  Zero re-explaining. Starts working immediately.

Every AI coding agent now ships with built-in memory — Claude Code has MEMORY.md, Cursor has notepads, Windsurf has Cascade memories, Cline has memory bank. These work like sticky notes: fast, always-on, but fundamentally limited.

agentmemory is the searchable database behind the sticky notes.

Evaluated on LongMemEval-S, an academic benchmark with 500 questions across ~48 sessions per question (~115K tokens). Same dataset and metric (recall_any@K) used by other memory systems.

These are retrieval recall scores (not end-to-end QA accuracy). Embedding model: all-MiniLM-L6-v2 (local, no API key).

agentmemory finds "N+1 query fix" when you search "database performance optimization" — something keyword matching literally cannot do.

Full benchmark reports: benchmark/LONGMEMEVAL.md, benchmark/QUALITY.md, benchmark/SCALE.md, benchmark/REAL-EMBEDDINGS.md

agentmemory works with any agent that supports hooks, MCP, or via its REST API.

These agents support hooks natively. agentmemory captures tool usage automatically via its 12 hooks.

Any agent that connects to MCP servers can use agentmemory's 43 tools, 6 resources, and 3 prompts. The agent actively queries and saves memory through MCP calls.

Agents without hooks or MCP can integrate via 103 REST endpoints directly. This works with any agent, language, or framework.

POST /agentmemory/observe       # Capture what the agent did
POST /agentmemory/smart-search  # Find relevant memories
POST /agentmemory/context       # Get context for injection
POST /agentmemory/enrich        # Get enriched context (files + memories + bugs)
POST /agentmemory/remember      # Save long-term memory
GET  /agentmemory/profile       # Get project intelligence

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

Once hooks are installed, memory builds silently. No action needed — just use your agent normally.

You: "Add JWT auth to the Express API"
Agent: reads files, writes code, runs tests, fixes errors

agentmemory captures every tool use via PostToolUse hooks. At session end, 47 raw observations compress into structured memory:

{
  "type": "file_edit",
  "title": "Implement JWT middleware with jose",
  "facts": ["Using jose library for Edge compatibility", "JWT tokens expire after 30 days", "Middleware in src/middleware/auth.ts"],
  "concepts": ["jwt", "authentication", "jose", "middleware"],
  "files": ["src/middleware/auth.ts", "src/app/api/auth/route.ts"],
  "importance": 9
}

You start a new session. Before the agent responds, the SessionStart hook fires and injects context (~1,900 tokens):

Agent already knows:
  - Auth uses jose JWT middleware in src/middleware/auth.ts
  - Tests in test/auth.test.ts cover token validation
  - You chose jose over jsonwebtoken for Edge compatibility
  - Rate limiting discussion from last week's debugging session

No re-explaining. The agent starts working immediately.

npx @agentmemory/agentmemory status   # quick terminal check
curl http://localhost:3111/agentmemory/health
open http://localhost:3113              # real-time viewer

After 1 session: check the Timeline tab in the viewer. After 2+ sessions: check Dashboard for memory count > 0 and the Token Savings card.

PostToolUse hook fires
  -> Dedup check      SHA-256 hash (5min window, no duplicates)
  -> mem::privacy     Strip secrets, API keys, <private> tags
  -> mem::observe     Store raw observation, push to real-time stream
  -> mem::compress    LLM extracts: type, facts, narrative, concepts, files
                      Validates with Zod, scores quality (0-100)
                      Self-corrects on validation failure (1 retry)
                      Generates vector embedding for semantic search

SessionStart hook fires
  -> mem::context     Load recent sessions for this project
                      Hybrid search (BM25 + vector) across observations
                      Inject project profile (top concepts, files, patterns)
                      Apply token budget (default: 2000 tokens)
  -> stdout           Agent receives context in the conversation

agentmemory uses triple-stream retrieval combining three signals for maximum recall.

All three streams are fused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 results per session) to maximize coverage.

BM25 enhancements (v0.6.0): Porter stemmer normalizes word forms ("authentication" ↔ "authenticating"), coding-domain synonyms expand queries ("db" ↔ "database", "perf" ↔ "performance"), and binary-search prefix matching replaces O(n) scans.

agentmemory auto-detects which provider to use. For best results, install local embeddings (no API key needed):

npm install @xenova/transformers

No embedding provider? BM25-only mode with stemming and synonyms still outperforms built-in memory.

Smart search returns compact results first (title, type, score, timestamp) to save tokens. Expand specific IDs to get full observation details.

# Compact results (50-100 tokens each)
curl -X POST http://localhost:3111/agentmemory/smart-search \
  -d '{"query": "database migration"}'

# Expand specific results (500-1000 tokens each)
curl -X POST http://localhost:3111/agentmemory/smart-search \
  -d '{"expandIds": ["obs_abc123", "obs_def456"]}'

Memories in agentmemory are not static. They version, evolve, and form relationships.

When you save a memory that's similar to an existing one (Jaccard > 0.7), the old memory is superseded:

v1: "Use Express for API routes"
v2: "Use Fastify instead of Express for API routes" (supersedes v1)
v3: "Use Hono instead of Fastify for Edge API routes" (supersedes v2)

Only the latest version is returned in search results. The full chain is preserved for audit.

Memories can be linked: supersedes, extends, derives, contradicts, related. Each relationship carries a confidence score (0-1) computed from co-occurrence, recency, and relation type. Traversal follows these links up to N hops, with optional minConfidence filtering.

agentmemory automatically cleans itself:

Run POST /agentmemory/auto-forget?dryRun=true to preview what would be cleaned.

agentmemory aggregates observations into per-project intelligence:

curl "http://localhost:3111/agentmemory/profile?project=/my/project"

Returns top concepts, most-touched files, coding conventions, common errors, and a session count. This profile is automatically injected into session context.

Navigate observations chronologically around any anchor point:

curl -X POST http://localhost:3111/agentmemory/timeline \
  -d '{"anchor": "2026-02-15", "before": 5, "after": 5}'

Full data portability:

# Export everything
curl http://localhost:3111/agentmemory/export > backup.json

# Import with merge strategy
curl -X POST http://localhost:3111/agentmemory/import \
  -d '{"exportData": ..., "strategy": "merge"}'

Strategies: merge (combine), replace (overwrite), skip (ignore duplicates).

agentmemory monitors its own health and validates its own output.

Every LLM compression is scored 0-100 based on structured facts, narrative quality, concept extraction, title quality, and importance range. Scores are tracked per-function and exposed via /health.

When LLM output fails Zod validation, agentmemory retries with a stricter prompt explaining the exact errors. This recovers from malformed JSON, missing fields, and out-of-range values.

Primary provider fails
  -> Circuit breaker opens (3 failures in 60s)
  -> Falls back to next provider in FALLBACK_PROVIDERS chain
  -> 30s cooldown -> half-open -> test call -> recovery

Configure with FALLBACK_PROVIDERS=anthropic,gemini,openrouter. When all providers are down, observations are stored raw without compression. No data is lost.

Collects every 30 seconds: heap usage, CPU percentage (delta sampling), event loop lag, connection state. Alerts at warning (80% CPU, 100ms lag) and critical (90% CPU, 500ms lag) thresholds. GET /agentmemory/health returns HTTP 503 when critical.

Run agentmemory as a standalone MCP server for any MCP-compatible agent (Cursor, Gemini CLI, OpenCode, Claude Desktop, Cline):

npx agentmemory-mcp

Or add to your agent's MCP config:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["agentmemory-mcp"]
    }
  }
}

The standalone server uses in-memory KV with optional JSON persistence (STANDALONE_PERSIST_PATH).

GET  /agentmemory/mcp/tools          — List available tools
POST /agentmemory/mcp/call           — Execute a tool
GET  /agentmemory/mcp/resources      — List available resources
POST /agentmemory/mcp/resources/read — Read a resource by URI
GET  /agentmemory/mcp/prompts        — List available prompts
POST /agentmemory/mcp/prompts/get    — Get a prompt with arguments

Four slash commands for interacting with memory:

agentmemory includes a real-time web dashboard that auto-starts on port 3113 (configurable via III_REST_PORT + 2).

• Live observation stream via WebSocket
• Session explorer with observation details
• Memory browser with search and filtering
• Knowledge graph visualization
• Health and metrics dashboard

Access at http://localhost:3113 or via GET /agentmemory/viewer on the API port. Protected by AGENTMEMORY_SECRET when set. CSP headers applied to all HTML responses.

agentmemory needs an LLM for compressing observations and generating summaries. It auto-detects from your environment.

No API key? agentmemory uses your Claude subscription automatically. Zero config.

Create ~/.agentmemory/.env:

# LLM provider (pick one, or leave empty for Claude subscription)
ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=https://custom-endpoint.example.com
# MINIMAX_API_KEY=...
# MINIMAX_MODEL=MiniMax-M2.7
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...

# Embedding provider (auto-detected from LLM keys, or override)
# EMBEDDING_PROVIDER=voyage
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=...
# COHERE_API_KEY=...

# Hybrid search weights (default: 0.4 BM25 + 0.6 vector)
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6

# Provider fallback chain (comma-separated, tried in order)
# FALLBACK_PROVIDERS=anthropic,minimax,gemini,openrouter

# Bearer token for API auth
# AGENTMEMORY_SECRET=your-secret-here

# Engine connection
# III_ENGINE_URL=ws://localhost:49134
# III_REST_PORT=3111
# III_STREAMS_PORT=3112
# Viewer runs on III_REST_PORT + 2 (default: 3113)

# Memory tuning
# TOKEN_BUDGET=2000
# MAX_OBS_PER_SESSION=500

# Claude Code Memory Bridge (v0.5.0)
# CLAUDE_MEMORY_BRIDGE=false
# CLAUDE_MEMORY_LINE_BUDGET=200

# Standalone MCP Server (v0.5.0)
# STANDALONE_MCP=false
# STANDALONE_PERSIST_PATH=~/.agentmemory/standalone.json

# Knowledge Graph (v0.5.0)
# GRAPH_EXTRACTION_ENABLED=false
# GRAPH_EXTRACTION_BATCH_SIZE=10

# Consolidation Pipeline (v0.5.0)
# CONSOLIDATION_ENABLED=true
# CONSOLIDATION_DECAY_DAYS=30

# Lesson Decay (v0.7.0)
# LESSON_DECAY_ENABLED=true

# Obsidian Export (v0.7.0)
# OBSIDIAN_AUTO_EXPORT=false

# MCP Tool Visibility (v0.7.0) — "core" (7 tools) or "all" (43 tools)
# AGENTMEMORY_TOOLS=core

# Team Memory (v0.5.0)
# TEAM_ID=
# USER_ID=
# TEAM_MODE=private

# Git Snapshots (v0.5.0)
# SNAPSHOT_ENABLED=false
# SNAPSHOT_INTERVAL=3600
# SNAPSHOT_DIR=~/.agentmemory/snapshots

109 endpoints on port 3111 (103 core + 6 MCP protocol). Protected endpoints require Authorization: Bearer <secret> when AGENTMEMORY_SECRET is set. The table below shows a representative subset; see src/triggers/api.ts for the full endpoint list.

/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

Restart Claude Code. All 12 hooks, 4 skills, and 43 MCP tools are registered automatically.

/plugin install agentmemory          # Install
/plugin disable agentmemory          # Disable without uninstalling
/plugin enable agentmemory           # Re-enable
/plugin uninstall agentmemory        # Remove

agentmemory is built on iii-engine's three primitives:

118 source files. ~21,800 LOC. 646 tests. Zero external DB dependencies.

npm run dev               # Hot reload
npm run build             # Production build (~425KB)
npm test                  # Unit tests (646 tests, ~1.7s)
npm run test:integration  # API tests (requires running services)

• Node.js >= 20
• iii-engine (curl -fsSL https://install.iii.dev/iii/main/install.sh | sh)

Apache-2.0