Retrieval

Ratel Local uses BM25 by default. It needs no model, download, or embedding request. Semantic and hybrid retrieval are explicit opt-ins.

Inspect the effective mode

ratel-local retrieval status

The command shows user, project, and local overrides, then the effective mode. The retrieval block is atomic: the narrowest scope that defines it replaces the entire earlier block.

Configure or reset a scope

# Keep every project model-free unless a narrower scope overrides it.
ratel-local retrieval configure --scope user --method bm25

# Use the built-in model for one project.
ratel-local retrieval configure \
  --scope project \
  --method hybrid \
  --source built-in

# Remove that override and inherit the earlier scope again.
ratel-local retrieval reset --scope project

Writes use the same revision checks, transaction journal, and local Git-exclude safeguards as other scoped changes.

Prepare a dense source

Dense retrieval fails closed when its model or endpoint is unavailable. Preflight it before reconnecting the agent:

# Prepare the effective merged configuration.
ratel-local retrieval prepare

# Prepare only the project override.
ratel-local retrieval prepare --scope project

The CLI keeps an active preparation status on screen. A missing Hugging Face model shows the file, bytes transferred, and percentage before Ratel verifies it.

The built-in source uses the SDK-pinned BAAI/bge-small-en-v1.5 model. It downloads to the Hugging Face cache when prepared and uses roughly 130 MB of process memory while loaded. The model is shared by tool and skill catalogs.

Other embedding sources

Use a source that matches your language, network, and privacy requirements:

# Hugging Face
ratel-local retrieval configure --scope project --method hybrid \
  --source huggingface --model intfloat/multilingual-e5-small --revision main --download

# Local model directory
ratel-local retrieval configure --scope local --method semantic \
  --source local --model ~/.cache/models/bge-small

# Ollama
ratel-local retrieval configure --scope project --method semantic \
  --source ollama --model nomic-embed-text

# OpenAI-compatible endpoint
ratel-local retrieval configure --scope project --method hybrid \
  --source endpoint --url https://api.example.com/v1/embeddings \
  --model text-embedding-3-small --api-key-env EMBEDDING_API_KEY

Literal endpoint API keys are rejected. --api-key-env names an environment variable the daemon must receive.

• Built-in, Hugging Face, and local sources keep metadata and queries on the machine.
• Ollama sends one preflight and retrieval requests to the configured local service.
• Endpoint sources send tool and skill metadata while indexing and queries while searching.

Apply the change

Reconnect the affected agent after configure, reset, prepare, or dense OAuth changes. The new connection acquires the latest gateway generation; existing sessions continue on their old immutable generation until they disconnect.

Use Settings in the daemon UI for the same validated save and preflight flow.

Roll back to BM25

Configure BM25 at the scope that currently owns the dense override, then reconnect:

ratel-local retrieval configure --scope project --method bm25

Next steps