Recall

The memory layer for AI agents — typed-edge graph, bounded hallucination, surgically forgettable.

# One-time MCP setup: asks which client (Codex / Claude Code / Cursor /
# Windsurf), lite vs full, optional API key, then writes the config
# and pre-warms the cache so MCP starts are instant.
npx typed-recall install

# Or use the Python library directly:
pip install typed-recall

Live: PyPI · npm · GitHub releases

v0.6 (2026-05-07) — what's new

The v0.5 LongMemEval gap is closed. By decoupling the symmetric retrieval embedding from the f/b dual prompts, Recall now matches plain cosine RAG on every question type LongMemEval tests, while keeping its 60-pt lead on causal-chain queries and its non-vacuous hallucination bound.

Full v0.6 details: CHANGELOG.md. Per-benchmark numbers: docs/BENCHMARKS.md. The math behind the decoupling: docs/MATH.md §2.6.

What Recall is, in plain language

Most AI memory systems (Mem0, Letta, ChatGPT memory, Graphiti) store memories as a flat bag of facts and retrieve by cosine similarity. When the agent forgets or hallucinates, you have no way to debug why.

Recall stores memories as a typed-edge graph where every connection has a meaning — supports, contradicts, corrects, pivots, temporal-next, superseded. Retrieval walks the typed graph and returns a connected reasoning path instead of a chunk bag. Every answer comes with a mathematical hallucination bound and a full audit trail.

The library is Apache-2.0, runs locally (no required cloud), works as a Python lib, an MCP server (Claude Desktop / Cursor / Cline / Codex / Continue / Zed / Windsurf), or a personal CLI.

Three lines to integrate

from recall import Memory

mem = Memory(tenant="my_app")

mem.observe(user_msg, agent_msg, scope={"project": "platform"})
answer = mem.bounded_generate("what queue tech do we use, and why?",
                               scope={"project": "platform"})
trace  = mem.trace(answer)        # full provenance
mem.forget(node_id, reason="...") # surgical, audit-logged

That's the entire surface. Five public methods. Local SQLite. No required API key.

What makes Recall genuinely different

Real benchmark results

All numbers reproducible from benchmarks/ on a clean install. No marketing massaging — every script lists its full configuration.

HotpotQA distractor (real public benchmark)

The auto-router correctly picks symmetric mode for fact-lookup queries on sparse graphs (HotpotQA's atomic-passage structure) and path mode for causal chains.

Synthetic causal-chain benchmark (5-step planted chain + 20 distractors)

Path-mode Γ-walk recovers full reasoning chains where cosine misses 60%.

mem0 #4573 junk-replay (the famous "97.8% junk" failure mode)

Synthetic replay of the mem0 #4573 corpus shape. Recall achieves a 5.9× reduction in stored junk by hash-dedup + provenance firewall + LLM-driven quality gate + bio-fingerprint hard-reject for fabricated profile claims.

Conformal Risk Control hallucination bound

The Conformal Risk Control bound replaces a vacuous PAC-Bayes value with a non-vacuous, finite-sample, distribution-free guarantee at 95% confidence.

Sheaf-Laplacian H¹ inconsistency detector

Verified on synthetic graphs:

Detects cycle-level inconsistencies that pairwise contradiction checks miss — a class of bug in agent reasoning that nothing else surfaces.

Research foundations

Recall composes published mathematics from three Nordic ML labs into one coherent Bayesian framework. Every primitive cites a paper.

Hauberg (DTU) — the metric

The Γ retrieval primitive Γ(i→j) = f·b − s·s is the antisymmetric component of a Fisher-Rao pull-back metric on dual LLM-prompted views.

• Arvanitidis, González-Duque, Pouplin, Kalatzis, Hauberg, Pulling Back Information Geometry, AISTATS 2022. arXiv:2106.05367

• Syrota, Zainchkovskyy, Xi, Bloem-Reddy, Hauberg, Identifying Metric Structures of Deep Latent Variable Models, ICML 2025. arXiv:2502.13757

• Karczewski, Heinonen, Pouplin, Hauberg, Garg, Spacetime Geometry of Denoising in Diffusion Models, ICLR 2026 oral. arXiv:2505.17517

Igel (KU) — the bound

The PAC-Bayes second-order tandem-loss bound for retrieval-conditioned generation.

• Masegosa, Lorenzen, Igel, Seldin, Second Order PAC-Bayesian Bounds for the Weighted Majority Vote, NeurIPS 2020. arXiv:2007.13532

• Wu, Masegosa, Lorenzen, Igel, Seldin, Chebyshev–Cantelli PAC-Bayes- Bennett Inequality, NeurIPS 2021. arXiv:2106.13624

Selvan (KU, with Igel) — the consolidator

BMRS Bayesian Model Reduction for threshold-free edge pruning during sleep-time consolidation.

• Wright, Igel, Selvan, BMRS: Bayesian Model Reduction for Structured Pruning, NeurIPS 2024 spotlight. arXiv:2406.01345

Additional load-bearing math

• Kang, Liu, et al., C-RAG: Certified Generation Risks for RAG, ICML 2024. arXiv:2402.03181 — basis for the Conformal Risk Control bound

• Zhang et al., RAG-as-Noisy-In-Context-Learning: A Unified Theory and Risk Bounds, 2025. arXiv:2506.03100

• Hansen & Ghrist, Toward a spectral theory of cellular sheaves, 2019; Wei et al., Learning Sheaf Laplacian Optimizing Restriction Maps, 2025 (arXiv:2501.19207) — basis for H¹ inconsistency detector

• Ahmadi, Hajiaghayi, Jabbarzade, Mahdavi, Springer, Prize-Collecting Steiner Forest 2-Approximation, JACM 2025. arXiv:2309.05172

• Ollivier, Ricci curvature of metric spaces (2009); applied to typed-edge bottleneck protection

• Vietoris-Rips persistent homology via gudhi; Wasserstein/Gromov-Wasserstein via POT

Full derivations in docs/MATH.md.

Installation

As a Python library

pip install typed-recall          # full install: BGE + OpenAI + MCP + graph math
recall-setup                       # interactive: API key, MCP client, DB dir, …

pip install typed-recall (v0.2+) bundles everything you need in one command — neural embedder, real LLM client, MCP server, graph math. The first install is ~150MB but you don't need to remember which extras to add later.

The post-install recall-setup wizard:

• Asks for an OpenAI / TokenRouter API key (so bounded_answer returns real LLM output, not stubs).

• Asks for the base URL + model.

• Asks where to put the SQLite DB (~/.recall by default).

• Optionally registers the MCP server with Codex / Claude Code / Cursor / Windsurf in the same step.

• Pre-downloads the BGE model so the first Memory(...) call is fast.

• Saves everything to ~/.recall/.env — auto-loaded on every import, every CLI invocation, every MCP-server launch. No need to export anything.

Non-interactive (CI / scripts):

pip install typed-recall
recall-setup --yes \
    --client claude-code \
    --openai-key sk-... \
    --openai-base-url https://api.openai.com/v1 \
    --openai-model gpt-4o-mini

Optional power-user extras:

pip install 'typed-recall[server]'     # +FastAPI HTTP server
pip install 'typed-recall[gudhi,ot]'   # +persistent homology, optimal transport
pip install 'typed-recall[dev]'        # everything including pytest, ruff, mypy

Lite install (without torch / transformers)

If 150MB is too much (CI runners, edge boxes), skip the heavy deps:

pip install --no-deps typed-recall numpy scikit-learn mcp python-dotenv

You'll get the full Python API and CLI but with the TF-IDF embedder instead of BGE, and the mock LLM instead of real OpenAI. Works fine for prototyping; lower retrieval quality.

As an MCP server (Claude Code / Cursor / Codex / Windsurf / Cline)

One-command setup (recommended)

npx typed-recall install

The installer:

1. Asks which client(s) to register with — Codex, Claude Code, Cursor, Windsurf, or all of them.

2. Asks lite (~10MB, TF-IDF embedder, mock LLM) vs full (~150MB, BGE neural embedder + OpenAI/TokenRouter LLM client).

3. Optionally collects an OpenAI / TokenRouter API key for real bounded generation.

4. Installs uv (Python tool runner) if missing.

5. Pre-warms uv's cache so subsequent MCP starts are instant — no on-demand download when Codex/Claude Code spawns the server.

6. Writes the MCP entry to each chosen client's config file (~/.codex/config.toml, ~/.cursor/mcp.json, etc., or runs claude mcp add recall ...).

Then restart your client. recall MCP is ready, with all 8 tools: add_memory, search_memory, bounded_answer, forget, audit, graph_health, consolidate, stats.

Non-interactive (CI / scripts):

npx typed-recall install --yes \
    --client claude-code \
    --version full \
    --openai-key sk-...  --openai-base-url https://api.openai.com/v1

Manual setup

If you'd rather skip the installer and write the config yourself:

# Claude Code
claude mcp add recall -- npx -y typed-recall

# Codex (~/.codex/config.toml)
[mcp_servers.recall]
command = "npx"
args = ["-y", "typed-recall"]

# Cursor / Windsurf — paste the same JSON-block in their MCP settings
{ "mcpServers": { "recall": { "command": "npx", "args": ["-y", "typed-recall"] } } }

⚠️ Without the installer, the first MCP startup runs a live Python install via uvx. Lite extras (mcp) finish in <1s; full extras (mcp,embed-bge,llm-openai) download ~150MB and can exceed the MCP client's startup timeout. Either run the installer first, or override extras to lite by setting RECALL_MCP_EXTRAS=mcp in the MCP env block.

As a personal CLI

pipx install typed-recall
recall me add "decided to migrate from Postgres LISTEN/NOTIFY to Redis Streams"
recall me ask "what queue tech are we using?"
recall me health         # spectral / topology / curvature diagnostics
recall me trace          # full audit log
recall me consolidate    # run sleep-time pruning

As a self-hosted server

docker compose up
# server at http://localhost:8765

docker-compose.yml brings up the FastAPI server, background consolidator, Postgres + pgvector, and Redis. Suitable for teams running Recall in their own VPC.

How it works

Storage layer (3 primitives)

• Drawer — verbatim immutable text (the truth layer)

• Node — distilled thought, points to drawer ranges, has dual embeddings (f, b)

• Edge — typed (supports/contradicts/etc.), asymmetric, signed-weighted

Write pipeline (gated)

user message
    │
    ├─ hash dedup       (skip exact duplicates)
    ├─ provenance check (reject recall artifacts)
    ├─ quality classify (LLM gate + bio-fingerprint)
    ├─ node split       (LLM with sentence fallback)
    ├─ dual embedding   (f, b via prompted views)
    ├─ edge induction   (Γ score vs top-k neighbors)
    └─ persist          (with audit log entry)

Retrieval (auto-routed)

query → cosine seed → graph-aware router decides:
        ├─ symmetric (sparse graph or factual query)
        ├─ path (causal/directional query)
        ├─ walk_short (moderately spread seeds)
        └─ hybrid (RRF-fused symmetric + path)
              │
              └─ PCST/PCSF subgraph extraction → reasoning path

Bounded generation

LLM only sees the retrieved subgraph as context. Each generated claim is checked for structural support; unsupported claims are flagged. The Conformal Risk Control bound is reported alongside every answer.

Sleep-time consolidator

Runs periodically:

priority queue of dirty regions →
    1. curvature analysis (protect bottleneck edges)
    2. BMRS Bayesian pruning (Wright-Igel-Selvan NeurIPS 2024)
    3. mean-field GNN refinement (Selvan MedIA 2020)
    4. motif extraction (Mosaic-of-Motifs)
    5. PMED scoring (D_RPD, DCR, P_syco, Q_corr, Q_eff, Q_rare)

Working set stays bounded; perceived memory feels infinite.

Full architecture: docs/ARCHITECTURE.md.

Distribution channels

Tests

PYTHONPATH=src pytest tests/ -q
# 154 passed in 1.6s

Coverage spans: Γ algebra, identifiability, storage roundtrips (incl. v0.5 scope-subset semantics, v0.6 s_embedding + adjacency cache), write pipeline gates (incl. v0.5 bulk-mode), retrieval modes, PCST/PCSF, PAC-Bayes bounds, Conformal Risk Control (Hoeffding + Wilson), sheaf Laplacian, BMRS pruning, mean-field, motif extraction, PMED scoring, graph spectral/topology/transport/ curvature, MCP server, FastAPI server, Letta adapter, telemetry, embedder fallbacks (incl. v0.6 embed_symmetric).

Repository layout

recall/
├── src/recall/                # 50+ modules
│   ├── api.py                 # public Memory class
│   ├── geometry/              # Γ + spectral + identifiability
│   ├── graph/                 # spectral, topology, transport, curvature, sheaf
│   ├── retrieval/             # walk, PCST, PCSF, intent, router, linearize
│   ├── bound/                 # PAC-Bayes, RAG-noisy-ICL, Conformal Risk Control
│   ├── consolidate/           # BMRS, mean-field, motif, PMED, scheduler
│   ├── core/                  # SQLite storage
│   ├── audit/                 # append-only audit log
│   ├── write/                 # pipeline, quality, splitter, edge classifier, bio-fingerprint
│   ├── integrations/          # Letta adapter
│   ├── server.py              # FastAPI HTTP server
│   ├── mcp_server.py          # MCP stdio server
│   └── personal.py            # CLI for personal knowledge graph
├── tests/                     # 27 test files, 144 tests
├── benchmarks/                # 8 benchmarks, all reproducible
├── examples/                  # quickstart, full demo, real LLM
├── extensions/
│   ├── browser/               # Chrome/Firefox MV3 extension scaffold
│   └── mcp_bundle/            # MCP registry manifest
├── docs/                      # MATH.md, ARCHITECTURE.md, CUSTOMER_JOURNEY.md, etc.
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── GOVERNANCE.md              # OSS-forever commitment
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE                    # Apache-2.0

Status

v0.4 — feature-complete alpha. All five core primitives implemented and tested: typed-edge graph, Γ retrieval, bounded generation, sleep-time consolidation, audit-grade forget. Three distribution channels working: Python library, MCP server, personal CLI.

The substrate is shippable. Remaining work is engineering polish, integration PRs to upstream frameworks (Letta, LangGraph, Mastra, Cline, Continue), and public-launch artifacts (recall.dev landing page, Show HN post, benchmark publication).

Roadmap

Cloud hosting is not on the roadmap unless 50+ users explicitly request it. The OSS is the product.

Contributing

See CONTRIBUTING.md for the full contributor guide.

Quick start:

git clone https://github.com/yash194/recall.git
cd recall
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
PYTHONPATH=src pytest

Areas needing help:

• Integrations: Mastra, LangGraph, CrewAI, AutoGen memory backends

• Benchmarks: LongMemEval and MemoryAgentBench harnesses

• Storage: Postgres adapter implementing the Storage protocol

• Math: identifiability tests for Γ; sheaf-Laplacian eigenmode localization

• Docs: walkthroughs for the spectral / topology / curvature modules

All contributions require DCO sign-off (git commit -s).

Citation

If you use Recall in research, please cite:

@software{aggarwal2026recall,
  title  = {Recall: A Typed-Edge Memory Substrate for AI Agents},
  author = {Aggarwal, Yash},
  year   = {2026},
  url    = {https://github.com/yash194/recall},
  note   = {Apache-2.0 licensed open-source software}
}

A formal arXiv preprint is in preparation.

Machine-readable metadata: CITATION.cff.

License & governance

Apache License 2.0 (LICENSE).

The Apache-2.0 license is committed in perpetuity per GOVERNANCE.md. The full retrieval engine, typed-edge runtime, all graph mathematics, all hallucination bounds, all consolidation primitives, all benchmarks, and all integrations stay open-source forever. No crippleware. No business-source license. No bait-and-switch.

If we ever break this commitment, the OSS-forever clause requires us to provide a clean fork-friendly snapshot.

Documentation index

If you only read one, read docs/PRINCIPLES.md. If you only read two, add docs/MATH.md.

Acknowledgements

Recall builds on published mathematics from:

• Søren Hauberg (DTU Compute) — Riemannian latent geometry, Fisher-Rao pull-back

• Christian Igel (DIKU/KU) — PAC-Bayes second-order tandem-loss bounds

• Raghavendra Selvan (KU) — BMRS Bayesian model reduction

• Mohammad Hajiaghayi (UMD) — PCSF 2-approximation

• Aapo Hyvärinen (Helsinki) — identifiability of dual encoders

• Yann Ollivier (Meta FAIR) — graph Ricci curvature

• OSU NLP / HippoRAG — Personalized PageRank for memory

• Hansen-Ghrist & Wei et al. — sheaf Laplacian inconsistency detection

• Kang et al. / Zhang et al. — Conformal Risk Control + RAG-as-noisy-ICL bounds

The 2024-2026 AI memory ecosystem (Mem0, Letta/MemGPT, Graphiti, Cognee, HippoRAG, MemoryOS, EM-LLM, A-MEM, Hindsight, Supermemory, Mastra) shaped the design through their published artifacts and audited failure modes.

Documentation · Math · Architecture · Customer journeys · Deployment · Launch plan