> For the complete documentation index, see [llms.txt](https://docs.hexabot.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hexabot.ai/retrieval-augmented-generation/migrate-from-v3.3.x.md).

# Migrate from v3.3.x

Hexabot 3.4.x replaces the former LlamaIndex-coupled RAG implementation with a selected RAG helper. The migration path depends on whether you need lexical or semantic retrieval.

### Before upgrading

1. Back up the Hexabot database and deployment configuration.
2. Export or record the current RAG provider, model, API endpoint, dimensions, and chunk settings.
3. Identify workflows that use the old lexical/embedding `mode` setting.
4. Record a small set of queries and expected results for post-upgrade validation.
5. For PostgreSQL, define a rollback window before deleting any legacy structures.

### Option A: use built-in full-text retrieval

Choose this option when exact terms and keyword retrieval meet the use case.

1. Upgrade `@hexabot-ai/api` and the rest of the deployment to Hexabot 3.4.x.
2. Run the normal Hexabot database migration process.
3. Open **Administration → Settings → Global settings**.
4. Keep **Default RAG helper** set to `fulltext-search`.
5. Remove any workflow logic that assumes a separate lexical mode.
6. Validate the expected queries.

No vector helper or embedding credential is required.

### Option B: keep semantic vector retrieval on SQLite

1. Upgrade Hexabot to 3.4.x and run migrations.
2. Install [`hexabot-helper-sqlite-vector`](https://hexabot.ai/extensions/6a6daf6d147efb889b884892):

```bash
npm install hexabot-helper-sqlite-vector
```

3. Restart the API.
4. Create an embedding credential under **Integrations → Credentials**.
5. Configure **Administration → Settings → Vector Search (SQLite)**.
6. Select the package's `sqlite-vector` runtime name as the default RAG helper.
7. Allow reconciliation to complete and run the evaluation queries.

The 3.4 migration automatically removes obsolete LlamaIndex-era SQLite tables and triggers. Do not manually recreate or retain those triggers: they can write to removed tables and break Content updates.

### Option C: keep semantic vector retrieval on PostgreSQL

1. Ensure PostgreSQL provides the `vector` extension. For Docker Compose, a pgvector-enabled image is the simplest option:

```yaml
services:
  postgres:
    image: pgvector/pgvector:pg16
```

2. Upgrade Hexabot and run migrations.
3. Install [`hexabot-helper-pgvector`](https://hexabot.ai/extensions/6a6dafd8147efb889b884994):

```bash
npm add hexabot-helper-pgvector
```

4. Restart the API.
5. Verify or create the embedding credential and review the migrated `pgvector` settings.
6. Select the package's `pgvector` runtime name as the default helper when it is not already selected.
7. Monitor indexing and validate expected queries.

`hexabot-helper-pgvector` performs a one-time, idempotent migration of recognized legacy RAG settings when it starts. Review the resulting provider, model, credential, dimensions, and chunking values rather than assuming every former deployment used the same defaults.

### Workflow changes

#### Remove mode-based assumptions

The old `mode` setting on `retrieve_rag_content` is retained only as a hidden compatibility field. It does not select lexical or embedding retrieval. The configured default helper always handles the query.

Replace logic such as:

```
mode = lexical for one workflow
mode = embedding for another workflow
```

with one of these approaches:

* select one default helper for the deployment;
* build a custom helper that implements hybrid or routed retrieval;
* call a custom action/service directly when a workflow intentionally needs a separate retrieval backend.

#### Handle `warning`

Update workflows to inspect the `warning` output before treating empty hits as a legitimate “no match” result.

#### Recheck output assumptions

The stable output is `hits`, combined `text`, and optional `warning`. Do not rely on legacy LlamaIndex-specific response shapes.

### Database cleanup and rollback

#### SQLite

The core migration removes the obsolete LlamaIndex-era tables and triggers automatically. No manual cleanup should be necessary.

#### PostgreSQL

Legacy LlamaIndex structures are intentionally retained for rollback. Keep them until:

* the new helper is configured;
* indexing has completed;
* representative queries pass;
* create/update/deactivate/delete behavior is validated;
* the agreed rollback window has closed.

Remove legacy PostgreSQL structures only through a reviewed database change after those conditions are met.

### Post-upgrade validation checklist

* [ ] `global_settings.default_rag_helper` points to the intended helper.
* [ ] The helper is visible and compatible with the active database.
* [ ] Required embedding credentials are present.
* [ ] PostgreSQL has the `vector` extension when using `hexabot-helper-pgvector`.
* [ ] Active entries are retrieved.
* [ ] Inactive entries are excluded by default.
* [ ] Updated entries replace old content in retrieval.
* [ ] Deleted entries no longer appear.
* [ ] Content Type filters work.
* [ ] Workflows handle both `warning` and empty `hits`.
* [ ] The final model answer is grounded in retrieved text.
* [ ] API logs show no persistent indexing or provider errors.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hexabot.ai/retrieval-augmented-generation/migrate-from-v3.3.x.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.