Trivium Lab GitHub ↗

Vector × Graph × Document

Three paths, one embedded AI database.

TriviumDB is a single-file engine for AI applications, built to weave agent context, multimodal memory, 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 file, 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 · residual query · DPP rerank

05 · QuIVer

ANN candidates, original-vector rerank.

QuIVer keeps BQ2 signatures and a Vamana-pruned ANN graph on the hot path, then scores candidates against original f32 vectors.

QuIVer ANN pathBQ2 query encoding, beam search over a Vamana-pruned ANN graph, candidate set, and f32 cosine rerank against original vectors.05QuIVer ANN pathHot BQ2 signatures + ANN graph.Cold original vectors for candidate rerank.queryBQ2 encodesign 01 10 00 11strong 10 00 01 102-bit sign/magnitude signatureentryid:42candidatesbeam searchVamana-pruned ANN graph · BQ distancecandidate setf32 cosine rerankid:42 score:.985id:88 score:.972id:10 score:.968id:55 score:.954id:99 score:.949original vectors · top_k SearchHit rowsQUIVER · BQ2 SIGNATURES / VAMANA-PRUNED ANN GRAPH / F32 CANDIDATE RERANKauto-routes to brute force at small scale
API bindings Python / Node / Rust
Rust core transactions / query pipeline / hooks
Workspace vectors / payload / edges
Storage .tdb / .vec / .tdb.quiver / .wal
Rom mode.tdb

portable knowledge stores and smaller databases

Mmap mode.tdb + .vec

large vector pools with zero-copy cold start

06 · Storage

Portable when small. Mmap-backed when large.

Rom mode keeps a compact `.tdb` file easy to copy. Mmap mode separates vector pools into `.vec` while the `.tdb` file remains the source of metadata, graph structure, and durable state.

07 · Reliability

Crash recovery is part of the write path.

TriviumDB treats embedded durability as an engine primitive: dry-run validation, WAL frames with CRCs, fsync boundaries, atomic rename, and deterministic replay keep the three planes moving together.

commit pipeline wal_safe=true
  1. 01

    Validate as a dry run

    Mutations are shaped before commit so vector, payload, and edge updates can be rejected without partially changing the node.

  2. 02

    Append WAL records

    The write-ahead log captures intent first, giving replay a precise source of truth after process or host interruption.

  3. 03

    Guard each frame with CRC

    Checksummed log frames make torn or corrupted records detectable before they can be applied to the embedded store.

  4. 04

    Flush, rename, replay

    fsync and atomic rename make durable checkpoints explicit; startup replay completes committed records and ignores unsafe tails.

startup replay WAL
checkpoint atomic rename
integrity CRC verified

08 · Developer Experience

Embedded memory without a service graph.

Start from Python, Node, or Rust and keep vectors, JSON, and edges in one local database file. The API is designed for agent memory loops where every result can point back to a durable node.

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)
    context = db.search([0.10, -0.48, 0.80], top_k=5, expand_depth=2)
    print(context)

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 ↗