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

# RAG & Retrieval

> Understand Starfire AI retrieval-augmented generation, chunking, embeddings, reranking, and source selection.

# RAG & retrieval

Retrieval-augmented generation (RAG) lets Starfire answer with relevant material from a larger knowledge collection without placing every source into every request.

## Core flow

```text theme={null}
User question
    ↓
Query understanding
    ↓
Candidate retrieval
    ↓
Filtering / permissions
    ↓
Reranking
    ↓
Selected chunks
    ↓
Model context
    ↓
Answer
```

## Chunking

Large sources are split into smaller retrievable units. Good chunking tries to preserve meaning while keeping each unit useful enough to stand on its own.

Chunk size and overlap are implementation details that can evolve. Users should care more about whether the retrieved passage actually supports the answer.

## Embeddings

Embeddings represent text in a form that supports semantic similarity. Starfire can use configured embedding providers to index knowledge and compare a query with stored material.

An embedding match is a relevance signal, not proof that the source is correct.

## Reranking

A first retrieval pass can return broad candidates. Reranking can reorder those candidates using a stronger relevance signal before they are inserted into model context.

## Permissions are part of retrieval

A retrieval system must not return material merely because it is semantically relevant. The requesting account, project, organization, and active policy must also be allowed to access the source.

## Inspecting retrieval

When an answer appears to ignore a known source, possible causes include:

* the source was not indexed successfully
* the query did not retrieve the right chunk
* reranking removed it
* the source is outside the active project or organization context
* permissions exclude the source
* the active model/context budget limited how much material could be injected

Authorized operators can use Knowledge diagnostics to inspect indexing and retrieval behavior.

<Note>
  RAG helps ground a model in provided material, but it does not guarantee perfect interpretation. For important claims, inspect the source text and citation relationship directly.
</Note>