RE-call

<p align="center">
  <img src="https://raw.githubusercontent.com/GiulioDER/RE-call/master/docs/banner.png" alt="RE-call: memory that knows when not to guess" width="900">
</p>

<!-- mcp-name: io.github.GiulioDER/re-call -->

<p align="center">
  <b>Memory that knows what it no longer believes.</b><br>
  RE-call is the retrieval engine I extracted from a research agent that had been running for months, after its memory outgrew its context window and it started confidently repeating conclusions it had already disproved.
</p>

<p align="center">
  <a href="https://github.com/GiulioDER/RE-call/actions/workflows/ci.yml"><img src="https://github.com/GiulioDER/RE-call/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/GiulioDER/RE-call/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a>
  <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
  <img src="docs/postgresql-badge.svg" alt="PostgreSQL + pgvector">
  <img src="https://img.shields.io/badge/CI-real%20pgvector%20·%20types%20·%20audit-brightgreen" alt="CI: real pgvector, types, audit">
  <a href="https://glama.ai/mcp/servers/GiulioDER/RE-call"><img src="https://glama.ai/mcp/servers/GiulioDER/RE-call/badges/score.svg" alt="RE-call MCP server"></a>
</p>

<p align="center">
  <a href="#why-re-call">Why RE-call</a>
  &nbsp;·&nbsp;
  <a href="#quickstart">Quickstart</a>
  &nbsp;·&nbsp;
  <a href="#how-it-works">How it works</a>
  &nbsp;·&nbsp;
  <a href="#product-surface">Product surface</a>
  &nbsp;·&nbsp;
  <a href="#documentation">Documentation</a>
  &nbsp;·&nbsp;
  <a href="#evidence">Evidence</a>
</p>

<p align="center">
  <a href="https://giulioder.github.io/RE-call/">Setup guide: install, configure and run RE-call</a>
  &nbsp;·&nbsp;
  <a href="https://github.com/GiulioDER/validity-frontmatter">Validity Frontmatter: the open spec RE-call implements</a>
</p>

## Why RE-call

Nearest-match retrieval cannot tell the difference between what is true and what merely reads like
it. When a corpus keeps its history, and real agent memory does, the retracted claim and its
correction are both retrievable, and the retracted one is often the nearer match. That is not a
tuning problem. A ranker with no notion of validity has no way to prefer the correction.

RE-call came out of a production, long-running trading-research agent: months of operation,
792 <!--@ citation-pending: measured in docs/CASE_STUDY.md, not backed by a committed results artifact -->
typed memos, 6,469 <!--@ citation-pending: measured in docs/CASE_STUDY.md, not backed by a committed results artifact -->
chunks, re-indexed daily by a session-end hook. Every guard in this repository
exists because that agent failed a specific way without it. See
[docs/CASE_STUDY.md](https://github.com/GiulioDER/RE-call/blob/master/docs/CASE_STUDY.md).

It is for teams putting agent memory behind real applications, where a stale or unsupported memory
is worse than no memory: keep the memory layer local by default, attach policy to every hit,
calibrate the refusal threshold on your corpus, and let the application decide what to do with a
result that is not trustworthy enough to answer from.

The vocabulary that carries that validity, `supersedes`, `valid_from` and `valid_until` in a
document's frontmatter, is published separately as
[Validity Frontmatter](https://github.com/GiulioDER/validity-frontmatter): MIT licensed, with a
zero-dependency TypeScript implementation beside it. RE-call is its Python implementation, not its
owner. The specification is deliberately licensed more permissively than this repository, so
adopting the vocabulary carries no obligation to adopt the engine.

| Capability | What it means in practice |
|---|---|
| Validity-aware retrieval | Superseded, expired, not-yet-valid, low-confidence, and not-entailed hits are surfaced as verdicts rather than flattened into ordinary search results. |
| Explicit abstention | When no valid result clears the calibrated threshold, callers receive an abstention with a reason instead of a nearest-neighbor guess. |
| Local operation | Ingest and retrieval run on PostgreSQL plus pgvector. Local embeddings are supported, so memory can be built and queried without a memory-layer LLM call. |
| Policy-driven configuration | Embedder, reranker, calibration, trust policy, and retrieval profile are selected to match legal, hardware, latency, quality, and cost requirements. The default is local and offline; higher-quality or hosted options are opt-in. |
| Production boundaries | Tenant IDs, row-level security, token-scoped MCP HTTP transports, erasure, quotas, timeouts, migrations, and observability are part of the shipped surface. |
| Reproducible evidence | Published numbers are tied to committed artifacts, and the claim gate checks them in CI. |

Measured strengths:

| Strength | Evidence boundary |
|---|---|
| Lower memory-layer cost | The LOCOMO head-to-head records no RE-call memory-layer LLM calls, while the comparator pays for extraction calls. See [benchmarks/REVIEW.md](https://github.com/GiulioDER/RE-call/blob/master/benchmarks/REVIEW.md). |
| External abstention check | On MTRAG, IBM's multi-turn RAG benchmark, RE-call is second on correct refusals among the recomputed systems and stays near the top answer-quality rows. See [docs/MTRAG_BENCHMARK.md](https://github.com/GiulioDER/RE-call/blob/master/docs/MTRAG_BENCHMARK.md). |
| Retrieval on a third-party personal-memory benchmark | On ATM-Bench, across 1,013 <!--@ atm/atm_bench_full_20260821.json # question_count --> questions of personal memory QA, the benchmark's own evaluator scores this run at Recall@10 **92.8924** <!--@ atm/atm_bench_full_20260821.json # retrieval.recall_at_10_percent --> and QS **68.4264** <!--@ atm/atm_bench_full_20260821.json # official_score.qs_percent -->. The leaderboard submission is open, not accepted, the answer model is not matched to the published baselines, and both limits are stated in [docs/ATM_BENCH.md](https://github.com/GiulioDER/RE-call/blob/master/docs/ATM_BENCH.md). |
| Validity beats nearest-match retrieval | Declared supersession makes the current memory win over stale but similar memory. The larger trust study is in [results/FINDINGS.md](https://github.com/GiulioDER/RE-call/blob/master/results/FINDINGS.md). |
| Stronger than a plain vector store | Returned hits carry verdicts, confidence, provenance, tenant scope, and validity metadata. Plain top-k retrieval returns neighbors and leaves trust to the caller. |
| Clear limits | The evidence states where RE-call works, where it does not, and when a corpus-specific measurement is required. |

The README is the product overview. For evidence behind these claims, start with
[docs/EVIDENCE.md](https://github.com/GiulioDER/RE-call/blob/master/docs/EVIDENCE.md), then use
[results/FINDINGS.md](https://github.com/GiulioDER/RE-call/blob/master/results/FINDINGS.md) for
the full interpretation and limits.

## Quickstart

Two commands, and the second one starts its own database:

```bash
pip install "recall-rag[fastembed]"
recall quickstart
```

That provisions a throwaway PostgreSQL with pgvector in Docker, indexes a small corpus that ships
inside the package, and answers three questions: one it can answer, one whose nearest match is a
claim that was later retracted, and one it refuses. The middle one is the point.

Measured 2026-08-22 on one Windows machine with the pgvector image already pulled:
about **50 seconds** <!--@ citation-pending: one machine, one hand-timed run, not backed by a committed results artifact -->
cold, and about **22 seconds** <!--@ citation-pending: one machine, one hand-timed run, not backed by a committed results artifact -->
on a re-run that reuses the container. A machine without the image also pays for that pull, which
is the largest and most variable part and is not included here. Re-measure with
`time recall quickstart`.

Nothing is calibrated and nothing is registered with an agent. It prints the next command for each.

```bash
recall quickstart --remove          # stops the database and destroys its volume
```

Already running PostgreSQL with pgvector? `recall quickstart --existing-dsn <dsn>` skips Docker
entirely.

### The full install

The quickstart is a demonstration, not an install: it answers questions about a sample corpus with
an uncertified threshold, and it leaves your own notes untouched. What follows is the different and
longer thing, which points RE-call at your memory, fits a threshold to it, and registers the MCP
server with your agent.

RE-call keeps memory in your own PostgreSQL with pgvector, so a database comes first.

**Already running PostgreSQL with pgvector?** Skip ahead and point the DSN at it.

**Want a throwaway one?** Save this as `docker-compose.yml`, then start it:

```yaml
services:
  db:
    image: pgvector/pgvector:pg18
    environment:
      POSTGRES_USER: recall
      POSTGRES_PASSWORD: recall
      POSTGRES_DB: recall
    volumes:
      - recall_pgdata:/var/lib/postgresql
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U recall"]
      interval: 2s
      timeout: 3s
      retries: 30

volumes:
  recall_pgdata:
```

```bash
docker compose up -d --wait
```

Then install, create the schema, and run the guided setup wizard. The wizard records the selected
embedder, retrieval options, and an optional calibration that is fitted to your labeled queries and
your corpus.

```bash
pip install "recall-rag[fastembed]"
python -m recall.cli --migration-dsn postgresql://recall:recall@localhost:5432/recall schema --dim 384 apply
python -m recall.cli setup
```

Those three run unchanged in PowerShell.

The schema command targets the default `chunks` table deliberately. Global migrations have to be
applied there before any other table, so starting with `--table something_else` on a fresh database
stops with `SchemaTooOld`. To