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

# Knowledge Bases

> Ground your agents in your own documents with retrieval-augmented generation

Knowledge bases let you ground an agent in your own documents. Documents are chunked, embedded, and stored in a vector index; at call time the most relevant chunks are retrieved and injected into the prompt so the agent answers from your content rather than its training data.

## Creating a knowledge base

1. Open **Agent Framework → Knowledge Bases**.
2. Click **Create Knowledge Base**.
3. Fill in the form and click **Create**.

### Fields

| Field                    | Description                                                                                                                                                                                                                                                             |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                 | Required. Human-readable identifier shown in the UI and used when attaching to an agent.                                                                                                                                                                                |
| **Description**          | Optional. Surfaced alongside the name in lists and selectors.                                                                                                                                                                                                           |
| **Storage Type**         | Where the raw document bytes live. **Local Storage** keeps them on the server's disk; **Amazon S3** offloads them to an S3 bucket.                                                                                                                                      |
| **Chunking Strategy**    | How the document is split into chunks before embedding. **Fixed** is the default — fixed-size windows with overlap.                                                                                                                                                     |
| **Chunk Size**           | Target characters per chunk. Default **1000**. Larger chunks preserve more context per match; smaller chunks improve retrieval precision.                                                                                                                               |
| **Chunk Overlap**        | Characters shared between adjacent chunks so a relevant span doesn't fall on a boundary. Default **200**.                                                                                                                                                               |
| **Mandatory Separators** | Optional list of strings the chunker must split on (one per row). Useful for respecting Markdown headings (`\n##`), paragraph breaks (`\n\n`), or other structural markers. Use `\n` for newline and `\t` for tab. Comma and newline can be used as literal separators. |
| **Embedding Provider**   | LLM provider used to compute embeddings. Supported: Anthropic, ElevenLabs, Gemini, Ollama, OpenAI, OpenRouter, xAI, Bedrock.                                                                                                                                            |
| **Embedding Model**      | The specific embedding model for the chosen provider (e.g. `text-embedding-3-small`).                                                                                                                                                                                   |
| **Embedding Dimension**  | Vector dimension of the embedding. Default **1536** (matches OpenAI's `text-embedding-3-small`). Must match the dimension produced by the selected model.                                                                                                               |

## Adding documents

After creating the knowledge base, open it from the list. The detail view lets you upload documents that will be chunked and embedded according to the configuration above. Subsequent uploads use the same chunking and embedding settings, so all chunks in one knowledge base share the same vector dimension and chunking strategy.

## Attaching to an agent

1. Open your agent in the **Agent Builder**.
2. Go to the **Knowledge Bases** tab.
3. Select one or more knowledge bases to attach.
4. Save the agent.

A knowledge base can be attached to multiple agents — you don't need to duplicate documents per agent.

## How retrieval works at runtime

When the agent runs:

1. The user message (and, optionally, recent conversation context) is embedded with the same model used to ingest the knowledge base.
2. The vector index returns the top-K most similar chunks across all attached knowledge bases.
3. Those chunks are injected into the agent's prompt with their source metadata.
4. The agent responds, and the retrieval step appears as a span in the [trace](/docs/gateway/llm/tracing) — including which chunks were retrieved, their similarity scores, and the source document — so you can audit how every answer was grounded.

## Tuning

| Symptom                                               | Try                                                                                                                            |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Answers feel "lost in the doc" / missing context      | Increase **Chunk Size** (e.g. 1500–2000) or **Chunk Overlap** (e.g. 300–400).                                                  |
| Irrelevant chunks crowd the prompt                    | Decrease **Chunk Size**, or add **Mandatory Separators** that respect document structure (e.g. `\n##` for Markdown headings).  |
| Multilingual or domain-specific content underperforms | Pick an embedding model tuned for that language or domain; create a separate knowledge base if it needs a different dimension. |

## Relation to other features

* [Skills](/docs/gateway/agent-builder/skills) — skills are agent-mounted instruction bundles read on demand; knowledge bases are document corpora retrieved by semantic similarity. Use skills for "how to do X"; use knowledge bases for "what does our doc say about Y."
* [Memories](/docs/gateway/agent-builder/memories) — memories are durable per-user facts extracted from conversations. Knowledge bases are shared document corpora retrieved by semantic similarity. Use memories for "what do I know about *this* user"; use knowledge bases for "what does our doc say about Y."