agentmemory

agentmemory is a persistent memory engine purpose-built for AI coding agents, addressing the fundamental pain point of context loss across sessions where users must repeatedly re-explain project architecture, technical decisions, and existing code patterns.

On the acquisition layer, 12 Auto-Hooks spanning the full agent lifecycle (SessionStart through SessionEnd) enable zero-configuration automatic capture with no manual annotation required. On the retrieval layer, a triple-stream hybrid architecture combines BM25 keyword matching, dense vector semantic search (cosine similarity), and knowledge graph entity traversal, fused via Reciprocal Rank Fusion (k=60) with P50 latency under 20ms. On the consolidation layer, a sleep-inspired 4-tier model transforms Working memories (raw observations) through LLM compression into Episodic (session summaries), then extracts Semantic (facts and patterns), and finally crystallizes Procedural (workflow and decision patterns), incorporating Ebbinghaus forgetting curve decay and contradiction detection.

The engine is powered by iii-engine, a Rust native binary, with disk JSON + SQLite storage requiring zero external databases. It exposes 51 MCP tools and 121 REST endpoints, connectable by any MCP-compatible agent including Claude Code, Cursor, Gemini CLI, and Aider. Additional capabilities include team namespace isolation, Mesh federation sync, Git-versioned snapshots, session replay (0.5×–4× speed), Obsidian export, and OpenTelemetry observability integration. On the LongMemEval-S (ICLR 2025) benchmark, it achieves R@5 95.2% and MRR 88.2%, with token efficiency at approximately 8% of full-context pasting.

Memory Lifecycle Management#

• 12 Auto-Hooks: Automatic capture of SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, SubagentStart/Stop, Stop, SessionEnd
• 4-Tier Consolidation: Working (raw observations) → Episodic (session summaries) → Semantic (facts & patterns) → Procedural (workflows & decision patterns)
• Forgetting Mechanism: Ebbinghaus forgetting curve decay + auto-forgetting + contradiction detection & resolution
• Git Snapshots: Versioning, rollback, diff of memory states

Retrieval & Recall#

• Triple-Stream Hybrid Retrieval: BM25 (stemming + synonym expansion) + vector semantic (cosine similarity) + knowledge graph (entity BFS traversal)
• RRF Fusion: Reciprocal Rank Fusion (k=60) with session diversity control (max 3 results per session)
• Deduplication: SHA-256 hash dedup (5-minute window)

Knowledge Graph#

• Entity and relation extraction (enable via GRAPH_EXTRACTION_ENABLED=true)
• Time-annotated graph traversal
• Force-directed graph visualization in Viewer (:3113)

Privacy & Security#

• Privacy filtering enabled by default: API keys, secrets, <private> tags auto-stripped before storage
• Full provenance: any memory traceable to its raw observation source

Collaboration & Federation#

• Team memory: namespace-isolated shared/private memories
• Mesh federation: register peer nodes with Bearer Token authenticated HTTPS push/pull

Observability & Fault Tolerance#

• Self-healing: circuit breaker, provider fallback chain
• Health monitoring: OpenTelemetry integration (local memory exporter by default, OTLP for Jaeger/Honeycomb/Tempo)

Export & Replay#

• Session replay: play/pause, 0.5×–4× speed, keyboard shortcuts; Claude Code JSONL transcript import
• Obsidian export: frontmatter-tagged Markdown compatible with graph view

Benchmark Performance#

Quick Start#

npx @agentmemory/agentmemory
npx @agentmemory/agentmemory demo
open http://localhost:3113

Claude Code one-line install:

/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

Generic MCP configuration:

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