> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.livingbrain.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.livingbrain.com/_mcp/server.

# How search ranks pages

Each search runs two lookups and merges them. Semantic search finds pages whose meaning is close to
the query even when the wording differs. Keyword search finds pages that contain the query's names,
codes and identifiers, which semantic search can miss.

Query → semantic candidates (cosine similarity) and keyword candidates (title, summary, body) → merged and ranked → up to `topK` results.

## How results are ordered

A page ranks higher when it's closer to the query in meaning and when the query's words appear in its
title, summary or body. A page found only by semantic search ranks by similarity alone.

Each result's `similarity` field holds the vector score only, so two results can appear out of
similarity order when one of them also matched on keywords. The combined rank isn't returned.

## The similarity floor

`minSimilarity` drops semantic matches below 0.35. Keyword matches are kept below it.

Query → semantic candidates (cosine similarity) and keyword candidates (title, summary, body) → merged and ranked → up to `topK` results.

## Defaults and limits

| Setting            | Default                                  | Notes                                                                          |
| ------------------ | ---------------------------------------- | ------------------------------------------------------------------------------ |
| `topK`             | 5                                        | How many results to return                                                     |
| `minSimilarity`    | 0.35                                     | Floor for semantic matches. Keyword matches are returned below it              |
| What gets embedded | Title, summary and the start of the body | Text further into a long page is reached by reading the page                   |
| Excerpts           | 500 characters, 5 results                | Up to 20 results and 2,000 characters each, where a response includes excerpts |

## Reading a result

`matchedOn` says why a page came back:

| `matchedOn` | What it means                                         | What to do with it                                                  |
| ----------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
| `both`      | Close in meaning and contains the query's words       | Usually the strongest candidate                                     |
| `semantic`  | Close in meaning, no shared keywords                  | Useful for paraphrased questions. Check the page says what you need |
| `keyword`   | Contains the words, may be below the similarity floor | Useful for names and IDs. The word may only appear in passing       |

## Similarity and correctness

A similarity of 0.82 says the page sits close to the query in embedding space. It gives no 82%
chance that the page answers the question. A page that contains the answer and a page that only
discusses the topic can score the same.

Use the score to choose which pages to open, then read them to decide whether you have an answer.
[How to build with Living Brain](/docs/build#reading-from-a-brain) covers that step.

## Search or the prompt index

Search answers a specific question. The [prompt index](/docs/search#prompt-index) is a short digest of
the brain's most important pages, pinned pages first, that gives an agent general context. Agents that
hold a conversation usually load the index at the start of a session and search when a question needs
something specific.