Agent-Memory: Persistent Memory for AI Coding Agents

Introduction

Agent-Memory is a groundbreaking open-source solution providing persistent memory for AI coding agents. It addresses the common challenge of agents forgetting context between sessions, ensuring they remember everything from architectural decisions to specific code patterns. Built on the robust iii engine, Agent-Memory significantly enhances agent efficiency, reduces token usage, and offers seamless integration across various AI coding environments.

This tool ensures your coding agent remembers everything, eliminating the need for constant re-explanation. It boasts impressive benchmarks, including 95.2% retrieval R@5 and 92% fewer tokens, all while requiring zero external databases. Agent-Memory is compatible with a wide range of agents, including Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client.

Installation

Getting started with Agent-Memory is straightforward. You can install it globally via npm or use npx for a quick start.

To install globally and have agentmemory on your PATH:

npm install -g @agentmemory/agentmemory
# If you encounter EACCES on macOS/Linux, try:
# sudo npm install -g @agentmemory/agentmemory

Once installed, start the memory server:

agentmemory

Alternatively, use npx for a no-install run:

npx @agentmemory/agentmemory

Examples

Try it in 30 seconds

To see Agent-Memory in action, run the demo which seeds sample data and demonstrates recall:

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

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

The demo command populates Agent-Memory with realistic sessions (e.g., JWT auth, N+1 query fix, rate limiting) and performs semantic searches, showcasing its ability to find relevant information beyond keyword matching. You can also open http://localhost:3113 in your browser to watch the memory build live.

Connecting with Agents

Agent-Memory works with any agent that supports hooks, MCP, or a REST API. For example, to connect with Claude Code, you can use the following steps:

Start the memory server: npx @agentmemory/agentmemory in a separate terminal.
In Claude Code, add and install the plugin: /plugin marketplace add rohitg00/agentmemory and /plugin install agentmemory.

For other agents like Codex CLI, Cursor, or Gemini CLI, similar integration steps involving MCP configuration or plugin installation are available. Refer to the official repository for detailed instructions for each agent.

Programmatic Access

Agent-Memory's core operations are exposed as iii functions (mem::remember, mem::observe, mem::smart-search). You can access these programmatically using the iii-sdk in Python, Rust, or Node.js.

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"},
})

Why use Agent-Memory

AI coding agents often forget context, leading to repetitive explanations and wasted tokens. Agent-Memory solves this by silently capturing agent interactions, compressing them into searchable memory, and injecting relevant context into new sessions. This results in significant token savings, improved precision in retrieval, and a more natural, continuous development experience.

Unlike built-in agent memory solutions (like MEMORY.md in Claude Code or notepads in Cursor), Agent-Memory offers:

Unlimited Scale: No 200-line cap, handles vast amounts of information.
Advanced Search: Hybrid semantic, keyword (BM25), and knowledge graph search with RRF fusion.
Token Efficiency: Achieves approximately 1,900 tokens per session, a 92% reduction compared to loading full context.
Cross-Agent Compatibility: Works across multiple agents via MCP and REST APIs, allowing shared memory.
4-Tier Memory Consolidation: Inspired by human memory, it processes raw observations into episodic, semantic, and procedural memories, with decay and strengthening mechanisms.
Automatic Capture: Records every tool use via hooks, requiring zero manual effort.
Privacy First: Strips API keys and secrets before storage.
Real-time Viewer: Provides a live observation stream, session explorer, and knowledge graph visualization on http://localhost:3113.