Storage Engines and Deployment

The engine's storage layer adapts to the infrastructure you already run instead of demanding its own: the same API and the same access model ride on an embedded local store, on PostgreSQL, or on the enterprise databases your organization operates. This guide covers the engines, what each one gives up, and the mechanisms that keep the index healthy as volume grows.

1It works before you deploy anything#

A fresh installation auto-provisions a LOCAL cluster: an embedded store plus a local vector store, zero external dependencies. Every capability of the API (tenants, collections, hybrid search, grounded answers, evaluation) works against it immediately, which makes it the right place to develop, demo, and run modest corpora indefinitely. Deleting the last cluster from the Search section is remembered as a deliberate choice; the next restart does not re-provision behind the operator's back.

2The engines#

A cluster's engine is fixed at creation, and engines never mix inside a cluster; different clusters on one server can use different engines side by side.

Two practical notes: on the app-level engines (Embedded, SQL Server, MySQL) the server itself owns tenancy, the text index, metadata filtering, and embedding at ingest, so behavior stays identical across engines; and clusters are created by the operator in the admin panel, never through the public API, so topology stays an operator decision.

3When to reach for PostgreSQL#

The embedded engine is not a toy, but three needs move a deployment to PostgreSQL:

• Defense in depth. Tenant grants are enforced by row-level security inside the database as well as in the query predicate, so the boundary holds even against an application-layer defect (see the isolation menu).
• Volume. Storage is hash-partitioned, reindexes run in the background while search keeps serving, and per-tenant vector partitions keep nearest-neighbor quality stable as individual tenants grow large.
• Operational fit. Backups, replication, and monitoring ride the PostgreSQL tooling your operations team already trusts.

Moving is a provisioning exercise, not a migration feature: create the new cluster, provision tenants, and re-index from your sources (ingestion is idempotent by content hash, so re-sending a corpus is safe and only real changes cost work).

4Scaling the semantic index#

Semantic search quality depends on the health of the nearest-neighbor index, and the engine manages it actively:

• Shared pool by default. Tenants share pooled vector capacity, which is right for most of them: small tenants get big-index quality without per-tenant overhead.
• Dedicated partitions for the whales. A tenant whose vector volume crosses a threshold (250k vectors by default) is PROMOTED automatically to dedicated partitions when that move is free; operators can promote explicitly before bulk-indexing a large tenant, which is the right order. A dedicated partition keeps the tenant's graph pure (its recall does not depend on neighbors), makes wipes instant truncations instead of million-row deletions, and lets re-embeds build into an empty graph. Demotion returns the tenant to the pool, vectors preserved, no re-embedding.
• Background embedding. Ingestion never waits on inference by default: documents become full-text searchable immediately and the embedding backlog drains in the background, so write throughput is bounded by storage, not by the embedding model. Callers that need a document semantically searchable the instant the call returns opt in per request. Embedding runs on its own inference pool, so bulk indexing never competes with chat for slots (see Inference Capacity).
• Live-tunable reindexing. Rebuilds (an embedding-model change, a normalization change) run in the background with a parallelism setting read live from the admin panel, and search keeps serving on the previous state until the swap completes. Progress is visible per collection and in Jobs.

5Ingestion bounds that protect the box#

Three limits, all live-tunable from the admin panel, bound what one upload can cost: a per-page character cap for paginated documents (generous; only pathological pages hit it), a re-pagination size for single-flow documents (plain text, Markdown, HTML are split on line boundaries into indexable pages, no content lost), and a maximum page count per document, which is the denial-of-service backstop bounding the total embedding and storage work a single request can generate.

6Operating it#

The Search section drills from clusters to one cluster to one tenant: storage and document counts, embedding backlogs, health, and database recommendations where the engine can see them. GET /lmkit/v1/search/status answers availability per caller for machines, and Observability covers the request, log, and telemetry story that Search shares with the rest of the server.

7Stated plainly#

• Same API, same access model, four storage engines: the infrastructure decision never leaks into the application.
• Start on the auto-provisioned local cluster; move to PostgreSQL for row-level security, volume, or operational fit; use SQL Server or MySQL plus Qdrant where policy dictates.
• The index maintains itself in the background (embedding backlogs, reindexes, whale promotion); the admin panel shows it happening, and search keeps serving throughout.