VelesDB Mobile Deployment: A Complete Guide to iOS and Android Integration

Yes, VelesDB can be deployed on both iOS and Android devices through the velesdb-mobile crate, which compiles the Rust core engine into native libraries with UniFFI-generated Swift and Kotlin bindings.

The cyberlife-coder/velesdb repository ships a dedicated mobile crate that packages the same high-performance vector, graph, and column-store logic used in server deployments into a 15 MB binary (or under 5 MB with compression) capable of running fully offline on mobile hardware.

Architecture of VelesDB Mobile Deployment

The mobile deployment strategy centers on exposing the existing velesdb-core Rust engine through a Foreign Function Interface (FFI) layer, eliminating code duplication while providing idiomatic APIs for each platform.

Core Engine Reuse via UniFFI

In crates/velesdb-mobile/src/lib.rs, the VelesDatabase and VelesCollection structs wrap the core engine using UniFFI to generate type-safe bindings. This approach exposes mobile-specific methods including open, createCollectionWithStorage, upsert, search, and multiQuerySearch directly to Swift and Kotlin without manual JNI or Objective-C bridging code.

The crate compiles to a static library (.a) for iOS and a shared library (.so) for Android, linking against the same SIMD-optimized kernels found in crates/velesdb-core/src/simd_native. When built for aarch64 targets, the mobile library automatically enables ARM NEON instructions for vectorized operations.

Thread Safety and Memory Management

Both VelesDatabase and VelesCollection are wrapped in Arc (atomic reference counting) within the Rust implementation at crates/velesdb-mobile/src/lib.rs#L71-L86. This design allows safe concurrent access from UI threads and background workers on mobile platforms, with the Rust borrow checker enforcing memory safety across the FFI boundary.

Storage Modes for Constrained Devices

The StorageMode enum defined in crates/velesdb-mobile/src/types.rs provides three quantization levels to balance accuracy against memory constraints:

• Full: No compression, maximum recall
• SQ8: 4× compression with approximately 1% recall loss (recommended for mobile)
• Binary: 32× compression for extreme memory constraints

Building VelesDB for iOS

The iOS build targets aarch64-apple-ios for physical devices and aarch64-apple-ios-sim for the simulator. The output is packaged as an .xcframework containing the static library and Swift module map.

Swift Integration Example

After importing the generated Swift bindings into your Xcode project, initialize the database in your app's Documents directory:

import VelesDB

// Open database in app container
let db = try VelesDatabase.open(path: documentsPath + "/velesdb")

// Create collection with SQ8 compression for 4× memory reduction
try db.createCollectionWithStorage(
    name: "embeddings",
    dimension: 384,            // e.g., MiniLM-L6-v2 vectors
    metric: .cosine,
    storageMode: .sq8
)

// Retrieve collection handle
guard let collection = try db.getCollection(name: "embeddings") else {
    fatalError("Collection not created")
}

// Insert vector with JSON payload
let point = VelesPoint(
    id: 1,
    vector: embedding,
    payload: "{\"title\":\"On-Device Semantic Search\"}"
)
try collection.upsert(point: point)

// Execute nearest-neighbor search
let results = try collection.search(vector: queryEmbedding, limit: 10)
results.forEach { result in
    print("ID: \(result.id), Score: \(result.score)")
}

Building VelesDB for Android

Android builds use cargo ndk to compile for multiple ABIs (arm64-v8a, armeabi-v7a, x86_64). The resulting .so files and Kotlin bindings are packaged as an AAR for Gradle integration.

Kotlin Integration Example

Access the native library through the generated Kotlin bindings in your Android project:

import com.velesdb.mobile.*

// Initialize database in private app storage
val db = VelesDatabase.open("${context.filesDir}/velesdb")

// Configure collection with mobile-optimized storage
db.createCollectionWithStorage(
    "embeddings",
    384u,
    DistanceMetric.COSINE,
    StorageMode.SQ8
)

val collection = db.getCollection("embeddings")
    ?: throw IllegalStateException("Collection missing")

// Upsert vector data
val point = VelesPoint(
    id = 1uL,
    vector = modelOutput,
    payload = """{"category":"mobile_rag"}"""
)
collection.upsert(point)

// Perform similarity search
val results = collection.search(queryVector, 10u)
results.forEach { 
    Log.d("VelesDB", "Hit: ${it.id} with score ${it.score}")
}

Advanced Mobile Features

Beyond basic vector search, the mobile deployment supports sophisticated query patterns essential for on-device AI applications.

Multi-Query Fusion (MQG)

The multiQuerySearch method, implemented in crates/velesdb-mobile/src/lib.rs#L260-L274, enables running multiple query vectors in parallel and fusing results using Reciprocal Rank Fusion (RRF) with a default $k=60$ parameter.

Swift:

let fusedResults = try collection.multiQuerySearch(
    vectors: [queryVariant1, queryVariant2, queryVariant3],
    limit: 10,
    strategy: .rrf(k: 60)
)

Kotlin:

val results = collection.multiQuerySearch(
    vectors = listOf(q1, q2, q3),
    limit = 10u,
    strategy = FusionStrategy.Rrf(k = 60u)
)

Graph Traversal and Agent Support

The mobile crate includes optional modules for graph operations (crates/velesdb-mobile/src/graph.rs) and AI agent utilities (crates/velesdb-mobile/src/agent.rs), supporting on-device RAG (Retrieval-Augmented Generation) workflows without network connectivity.

Performance Characteristics and Binary Size

The mobile build produces a 15 MB binary for the full-precision engine. Enabling SQ8 quantization reduces the footprint to under 5 MB while maintaining sub-millisecond vector search latency on modern ARM chips. The binary includes ARM NEON SIMD kernels from crates/velesdb-core/src/simd_native, ensuring hardware-accelerated distance calculations on both iOS and Android devices.

Summary

• VelesDB mobile deployment is supported through the velesdb-mobile crate, which compiles the Rust core to platform-specific libraries.
• UniFFI generates type-safe Swift and Kotlin bindings from crates/velesdb-mobile/src/lib.rs, exposing VelesDatabase and VelesCollection APIs.
• Storage modes (Full, SQ8, Binary) in crates/velesdb-mobile/src/types.rs allow trading recall for memory efficiency on constrained devices.
• Thread-safe architecture using Arc wrapping enables safe concurrent access from mobile UI and background threads.
• Multi-query fusion and graph traversal APIs support advanced on-device AI applications like mobile RAG.

Frequently Asked Questions

Does VelesDB mobile require an internet connection?

No. Once the native library is bundled in your iOS or Android app, VelesDB operates entirely offline. The vector search, graph traversal, and data persistence all happen locally on the device using the embedded binary compiled from velesdb-core.

What is the memory overhead of running VelesDB on a mobile device?

The base binary adds approximately 15 MB to your app size, or under 5 MB when using SQ8 quantization. At runtime, memory usage depends on dataset size, but the SQ8 mode provides 4× compression and Binary mode offers 32× compression, allowing million-scale vector databases to fit within mobile RAM constraints.

Can I use the same Rust core for both server and mobile deployments?

Yes. The velesdb-mobile crate links directly against velesdb-core without forking the code, ensuring identical search semantics and recall characteristics across platforms. The core's ARM NEON SIMD kernels in crates/velesdb-core/src/simd_native automatically activate when targeting mobile aarch64 architectures.

How do I handle database migrations or schema changes in mobile apps?

The VelesDatabase struct provides collection management methods that allow creation, deletion, and inspection of collections at runtime. Since VelesDB uses a file-based storage backend, you can implement migration logic in your Swift or Kotlin code by checking collection metadata and re-indexing data when your app updates, treating the database file similarly to SQLite migrations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}