How agentmemory Fixes Claude Code Forgetting and Slashes Token Usage by 92%

Development pain points with AI coding assistants

Each new session requires re‑describing project architecture, tech stack, directory conventions and past pitfalls.

Built‑in simple memory files (e.g., CLAUDE.md, .cursorrules) hold only ~200 lines and overflow quickly.

In multi‑tool workflows (Cursor, Claude Code, Gemini CLI, etc.) memory cannot be shared, forcing repeated pasting of large code snippets and causing token consumption to explode.

agentmemory overview

agentmemory is an open‑source persistent memory system for AI coding agents, built on the iii engine and hosted on GitHub. It records developer habits, project structure, code logic and problem‑solving steps silently and injects the relevant context into new sessions.

Core problems solved

Session amnesia – AI retains architecture, code logic and bug‑fix knowledge after restart.

Repeated context feeding – project information is retrieved and injected automatically.

Memory islands – a single memory service is accessible by multiple agents.

Token explosion – precise retrieval replaces full‑context injection, reducing token usage by 92%.

Complex configuration – built‑in SQLite removes the need for external vector databases; a single command starts the service.

Unobservable memory – an integrated web viewer provides session replay, knowledge‑graph visualization, editing and audit.

Sensitive data leakage – a privacy filter automatically strips API keys, tokens and other secrets.

Technical capabilities

Automatic memory capture via 12 lifecycle hooks (session start/end, user query, tool calls, failures, sub‑agent lifecycle, etc.) with no manual remember or add calls required.

Four‑layer memory architecture mimicking human cognition:

Work memory – short‑term raw observations.

Situational memory – session‑level summaries.

Semantic memory – structured facts.

Procedural memory – workflow patterns.

Memory automatically decays, consolidates, merges and updates over time.

Triple hybrid retrieval combining BM25 keyword search, vector semantic search and knowledge‑graph relational search, with Reciprocal Rank Fusion (RRF) re‑ranking. Reported precision: 95.2% R@5 on LongMemEval‑S (500 professional questions), 2.2× the accuracy of traditional grep.

MCP compatibility – implements the Model Context Protocol and exposes 53 tool interfaces (smart search, memory CRUD, session history, project archive, knowledge‑graph queries, audit, team sharing, etc.).

Real‑time visualizer runs on port 3113, showing memory streams, timeline replay, speed control, knowledge‑graph view and health monitoring.

Zero external dependencies – embedded SQLite works out‑of‑the‑box; optional local embedding models make the system completely offline and free.

Performance benchmarks

R@5 = 95.2% on a 500‑question professional test set (LongMemEval‑S).

Top‑5 hit rate = 100% on an internal code dataset.

Retrieval precision = 2.2× that of traditional grep.

p50 latency = 14 ms.

Annual token consumption ≈ 170 K (≈ $10) – 92% reduction compared with full‑context pasting; local embedding mode can reduce cost to $0.

Stability – >950 unit tests passed, suitable for production use.

Comparison with alternative memory solutions

Retrieval R@5 : agentmemory 95.2% vs mem0 68.5% vs Letta/MemGPT 83.2% vs native memory (no structured retrieval).

Memory capture : agentmemory uses 12 automatic hooks; mem0 requires manual API calls; Letta/MemGPT relies on agent‑side editing; native memory requires manual file maintenance.

Retrieval method : BM25 + vector + graph (agentmemory) vs vector + graph (mem0) vs vector only (Letta/MemGPT) vs full‑text load (native).

External dependencies : agentmemory 0 dependencies; mem0 needs Qdrant/pgvector; Letta/MemGPT needs Postgres + vector store; native memory needs none.

Cross‑agent support : agentmemory provides full‑platform interoperability; mem0 offers API‑level coordination; Letta/MemGPT limited to its own runtime; native memory is isolated per tool.

Memory lifecycle : agentmemory automatically merges, decays and forgets; mem0 provides passive extraction; Letta/MemGPT leaves lifecycle to the agent; native memory requires manual pruning.

Real‑time viewer : built‑in local viewer (agentmemory) vs cloud panels for mem0 and Letta/MemGPT; none for native memory.

Installation & startup

# Global install
npm install -g @agentmemory/agentmemory

# One‑click run without install
npx @agentmemory/agentmemory

# Start the memory service
agentmemory

Service defaults:

REST API: http://localhost:3111 Web visualizer: http://localhost:3113 (keep the terminal window open).

Configuration examples for major agents

Cursor : add an MCP entry in ~/.cursor/mcp.json pointing to http://localhost:3111.

Claude Code : agentmemory connect claude-code --with-hooks Gemini CLI :

gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user

Codex CLI :

codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory

Advanced deployment & configuration

One‑click cloud deployment is supported on providers such as fly.io, Railway, Render and Coolify via the included Dockerfile (data persisted under /data, only port 3111 exposed). Local configuration can be stored in ~/.agentmemory/.env:

# Example .env
EMBEDDING_PROVIDER=local
# Optional API keys
# ANTHROPIC_API_KEY=xxx
# GEMINI_API_KEY=xxx
# OPENAI_API_KEY=xxx
AGENTMEMORY_SECRET=your_custom_secret
TOKEN_BUDGET=2000
GRAPH_EXTRACTION_ENABLED=true
CONSOLIDATION_ENABLED=true

Common troubleshooting

Port 3111 conflict : Windows – netstat -ano | findstr :3111; macOS/Linux – lsof -i :3111. Stop the occupying process and restart.

Viewer not reachable : ensure the agentmemory service is running and firewall allows port 3113.

Demo execution failure : re‑run agentmemory demo, verify Node ≥ 20, disable any proxy.

MCP tool shows only 7 capabilities : confirm the service is running and AGENTMEMORY_URL is correctly set; restart the AI client.

Windows startup issues : prefer Docker Desktop mode to avoid native compatibility problems.

Best‑practice recommendations

Provide a complete project description in the first session to build high‑quality base memory.

Prefer the local embedding model for speed, privacy and zero cost.

Run a single agentmemory instance and let all AI clients share it.

Regularly inspect the memory panel to delete incorrect entries.

Enable memory snapshots for critical projects.

Activate knowledge‑graph sharing in team scenarios.

Avoid manual edits to the underlying storage files; use the panel or MCP tools for all operations.

Project repository

https://github.com/rohitg00/agentmemory