Skip to main content
Glama
Recall by Polign

Recall by Polign

Official

Polign Recall

Recall gives an agent memory and state that survive the conversation and the process. Memory is what the agent knows: facts a user stated, with every correction kept, so the agent can say what it believes now, what it believed before, and why. State is where the agent is: its progress, its notes to its next instance, and the tool calls it had in flight, so a run that crashes or moves machines resumes from its own records.

Recall is a Go library, a recall binary that serves the same operations as MCP tools and as HTTP, and a Python client. It stores everything in a database you run: polign_db, PostgreSQL, MongoDB or Qdrant. Apache 2.0.

Recall, mem0 and Zep answering questions about a user whose facts changed over nine months

One user over nine months, three homes, three employers, three work emails, six questions, Claude Opus 5.5 extracting, answering and judging for all three systems: Recall 18/18, mem0 18/18, Zep 12/18. Tokens to save one message: Recall 3.0k, mem0 12.7k, Zep 14.7k.

The code to the Recall repository.

Install

pip install polign-recall          # the Python client, the recall binary, and the database it runs
brew install polign/tap/recall     # the same for Homebrew
go install github.com/Polign/recall/cmd/recall@latest   # the binary alone; it fetches the database on first use

Then give it to the agent you use:

claude mcp add recall -- recall mcp -write      # Claude Code

Add to Cursor · Add to VS Code · any other MCP host: command recall, arguments mcp -write (details).

With nothing configured, memory lives in a local database in ~/.local/share/recall, started on first use and shared by every agent on the machine. No model and no API key are needed to start. To keep memory in a database you already run, see Backends.

Related MCP server: engram-mcp

What a correction looks like

Every change is kept. Three commands read the record:

$ recall history "which editor do I use"
user preferred editor
  believed now: user preferred editor: zed
  2026-09-01 10:00  stated, user_stated
      + user preferred editor: vim
  2026-09-20 10:00  replaced, user_stated
      - user preferred editor: vim
      + user preferred editor: emacs
  2026-10-05 10:00  replaced, user_stated
      - user preferred editor: emacs
      + user preferred editor: zed

$ recall ask -as-of 2026-09-25 "which editor do I use"
Believed as of 2026-09-25 00:00:
user preferred editor: emacs  (since 2026-09-20)
  replaced: vim  (since 2026-09-01)

$ recall diff -from 2026-09-15 -to 2026-10-31
Changed between 2026-09-15 00:00 and 2026-10-31 00:00:
- user home city: Lisbon
+ user home city: Porto
- user preferred editor: vim
+ user preferred editor: zed

Why Recall

  • Corrections are records, not overwrites. A new value replaces the old one by a rule you can read, and every answer arrives with what it replaced.

  • Any moment is readable. as_of, history and diff say what the agent believed then and when that changed.

  • Every answer has a source. recall explain shows the message a fact came from, the rule that decided it, and its history.

  • Agents resume from records. A crashed or moved agent gets its working state, recent turns and unfinished tool calls back, not a snapshot.

  • Your storage, your rules. Memory lives in a database you already run, and the vocabulary of what gets remembered is yours to define or leave open.

Quickstart

Python 3.10 or later. Save a preference, then correct it:

pip install polign-recall
python - <<'PY'
from polign_recall import Client

with Client(local_dir="./recall-data", typed=True) as memory:
    memory.remember("user", "prefers_editor", "vim")
    memory.remember("user", "prefers_editor", "neovim")
PY

A second process reads the current value, the history, and what was believed before the correction:

python - <<'PY'
from polign_recall import Client

with Client(local_dir="./recall-data", typed=True) as memory:
    print(memory.recall("user", "prefers_editor")[0].value)   # neovim

    events = memory.history("user", "prefers_editor")
    print([e.value for e in events])                           # ['vim', 'neovim']

    before = memory.recall("user", "prefers_editor", as_of=events[0].observed_at)
    print(before[0].value)                                      # vim
PY

The first client to open ./recall-data starts a local database for it and later clients share it; the memories stay there after the program exits. A bare Client() uses ~/.local/share/recall, the memory every agent on the machine shares. The Python client guide covers the rest: plain-text memory with a model, forgetting, history, and resuming an agent.

How memory works

A memory is a subject, a predicate and a typed value: user, prefers_editor, neovim. Predicates live in a registry that says what type a value has, whether the predicate holds one value or many, and which predicates it contradicts: dislikes excludes likes, gave_away excludes owns. A single-valued predicate replaces its value on a new statement; a multi-valued one accumulates. Forgetting records a withdrawal; nothing is deleted. Recall ships starter registries for coding, personal assistant, support, sales and voice agents, and you can change a registry later without touching what was already remembered.

You do not have to define predicates. With an open vocabulary the first use of a predicate defines it, and with a model configured the MCP tools take plain text and no predicates appear anywhere:

recall setup -extract-model anthropic:claude-haiku-4-5-20251001
remember("I switched from helix to zed last week")
recall("which editor do I use?")  ->  "user prefers editor: zed" (before: helix)
forget("my editor")

The model decides how each statement is filed. Once filed, replacement follows the predicate's rule, every filing is recorded, and a wrong filing is corrected with one event that every later answer follows. No model reconciles memory on its own: Recall applies the registry's rules, shows what may conflict, and lets the agent confirm the rest, so every correction reads back to the rule or statement that made it. recall mcp -typed serves the typed tools (remember(subject, predicate, value)) instead. The developer reference has the details and the Memory API is the contract.

State

The second half of Recall, with its own contract, docs/state-api-v1.md. An agent writes down where it is as it works, and a new process resumes from those records instead of from a snapshot:

  • Working state: goal, plan, progress, focus, decisions, open questions.

  • Turns, verbatim, and large tool outputs stored by reference.

  • Pointers to where the work lives: a branch, an object key, a process.

  • Actions: each tool call that touches the world, recorded before it runs and closed with its result, so a crash between the two is visible and the next resume lists the call as unconfirmed instead of repeating it.

Resume takes a lease on the agent id, so one process acts for an agent at a time, rebuilds the context within a token budget, and renders it as one briefing for the model:

agent, err := client.Resume(ctx, recall.ResumeRequest{AgentID: "coder-1", TokenBudget: 8000})
if err != nil {
    return err
}
defer agent.Release(context.Background())

briefing := agent.Resumed().Briefing // hand this to the model

In Python, an agent remembers a fact and records where it is, the process is killed, and a new process resumes from the records:

import os, signal
from polign_recall import Client

with Client(local_dir="./recall-data", agent=True, typed=True) as client:
    client.remember("user", "project_constraint", "deploy only on weekdays after 18:00 UTC")
    with client.resume("coder-1") as agent:
        agent.update_working_state(goal="Move billing to the v2 API",
                                   plan=["find call sites", "migrate them", "run the tests"])
        agent.record_turn("user", "Start with the charge endpoint.")
        agent.milestone("call sites found", progress="12 call sites listed")
        os.kill(os.getpid(), signal.SIGKILL)   # dies here, lease unreleased
import time
from polign_recall import Client

with Client(local_dir="./recall-data", agent=True, typed=True) as client:
    agent = client.resume("coder-1", token_budget=8000, defer_lease=True)
    print(agent.context.briefing)   # at once: the goal, plan, milestone, turn, and constraint
    while not agent.acquire():      # False until the dead process's lease expires
        time.sleep(1)
    agent.record_turn("assistant", "Picking up at the charge endpoint.")

Without defer_lease=True, resume raises lease_held until the crashed process's lease expires (Python client guide).

The same operations are MCP tools (agent_resume, update_working_state, record_turn, begin_action, ...) and, on recall serve, HTTP routes at POST /v1/agent/<verb>. Over HTTP the server holds the lease between requests: resume returns an epoch and every write carries it, so a stale process cannot write over its successor. The State API is beta; the records it writes are stable (STABILITY.md). The resume example kills an agent mid-task and continues it in a new process.

Serving many agents

recall mcp is one agent, one process. recall serve is the same memory and state for many agents over HTTP, each inside the namespace its key names. The server holds the database credentials; agents hold Recall keys.

recall serve -backend polign -url http://polign:23000 -bootstrap-key-file admin.key
recall key create -backend polign -url http://polign:23000 -namespace acme:agent-7 -expires 168h

Each namespace gets its own collection, so nothing a caller sends can reach another namespace's records. POST /mcp is MCP over streamable HTTP; POST /v1/<tool> takes a memory tool's arguments as the body, and POST /v1/agent/<verb> a state tool's. Any stdio MCP client reaches the server through recall connect with RECALL_URL and RECALL_API_KEY set.

On Kubernetes a pod needs no key at all. With recall serve -kubernetes, it posts its projected service account token and gets a short-lived key fixed to its own agent id, which recall connect and the Python client obtain and renew by themselves. The Helm chart is charts/recall in Polign/polign; the agent-sandbox demo runs it on kind.

On Agent Substrate an actor needs no key either. With recall serve -substrate-issuer, the actor's egress policy has Substrate's gateway put a short-lived token for that actor in the Authorization header, and the server gives each actor its own memory. The agent-substrate example runs it on kind.

Backends

local (default)

polign_db

PostgreSQL + pgvector

MongoDB

Qdrant

RECALL_BACKEND

local

polign

pgvector

mongodb

qdrant

RECALL_BACKEND_URL

a directory

http://host:23000

postgres://user:pw@host/db

mongodb://user:pw@host/db

http://host:6333

Memory, history, as-of

yes

yes

yes

yes

yes

Keyword search

yes

yes

yes

yes

no

Cached reads

yes

yes

yes

yes

no

State API (leases)

yes

yes

yes

yes

no

export RECALL_BACKEND=pgvector RECALL_BACKEND_URL=postgres://user:password@localhost:5432/mydb
recall mcp -write

Three settings name the database for every command: -backend, -url and -key, or the variables above. Everything else, including what each backend needs and how to add one, is in docs/backends.md.

Benchmark

LongMemEval user-facts subset, 267 questions about a user's own facts, preferences, updates and dates, with Claude Sonnet 5.5 as reader and judge and the upstream prompts:

What the reader is given

Score

Nothing

6.0

The full chat history

88.0

BM25 over sessions, top 10

89.9

Recall, built-in word search

88.8

Recall with a model embedder (OpenAI text-embedding-3-small, 512 dims)

92.9

Only the sessions that hold the answer

96.6

With word search Recall is even with BM25 overall and behind it on preference questions (70.0 against 83.3); a model embedder puts it ahead. Recall handed the reader about 28k tokens per question, against 44k for BM25 and 168k for the full history. The harness is in eval/longmemeval.

Integrations

Python

pip install polign-recall, then the client guide.

Go

go get github.com/Polign/recall, then the Go library guide.

MCP

Connect any agent to remember, recall and forget.

Claude Code

The Recall plugin: memory across coding sessions.

LangGraph

pip install recall-langgraph to resume LangGraph agents.

LiveKit, Vapi

recall-livekit and recall-vapi for caller memory in voice agents.

Pydantic AI

pip install recall-pydantic-ai for memory tools in Pydantic AI agents.

Vercel AI SDK

The Next.js chat example, one click to deploy.

OpenClaw

@polign/openclaw-recall on npm, the OpenClaw plugin.

Documentation

Developer reference · Memory API contract · State API contract · Backends · Connecting through MCP · Caching memory reads · Exporting and replaying history · What is stable and what is beta · Development guide · Usage statistics

Usage statistics

Release builds send an anonymous heartbeat: version, platform, a random install ID, and counts of memory operations. Nothing that is remembered is ever sent. recall telemetry prints exactly what is sent, and recall telemetry off, RECALL_TELEMETRY=0 or DO_NOT_TRACK=1 turns it off. TELEMETRY.md lists every field.

Support the project

If Recall kept your agent from acting on a stale fact, a star on this repository helps other people find it. Bugs, questions and ideas go in issues.

License

Apache 2.0.

Available Tools

5 tools
diffDiffA
Read-only

What was believed differently at one instant than at another: each thing that began or stopped being believed in between. Use it to say what changed over a period, such as since the last session or during an incident.

Inputs: from (required), to.

forgetForgetA

Stop believing what a description names, such as "my editor" or "that I live in Lisbon". Returns what was withdrawn. Nothing is deleted: it stays in the history, and remembering it again brings it back.

Inputs: text (required).

historyHistoryA
Read-only

How something remembered changed, in words: every statement about it, oldest first, each with what it began and ended believing, and what is believed now. Use it when the user asks what changed, when, or why something is believed, and to show a correction whole. Something since forgotten still has its history.

Inputs: question (required).

recallRecallA
Read-only

Ask what is remembered, in words, before assuming anything about the user. Answers are what is believed now, as sentences. Each lists under before what it replaced and when, so a correction comes with the answer, and under elsewhere anything else believed about the same thing in other words, such as a later dislike beside a like; the newer statement usually holds. days_ago says how long ago it was stated. A time named in the question, such as "last week", is searched first. Each also gives under said the sentence it was drawn from, as the user said it. Pass as_of to ask what was believed at an earlier instant. Leave out question to get everything believed about the user, a profile to start a conversation with. Pass since to get only what changed after then, newest first: at the start of a session, since the last one, it says what is new.

Inputs: as_of, since, question.

rememberRememberA

Keep something worth remembering about the user or their work: a preference, a fact, a decision, or a correction. Pass the passage as text, in the user's words where you can, or pass the conversation as messages with their roles, so that only what the user said or agreed to is kept and nothing the assistant suggested. The server works out what it says. A newer statement replaces an older one about the same thing, and the older one stays in the history. Restating something already known changes nothing.

Inputs: text, messages, observed_at.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    The five tools cover clearly different operations: storing, querying, withdrawing, tracing one item's history, and comparing beliefs across time. The only mild overlap is between recall's `since` mode and diff, which both answer 'what changed', though their descriptions differentiate instants versus periods.

    Naming Consistency4/5

    All names are single, lowercase words with a consistent terse style. However, remember/recall/forget are verbs while history and diff are nouns, a minor deviation from a pure verb convention.

    Tool Count5/5

    Five tools is well scoped for a focused memory service, with each tool earning its place across the read/write/history lifecycle. No tool feels redundant or missing from the core set.

    Completeness5/5

    The surface covers the full memory lifecycle: write (remember), read (recall with profile, point-in-time, and delta views), soft delete (forget), per-item history, and cross-instant diff. No dead ends are apparent for the stated purpose.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Open-source AI memory layer for LLM agents. Importance scoring, temporal decay, hierarchical memory (facts, summaries, themes), YMYL prioritization, and active retrieval with contradiction detection. Supports OpenAI, Anthropic, Ollama. Local-first with SQLite + FAISS.
      50
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Integrates an Engram brain with Claude Code via MCP, providing tools for searching, retrieving, and adding memories.
      12 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Local memory for AI agents in one SQLite file on your own machine. Facts carry a validity window and a confidence score, so an outdated one is superseded and downweighted rather than deleted, and retrieval fuses BM25, vector similarity and a knowledge graph.
      4
      Business Source 1.1
    • A
      license
      Not graded
      quality
      C
      maintenance
      Self-hosted long-term memory for AI agents on your own Postgres. Facts are dated, versioned and superseded rather than silently overwritten, every recall ships with an inspectable trace, and agents can correct wrong memories from inside the conversation.
      2
      Apache 2.0