Configuration

Storage-root overrides

Each adapter resolves its storage root from $HOME by default — the live store. To point the CLI and the MCP server at fixtures or a scratch copy instead, without ever touching live sessions, set the harness’s root override.

Precedence: an explicit root (tests) > the env override (non-empty) > the $HOME-derived default. An empty value counts as unset. An override that resolves to nothing usable is an error, never a silent fall-back to $HOME.

The shadow index root follows the session root, so an override moves the tantivy indexes and the profile cache with it.

The sandbox guard

TOTAL_RECALL_SANDBOX=1 refuses to build any adapter whose root did not come from its override. With the sandbox armed and no override set, adapter construction fails closed with a descriptive error instead of reading the live store — a mechanical guarantee that sandboxed dev and test runs never read live sessions:

TOTAL_RECALL_SANDBOX is set but TOTAL_RECALL_VIBE_ROOT is not: refusing to read
the live store. Point TOTAL_RECALL_VIBE_ROOT at a fixture or scratch copy.

The guard is a constructor check, so it covers every tool: a sandboxed run cannot read the live store by any route.

API keys

A key reaches the binary one of two ways:

• Environment / MCP environment block. An MCP server finds a key only in its own environment, so the key belongs in the registration snippet’s environment map (or [mcp_servers.env]). Exporting it in the shell that launches the client works too — the server inherits it. This is the recommended path: a spawned server’s working directory is chosen by the MCP client, not by you, so a .env file may simply not be found.
• .env in the working directory, for the build-from-source CLI path: copy .env.template to .env and fill in the key. Only a default build reads it.

Build features

The LLM vendor is a compile-time cargo feature. A vendor is a third-party service that can be acquired, renamed or disappear entirely, so no build of this tool requires one: the default build has both vendors, and a vendor-free build is a first-class artifact.

[features]
default = ["mercury", "mistral"]
mercury = ["dep:dotenvy"]   # Inception Mercury 2.5 (the default provider)
mistral = ["dep:dotenvy"]   # Mistral, selected with --provider mistral

cargo build --release                        # both vendors (default)
cargo build --release --no-default-features   # vendor-free

A vendor-free build makes no LLM calls and needs no API key — it never reads INCEPTION_API_KEY or MISTRAL_API_KEY, and does not even load a .env file.

The LLM-backed MCP tool names stay in tools/list in every build — clients bind by name — and the call itself returns the error:

LLM provider `mercury` is not compiled into this build: it was built without the
`mercury` cargo feature. Rebuild with `cargo build --release --features mercury`,
or use the vendor-free build (`--no-default-features`) — it makes no LLM calls and
needs no API key, and every log-mining tool still works. Vendors compiled into
this build: none.

Provider selection

--provider selects between the vendors compiled into the build (mercury, mistral); a vendor that is not compiled in fails the same way, and an unrecognised name is refused rather than silently falling back to Mercury:

unknown LLM provider `gpt`: pass it to --provider. Known vendors: mercury,
mistral; compiled into this build: mercury, mistral.

Vendor identity (endpoint, model, key variable) is the gated part. The OpenAI-compatible chat transport itself compiles in every build but is unreachable without a vendor constructor.

--provider applies to the CLI’s summarise-from and prior-period-summary subcommands. The mcp subcommand constructs the default provider; see MCP setup.

OPENCODE_DB

Not read by the binary. scripts/opencode-db-vacuum.sh reads it to locate the store it operates on, defaulting to $HOME/.local/share/opencode/opencode.db. See the store-vacuum runbook.

What is written where

Nothing is written inside a session store. total-recall creates files only in the harness’s shadow root:

Both are disposable: delete the folder at any time, or override the session root to move it. A shadow root inside a git repository MUST NOT be committed.

Pricing

Mercury 2.5, launch (80% off) versus normal:

100M free tokens for new accounts.