agentmemory Deep Dive: A Four-Layer Long-Term Memory Architecture for AI Coding Assistants

Forum topic · 小凯 · 2026-06-20

Summary

agentmemory, an open-source project by Rohit Gupta, gives AI coding assistants persistent long-term memory by running a local memory server (default 127.0.0.1:3111) that automatically captures tool calls, conversations, and code edits via 12 hooks, then compresses them into searchable structured memory injected into new sessions. Its four-layer architecture mirrors human cognition: working, episodic, semantic, and procedural memory, with Ebbinghaus-like decay and reinforcement. Retrieval combines BM25, vector search, and knowledge-graph traversal fused via Reciprocal Rank Fusion, scoring 95.2% R@5 on LongMemEval-S. Token costs drop from roughly $500/year (LLM summaries) to about $10/year, or $0 with local embeddings. Built on the iii engine (SQLite instead of Postgres), it offers 53 MCP tools, supports 16+ tools including Claude Code, Cursor, and Copilot CLI, works self-hosted with privacy filtering, and requires zero manual memory management.

The Problem: Session-Level Amnesia in AI Coding Assistants

Anyone who has used Claude Code, Cursor, or Copilot knows the pain: every new session, you must re-explain the project structure, tech stack, past decisions, and known pitfalls. Current vendor "solutions" all fall short:

Claude Code: MEMORY.md (200-line cap, manually maintained)
Cursor: notepads (static notes)
Cline: memory bank (file-based, no search)

Common issues: capacity bottlenecks, no search, manual upkeep, no cross-agent sharing, and no memory evolution (no forgetting stale info, no reinforcing important memories).

As creator Rohit Gupta puts it: "You explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences."

What Is agentmemory?

agentmemory is a memory engine + MCP server that runs locally in the background (default 127.0.0.1:3111). Via hooks, it automatically captures tool calls, conversations, and code changes from AI coding assistants, compresses them into structured, searchable memory, and injects relevant context at the start of each new session.

> "Built-in memory works like sticky notes. agentmemory is the searchable database behind the sticky notes."

It supports 16+ tools, including Claude Code (native plugin + MCP + 12 hooks), Codex CLI, GitHub Copilot CLI, Cursor, Gemini CLI, OpenClaw, Hermes, OpenCode, Cline, Windsurf, Goose, Aider (REST API), Claude Desktop, and Warp. Core design: one memory server shared by all agents — decisions made in Claude Code are visible in Cursor.

Four-Layer Memory Architecture (Modeled on the Human Brain)

| Layer | Content | Brain Analogy | Implementation | |---|---|---|---| | Working memory | Raw observations (tool call inputs/outputs) | Short-term memory | SQLite raw storage, 5-min dedup window | | Episodic memory | Session summaries | Event memory | LLM-compressed session narratives | | Semantic memory | Extracted facts and patterns | Knowledge base | Structured facts + concept extraction | | Procedural memory | Workflows and decision habits | Skills/habits | Pattern detection + workflow logs |

Memory lifecycle: PostToolUse hook → SHA-256 dedup → privacy filtering (strips API keys/secrets) → raw storage → LLM compression into facts/concepts/narrative → vector embedding → BM25 + vector indexing. On Stop/SessionEnd: session summaries and knowledge-graph extraction. On SessionStart: project profile loading, hybrid search, token budget (default 2,000 tokens), context injection.

Memory decay follows an Ebbinghaus-like curve: frequently accessed memories are reinforced, stale ones expire via TTL and importance-based eviction, and contradictory memories are detected and resolved.

Three-Stream Hybrid Retrieval: BM25 + Vector + Graph

BM25: stemming, keyword matching, synonym expansion — fast, exact matching
Vector: dense embedding cosine similarity — semantic search
Graph: knowledge-graph entity matching + BFS — relational reasoning

Fusion via Reciprocal Rank Fusion (RRF, k=60) plus per-session result diversity (max 3 per session).

LongMemEval-S Benchmarks

| System | R@5 | R@10 | MRR | |---|---|---|---| | agentmemory | 95.2% | 98.6% | 88.2% | | BM25-only fallback | 86.2% | 94.6% | 71.5% | | mem0 (LoCoMo) | 68.5% | — | — | | Letta/MemGPT (LoCoMo) | 83.2% | — | — |

Note: agentmemory's R@5 is independently measured; other systems' figures come from their own papers (not a direct head-to-head on the same benchmark). Even so, the hybrid fusion gains +9pp R@5 and +16.7pp MRR over BM25-only.

Token Efficiency

| Approach | Tokens/Year | Cost | |---|---|---| | Pasting full context | 19.5M+ | Impossible (over window) | | LLM summaries | ~650K | ~$500 | | agentmemory | ~170K | ~$10 | | + local embeddings | ~170K | $0 |

The ~92% token savings come from precise retrieval — only injecting memories relevant to the current task.

12 Hooks: Zero Manual Capture

Unlike systems such as mem0 that require manual add() calls, agentmemory captures automatically: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, SubagentStart/Stop, Stop, and SessionEnd — covering the full session lifecycle with no developer friction.

Technical Foundation: iii Engine

agentmemory avoids the traditional stack (Postgres, Redis, Express, pm2) in favor of the iii engine unified runtime: SQLite + iii-state KV replaces Postgres, iii-stream WebSocket replaces Redis, iii function routing replaces Express, iii process management replaces pm2, and iii-observability OTEL replaces Prometheus. The built-in viewer (port 3113) is a default iii capability — every memory operation has an OTEL trace, editable KV entries, and replayable triggers.

Competitive Comparison

| Dimension | agentmemory | mem0 | Letta/MemGPT | Built-in MEMORY.md | |---|---|---|---|---| | Type | Memory engine + MCP | Memory API layer | Full agent runtime | Static file | | Auto capture | 12 hooks (zero manual) | Manual add() | Agent self-edit | Manual edit | | Search | BM25 + Vector + Graph | Vector + Graph | Vector (archival) | None | | Cross-agent | MCP + REST + shared | API (no coordination) | Letta-only | Per-agent files | | External deps | None (SQLite + iii) | Qdrant/pgvector | Postgres + vector DB | None | | Memory lifecycle | 4-layer + decay + forgetting | Passive extraction | Agent-managed | Manual pruning | | Self-hosted | Yes (default) | Optional | Optional | Yes |

53 MCP Tools

Core tools include memory_recall, memory_smart_search, memory_save, memory_sessions, memory_profile, and memory_file_history. Extended tools (53 total) cover memory management (consolidate, snapshot_create), team collaboration (team_share, team_feed), multi-agent coordination (lease, signal_send, mesh_sync), workflows (action_create, routine_run), audit (audit, governance_delete, verify), and health (diagnose, heal). Most memory MCPs offer only 5–10 tools.

Example Workflow: Session 1 → Session 2

Session 1 ("add auth to the API"): the agent writes code, runs tests, fixes bugs; agentmemory silently captures every tool use and compresses observations into structured memory.
Session 2 ("now add rate limiting"): relevant context is auto-injected — "Auth uses JWT middleware in src/middleware/auth.ts", "Tests cover token validation in test/auth.test.ts", "You chose jose over jsonwebtoken for Edge compatibility" — so the agent starts working immediately with no re-explanation.

Privacy and Security

1. Local-first: bound to 127.0.0.1 by default; data never leaves the machine 2. Privacy filtering: auto-strips API keys, secrets, and <private>-tagged content 3. SHA-256 dedup: identical observations stored once within a 5-minute window 4. HMAC auth: optional secret protection for remote deployment 5. Audit trail: every operation traceable to its source observation

Limitations and Risks

1. iii engine dependency: requires the iii-engine binary (v0.11.2); weak Windows support 2. Model lock-in: some hooks are Claude Code-specific; other agents may capture less detail 3. Context pollution: inaccurate retrieval can inject irrelevant stale information, causing hallucination 4. Storage growth: long-running projects may accumulate large memory databases despite expiration 5. Team-sharing complexity: namespaced shared/private memory permissions need careful configuration

Bottom Line

agentmemory upgrades AI coding assistant memory from static sticky notes to a dynamic database: automatic capture, intelligent compression, precise retrieval, and natural forgetting. Its value lies not in any single technique but in combining mature technologies (BM25, vector search, knowledge graphs) into a zero-friction, self-hosted, cross-agent memory system.

When GPT-5, Claude 4, and Gemini 3 converge on raw coding capability, the competition shifts to context management: whoever manages cross-session context best and retrieves relevant memory most precisely wins. At 95.2% R@5, agentmemory may be the furthest along this path among open-source options — and if retrieval error drops below 1%, the AI coding assistant transforms from an intern you retrain every session into a seasoned partner who has worked with you for years.

---

Reference

Project: agentmemory (author: Rohit Gupta)
GitHub: https://github.com/rohitg00/agentmemory
Install: npm install -g @agentmemory/agentmemory
MCP: npx -y @agentmemory/mcp
Engine: iii engine (https://iii.dev)
Architecture: 4 layers (working/episodic/semantic/procedural) + decay
Retrieval: BM25 + Vector + Graph (RRF fusion)
Benchmark: LongMemEval-S R@5=95.2%, R@10=98.6%, MRR=88.2%
Tooling: 53 MCP tools + 15 skills
Deployment: self-hosted (default 127.0.0.1); Fly.io/Railway/Render/Coolify supported