API and lifecycle reference

Choose one owner for each operation.

RetrievalKit wrappers adapt language types and concurrency while the Rust core owns validation, filtering, ranking, graph traversal, and native snapshots. Use this reference to select a database, manage its lifetime, and understand what can survive an upgrade.

Public API families

Choose the API that owns the query.

Graph is an independent query path. It can return relationships directly or define the candidate set for retrieval.

RetrievalDatabaseBuild a flat local corpus and run exact vector, BM25, or query-time hybrid ranking. Text, an embedding, or both select the query form.

GraphDatabaseTraverse application-supplied relationships and return stable records without a vector index, embedding dimension, or embedding model.

GraphRetrievalDatabaseUse graph traversal to choose an eligible candidate set, then run the same exact vector, BM25, or hybrid ranker only inside that scope.

Embedding packagesProvide an optional local embedding implementation independently from retrieval. A retrieval database never downloads, selects, or invokes a model by itself.

Lifecycle reference

Build, query, and close without crossing ownership boundaries.

The same lifecycle applies across wrappers even where method names, async behavior, and native language types differ.

Select

Load one native retrieval aggregate

Python, Node.js, and Kotlin processes choose either the base or graph-capable retrieval package; the graph package already includes base retrieval. Swift exposes selectable products over one graph-capable binary. The browser retrieval Worker includes all three query paths.

Build

Let the first embedding establish dimension

The first non-empty document embedding fixes the database dimension in Rust. Later document and query embeddings must match it; callers do not maintain a separate dimension setting.

Query

Keep constraints separate from ranking

Metadata filters and graph selections determine eligibility. Text, embeddings, and query-time alpha determine BM25, vector, or hybrid ranking inside the eligible set.

Release

Close every native or Worker-owned handle

Each wrapper exposes explicit cleanup. Close selections before databases and databases before their owning client or kit; do not submit new operations after close begins.

Persistence and upgrades

Know what survives an upgrade.

The published preview has an explicit compatibility policy. It does not promise that every 0.x source API stays frozen.

Read the v0.1.0 compatibility policy → Open the v0.1.0 migration record →

Preview source compatibilityRetrievalKit 0.x releases may refine APIs. Intentional source or persistence changes require a changelog entry and migration guidance.

Native persistenceBase snapshot formats V1 through V4 remain readable and new saves use checksummed V4. Validate or back up data before migration and never edit snapshot files directly.

Graph persistenceGraph capability formats are versioned and validated independently from the embedded base snapshot.

Browser persistenceThe v0.1.0 browser database is Worker-owned and in memory. Rebuild it after a Worker or page lifecycle ends; filesystem snapshots are not claimed.