# VelesDB Local-First Database: Architecture, Performance, and Trade-offs

> Explore VelesDB's local-first architecture for sub-millisecond vector search. Eliminate network overhead and cloud costs with this efficient in-process database.

- Repository: [Wiscale/velesdb](https://github.com/cyberlife-coder/velesdb)
- Tags: architecture
- Published: 2026-02-28

---

**VelesDB runs entirely on the host machine using memory-mapped files and in-process HNSW indexing, delivering sub-millisecond vector search latency while eliminating network overhead, cloud costs, and external compliance risks.**

VelesDB is deliberately engineered as a **local-first database**, meaning the entire engine executes on the same physical host as the application. Unlike cloud-hosted vector services, VelesDB requires no remote API calls, external authentication tokens, or network hops. This architectural choice fundamentally shapes the system's performance characteristics, security posture, and operational model.

## Zero-Network Latency and Predictable Performance

The absence of network I/O allows VelesDB to achieve microsecond-scale query latency that is impossible for client-server architectures to match.

### Memory-Mapped Storage Architecture

All data—including vectors, graph edges, and columnar rows—persists in **memory-mapped files** on the local filesystem. The storage layer in [`crates/velesdb-core/src/storage/mmap.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/storage/mmap.rs) implements aligned `f32` vector layouts and fast random reads via `mmap` system calls. This eliminates the serialization overhead and TCP latency inherent in networked databases.

### In-Process HNSW Indexing

Vector search executes through an **in-process HNSW index** with SIMD-accelerated distance calculations (AVX-512, AVX2, NEON). The query planner assigns minimal cost weights to local HNSW operations—`HNSW_IO_WEIGHT = 0.5` and `HNSW_CPU_WEIGHT = 1.0`—as defined in [`crates/velesdb-core/src/velesql/planner.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/velesql/planner.rs). Consequently, a typical 10,000-vector nearest-neighbor query completes in approximately **100 microseconds**, entirely within the application process.

## Data Sovereignty and Compliance Implications

Because VelesDB never transmits data over the internet, it satisfies stringent regulatory requirements without additional engineering effort.

All payloads, embeddings, and metadata remain on-disk, making the system **HIPAA and GDPR-ready** by default. The project documentation explicitly labels this capability as "local-first compliance," highlighting that no API keys, cloud accounts, or third-party services are required. This architecture eliminates the external attack surface associated with credential leaks or man-in-the-middle attacks on database connections.

## Deployment Simplicity and Cost Structure

The local-first model collapses operational complexity to a single artifact.

VelesDB ships as a **~15 MB single binary** compatible with Linux, Windows, macOS, ARM, and WebAssembly targets. No container orchestration, network routing rules, or managed service provisioning is necessary. The cost model reduces to **zero cloud spend**—organizations pay only for the local hardware they already own, whether a developer laptop, edge gateway, or IoT board.

## Cross-Platform Portability

The Rust core library compiles to multiple targets without code changes, extending the local-first guarantee across environments.

Supported platforms include desktop operating systems, server hardware, mobile devices (via UniFFI bindings), and browsers (via WebAssembly). The `crates/velesdb-wasm` package enables **offline browser applications** and **air-gapped edge devices**, maintaining the same sub-millisecond latency guarantees in environments with no network connectivity.

## Single-Node Limitations and Mitigations

The local-first architecture imposes a single-node data model that requires careful capacity planning.

Horizontal scaling and multi-node replication are not implemented in the current release (the roadmap identifies a future "distributed mode"). Applications must fit data volumes within the host's storage and memory constraints. VelesDB addresses this limitation through aggressive storage optimization.

### Storage Optimization via Quantization

The core includes a scalar-quantization module ([`crates/velesdb-core/src/index/hnsw/native/quantization.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/index/hnsw/native/quantization.rs)) that compresses 768-dimensional vectors from approximately 3 KB to 0.8 KB using SQ8 encoding. This reduces memory pressure and allows larger datasets to operate within single-node boundaries.

## Resilience and Offline-First Guarantees

Local storage enables durability guarantees independent of network availability.

The storage layer implements a **write-ahead log (WAL)** for crash recovery, verified in [`storage/wal_recovery_tests.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/storage/wal_recovery_tests.rs). Because no external network service is required, VelesDB **continues to serve queries during internet outages**, providing mission-critical availability for edge-deployed AI agents and IoT systems.

## Developer Experience and API Design

The local-first model simplifies the programming interface by eliminating client-server complexity.

Developers interact with a **single unified API** called **VelesQL** that can query vectors, graph relationships, and columnar data in one statement, as documented in [`docs/guides/USE_CASES.md`](https://github.com/cyberlife-coder/velesdb/blob/main/docs/guides/USE_CASES.md). The same binary exposes bindings for **Rust, Python, TypeScript, and WebAssembly** with zero-configuration SDKs, removing the "glue code" typically required to bridge separate vector, graph, and relational databases.

## Local-First Implementation Examples

The following examples demonstrate the zero-network workflow across three languages.

### Rust (Core Library)

```rust
use velesdb_core::Database;

// Create a database stored in a local folder (no server needed)
let mut db = Database::open("./my_local_db")?;

// Define a collection with 768-dim cosine vectors
let coll = db.create_collection("docs", 768, Metric::Cosine)?;

// Upsert a few points (vectors + metadata)
coll.upsert(vec![
    Point::new(1, embedding1, payload!{ "title": "Intro to AI" }),
    Point::new(2, embedding2, payload!{ "title": "Vector Search" }),
])?;

// Perform a pure-vector search – all in-process, sub-ms latency
let hits = coll.search(&query_vec, TopK::new(5))?;
println!("Top hits: {:?}", hits);

```

The `Database::open` call points to a local directory; the engine reads/writes via memory-mapped files ([`mmap.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/mmap.rs)).

### Python (PyO3 Bindings)

```python
import velesdb

# Open (or create) a local database directory

db = velesdb.Database("./local_db")

# Create a collection

col = db.create_collection(name="articles", dimension=768, metric="cosine")

# Insert vectors

col.upsert([
    {"id": 1, "vector": emb1, "payload": {"title": "Rust vs Go"}},
    {"id": 2, "vector": emb2, "payload": {"title": "Local-First Systems"}},
])

# Query locally – no network request

results = col.search(vector=query_emb, top_k=3)
print(results)

```

Under the hood the Python wrapper calls the same Rust core, which stores data on disk via [`mmap.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/mmap.rs).

### TypeScript (Node / Browser SDK)

```typescript
import { VelesDB } from "@wiscale/velesdb";

(async () => {
  // In Node: local filesystem; in the browser: IndexedDB + WASM
  const db = await VelesDB.open("./browser_db"); // automatically uses WASM in the browser

  const coll = await db.createCollection("docs", { dimension: 768, metric: "cosine" });

  await coll.upsert([
    { id: "a1", vector: embA, payload: { title: "Edge AI" } },
    { id: "a2", vector: embB, payload: { title: "Privacy First" } },
  ]);

  const hits = await coll.search({ vector: queryEmb, topK: 5 });
  console.log(hits);
})();

```

The SDK compiles the same Rust core to WebAssembly (`velesdb-wasm`), delivering the local-first guarantee even inside a browser.

## Key Source Files

| Category | File | Why It Matters |
|----------|------|----------------|
| **Core Storage** | [`crates/velesdb-core/src/storage/mmap.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/storage/mmap.rs) | Implements the memory-mapped, on-disk vector store that makes the database truly local. |
| **Query Planner** | [`crates/velesdb-core/src/velesql/planner.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/velesql/planner.rs) | Shows the cost model for local HNSW search and how VelesQL is optimized for zero-network latency. |
| **HNSW Index** | [`crates/velesdb-core/src/index/hnsw/native_index.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/index/hnsw/native_index.rs) | The native approximate-nearest-neighbor index that runs wholly in-process. |
| **Quantization** | [`crates/velesdb-core/src/index/hnsw/native/quantization.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/index/hnsw/native/quantization.rs) | Enables memory-efficient storage for edge devices. |
| **REST Server (optional)** | [`crates/velesdb-server/src/lib.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-server/src/lib.rs) | Provides a thin HTTP façade when you do want an API endpoint, but still runs locally. |
| **Documentation of Local-First Value** | [`README.md`](https://github.com/cyberlife-coder/velesdb/blob/main/README.md) – sections *Latency kills UX*, *Compliance*, *ROI* | Summarizes business implications of the local-first approach. |
| **Python Bindings** | [`crates/velesdb-python/src/lib.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-python/src/lib.rs) | Shows how the same local engine is exposed to Python developers. |
| **WASM SDK** | [`crates/velesdb-wasm/README.md`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-wasm/README.md) | Demonstrates browser-side, offline usage. |

## Summary

- **Sub-millisecond latency**: By eliminating network hops and using memory-mapped files ([`mmap.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/mmap.rs)) with in-process HNSW indexing, VelesDB achieves ~100 µs query times for 10,000-vector searches.
- **Zero cloud costs**: The ~15 MB single binary runs entirely on local hardware, removing managed service fees and container orchestration complexity.
- **Regulatory compliance**: Data never leaves the host, making HIPAA and GDPR adherence achievable without additional security tooling or API key management.
- **Offline resilience**: The write-ahead log ([`wal_recovery_tests.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/wal_recovery_tests.rs)) ensures durability, while the lack of network dependencies guarantees availability during outages.
- **Single-node constraints**: Horizontal scaling is not currently supported; users must rely on quantization ([`quantization.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/quantization.rs)) and data pruning to fit workloads within host memory and storage limits.

## Frequently Asked Questions

### What makes VelesDB different from cloud vector databases like Pinecone or Weaviate?

VelesDB operates entirely on the local host using memory-mapped storage and in-process computation, whereas cloud solutions require network round-trips for every query. According to the source code in [`crates/velesdb-core/src/storage/mmap.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/storage/mmap.rs), VelesDB accesses data via local filesystem `mmap` calls rather than TCP sockets, eliminating serialization overhead and achieving ~100 µs latency for 10,000-vector searches. Cloud databases offer managed scaling but introduce milliseconds of network latency and ongoing operational costs that VelesDB avoids.

### How does VelesDB handle data durability without a remote server?

The storage layer implements a **write-ahead log (WAL)** for crash recovery, verified in [`storage/wal_recovery_tests.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/storage/wal_recovery_tests.rs). When the application process restarts after a failure, VelesDB replays the WAL to restore the memory-mapped files to a consistent state. Because the database runs locally, durability depends only on the host's filesystem rather than remote replication, ensuring that committed writes survive process crashes without requiring network connectivity.

### Can VelesDB run in a browser or mobile environment?

Yes. The Rust core compiles to WebAssembly for browser deployment and uses UniFFI for mobile bindings. The `crates/velesdb-wasm` package enables the database to run inside browsers using IndexedDB for persistence, while the TypeScript SDK (`@wiscale/velesdb`) provides the same API across Node.js and browser environments. This allows offline-capable applications to execute vector searches on devices without internet connectivity, maintaining the local-first guarantee even in constrained edge environments.

### What are the scalability limitations of VelesDB's local-first design?

VelesDB currently operates as a single-node system without built-in horizontal scaling or multi-node replication (though the roadmap mentions future distributed capabilities). Applications must fit their working set within the host's RAM and local storage constraints. To mitigate this, VelesDB implements scalar quantization ([`crates/velesdb-core/src/index/hnsw/native/quantization.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/index/hnsw/native/quantization.rs)) that compresses 768-dimensional vectors from ~3 KB to ~0.8 KB, reducing memory pressure and enabling larger datasets to operate within single-node boundaries. Users must also implement data pruning strategies to manage storage limits.