Installation and Setup

Installation and Setup

RE-call is a library over your PostgreSQL. There is no managed service. The pieces you operate are the database, the optional MCP process, and, for production, the migration job that owns DDL.

Requirements: Python 3.11+, PostgreSQL 16 or 17 with the pgvector extension.

Two minutes, no API key

docker compose up -d --wait          # PostgreSQL + pgvector
pip install -e ".[fastembed]"        # local embeddings, no API key
python -m recall.cli --migration-dsn postgresql://recall:recall@localhost:5432/recall schema --dim 384 apply
RECALL_TRUST_MODE=development python -m recall.cli demo

The demo indexes the shipped corpus and runs the case the project turns on — a stale memory outranking its successor on raw cosine, correctly demoted — plus an unanswerable query that returns an explicit abstention.

The docker-compose.yml in the repo is for development. See the warning under Tenancy-and-Auth before pointing anything real at it: it connects as a privileged role, which silently disables the row-level-security layer.

Strict trust is the default. The demo opts into development mode because it indexes a local sample corpus directly, without first building an immutable generation and publishing a certified calibration.

Choosing extras

The base install is deliberately thin. Everything with a model or a service behind it is opt-in, so you install what you use. Exact version floors live in pyproject.toml.

Extra	Gives you	Install it when
fastembed	Local ONNX embeddings, no API key	Almost always — this is the default embedder
pool	Connection pooling	Any server process. A CLI runs single-connection and should not pay for a pool's background maintenance thread
mcp	The MCP server (includes pooling)	Exposing RE-call to an agent
voyage	Cloud embeddings	You have measured that the hosted embedder is worth the privacy, latency and API-cost trade → Embedders-and-Rerankers
rerank	Cross-encoder reranking	You want retrieval quality and can afford the query latency. This is the largest single retrieval gain measured in this project → Embedders-and-Rerankers
entail	The near-miss entailment judge	You are hitting near-misses specifically. Off by default for a measured reason
splade	Learned sparse retrieval	You want the SPLADE leg measured in the MTRAG work and can afford transformer sparse encoding
eval	Charting for the evaluation harness	Reproducing the published results
finetune	Fine-tuning trainer	Domain-adapting an embedder to a jargon-heavy corpus
langchain / llamaindex	Framework adapters	Using RE-call through those retriever interfaces
dev	pytest, ruff, and what the suite needs	Contributing → Contributing-and-Testing

You can combine them: pip install -e ".[fastembed,mcp]".

Pointing at your own Postgres

For development, RECALL_DSN is still accepted as a fallback. For real deployments, split the credentials:

Variable	Use
RECALL_SERVING_DSN	Unprivileged runtime credential used by indexing, search, forget and MCP
RECALL_MIGRATION_DSN	Schema-owner credential used only by recall schema apply
RECALL_DSN	Deprecated development fallback for the serving DSN

Normal library data operations, CLI data commands and MCP startup do not execute DDL in v1. Apply migrations explicitly:

python -m recall.cli --migration-dsn "$RECALL_MIGRATION_DSN" schema --dim 384 apply

status and plan are read-only checks. apply takes the migration credential, records checksums in the migration ledger, and can resume an interrupted concurrent index phase. The full role split and grant generator are in docs/MIGRATIONS.md.

PgVectorStore.ensure_schema() remains as a deprecated explicit compatibility wrapper for disposable test and evaluation stores. Production should call check_schema() and keep the migration credential out of the serving process.

The insecure-DSN refusal

The MCP server refuses to start if the serving DSN carries the repo's published default credentials against a non-local host. Not a warning — a refusal.

The reasoning is worth internalising because it recurs throughout this codebase: a warning produces a server that comes up looking healthy, with every memory in it readable by anything that can reach the port, and the warning is discovered afterwards. If you genuinely mean it, an explicit environment variable accepts the risk deliberately. → Configuration-Reference

First index

RECALL_TRUST_MODE=development python -m recall.cli index ./notes
RECALL_TRUST_MODE=development python -m recall.cli search "what did we decide about caching?"

Then, in rough order of value:

1. recall lint ./notes — check the supersession graph. Cheap, no database.
2. recall calibrate — fit the abstention threshold for your embedder. Without it the system falls back to a default and flags every result as uncalibrated.
3. recall check in a pre-commit hook — catch missing supersession edges at write time, which is the only moment they can be answered cheaply.

For production generation mode, build and validate a generation, bind or import calibration, promote it, then serve the tenant's active route. Start with docs/ENTERPRISE_RETRIEVAL.md when you need immutable generations, shadow cutovers and readiness gates.

All three: CLI-Reference.

The test-DSN separation

The test suite DROPs tables. It therefore reads RECALL_TEST_DSN and never RECALL_DSN — exporting your real DSN and running pytest cannot touch your data.

This is not a convention to remember; it is enforced in the test configuration. Details → Contributing-and-Testing.

A note on the local .env

Entry points load a .env file if present, using a minimal loader that does not override variables already set in the environment. The file is gitignored and intended for local development secrets. Precedence is: real environment first, .env second, defaults last.

---

Next: CLI-Reference · Python-API-and-MCP · Configuration-Reference · Tenancy-and-Auth before exposing it over a network.