velesdb-mobile

Native iOS (Swift) and Android (Kotlin) bindings to the VelesDB engine, generated with UniFFI.

Maturity — read before shipping. The Rust binding layer is production-grade: 135 tests pass on the host (cargo test -p velesdb-mobile), CI re-runs them on every pull request via cargo test --workspace, a parity test fails the build when velesdb-core grows an enum variant the binding has not mirrored, and the crate is published to crates.io by the release workflow. The device toolchain is not: no CI job cross-compiles for an iOS or Android target, no job compiles the generated Swift/Kotlin, no XCFramework or AAR is published, and the repository contains no Swift/Kotlin test suite. Treat the packaging steps in Mobile build guide as "documented and manual", not "verified per release", and validate them on your own device matrix before you depend on them.

Objective

An on-device AI feature needs its embeddings on the device: no network hop for a semantic search, no user data leaving the phone, and a working app in airplane mode. Reimplementing a vector index in Swift and again in Kotlin is expensive and the two copies drift. This crate exposes the single Rust engine (velesdb-core) to both platforms through one UniFFI interface, so search semantics, distance metrics, and quantization behave identically on iOS, Android, and the server.

It is the mobile face of VelesDB, the explainable, local-first memory engine for AI agents — vector, graph, and columnar data fused under VelesQL. The explainability layer itself (why() recall trails) lives in velesdb-memory; this crate exposes the engine.

Use cases

• An iOS notes app that answers "what did I write about X?" offline, over locally computed embeddings.
• An Android field-service app that ships a pre-built knowledge base and does semantic + BM25 hybrid retrieval with no connectivity.
• An on-device agent that keeps a semantic memory of past interactions (VelesSemanticMemory) and a small knowledge graph (MobileGraphStore).
• An IoT/edge build where binary quantization trades ~5–10% recall for 32x less memory per vector.
• A read-audited app: a Swift/Kotlin MobileObserver sees every read and can deny it (MobileAccessDecision), for consent gating or per-tenant isolation.

Prerequisites

Rust targets are not installed by default:

rustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android

Installation

There is no published XCFramework or AAR — you build the library and generate the bindings from source:

git clone https://github.com/cyberlife-coder/velesdb.git
cd velesdb
cargo build --profile release-mobile -p velesdb-mobile

The release-mobile profile is not optional for device builds: the default release profile sets panic = "abort", which disables the catch_unwind net inside UniFFI's trampolines — a throwing Swift/Kotlin callback would abort the whole app instead of raising a catchable exception. release-mobile restores panic = "unwind" and inherits everything else from release.

A Rust application (including a Tauri or desktop host) can depend on the crate directly instead:

cargo add velesdb-mobile

Per-platform packaging: Mobile build guide.

First success in 60 seconds

Generate the Swift bindings from a host build — no device, no simulator, no Xcode project. Run from the repository root:

cargo build -p velesdb-mobile
cargo run -p velesdb-mobile --bin uniffi-bindgen -- generate \
    --library target/debug/libvelesdb_mobile.dylib \
    --language swift \
    --out-dir bindings/swift
ls -1 bindings/swift

Expected output of the final ls -1 — three files, nothing else:

velesdb_mobile.swift
velesdb_mobileFFI.h
velesdb_mobileFFI.modulemap

Any other outcome — a bindgen error about the library, or an empty directory — means the --library path is wrong for your host: on Linux the file is target/debug/libvelesdb_mobile.so, on Windows target/debug/velesdb_mobile.dll (and target/release/... after a --release build). The first cargo build compiles velesdb-core and takes several minutes on a cold cache; every step after that is seconds.

The same command with --language kotlin writes one file, bindings/kotlin/uniffi/velesdb_mobile/velesdb_mobile.kt — note the package, uniffi.velesdb_mobile.

Sanity-check the engine itself without any mobile toolchain:

cargo test -p velesdb-mobile

Expected on a host with default features: test result: ok. 123 passed for the lib target, then 8 passed (tests/coverage_native.rs) and 4 passed (tests/feature_parity.rs).

Configuration

The engine is configured at open time; there is no mobile-specific config file format. Environment variables (VELESDB_*) still layer on top of a loaded file.

Field-by-field reference: velesdb.toml guide.

Examples

The examples/ directory holds a bindings-generation script (generate_bindings.sh), Swift and Kotlin quickstart walkthroughs, and an engine-only velesdb.toml — see its README for what is and is not compiled by CI. The runnable, always-compiled references are the crate's own tests — crates/velesdb-mobile/tests/coverage_native.rs drives the real binding types (VelesDatabase, VelesCollection, MobileGraphStore) as plain Rust.

Swift and Kotlin snippets for every API group live in the Mobile API guide.

API / commands

Full method tables, the filterJson shape, storage modes, fusion strategies, and the record types: Mobile API guide.

Rust-side signatures are generated: docs.rs/velesdb-mobile. Every Swift/Kotlin name is the camelCase form of the Rust name.

Two naming traps worth knowing before your first build:

• open is a named constructor. UniFFI emits it as a Swift static method (VelesDatabase.open(path:)) and a Kotlin companion factory (VelesDatabase.open(path)) — not a default initializer.
• The Kotlin package is uniffi.velesdb_mobile, and the Swift module name is whatever you call the framework you package the sources into.

Known limits

• Every call is blocking. No method in the binding is async, and the generated Swift contains no async function. Call from a background queue/dispatcher; a search on the main thread blocks the UI.
• No prebuilt artifacts. No XCFramework, no AAR, no Maven/SwiftPM package.
• No device CI. iOS/Android cross-compilation and the generated Swift/Kotlin are not built by any workflow in this repository.
• Agent memory is semantic-only. VelesSemanticMemory covers store/query/delete; episodic and procedural memory, TTL setters, and snapshots are not exposed (see ecosystem parity).
• MobileGraphStore is a deliberate in-memory fork of core's graph engine, not a delegate: RAM-only, no WAL, no on-disk payloads (it has explicit save/load). Rationale in known limitations §14.
• Bulk paths are chunked, not raw. The zero-copy raw-bulk insert available on core, server, CLI, WASM, and the TS SDK is not exposed here; use upsertBatch or streaming ingestion.

Compatibility

Cross-compilation targets, as declared in crates/velesdb-mobile/Cargo.toml. "CI-built" means a workflow in this repository compiles that target.

ARM64 devices get core's NEON paths (velesdb_core::simd_neon, simd_neon_prefetch) for distance computation and prefetching.

Troubleshooting

License

VelesDB Core License 1.0 (source-available). The compiled bindings embed the VelesDB engine and are governed by that license.

velesdb-mobile v5.1.0 · Last updated: 2026-08-10 · Applies to: velesdb-core 5.1.0 · Report a docs error