agent-recall

agent-recall

Persistent memory for AI coding agents. Your agent forgets everything between sessions — names, decisions, preferences, context. agent-recall fixes this.

Built from production: extracted from a real system running 30+ concurrent AI agents at a digital agency. Not a prototype — every feature exists because something broke in production.

Before:  "Who is Alice?" (every single session)
After:   Agent starts with: "Alice — Lead Engineer at Acme, prefers async,
         last discussed the API migration on Feb 12"

MCP-native — designed for MCP-compatible clients. Tested configs included for Claude Code, Cursor, Windsurf, and Cline. Battle-tested daily with Claude Code (30+ agents in production). PRs and issue reports welcome!

Why agent-recall?

Other memory solutions exist (Mem0, Zep/Graphiti, LangMem). Here's what makes agent-recall different:

• Scope hierarchy — not flat memory. The same person can have different roles in different projects. agent-recall is built around scope chains with inheritance — designed for agents working across multiple clients, projects, and nested contexts.
• AI briefings — raw data dumps don't work. agent-recall uses an LLM to summarize hundreds of facts into structured, actionable context injected at session start.
• Local-first — single SQLite file. No cloud, no vector DB, no Docker, no Neo4j. Your data stays on your machine.
• MCP-native — 9 memory tools with proactive-saving instructions. Tested configs for Claude Code, Cursor, Windsurf, and Cline.
• Bitemporal — old values are archived, not deleted. Query what was true at any point in time.
• Minimal dependencies — just pyyaml + click. MCP and Anthropic SDK are optional extras.

---

How It Works

┌─────────────────────────────────────────────────────────────────────┐
│                         SESSION 1                                   │
│                                                                     │
│  You: "Alice from Acme called. She wants the API done by Friday."   │
│                           │                                         │
│                           ▼                                         │
│  Agent saves automatically via MCP tools:                           │
│    create_entities: Alice (person), Acme (client)                   │
│    add_observations: "wants API done by Friday"                     │
│    create_relations: Alice → works_at → Acme                        │
│                           │                                         │
│                           ▼                                         │
│  Stored in local SQLite ─────► ~/.agent-recall/frames.db            │
└─────────────────────────────────────────────────────────────────────┘
                            │
                     (session ends)
                            │
┌─────────────────────────────────────────────────────────────────────┐
│                         SESSION 2                                   │
│                                                                     │
│  Agent starts and receives a briefing:                              │
│    "Alice (Lead Engineer, Acme) — wants API done by Friday.         │
│     Acme is a client. Last discussed Feb 12."                       │
│                           │                                         │
│                           ▼                                         │
│  Agent already knows who Alice is, what's urgent, and what to do.   │
└─────────────────────────────────────────────────────────────────────┘

Why does the agent save facts automatically? The MCP server includes behavioral instructions that tell the agent to proactively save people, decisions, and context as it encounters them. No special prompting needed — the agent receives these instructions when it connects to the memory server.

---

Setup

Step 1: Install

pip install 'agent-recall[mcp]'
agent-recall init

This creates the SQLite database at ~/.agent-recall/frames.db.

agent-recall[mcp] installs with MCP server support. Use pip install agent-recall if you only need the Python API/CLI.

Step 2: Add MCP server to your editor

This gives your agent the memory tools (create_entities, add_observations, search_nodes, etc.) and the instructions to use them proactively.

Claude Code ✅ Production-tested