> ## Documentation Index
> Fetch the complete documentation index at: https://docs.px0.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieval backends

> Keyword search works out of the box with nothing to install. Semantic search is one config change plus a model download you explicitly consent to.

`retrieval.backend` decides how searching your brain works. There are two options, and the default is genuinely usable - the second is an upgrade, not a fix for something broken.

| Backend           | What you get                                             | Cost                                            |
| :---------------- | :------------------------------------------------------- | :---------------------------------------------- |
| `local` (default) | SQLite FTS5 keyword matching with BM25 ranking, embedded | Nothing to install                              |
| `qmd`             | Hybrid keyword + vector search with LLM reranking        | Needs the qmd CLI and about 2GB of local models |

## The local backend

Keyword matching, embedded in px0, no server and no models. It is fast, it works offline, and it needs zero setup.

Its one real limitation is worth stating plainly: it only matches words that are actually in the text. A search for "connection pooling" will not surface a passage that says "reusing database connections" - the same idea with no shared keywords. For a library you wrote or curated yourself, where you tend to remember the words used, this matters less than you might expect.

### Reranking

With `retrieval.rerank` on (the default), a search asks the backend for more candidates than `k` and then reorders them: how much of the query each passage covers first, how close the matched terms sit to each other second, the backend's own score as the tie-break. BM25 rewards a passage that repeats one query term; a question with three terms in it usually wants the passage that mentions all three. The rescoring is local arithmetic - no model call.

Turn it off and `k` rows in are `k` rows out, ranked by the backend alone:

```bash theme={null}
px0 config set retrieval.rerank false
```

## The qmd backend

`qmd` adds vector search and reranking, so meaning matches even when vocabulary does not.

```bash theme={null}
npm install -g @tobilu/qmd     # or: bun install -g @tobilu/qmd
px0 config set retrieval.backend qmd
px0 brain reindex
```

If `qmd` is not on your `PATH`, px0 says so and points you back at `local` rather than failing obscurely mid-search.

### The model download is your call

The first reindex after switching prints the download sizes and waits for an explicit `y`:

```
Local models needed for semantic search & reranking:
--------------------------------------------------
embeddinggemma-300M       ~300MB  (Embeddings)
qwen3-reranker-0.6b       ~640MB  (Reranking)
qmd-query-expansion-1.7B  ~1.1GB  (Expansion)
--------------------------------------------------
Total Download Size:      ~2.04GB
--------------------------------------------------
Download ~2.04GB of local models for semantic search? [y/N]
```

Decline and px0 keeps indexing keywords only. It degrades rather than breaks, and it will not ask again until you consent - nothing about px0 downloads two gigabytes onto your machine without asking.

Your answer is recorded in the store, and `px0 doctor` reports both the consent state and whether your installed qmd matches the version px0 is pinned to:

```
✓ index  qmd backend configured (version: 2.8.3, consented)
```

If the versions drift, `doctor` tells you the exact install command for the pinned build - and reminds you that dropping back to `local` is a legitimate answer, not a defeat.

### Pointing at a specific binary

```bash theme={null}
px0 config set retrieval.qmd_cmd /opt/qmd/bin/qmd
```

Useful when `qmd` is not the right command - a wrapper script, a pinned path, a version manager shim.

## Switching back

```bash theme={null}
px0 config set retrieval.backend local
px0 brain reindex
```

Nothing is lost. The index is rebuilt from `brain/` either way, because the Markdown files are the source of truth and the index is derived.

## Settings

| Key                   | Default        | What it does                                              |
| :-------------------- | :------------- | :-------------------------------------------------------- |
| `retrieval.backend`   | `local`        | `local` or `qmd`                                          |
| `retrieval.qmd_cmd`   | `qmd`          | Command prefix used to run the qmd CLI                    |
| `retrieval.k_default` | `5`            | Default number of passages retrieved per query            |
| `retrieval.rerank`    | `true`         | Rescore retrieved passages locally before trimming to `k` |
| `brain.path`          | `~/.px0/brain` | The directory being indexed                               |

## What is never indexed

The private folder (`brain/work/` by default) is excluded from every retrieval on both backends - a hard exclusion, not a ranking penalty. See [The brain](/brain/library).