Hexabot sqlite-vector Helper

hexabot-helper-sqlite-vector adds semantic Retrieval-Augmented Generation (RAG) to Hexabot v3, backed by embeddings stored in the application's own SQLite database via the sqlite-vec extension. The helper is installed as a standard npm package and is discovered by the API automatically.

This is an optional extension. Install it only when you run Hexabot on SQLite and want embedding-based semantic retrieval. Without it, Hexabot falls back to the built-in lexical fulltext-search helper.

It is the SQLite counterpart of the built-in pgvector helper: the two cover different databases, so exactly one of them is ever available on a given deployment.

Installation

Install the package in the same workspace or deployment that runs @hexabot-ai/api:

npm install hexabot-helper-sqlite-vector

Restart the API after installation. The helper is picked up by the dynamic-provider loader (node_modules/hexabot-helper-*/**/*.helper.js) and appears with the name sqlite-vector, exposing a sqlite-vector settings group. No manual registration is required.

Prerequisites

Before configuring the helper, make sure you have:

• a Hexabot deployment running @hexabot-ai/api v3.4.0 or later;
• a SQLite database (the better-sqlite3 TypeORM driver). The helper is a no-op on PostgreSQL — isAvailable() returns false;
• an embedding provider reachable from the API (OpenAI or any OpenAI-compatible endpoint), and a Hexabot credential holding its API key.

What It Does

• Creates and self-heals its own schema on SQLite — rag_sqlite_vector_documents and rag_sqlite_vector_chunks. See src/sqlite-vector.provisioning.ts. Provisioning happens lazily at runtime, applied idempotently the first time the helper is used, so no core database migration is needed.
• Loads sqlite-vec into the connection TypeORM already owns, persists chunk vectors as vec_f32 BLOBs, and runs retrieval as an exact cosine search — content lifecycle hooks update the index directly, with no background queue or worker involved.
• index.helper.ts extends BaseRagEmbeddingHelper from @hexabot-ai/api, which carries the chunking, provider resolution, embedding, and profile hash shared with pgvector. A profile hash over the provider, model, dimensions and chunking settings keys every stored vector, so a configuration change rebuilds the corpus under a new profile.

Configuration

Configure the helper from the Hexabot admin UI under the sqlite-vector settings group:

• embedding provider, model, credential, base URL and dimensions;
• the chunking parameters used when indexing content.

Select it as the active RAG helper by setting global_settings:default_rag_helper to sqlite-vector.

Development

npm install
npm run lint         # eslint
npm run typecheck    # tsc --noEmit
npm test             # unit tests
npm run build        # tsc -> dist/

sqlite-vec ships as a native binary loaded into an in-process better-sqlite3 connection, so the integration suite in src/sqlite-vector.integration.spec.ts runs against a throwaway SQLite file with no external service to start — just npm test.

Release

Publishing is handled by the Publish NPM Package GitHub Actions workflow, which runs on pushes to main and on v* tags. It publishes only when the version in package.json is not already on npm, tagging pre-release versions as next and everything else as latest. The workflow needs an NPM_TOKEN repository secret.

To cut a release:

npm run release:patch   # or release:minor