Retrieval-Augmented Generation

Ground Hexabot AI workflows in CMS content with a built-in, vector, or custom retrieval helper.

Retrieval-Augmented Generation, or RAG, lets an AI workflow retrieve relevant information before it generates an answer. In Hexabot, the source information normally comes from Content entries managed in the administration interface.

Starting with Hexabot 3.4.x, RAG is helper-based. Hexabot no longer imposes one indexing framework or one retrieval strategy. You can use:

• fulltext-search, the built-in lexical helper for SQLite and PostgreSQL;

• hexabot-helper-sqlite-vector, the installable semantic-search helper based on sqlite-vec;

• hexabot-helper-pgvector, the installable semantic-search helper for PostgreSQL;

• a custom helper backed by Weaviate, Pinecone, Elasticsearch, a graph-retrieval pipeline, a hybrid ranker, or another system.

The npm package names identify the installable extensions. After installation, select their runtime helper names—sqlite-vector or pgvector—under Default RAG helper.

A RAG helper performs retrieval. It does not automatically ground every LLM call. Your workflow must pass the retrieved text to an AI generation action, or mount retrieve_rag_content as a tool on an AI Agent.

How RAG works in Hexabot

1. You create structured entries under Content.

2. Hexabot builds canonical search text from each entry's title and string-valued properties.

3. The helper selected in global_settings.default_rag_helper retrieves the most relevant entries or chunks.

4. The retrieve_rag_content action returns ranked hits and a combined text value.

5. An AI action or AI Agent uses that context to produce the final response.

Core concepts

Concept	Meaning
Content corpus	The Content entries that provide source material for retrieval.
Canonical search text	A text representation containing the entry title and its string-valued properties.
RAG helper	The strategy used to retrieve relevant content. One helper is selected as the default.
Retrieval action	retrieve_rag_content, which calls the selected helper from a workflow or as an agent tool.
Generator	The AI action or AI Agent that turns the question and retrieved context into a response.
Reindex	A reconciliation operation that rebuilds or refreshes a helper's retrieval structures.

What changed in Hexabot 3.4.x

The former RAG implementation was coupled to LlamaIndex and maintained separate lexical and embedding indexes. Hexabot 3.4.x replaces it with a smaller core contract and installable helpers.

The practical changes are:

• There is no RAG enable/disable switch. Retrieval is available through the selected helper.

• fulltext-search is built in and selected by default.

• Vector retrieval is optional and installed per database.

• The helper, not a per-action “mode,” determines how retrieval works.

• Configuration and availability failures are exposed by retrieve_rag_content through its warning output.

• Custom helpers can own their settings, storage, indexing, and ranking strategy.

What Hexabot retrieves

The default corpus is the CMS Content table. For each entry, Hexabot includes:

• the entry title;

• properties whose stored value is a string, typically Text and Text Area fields.

Numbers, booleans, relation objects, and media objects are not converted to descriptive text automatically.

Uploading a PDF, image, or other file to the Media Library does not automatically parse it into RAG content. Extract the text into Content entries or implement an ingestion/custom-helper pipeline for document retrieval.

Start here

• Follow Quickstart: build a grounded answer workflow to use the built-in helper without an embedding provider.

• Read Choose a retrieval helper to decide between lexical, vector, hybrid, and external retrieval.

• Use Tune and troubleshoot retrieval when results are missing or irrelevant.

• Existing deployments should read Migrate from v3.3.x.