Agent RecallPersistent Memory for AI Coding Agents

Your AI agent forgets everything between sessions

Agent Recall gives your coding agents persistent memory. Facts, people, decisions — remembered across every session. Open source, local-first, MCP native.

v0.3.0321 testsMITPython 3.10+py.typed

pip install 'agent-recall[mcp]'

GitHub PyPI☕ Buy me a coffee

agent-recall generate acme-project

--- Agent Briefing: acme-project ---

Key People:
  Alice — Lead Engineer, prefers async
  Bob — Product Manager, owns roadmap

Recent Decisions:
  API migration approved (Feb 12)
  Auth service blocked — waiting on Alice

Active Context:
  Sprint 14, 3 days remaining
  Focus: auth service unblock

MCP-native — tested with Claude Code, Cursor, Windsurf, and ClineClaude CodeBattle-testedCursorWindsurfCline

Context that compounds

Without memory

> Who is Alice?

I don't have any context about Alice.

Every session starts from zero.

Session 1 saves facts

create_entities: Alice (person)

set_slot: role = "Lead Engineer"

add_observation: "prefers async"

Agent saves what it learns through MCP tools.

Session 2 starts smart

Agent Briefing loaded

Alice — Lead Engineer

Prefers async communication

API migration approved Feb 12

Context compounds. Every session builds on the last.

How it works

Agent saves facts

Your agent calls MCP tools to save entities, observations, and relations as it works. Nine tools for full CRUD.

Stored in SQLite

Everything persists in a local SQLite database with WAL mode. Scoped by project — same person, different context per scope.

Briefing at startup

Next session, an AI-generated briefing loads automatically. Key people, recent decisions, active context — summarized, not dumped.

Quick Start

1. Install

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

2. Add to your editor

.mcp.json (Claude Code, Cline) or editor settings (Cursor, Windsurf)

{
  "mcpServers": {
    "memory": {
      "command": "python3",
      "args": ["-m", "agent_recall.mcp_server"]
    }
  }
}

3. Auto-briefing hook

.claude/settings.json — loads briefing at session start

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "agent-recall-session-start"
      }]
    }],
    "PostToolUse": [{
      "matcher": "mcp__memory__.*",
      "hooks": [{
        "type": "command",
        "command": "agent-recall-post-tool-use"
      }]
    }]
  }
}

4. Verify

agent-recall status

Database: ~/.agent-recall/frames.db
Entities: 27
  client: 11, person: 8, company: 1
  concept: 2, entity: 3, topic: 2

Scoped Memory

Same person, different contexts per project. Alice is "Engineer" at Acme, "Consultant" at BetaCorp. Data stays isolated by scope hierarchy.

AI Briefings

Summaries, not data dumps. Reads 147 facts, generates key people, current tasks, recent decisions. Bring your own LLM.

Multi-Agent Ready

Built for agencies. Scope hierarchy lets each agent read/write within its scope chain while sharing one knowledge base.

Local-First

SQLite on your machine. WAL mode for concurrent access. Your data stays yours — no cloud, no vendor lock-in.

MCP Native

Nine tools over Model Context Protocol. Designed for MCP-compatible clients. Tested configs for Claude Code, Cursor, Windsurf, and Cline.

Full History

Bitemporal tracking — know what was true when, not just what's true now. Full temporal history on every slot.

Code examples

Python API

from agent_recall import MemoryStore, ScopedView

with MemoryStore() as store:
    alice = store.resolve_entity("Alice", "person")
    store.set_slot(alice, "role", "Lead Engineer", scope="acme")
    store.add_observation(alice, "Prefers async", scope="acme")

    view = ScopedView(store, ["global", "acme"])
    entity = view.get_entity("Alice")
    print(entity["slots"]["role"])  # "Lead Engineer"

    # Search, history, transactions
    results = store.search("engineer")
    store.set_slot(alice, "role", "Staff Engineer", scope="acme")
    history = store.get_slot_history(alice, "role")

    with store.transaction():
        bob = store.resolve_entity("Bob", "person")
        store.set_slot(bob, "role", "PM")

CLI

$ agent-recall set Alice role Engineer --type person
Alice.role = Engineer

$ agent-recall list --type person
  Alice (person)  Bob (person)

$ agent-recall entity Alice --scope global --scope acme
  role: Lead Engineer (acme)

$ agent-recall logs Alice
  [2026-02-26] Joined the team

$ agent-recall generate my-agent --force
Generated: ~/.agent-recall/context_cache/my-agent.md

9 MCP tools your agent gets

create_entitiesadd_observationscreate_relationssearch_nodesopen_nodesread_graphdelete_entitiesdelete_relationsdelete_observations

Multi-agent YAML config

hierarchy:
  agency:
    - client-a
    - client-b

briefing:
  backend: cli
  model: opus
  adaptive: true
  auto_discover: true

agents:
  coordinator:
    model: opus
    output_budget: 12000
  client-a:
    template: client
    context_files:
      - docs/client-a-brief.md

Bring Your Own LLM

from agent_recall import generate_briefing, LLMResult

def my_llm(prompt, model, timeout):
    response = call_your_api(prompt)
    return LLMResult(
        text=response.text,
        input_tokens=0,
        output_tokens=0
    )

generate_briefing(
    "my-agent",
    llm_caller=my_llm,
    force=True
)

Why agent-recall?

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

✓
Scope hierarchy — Not flat memory. Scope chains with inheritance — designed for agents working across multiple clients, projects, and nested contexts. The same person can have different roles in different projects.
✓
AI briefings — Raw data dumps don’t work. An LLM summarizes 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 tools with proactive-saving instructions. Designed for MCP-compatible clients.
✓
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.

Born in production

Extracted from a real system running 30+ concurrent AI agents in production. Not a weekend experiment — battle-tested infrastructure that handles real workloads daily.

321

tests

modules

WAL

SQLite mode

30+

agents in production

Troubleshooting

Agent doesn't save facts automatically: Verify the MCP server is connected — your agent should list create_entities, search_nodes etc. as available tools. Check the server starts without errors: python3 -m agent_recall.mcp_server
Briefings are empty or generation fails: Check you have data: agent-recall status should show entities. The default cli backend needs Claude Code installed. Try the api backend with ANTHROPIC_API_KEY or pass your own LLM caller.
Windows: python3 not found: On Windows, Python is usually python not python3. Update "command": "python" in your MCP config.

Tech stack

PythonSQLiteMCPFastMCPYAMLClickpy.typed

Give your agents persistent memory

Open source. Local-first. MIT licensed. One pip install away.

pip install 'agent-recall[mcp]'

View on GitHub PyPI Package☕ Buy me a coffee