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

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 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. 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) 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. 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. 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)

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).

Python (PyO3 Bindings)

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.

TypeScript (Node / Browser SDK)

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	Implements the memory-mapped, on-disk vector store that makes the database truly local.
Query Planner	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	The native approximate-nearest-neighbor index that runs wholly in-process.
Quantization	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	Provides a thin HTTP façade when you do want an API endpoint, but still runs locally.
Documentation of Local-First Value	README.md – sections Latency kills UX, Compliance, ROI	Summarizes business implications of the local-first approach.
Python Bindings	crates/velesdb-python/src/lib.rs	Shows how the same local engine is exposed to Python developers.
WASM SDK	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) 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) 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) 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, 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. 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) 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.

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