Migrate from v3.3.x

Upgrade a legacy LlamaIndex-based Hexabot RAG setup to the helper-based architecture in Hexabot 3.4.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:

npm install hexabot-helper-sqlite-vector

1. Restart the API.

2. Create an embedding credential under Integrations → Credentials.

3. Configure Administration → Settings → Vector Search (SQLite).

4. Select the package's sqlite-vector runtime name as the default RAG helper.

5. 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:

services:
  postgres:
    image: pgvector/pgvector:pg16

1. Upgrade Hexabot and run migrations.

2. Install hexabot-helper-pgvector:

npm add hexabot-helper-pgvector

1. Restart the API.

2. Verify or create the embedding credential and review the migrated pgvector settings.

3. Select the package's pgvector runtime name as the default helper when it is not already selected.

4. 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.