NodeDB Lite
The embedded memory engine for AI agents and local-first apps.
Durable, queryable memory that lives in your app — vector, graph, document, full-text, timeseries,
and key-value NodeDB engines in-process, offline by
default, syncing conflict-free to NodeDB Origin when connectivity returns. One API, no server required.
Release Status
·
Platforms
·
CRDT Sync
·
Performance
·
NodeDB Origin
Agent memory and local-first data usually mean a pile of files, or a SQLite database with a vector sidecar, an ad-hoc cache, and a hand-written sync layer. NodeDB Lite is one embedded engine instead: durable, queryable memory in-process, available offline, with conflict-free sync to NodeDB Origin when you want it — and no rewrite to move from edge to cloud.
It's the engine behind ma8e, an in-development memory-and-knowledge layer for coding agents — deterministic capture, hybrid retrieval, and path-level access guards, all on embedded NodeDB Lite.
Release Status
NodeDB Lite is in public beta as of v0.1.0 (2026-10-16). All engines listed in docs/lite-support-matrix.md are feature-complete and covered by tests. The public surface — the NodeDb trait, the supported SQL plan variants, the C FFI ABI, and the WASM / npm bindings — is stable; clients written against 0.1.0 will keep working through 1.0.
v0.1.0 — Beta (today). Use it for embedded workloads and for piloting Lite ↔ Origin sync. The public surface is stable; expect internal changes (pagedb layout, on-disk index format, sync-protocol internals) between minor releases. Patch and minor bumps will land as needed.
v1.0.0 — Production-ready. What 1.0 guarantees:
- API & SQL stability — semver from 1.0 onward. No breaking changes to the
NodeDb trait, the supported SQL plan variants, or the C FFI / WASM ABIs within a major.
- Sync protocol stability — the Lite ↔ Origin WebSocket wire frames frozen at the version Origin ships in its 1.0.
- On-disk format stability — no breaking migrations within 1.x. Forward-compatible upgrades only.
- Platform parity — iOS FFI built and tested against a macOS environment; Android JNI packaging fully gated.
- Performance SLAs — published p99 targets per engine, regression-gated in CI.
- Security audit — third-party audit completed and findings remediated before 1.0 ships.
Pre-1.0 versions may change internals between releases — that work is critical-path hardening (persistence layouts, sync coordination, platform packaging) that has to be exercised in real production conditions before we put a stability stamp on it. The public API, SQL surface, and sync wire frames won't break; everything underneath is fair game until 1.0.
Note: This release track applies to NodeDB Lite only. NodeDB Origin, ndb CLI, and NodeDB Studio are versioned independently on their own tracks.
Why NodeDB Lite
- One embedded engine, not a stitched-together client stack. Vectors, graph, documents, full-text, timeseries, key-value, and other NodeDB data models run in one runtime with shared storage and one query surface.
- Built for offline-first. Every write is captured as a CRDT delta locally, then merged to Origin when the network comes back.
- Same API as Origin. The
NodeDb trait is identical across Lite and server deployments, so moving from on-device to remote is a connection decision, not an architecture rewrite.
- Edge-ready. Linux, macOS, Windows, Android, and browser/WASM in
0.1.0; iOS lands before 1.0.
When to Use
- Mobile apps that need to work offline
- AI agents that need local memory (vectors + graph + documents)
- Browser-based apps (WASM, target: < 10 MB)
- Desktop applications with local-first data
- IoT gateways with intermittent connectivity
Platforms
| Platform |
Crate |
Backend |
Size |
| Linux |
nodedb-lite |
pagedb (file-backed) |
Native |
| macOS |
nodedb-lite |
pagedb (file-backed) |
Native |
| Windows |
nodedb-lite |
pagedb (file-backed) |
Native |
| Android |
nodedb-lite-ffi |
pagedb + C FFI + Kotlin/JNI |
Native |
| iOS (in progress — not in 0.1.0) |
nodedb-lite-ffi |
pagedb + C FFI (cbindgen) |
Native (requires macOS build environment — not yet built/tested) |
| Browser |
nodedb-lite-wasm |
pagedb (in-memory + OPFS) |
Target: < 10 MB |
Packages
# Rust
cargo add nodedb-lite
# JavaScript / TypeScript (browser + Node)
npm install @nodedb-lab/nodedb-lite
Quick Start
The Rust crate API in 0.1.0:
use nodedb_lite::{NodeDbLite, PagedbStorageMem};
use nodedb_client::NodeDb;
// Open an in-memory database. The constructor returns an Arc.
// Background flushing uses auto_flush_ms as an interval, without a deadline guarantee.
// In-memory storage remains volatile after flush().
let storage = PagedbStorageMem::open_in_memory().await?;
let db = NodeDbLite::open(storage).await?;
// Insert a document
db.execute_sql("CREATE COLLECTION notes", &[]).await?;
// Put a document via the typed API
use nodedb_types::document::Document;
let mut doc = Document::new("n1");
doc.set("title", "Hello".into());
db.document_put("notes", doc).await?;
// Vector search
let embedding = vec![1.0_f32, 0.0, 0.0];
db.vector_insert("articles", "a1", &embedding, None).await?;
// vector_search(collection, query, k, filter, allowed_ids)
let results = db.vector_search("articles", &embedding, 10, None, None).await?;
// Graph traversal
use nodedb_types::{graph::Direction, id::NodeId};
let start = NodeId::try_new("alice")?;
let subgraph = db.graph_traverse("social", &start, 3, Direction::Out, None).await?;
Same API, Any Runtime
The NodeDb trait is identical across Lite and Origin. Application code doesn't change for the operations both implementations expose — Origin offers more (full SQL, Array DDL/DML, vector quantization, distributed search); see docs/lite-support-matrix.md for the exact Lite surface.
// Works with both NodeDbLite (in-process) and NodeDbRemote (over network)
async fn search(
db: &dyn NodeDb,
query: &[f32],
) -> nodedb_types::error::NodeDbResult<Vec<nodedb_types::result::SearchResult>> {
db.vector_search("articles", query, 10, None, None).await
}
Moving from embedded to server is a connection string change, not a rewrite.
CRDT Sync
Every write produces a delta. Deltas sync to Origin over WebSocket when online. Multiple devices converge regardless of operation order.
Offline: App writes locally -> Loro generates delta -> delta persisted to pagedb
Reconnect: Device opens WebSocket -> sends vector clock + accumulated deltas
Cloud: Origin validates (RLS, UNIQUE, FK) -> merges -> pushes back missed changes
Conflict: Rejected deltas -> dead-letter queue + CompensationHint -> device handles
Converged: Device and cloud share identical Loro state hash
- Shape subscriptions -- Control what data each device holds:
WHERE user_id = $me, not the entire database
- Conflict resolution -- Declarative per-collection policies. SQL constraints (UNIQUE, FK) enforced on Origin at sync time with typed compensation hints back to the device.
- ACK-based flow control (AIMD), CRC32C delta integrity, JWT token refresh, replay dedup
The sync Cargo feature gates the WebSocket client and is on by default. Build with --no-default-features to ship a native binary with no network code. That build links no WebSocket client and has no start_sync. Local change capture still compiles.
nodedb-lite = { version = "0.1", default-features = false }
Key Features
- Multi-model locally -- Vector, graph, document, full-text, timeseries, key-value, and more, all in-process with no network
- Sub-millisecond reads -- Hot data lives in memory indexes (HNSW, CSR, Loro)
- SQL -- Supports a documented subset of NodeDB's SQL surface; see SQL support below.
- Encryption at rest -- AES-256-GCM + Argon2id key derivation
- Memory governance -- Per-engine budgets, pressure levels, LRU eviction
SQL support
NodeDB Lite parses SQL via nodedb-sql and executes supported plans against local engines. SQL coverage includes document mutations, joins, aggregates, CTEs, and search index declarations. Unsupported plans return LiteError::Unsupported. The regression gates include tests/sql_matrix.rs and tests/sql_parity.rs.
See docs/lite-support-matrix.md for the full engine, SQL, and sync support matrix.
Performance
| Metric |
Target |
| Vector search (1K vectors, 384d, k=5) |
< 1ms p99 |
| Graph BFS (10K edges, 2 hops) |
< 1ms p99 |
| Document get |
< 0.1ms |
| Cold start (10K vectors + 100K edges) |
< 500ms |
| Sync round-trip (single delta) |
< 200ms |
| WASM bundle |
< 10 MB |
| Mobile memory |
< 100 MB |
Workspace
This repository contains three crates:
| Crate |
Description |
nodedb-lite |
Core embedded database library |
nodedb-lite-ffi |
C FFI bindings for Android (cbindgen, Kotlin/JNI); iOS lands before 1.0 |
nodedb-lite-wasm |
JavaScript/TypeScript bindings via wasm-bindgen |
Building from Source
git clone https://github.com/NodeDB-Lab/nodedb-lite.git
cd nodedb-lite
# Build all crates
cargo build --release
# Build WASM
cargo build -p nodedb-lite-wasm --target wasm32-unknown-unknown --release
# Run tests
cargo test
For local development against the NodeDB workspace, create .cargo/config.toml:
[patch.crates-io]
nodedb-types = { path = "../nodedb/nodedb-types" }
nodedb-client = { path = "../nodedb/nodedb-client" }
nodedb-codec = { path = "../nodedb/nodedb-codec" }
nodedb-crdt = { path = "../nodedb/nodedb-crdt" }
nodedb-query = { path = "../nodedb/nodedb-query" }
nodedb-spatial = { path = "../nodedb/nodedb-spatial" }
nodedb-graph = { path = "../nodedb/nodedb-graph" }
nodedb-vector = { path = "../nodedb/nodedb-vector" }
nodedb-fts = { path = "../nodedb/nodedb-fts" }
nodedb-strict = { path = "../nodedb/nodedb-strict" }
nodedb-columnar = { path = "../nodedb/nodedb-columnar" }
nodedb-array = { path = "../nodedb/nodedb-array" }
nodedb-sql = { path = "../nodedb/nodedb-sql" }
nodedb-physical = { path = "../nodedb/nodedb-physical" }
License
Apache-2.0 — see LICENSE. NodeDB Lite is fully open source, with
no BSL anywhere in its dependency tree: it builds only on NodeDB's Apache-2.0
engine and foundation crates. The Business Source License applies only to the
NodeDB Origin server — never to Lite.
Embed it anywhere: apps, browsers (WASM/OPFS), mobile, desktop, edge.