Installation and Setup

Installation and Setup

RE-call is a library over your PostgreSQL. There is no bundled server, no managed service, and nothing to operate beyond the database you already have.

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 demo            # index corpus/ and run the sample queries

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.

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	Your corpus vocabulary is idiosyncratic enough to need it — measure first, and note it sends your queries off your machine → Embedders-and-Rerankers
rerank	Cross-encoder reranking	You want retrieval quality and can afford the query latency — the largest single gain measured in this project. Widen the candidate pool with it or it does nothing → Embedders-and-Rerankers
entail	The near-miss entailment judge	You are hitting near-misses specifically. Off by default for a measured reason
eval	Charting for the evaluation harness	Reproducing the published results
finetune	Fine-tuning trainer	Domain-adapting an embedder to a jargon-heavy corpus
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

Set RECALL_DSN, or pass --dsn. Any reachable PostgreSQL with pgvector works.

The store creates its schema on first use — table, indexes, and the row-level-security policy — and migrates an existing pre-tenancy table in place. There is no separate migration step to run.

⚠️ There is no versioned upgrade path. Schema creation is idempotent DDL, not a migration framework. This is stated as a limitation in the README rather than presented as a feature.

The insecure-DSN refusal

The MCP server refuses to start if RECALL_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

python -m recall.cli index ./notes
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.

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.