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

# Knowledge (RAG)

> Knowledge bases with self-hosted embeddings and pgvector retrieval.

Knowledge bases hold documents that are chunked and embedded so agents can
retrieve grounded context.

## How it works

1. Create a **knowledge base**.
2. Add **documents** (title + text). Each document is chunked (\~1000 chars) and
   every chunk is embedded.
3. **Retrieval** runs a cosine-similarity search over the chunks with pgvector.

Embeddings are produced by a **self-hosted embedder** (`bge-small-en-v1.5`,
384-dim), so no external embeddings key is required.

## From the CLI

```bash theme={null}
cruqai knowledge create "Product docs"
cruqai knowledge add-doc "Product docs" --title "Policies" --file policies.txt
cruqai knowledge search "how long do refunds take" --k 3
```

## From an agent

Add a tool with the built-in key `knowledge_search` and reference it from an
agent node. At run time the agent calls `knowledge_search(query)`, which embeds
the query and returns the top matching chunks for the model to answer from.

## API

* `POST /v1/knowledge` - create a base
* `POST /v1/knowledge/{kb}/documents` - ingest a document
* `POST /v1/knowledge/search` - search chunks

See the [API overview](/docs/api-reference/overview).