Why this rank:Strong adoptionRelease freshnessHealthy release cadence
Description
Swift-based vector database for on-device RAG using MLTensor and MLX Embedders
README
VecturaKit
VecturaKit is a Swift-based vector database designed for on-device apps through local vector storage and retrieval.
Inspired by Dripfarm's SVDB, VecturaKit uses MLTensor and swift-embeddings for generating and managing embeddings. It features Model2Vec support with the 32M parameter model as default for fast static embeddings, and supports NomicBERT, ModernBERT, RoBERTa, and XLM-RoBERTa models.
The framework offers VecturaKit as the core vector database with pluggable embedding providers. Use SwiftEmbedder for swift-embeddings integration, OpenAICompatibleEmbedder for hosted or local /v1/embeddings providers, NLContextualEmbedder for Apple's NaturalLanguage framework with zero external dependencies, or MLXEmbedder for Apple's MLX framework acceleration (available as a separate package).
It also includes CLI tools (vectura-cli and vectura-oai-cli) for easily trying out the package.
Model2Vec Support: Uses the retrieval 32M parameter Model2Vec model as default for fast static embeddings.
NomicBERT Support: Supports Nomic embedding models such as nomic-ai/nomic-embed-text-v1.5.
ModernBERT Support: Supports ModernBERT embedding models such as nomic-ai/modernbert-embed-base.
RoBERTa/XLM-RoBERTa Support: Supports models such as FacebookAI/roberta-base and FacebookAI/xlm-roberta-base.
Auto-Dimension Detection: Automatically detects embedding dimensions from models.
On-Device Storage: Stores and manages vector embeddings locally.
Hybrid Search: Combines vector similarity with BM25 text search for relevant search results (VecturaKit).
Pluggable Search Engines: Implement custom search algorithms by conforming to the VecturaSearchEngine protocol.
Batch Processing: Indexes documents in parallel for faster data ingestion.
Persistent Storage: Automatically saves and loads document data, preserving the database state across app sessions.
Configurable Search: Customizes search behavior with adjustable thresholds, result limits, and hybrid search weights.
Custom Storage Location: Specifies a custom directory for database storage.
Custom Storage Provider: Implements custom storage backends (SQLite, Core Data, cloud storage) by conforming to the VecturaStorage protocol.
Memory Management Strategies: Choose between automatic, full-memory, or indexed modes to optimize performance for datasets ranging from thousands to millions of documents. Learn more
MLX Support: GPU-accelerated embedding generation available via the separate VecturaMLXKit package.
OpenAI-Compatible Support: Connects to OpenAI-compatible /v1/embeddings endpoints exposed by local servers and hosted providers through OpenAICompatibleEmbedder.
NaturalLanguage Support: Uses Apple's NaturalLanguage framework for contextual embeddings with zero external dependencies through NLContextualEmbedder.
CLI Tools: Includes vectura-cli and vectura-oai-cli for database management and testing.
Supported Platforms
macOS 14.0 or later
iOS 17.0 or later
tvOS 17.0 or later
visionOS 1.0 or later
watchOS 10.0 or later
Installation
Swift Package Manager handles the distribution of Swift code and comes built into the Swift compiler.
To integrate VecturaKit into your project using Swift Package Manager, add the following dependency in your Package.swift file:
Note:VecturaNLKit and VecturaOAIKit are shipped from this package. The standalone VecturaOAIKit repository is intended to be deprecated after this integration lands. For MLX-based embeddings, see VecturaMLXKit.
Quick Start
Get up and running with VecturaKit in minutes. Here is an example of adding and searching documents:
import VecturaKit
Task{do{letconfig=VecturaConfig(name:"my-db")letembedder=SwiftEmbedder(modelSource:.default)letvectorDB=tryawaitVecturaKit(config: config, embedder: embedder)
// Add documents
letids=tryawait vectorDB.addDocuments(texts:["The quick brown fox jumps over the lazy dog","Swift is a powerful programming language"])
// Search documents
letresults=tryawait vectorDB.search(query:"programming language", numResults:5)print("Found \(results.count) results!")}catch{print("Error: \(error)")}}
Usage
Import VecturaKit
import VecturaKit
Create Configuration and Initialize Database
import Foundation
import VecturaKit
letconfig=VecturaConfig(
name:"my-vector-db",
directoryURL:nil, // Optional custom storage location
dimension:nil, // Auto-detect dimension from embedder (recommended)
searchOptions:VecturaConfig.SearchOptions(
defaultNumResults:10,
minThreshold:0.7,
hybridWeight:0.5, // Balance between vector and text search
k1:1.2, // BM25 parameters
b:0.75,
bm25NormalizationFactor:10.0))
// Create an embedder (SwiftEmbedder uses swift-embeddings library)
letembedder=SwiftEmbedder(modelSource:.default)letvectorDB=tryawaitVecturaKit(config: config, embedder: embedder)
đĄ Tip: See the Indexed Storage Guide for detailed information on memory strategies and performance optimization for large-scale datasets.
đ Performance: Check out the Performance Test Results for detailed benchmarking data and recommendations. For documentation index, see Docs/.
Add Documents
Single document:
lettext="Sample text to be embedded"letdocumentId=tryawait vectorDB.addDocument(
text: text,
id:UUID() // Optional, will be generated if not provided
)
VecturaKit allows you to implement your own storage backend by conforming to the VecturaStorage protocol. This is useful for integrating with different storage systems like SQLite, Core Data, or cloud storage.
Define a custom storage provider:
import Foundation
import VecturaKit
finalclassMyCustomStorageProvider:VecturaStorage{privatevardocuments:[UUID:VecturaDocument]=[:]func createStorageDirectoryIfNeeded()asyncthrows{
// Initialize your storage system
}func loadDocuments()asyncthrows->[VecturaDocument]{
// Load documents from your storage
returnArray(documents.values)}func saveDocument(_ document:VecturaDocument)asyncthrows{
// Save document to your storage
documents[document.id]= document
}func deleteDocument(withID id:UUID)asyncthrows{
// Delete document from your storage
documents.removeValue(forKey: id)}func updateDocument(_ document:VecturaDocument)asyncthrows{
// Update document in your storage
documents[document.id]= document
}func getTotalDocumentCount()asyncthrows->Int{
// Return total count (optional - protocol provides default implementation)
return documents.count
}}
Use the custom storage provider:
letconfig=VecturaConfig(name:"my-db")letcustomStorage=MyCustomStorageProvider()letvectorDB=tryawaitVecturaKit(
config: config,
storageProvider: customStorage
)
// Use vectorDB normally - all storage operations will use your custom provider
letdocumentId=tryawait vectorDB.addDocument(text:"Sample text")
VecturaStorage also provides default getDocument(id:) and documentExists(id:)
implementations. Custom providers can override them for more efficient single-document
lookups when their backend supports it.
Custom Search Engine
VecturaKit supports custom search engine implementations by conforming to the VecturaSearchEngine protocol. This allows you to implement specialized search algorithms (pure vector, pure text, custom hybrid, or other ranking methods).
Define a custom search engine:
import Foundation
import VecturaKit
structMyCustomSearchEngine:VecturaSearchEngine{func search(
query:SearchQuery,
storage:VecturaStorage,
options:SearchOptions)asyncthrows->[VecturaSearchResult]{
// Load documents from storage
letdocuments=tryawait storage.loadDocuments()
// Implement your custom search logic
// This example does a simple exact text match
guard case .text(let queryText)= query else{return[]}letresults= documents.filter{ doc in
doc.text.lowercased().contains(queryText.lowercased())}.map{ doc inVecturaSearchResult(
id: doc.id,
text: doc.text,
score:1.0,
createdAt: doc.createdAt
)}returnArray(results.prefix(options.numResults))}func indexDocument(_ document:VecturaDocument)asyncthrows{
// Optional: Update your search engine's internal index
}func removeDocument(id:UUID)asyncthrows{
// Optional: Remove from your search engine's internal index
}}
Use the custom search engine:
letconfig=VecturaConfig(name:"my-db")letembedder=SwiftEmbedder(modelSource:.default)letcustomEngine=MyCustomSearchEngine()letvectorDB=tryawaitVecturaKit(
config: config,
embedder: embedder,
searchEngine: customEngine
)
// All searches will use your custom search engine
letresults=tryawait vectorDB.search(query:"search query")
MLX Integration
For GPU-accelerated embeddings using Apple's MLX framework, see the separate VecturaMLXKit package. It provides MLXEmbedder, a drop-in VecturaEmbedder implementation, plus the vectura-mlx-cli command-line tool.
// Add both packages to your dependencies:
.package(url:"https://github.com/rryam/VecturaKit.git", from:"3.0.0"),.package(url:"https://github.com/rryam/VecturaMLXKit.git", from:"1.0.0"),
OpenAI-Compatible Integration
VecturaKit supports OpenAI-compatible embedding APIs through OpenAICompatibleEmbedder. This is useful for local servers such as Ollama, LM Studio, llama.cpp-compatible servers, vLLM, and hosted providers that expose /v1/embeddings.
Import OpenAI-Compatible Support
import VecturaKit
import VecturaOAIKit
Initialize Database with OpenAI-Compatible Embeddings
// Initialize with specific language
letembedder=tryawaitNLContextualEmbedder(
language:.spanish
)
// Get model information
letmodelInfo=await embedder.modelInfo
print("Language: \(modelInfo.language)")iflet dimension = modelInfo.dimension {print("Dimension: \(dimension)")}else{print("Dimension: Not yet determined")}
Add Documents
lettexts=["Natural language understanding is fascinating","Swift makes iOS development enjoyable","Machine learning on device preserves privacy"]letdocumentIds=tryawait vectorDB.addDocuments(texts: texts)
## What's Changed * Restore the NaturalLanguage-backed vectura-cli and TestExamples executable. * Add CLI README coverage and Codemagic smoke validation. * Add NLContextualEmbedder adapter coverage for vector queries. * Count file-backed documents from disk so partially loaded caches do not report stale totals. **Full Changelog**: https://github.com/rryam/VecturaKit/compare/6.0.0...6.1.0
High
4/30/2026
6.0.0
## What's Changed * [codex] Remove swift-embeddings backend from core by @rudrankriyam in https://github.com/rryam/VecturaKit/pull/83 **Full Changelog**: https://github.com/rryam/VecturaKit/compare/5.3.0...6.0.0
High
4/29/2026
5.3.0
## What's Changed * Add VecturaOAIKit as a package target by @subsriram in https://github.com/rryam/VecturaKit/pull/81 **Full Changelog**: https://github.com/rryam/VecturaKit/compare/5.2.1...5.3.0
High
4/4/2026
5.2.1
## What's Changed * [codex] Pin swift-embeddings to stable 0.0.26 by @rudrankriyam in https://github.com/rryam/VecturaKit/pull/80 **Full Changelog**: https://github.com/rryam/VecturaKit/compare/5.2.0...5.2.1
Medium
4/2/2026
5.2.0
## What's Changed * Add getDocument, documentExists API and fix delete no-op bug by @thatswiftguy in https://github.com/rryam/VecturaKit/pull/77 ## New Contributors * @thatswiftguy made their first contribution in https://github.com/rryam/VecturaKit/pull/77 **Full Changelog**: https://github.com/rryam/VecturaKit/compare/5.1.0...5.2.0
Low
3/15/2026
5.1.0
## What's Changed * Improve storage and BM25 search performance by @rudrankriyam in https://github.com/rryam/VecturaKit/pull/74 * Use bounded top-K selection to avoid full result sorting by @rudrankriyam in https://github.com/rryam/VecturaKit/pull/75 * Add realistic workload benchmark profile and optional CI stage by @rudrankriyam in https://github.com/rryam/VecturaKit/pull/76 **Full Changelog**: https://github.com/rryam/VecturaKit/compare/5.0.0...5.1.0
Low
3/5/2026
5.0.0
## Highlights - Add core SwiftEmbedder model-family resolution refactor and static embedding dimension handling improvements. - Add ModernBERT support in SwiftEmbedder. - Add RoBERTa and XLM-RoBERTa support in SwiftEmbedder. - Add embedder validation and BERT fallback robustness fixes. - Align package platform minimums with runtime requirements and clean up redundant availability guardrails. ## Included pull requests - #69 Refactor SwiftEmbedder core model resolution - #70 Add ModernBE
Low
2/12/2026
4.0.0
## Breaking Changes - **VecturaMLXKit extracted to separate repository:** `VecturaMLXKit`, `VecturaMLXCLI`, and MLX-related tests have been moved to [rryam/VecturaMLXKit](https://github.com/rryam/VecturaMLXKit). This removes the need for Package Traits (SE-0450). - **Package Traits removed:** The `MLX` trait no longer exists. MLX users should add `VecturaMLXKit` as a separate dependency. - **swift-tools-version reverted to 6.0:** Swift 6.1 is no longer required for this package. - **mlx-swift-l
Low
2/5/2026
3.0.0
## Highlights - **Package Traits (SE-0450)**: MLX dependencies are now optional. Consumers using only `VecturaKit` or `VecturaNLKit` no longer download the heavy `mlx-swift-lm` package, significantly improving build times. - **Swift 6.1+ Required**: Bumped `swift-tools-version` to 6.1 for Package Traits support. - **Smaller Default Model**: Switched from `potion-retrieval-32M` to `potion-base-4M` for faster downloads and CI. ## Breaking Changes - **Swift 6.1+ / Xcode 16.3+ required** - **MLX
Low
1/29/2026
2.5.3
## Highlights - Hardened add/index rollback to restore overwritten documents and keep storage/search consistent. - Stricter config/input validation (DB name, search options, embedder inputs); BM25 handles empty queries safely. - Performance suites now default to a deterministic embedder for faster runs (opt-in real embeddings via `VECTURA_PERF_USE_SWIFT_EMBEDDER=1`). - Updated MLX dependencies to latest mlx-swift-lm (2.30.3 / mlx-swift 0.30.3). - CLI vector dimension is auto-detected by default;
Low
1/26/2026
v2.5.2
- Fix SwiftLint trailing whitespace failures in MLXEmbedder.\n- Update the README installation snippet to 2.5.2.
Low
1/16/2026
v2.5.1
Release 2.5.1: Throttled concurrency for file operations Fixes potential file descriptor exhaustion and memory pressure when working with large document collections. Changes: - Add ConcurrencyExtensions.swift with concurrentMap, concurrentForEach, orderedConcurrentMap, and chunked utilities - Replace unbounded parallel file loading in FileStorageProvider with throttled concurrentMap (max 50 concurrent operations) - Add saveDocuments batch method to VecturaStorage protocol - Implement saveDocum
Low
12/8/2025
v2.5.0
Release 2.5.0: NaturalLanguage framework support via VecturaNLKit Adds support for Apple's NaturalLanguage framework through a new VecturaNLKit module, providing contextual sentence embeddings with zero external dependencies.
Low
11/11/2025
v2.4.0
Release 2.4.0: Package dependency updates and StaticEmbeddings model support
## Overview This release introduces a major architectural refactoring with pluggable search engines, memory management strategies for large datasets, and significant performance optimizations. VecturaKit now supports three distinct search engines (vector, BM25, hybrid) with intelligent memory strategies that can handle datasets from small to very large scale. ## New Features ### Pluggable Search Engine Architecture - Introduced `VecturaSearchEngine` protocol as a unified interface for search
Low
11/4/2025
2.2.0
## Overview This release introduces a complete architectural overhaul with protocol-based embedding providers, Swift 6 actor concurrency model, and improved performance. This is a major version release with breaking changes that require code migration. ## New Features ### Protocol-Based Embedding Architecture - Introduced `VecturaEmbedder` protocol as a unified interface for embedding providers - Enables dependency injection and custom embedder implementations - Eliminates code duplication be
## Highlights - migrate VecturaKit and VecturaMLXKit test suites to the Swift Testing framework for better isolation - add SwiftLint configuration and enforce linting via repository guidelines - refresh contribution guidance in AGENTS.md to reflect the new testing workflow ## Verification - swift test - swiftlint
Low
10/11/2025
v1.0.1
# New in this release - Fix SwiftPM dependency conflicts by updating swift-embeddings to 0.0.21 (swift-transformers 1.0.0) - Refresh Package.resolved pins, including swift-jinja and latest mlx-swift-examples main
Low
10/10/2025
v1.0.0
First stable release with Model2Vec support using 32M parameter model and automatic dimension detection
Low
9/23/2025
v0.4.1
# New in this release Update version of Swift Argument Parser
Low
4/5/2025
v0.4.0
## What's Changed * Better performance using Accelerate by @rudrankriyam in https://github.com/rryam/VecturaKit/pull/9 **Full Changelog**: https://github.com/rryam/VecturaKit/compare/v0.3.1...v0.4.0
Low
2/1/2025
v0.3.1
# Version 0.3.1 ## What's Changed - Add vectura-mlx-cli target to play around in Xcode
Low
1/29/2025
v0.3.0
Version 0.3.0 ## What's Changed - Add VecturaMLXKit with MLXEmbedders
Low
1/29/2025
v0.2.1
# Version 0.2.1 Some more improvements that I forgot to merge, thanks to @insidegui!
Low
1/28/2025
v0.2.0
# Version 0.2.0 Some more changes + improvements from @insidegui. đ
Low
1/28/2025
v0.1.0
# Version 0.1.0 Initial release. Enjoy!
Low
1/18/2025
Dependencies & License Audit
Loading dependencies...
Similar Packages
mem9Enable AI agents to retain memory across sessions using persistent storage designed for continuous context retention.main@2026-06-05
rag-chatbotRAG (Retrieval-augmented generation) ChatBot that provides answers based on contextual information extracted from a collection of Markdown files.main@2026-06-04
HelixTransform Claude into a local AI assistant for Mac that controls apps, manages tasks, and remembers context across sessions.main@2026-06-04
bigragSelf-hostable RAG platform - document ingestion, embedding, and vector search behind a simple REST APImain@2026-06-03
consolidation-memoryStore, consolidate, and recall coding agent memories with provenance tracking using SQLite and FAISS for fast, structured knowledge access.main@2026-06-03
More in Databases
milvusMilvus is a high-performance, cloud-native vector database built for scalable vector ANN search
WeKnoraLLM-powered framework for deep document understanding, semantic retrieval, and context-aware answers using RAG paradigm.
ai-real-estate-assistantAdvanced AI Real Estate Assistant using RAG, LLMs, and Python. Features market analysis, property valuation, and intelligent search.