Establish the corpus contract
Upsert stable record IDs, content, metadata, and caller-produced embeddings. The first non-empty embedding fixes the database dimension; empty or drifting vectors fail before mutation.
How it works
One corpus. Three ways to query it.
Rank a flat corpus, follow application-supplied relationships, or let relationships choose the records that retrieval ranks. Each path runs locally through its own API. For retrieval, the preview targets 1K to fewer than 50K chunks with exact search; HNSW and other ANN indexes are outside that scope.
Fast, private retrieval for edge AI
Private is a boundary, not a badge.
Privacy is a property of the whole pipeline you assemble, so the boundary is worth stating exactly instead of asserting it loudly.
After first loadA query requires no network request. Model files are fetched once, then the query path stays on the machine.
Embeddings stay yoursNo retrieval database downloads, selects, or invokes an embedding model. The embedding packages are separate and optional.
Relationships stay yoursRetrievalKit never extracts or invents a graph. Your application supplies the records and the relationships between them.
The honest limitIf your application sends text to a remote embedding service, that step is not private. RetrievalKit still indexes and searches locally.
Execution model
What happens from record to result.
Wrappers adapt language types and concurrency. The Rust core owns identity, validation, candidate selection, filtering, ranking, traces, and native persistence.
Narrow before ranking
Graph traversal and strict metadata filters choose eligible records. A graph selection is a generation-bound candidate set, never an extra score signal.
Run one exact ranker
Embedding-only queries use exact vector similarity, text-only queries use BM25, and hybrid queries fuse both with alpha. Ranking traces retain the contribution of each stage.
Publish or release state
Native saves publish checksummed snapshot generations atomically. Browser databases remain in memory inside their dedicated Worker. Every wrapper exposes an explicit close lifecycle.
Embedding generation is deliberately separate. Use a first-party local embedding package, supply vectors from your own model, or call a remote provider with the understanding that the remote step is outside the local privacy boundary.
Query paths
Retrieval, graph search, or both.
Graph search does not require vectors. Use it alone, or use graph selection as the candidate scope for the exact ranker.
Vector, BM25, hybrid
Retrieval search
Search a flat corpus with an embedding, query text, or both. Query-time alpha selects embedding-only, BM25-only, or hybrid ranking.
RetrievalDatabase
.search(text?, embedding?, alpha?)Traversal and projection
Graph search
Follow relationships, match graph fields, and project stable candidates. No retrieval configuration, vector index, or embeddings.
GraphDatabase
.graph.query(...)Relationships to ranked hits
Graph-scoped retrieval
Let the graph choose the candidate neighborhood, then run exact vector, BM25, or hybrid ranking only inside that scope.
GraphRetrievalDatabase
.graph.query(...) → .retrieval.search(within:)