TriviumDB
GitHub ↗

Vector × Graph × Document

Three paths, one embedded AI database.

TriviumDB is an embedded engine for AI applications, built to weave agent context, vector recall, and structured metadata on one machine.

Explore the model Read docs ↗
Theoretical Trinity Aperture single node space · one embedded memory model
Interactive model drag to rotate · click a plane to focus
X
Y
Z
MODEL INVARIANT

One embedded engine, one node ID space, three coordinated representations.

02 · Problem

Three stores create one fragile memory.

A metadata store, vector index, and graph database can each be correct — while the agent's memory is still inconsistent.

3 ID spaces manual glue code x-db latency
Split Memory vs Unified MemoryComparison of an agent app connecting to three fractured stores versus a unified TriviumDB engine.Agent AppMetadata DBrow_7Vector DBvec_142Graph DBnode_91Application Glue CodeSync · transactions · deletesID drifttransaction gapdelete syncmerge latencyAgent AppOne queryTriviumDB EngineOne ID spacePayloadVector FieldGraph RelationsSPLIT ARCHITECTURE GLUE CODE VS UNIFIED EMBEDDED MEMORY

03 · Trinity Model

One ID space binds the planes.

A Trivium node is the shared address for semantic position, payload state, and graph relations.

node_id → vector + payload + edges
  • VECTOR: f32[]
  • PAYLOAD: JSON
  • GRAPH: edges[]
Trinity node modelA central node_id 42 connects to three large isometric planes: Vector, Payload, and Graph.Vector Planef32[0] → 0.12, -0.44f32[1] → 0.05, 0.91f32[2] → -0.88, 0.31Payload Planetype: documenttext: memorysource: chattags: noteGraph Planeentity_Aentity_Bentity_Centity_Drelated_tocaused_bymentionspart_ofnode_id: 42node_id → vector + payload + edges

04 · Search Pipeline

A query becomes ranked memory.

Search recalls top-k vector anchors, optionally expands through weighted graph edges, then returns ranked hits with payload attached.

vector recall graph expansion searchhit payload
db.search(query_vector, top_k=5, expand_depth=2)
optional advanced · text hybrid · FISTA residual · DPP diversify

05 · QuIVer

ANN candidates, original-vector rerank.

QuIVer keeps BQ2 signatures and a Vamana-pruned ANN graph on the hot path, then reranks candidates with f32 cosine scores over stored vectors.

QuIVer ANN pathBQ2 query encoding, beam search over a Vamana-pruned ANN graph, candidate set, and f32 cosine rerank over stored vectors.05QuIVer ANN pathHot BQ2 signatures + ANN graph.Stored vectors for candidate rerank.queryBQ2 encodepos mask 101101…strong mask 010010…BQ2 pos/strong bit masksentryid:42candidatesbeam searchVamana-pruned ANN graph · BQ distancecandidate setf32 cosine rerankid:42 score:.985id:88 score:.972id:10 score:.968id:55 score:.954id:99 score:.949stored vectors · top_k SearchHit rowsQUIVER · BQ2 SIGNATURES / VAMANA-PRUNED ANN GRAPH / F32 CANDIDATE RERANKdefault route: brute force until QuIVer is built
API Rust crate · Python · Node.js
Core WAL writes · transactions · query pipeline
In memory VecPool · payload JSON · edges · indexes
Checkpoint .tdb: header · payloads · edges · BQ metadata
Recovery / cache .tdb.wal · .tdb.quiver · .tdb.flush_ok
Single-file mode (Rom).tdb

vectors live inside the checkpoint after flush

Mmap mode.tdb + .tdb.vec

mapped vector pages for larger pools

06 · Storage

One database, two file layouts.

Single-file mode stores vectors, payloads, edges, and BQ metadata in one `.tdb` checkpoint. Mmap mode keeps payloads and graph edges in `.tdb` while vector pages live in `.tdb.vec`. Recent writes replay from `.tdb.wal`; `.tdb.quiver` is a rebuildable ANN index cache.

07 · Reliability

Recovery is built into commits and checkpoints.

TriviumDB records recoverable changes in a CRC-protected WAL and checkpoints state with synced temp files plus atomic rename. Transaction commits validate first, write a TxBegin/TxCommit batch, then apply to memory.

commit pipeline recovery=wal+crc
  1. 01

    Validate transaction

    Transaction commits dry-run check IDs, dimensions, payload size, and graph references before applying changes.

  2. 02

    Write WAL batch

    Transactions append TxBegin, records, and TxCommit before applying to memory; standalone writes are logged for recovery.

  3. 03

    Verify WAL frames

    Each WAL record is length-delimited and CRC32-checked during recovery so torn or corrupted tails stop replay.

  4. 04

    Replay safe prefix

    Startup replays verified records, promotes complete transactions, and truncates the log to the last safe offset.

  5. 05

    Checkpoint atomically

    Checkpoint files are written to temporary paths, synced, then published with atomic rename.

WAL len + bincode + CRC32
TX TxBegin / TxCommit
startup replay safe prefix
checkpoint sync + atomic rename

08 · Developer Experience

Agent memory without a database server.

Start from Python, Node, or Rust and keep vectors, JSON payloads, and edges in a local embedded database. Search returns durable node IDs with scores and payloads, so agent loops can jump from recall back to stored state.

Python pip install triviumdb
Node npm install triviumdb
Rust cargo add triviumdb
python · agent_memory.py 
import triviumdb

with triviumdb.TriviumDB("agent-memory.tdb", dim=3) as db:
    alice = db.insert([0.12, -0.45, 0.78], {
        "type": "memory",
        "text": "Alice works on embedded databases",
    })

    cafe = db.insert([0.08, -0.52, 0.81], {
        "type": "place",
        "name": "Blue Bottle",
    })

    db.link(alice, cafe, label="visited", weight=0.8)
    hits = db.search([0.10, -0.48, 0.80], top_k=5, expand_depth=2, min_score=0.1)

    for hit in hits:
        print(hit.id, hit.score, hit.payload)

09 · Build

Give your agent one durable memory substrate.

Explore the core concepts, then open the TriviumDB repository to inspect the embedded engine behind WAL recovery, CRC-protected frames, and the shared vector/graph/payload node model.

Read docs Open GitHub ↗