● Latest v1.0.5 · GPL-3.0-or-later

NEDB

The embedded database that answers “what did the system know, and when?” Bi-temporal queries, causal write provenance, AES-256-GCM encryption, and a Rust core — all in one append-only hash chain.

View on GitHub NEDB Studio →

$ pip install nedb-engine $ npm install nedb-engine

causal_bitemporal.py

from nedb import NEDB

db = NEDB("./data")   # AES-256-GCM if NEDB_TMK set

# Write with causal provenance
db.put("claims", "c1", {
    "fact": "Earth orbits Sun",
    "valid_from": "1543-01-01",
    "caused_by": "obs:heliocentric-model",
    "evidence": "Copernicus 1543",
    "confidence": 0.9999,
})

# Bi-temporal: what did the system know at
# seq 200 about what was true on 2024-06-15?
db.query(
    'FROM claims AS OF 200'
    ' VALID AS OF "2024-06-15"'
    ' WHERE confidence > 0.9'
)

# Causal trace: why does the agent believe X?
db.query('FROM claims TRACE caused_by')
# Forward: what did this observation cause?
db.query('FROM claims TRACE caused_by REVERSE')

assert db.verify()     # hash chain intact

Why NEDB

The first embedded database that answers “why does the agent believe X?”

NEDB seals caused_by, evidence, and confidence directly into its hash chain — so every fact carries a cryptographically-linked audit trail. Combine that with bi-temporal queries and a concurrent Rust core and you get something no other embedded database offers: four-dimensional auditability at embedded-database speed.

🕘

Bi-temporal Queries

VALID AS OF "date" for business time + AS OF seq for transaction time. Ask the four-dimensional question: “what did the system know at seq 200 about what was true on 2024-06-15?”

🔗

Causal Write Provenance

caused_by, evidence, confidence sealed in the hash chain. TRACE caused_by walks backward (why?) and TRACE caused_by REVERSE walks forward (what did this cause?).

⚡

Concurrent Group-Commit

nedbd handles parallel reads and batched writes safely via a lock-free sequencer. ~15 K writes/s under load — without sacrificing durability or chain integrity.

🔄

SQL + Redis + MongoDB Adapters

All three wire protocols speak the same Rust engine. Migrate from any stack without changing your queries — and add RESP2 for redis-cli compatibility via NEDBD_RESP2_PORT=6380.

🔒

AES-256-GCM Encryption

Set NEDB_TMK=<32-byte-hex> and every record is encrypted at rest. The hash chain remains verifiable; keys never touch the log.

🔧

Self-Healing Chains

Structural gaps are detected and auto-repaired on open. Combined with the Rust native core (napi-rs for Node, PyO3 for Python), the same compiled engine powers both runtimes.

NQL Grammar

One query language for all four dimensions

NQL composes cleanly — any clause is optional, order is consistent, and the same syntax works across the Python, Node, SQL, Redis, and MongoDB adapters.

Clause	Description
FROM <coll>	Target collection
AS OF <seq>	Transaction-time travel — read DB state as it existed at sequence number
VALID AS OF "<date>"	Valid-time travel — filter records whose validity window includes the given date
WHERE <expr>	Filter with equality, comparison, boolean logic, and nested field access
SEARCH "text"	Full-text search via incremental inverted index
ORDER BY <field>	Ordered result set (ascending/descending)
TRAVERSE <rel>	Graph traversal over adjacency-list edges (time-travels with the rest)
TRACE caused_by	Backward causal trace — follows the provenance chain: why does the agent believe X?
TRACE caused_by REVERSE	Forward causal trace — what downstream facts did this event produce?
LIMIT n	Cap result count
GROUP BY <field> COUNT\|SUM\|AVG\|MIN\|MAX	Aggregations, evaluated after all filters

Release highlights

The 1.0 line

v1.0.5

Bi-temporal stability & Studio GA

Production-hardened VALID AS OF indexing, improved self-healing on corrupt segments, and NEDB Studio goes generally available at studio.interchained.org — prompt-to-database GUI with live chain inspection.

v1.0.x

Rust native core (napi-rs + PyO3)

Same compiled Rust core surfaces to Node via napi-rs and to Python via maturin/PyO3. Both npm install nedb-engine and pip install nedb-engine ship native binaries with a pure fallback.

v0.9.x

RESP2 wire protocol + adapters

nedbd now speaks RESP2 — set NEDBD_RESP2_PORT=6380 and connect any redis-cli client. SQL and MongoDB adapters landed alongside, all sharing the same engine.

v0.8.x

Causal Write Provenance + bi-temporal

caused_by, evidence, and confidence are now first-class fields sealed in the hash chain. TRACE caused_by [REVERSE] introduced. Bi-temporal VALID AS OF clause added alongside existing AS OF seq.

v0.7.x

Concurrent group-commit sequencer + AES-256-GCM

nedbd gained a lock-free sequencer for parallel reads and batched writes (~15 K writes/s). At-rest encryption via NEDB_TMK and self-healing chain repair on open also shipped in this cycle.

Full history on GitHub Releases.

Run it as a server

nedbd

pip install nedb-engine or npm install nedb-engine ships the daemon. Run the Rust engine as its own process and connect clients over HTTP, RESP2, SQL, or MongoDB wire — whichever fits your stack. The group-commit sequencer handles concurrent access safely.

shell

$ nedbd                      # http://127.0.0.1:7070
$ NEDBD_RESP2_PORT=6380 nedbd # also speaks redis-cli

# Create a database and write with provenance
$ curl -X POST localhost:7070/v1/databases \
    -d '{"name":"agents"}'

$ curl -X POST localhost:7070/v1/databases/agents/query \
    -d '{"nql":"FROM beliefs AS OF 200 VALID AS OF \"2024-06-15\" WHERE confidence > 0.8 TRACE caused_by"}'

# env: NEDBD_HOST · NEDBD_PORT · NEDBD_DATA
#      NEDBD_TOKEN · NEDB_TMK (AES-256-GCM key)

Install

Two lines to a database

$ pip install nedb-engine $ npm install nedb-engine

NEDB() is in-memory; NEDB("./path") is durable. nedbd runs it as a server. The Rust core ships as a native binary with a pure fallback. Set NEDB_TMK for AES-256-GCM at-rest encryption. Read the format spec or explore your data visually in NEDB Studio.