# VecturaKit: a Swift vector database for on-device RAG

> VecturaKit stores embeddings locally in a Swift package and pairs vector similarity with BM25 text search. It fits Apple-platform apps that need retrieval without a server, and it is the wrong choice for teams that want a managed cluster.

**rryam/VecturaKit** — Swift-based vector database for on-device RAG using MLTensor and MLX Embedders

- Repository: https://github.com/rryam/VecturaKit
- Stars: 323 · Forks: 30
- Language: Swift
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/rryam-vecturakit

## What VecturaKit actually solves for Swift apps

Retrieval augmented generation normally assumes a server. You embed documents, push the vectors into a hosted index, and query it over the network. That arrangement breaks the moment the app has to work offline, or when the text being indexed is private enough that shipping it to a third party is not acceptable. VecturaKit takes the opposite position: the vector database lives inside the app process, on the device, and the README describes it as a Swift-based vector database for on-device apps through local vector storage and retrieval.

The project is explicit about its lineage. It says it was inspired by Dripfarm's SVDB, and it keeps the same shape: a core `VecturaKit` type, pluggable embedding providers, and a storage layer you can replace. The intended audience is Apple-platform developers. The supported platforms are macOS 15.0, iOS 18.0, tvOS 18.0, visionOS 2.0 and watchOS 11.0, which is a narrow band of recent OS releases rather than a broad compatibility story. If your app still ships to older systems, this package is not available to you.

Four embedder options are documented. `OpenAICompatibleEmbedder` talks to any `/v1/embeddings` endpoint, hosted or local. `NLContextualEmbedder` wraps Apple's NaturalLanguage framework and pulls in no external dependencies. `SwiftEmbedder` comes from the separate VecturaEmbeddingsKit package and covers models such as Model2Vec, StaticEmbeddings, NomicBERT, ModernBERT, RoBERTa, XLM-RoBERTa and BERT. `MLXEmbedder` comes from VecturaMLXKit and uses Apple's MLX framework for accelerated embedding generation. That spread matters because it lets the same database code run with a fully local embedder on a phone and a hosted embedder during development.

## How storage, embedding and hybrid search fit together

The architecture is a small set of protocols with default implementations. `VecturaEmbedder` is the embedding contract; anything that produces vectors conforms to it. `VecturaStorage` is the persistence contract, and the README names SQLite, Core Data and cloud storage as examples of backends a developer could implement against it. `VecturaSearchEngine` is the retrieval contract, so a custom ranking algorithm replaces the built-in one rather than sitting beside it.

The default retrieval path is hybrid. The README states that `VecturaKit` combines vector similarity with BM25 text search, and that the mix is configurable through hybrid search weights alongside adjustable thresholds and result limits. That is a meaningful design choice: pure vector search tends to miss exact tokens such as product codes or names, and BM25 catches them, so the two are blended instead of choosing one. Dimension detection is automatic, taken from the configured embedder, so you do not declare the vector width yourself.

Ingestion is batched. The feature list says documents are indexed in parallel for faster data ingestion, and that data is saved and loaded automatically so the database survives app restarts. Storage location is configurable. For larger corpora there are memory management strategies: automatic, full-memory and indexed modes, documented in Docs/INDEXED_STORAGE_GUIDE.md, which the README frames as spanning thousands to millions of documents. That guide is where the real trade-off lives, and the README does not reproduce it.

## Installing VecturaKit with Swift Package Manager

Distribution is through Swift Package Manager, which ships with the Swift compiler. Add the dependency to your Package.swift, pinning to 6.3.0 or later as the README shows. The current release line is 6.3.0, published on 2026-08-05, after 6.2.0 in July and 6.1.0 in April.

```swift
dependencies: [
    .package(url: "https://github.com/rryam/VecturaKit.git", from: "6.3.0"),
],
```

Then declare which products your target uses. VecturaKit, VecturaOAIKit and VecturaNLKit are all products of this one package, so you take only what you need.

```swift
target(
    name: "MyApp",
    dependencies: [
        .product(name: "VecturaKit", package: "VecturaKit"),
        .product(name: "VecturaOAIKit", package: "VecturaKit"),
        .product(name: "VecturaNLKit", package: "VecturaKit"),
    ]
)
```

MLX acceleration and the swift-embeddings models live in separate packages, not in this one. The README instructs adding VecturaMLXKit from 3.0.2 for MLX, and VecturaEmbeddingsKit from 1.1.0 for swift-embeddings model support. If you want the zero-dependency route, skip both and use `NLContextualEmbedder` from VecturaNLKit.

For a first run without writing an app, the package ships two command line tools. `vectura-cli` is described as the NaturalLanguage-backed tool for local workflows, and `vectura-oai-cli` for trying OpenAI-compatible embedding providers. That is the cheapest way to confirm that embeddings are produced and that search returns sensible neighbours before you wire the library into a UI.

## Where VecturaKit stops being the right tool

The constraint is the process boundary. VecturaKit is a library, so the index lives in the app: there is no server to query from another machine, no connection string, and no query language. If two clients need to share one index, or if a backend service needs to read the same vectors, this design does not give you a path. You would be building the sharing layer yourself on top of a `VecturaStorage` implementation.

Platform floors are the second limit. macOS 15.0, iOS 18.0, tvOS 18.0, visionOS 2.0 and watchOS 11.0 are recent releases, so an app supporting older OS versions cannot adopt the package at all. Watch is listed, but the README does not say anything about how the indexed storage mode behaves under a watchOS memory budget; that is a question the repository does not answer.

Scale is the third. The README points to Docs/INDEXED_STORAGE_GUIDE.md for datasets from thousands to millions of documents, which implies that the default full-memory mode is not meant for the large end. Choosing the indexed mode is therefore a decision you make early, and the README itself does not spell out the cost of getting it wrong. There is also no documented rollback behaviour: the README describes automatic saving and loading of document data, but not what happens if a write is interrupted mid-batch. Treat that as unverified rather than safe.

## How VecturaKit differs from a server-side vector database

The obvious alternative for a Swift app is to run a vector database as a service and call it over HTTP. Those systems are built for multi-tenant workloads: they expose a network API, they handle replication and sharding, and the index outlives any single client. VecturaKit inverts every one of those properties. Retrieval happens in-process, latency is local, and the index dies with the app installation unless you back it up.

There is also a closer comparison inside the project's own history. VecturaKit says it was inspired by Dripfarm's SVDB, so the two share the local-first premise: a Swift vector store with pluggable embeddings. The difference visible in the README is breadth. VecturaKit documents hybrid search combining vector similarity with BM25, three memory management modes, a custom storage protocol, a custom search engine protocol, two CLI tools, and separate companion packages for MLX and swift-embeddings models. If you only need nearest-neighbour lookup over a small local set, that extra surface is weight you are not using.

A third option is to skip a vector database and score embeddings in memory with Accelerate or plain Swift. That works for a few thousand short documents and removes a dependency entirely. VecturaKit's case is the moment persistence, batching and hybrid ranking stop being things you want to write yourself.

## Maintenance, releases and the MIT licence

The repository is not archived and the last push was on 2026-08-31, which is recent enough that the project is being worked on. The release cadence visible in the tags is roughly monthly to bi-monthly: 6.1.0 on 2026-04-30, 6.2.0 on 2026-07-02 and 6.3.0 on 2026-08-05. The version numbers are pre-1.0 in spirit but not in practice, since the major version is already 6, which signals that breaking changes are expected between majors rather than treated as exceptional.

The upgrade cost is concentrated in two places. First, the companion packages version independently: VecturaMLXKit is at 3.0.2 and VecturaEmbeddingsKit at 1.1.0, so an MLX or swift-embeddings setup means tracking three version lines instead of one. Second, anything you build against `VecturaStorage` or `VecturaSearchEngine` is your own code sitting on a protocol the package owns; a change to that protocol lands on you, not on the maintainer.

The licence is MIT, which permits commercial and closed-source use and requires preserving the copyright notice and permission notice. That is a permissive arrangement with few obligations, but it also means no warranty and no support commitment from the author. This is a description of the licence text, not legal advice; if your organisation has a policy on third-party dependencies, run it through that process.

## Conclusion

Adopt VecturaKit when the app runs on Apple platforms, the corpus is bounded, and retrieval must work without a server: the Swift Package Manager dependency plus a VecturaEmbedder conformance is the whole setup. Do not adopt it if you need a network-accessible index, a query language, or a database your backend team can operate separately, because VecturaKit is a library inside your process. Verify first that your deployment targets meet macOS 15.0, iOS 18.0, tvOS 18.0, visionOS 2.0 or watchOS 11.0, and check the Docs/INDEXED_STORAGE_GUIDE.md memory modes against the size of your corpus before you commit to a storage strategy.

## FAQ

### What is VecturaKit?

It is a Swift-based vector database for on-device apps, providing local vector storage, indexing and hybrid search with pluggable embedding providers. It ships as a Swift package with a core VecturaKit type, a CLI tool and optional companion packages.

### How do I install VecturaKit in a Swift project?

Add the package to your Package.swift with .package(url: "https://github.com/rryam/VecturaKit.git", from: "6.3.0") and then list the products you need, such as VecturaKit, VecturaOAIKit or VecturaNLKit, in your target's dependencies.

### Which platforms does VecturaKit support?

The README lists macOS 15.0 or later, iOS 18.0 or later, tvOS 18.0 or later, visionOS 2.0 or later and watchOS 11.0 or later. Older OS versions are not covered.

### Does VecturaKit need a server to store vectors?

No. The README describes on-device storage that saves and loads document data automatically across app sessions, with a configurable storage location and a VecturaStorage protocol for custom backends. There is no network API for other processes to query.

### What embedding providers can VecturaKit use?

Four are documented: OpenAICompatibleEmbedder for any /v1/embeddings endpoint, NLContextualEmbedder for Apple's NaturalLanguage framework, SwiftEmbedder via the separate VecturaEmbeddingsKit package, and MLXEmbedder via VecturaMLXKit.

## Sources

- [Issues](https://github.com/rryam/VecturaKit/issues)
- [License: MIT](https://github.com/rryam/VecturaKit/blob/main/LICENSE)
- [README](https://github.com/rryam/VecturaKit/blob/main/README.md)
- [Releases](https://github.com/rryam/VecturaKit/releases)
- [rryam/VecturaKit on GitHub](https://github.com/rryam/VecturaKit)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rryam-vecturakit