HexxlaDB

Embedded database — hex grid, vector search, provenance, contradiction tracking.

HexxlaDB is an embedded Go library for structured, spatially-organised records. Items live at hex grid coordinates — retrieval expands outward in rings, stays within a budget, and respects validity windows. Every record carries provenance, confidence, and temporal bounds. Contradictions are stored as seams, not silently overwritten.

Single binary, zero network dependencies, no daemon.

How it works

Cells sit at (q, r) hex coordinates. Related records sit nearby. LoadContext walks outward ring by ring from seed coordinates, filters superseded and low-confidence content, and returns a budget-bounded slice — a token window for a prompt, a tile range for a game engine, a context pack for an audit query.

Quick start

go get github.com/hexxla/hexxladb

Full runnable examples: examples/ — conversational memory, LLM context engine, spatial algorithms.

Open a database

db, err := hexxladb.Open("memory.db", &hexxladb.Options{
    EnableMVCC: true,
})
if err != nil {
    log.Fatal(err)
}
defer db.Close()

Store a record and its embedding

db.Update(func(tx *hexxladb.Tx) error {
    coord := hexxladb.Coord{Q: 3, R: 1}
    pk, _ := lattice.Pack(coord)

    err := tx.PutCell(ctx, record.CellRecord{
        Key:        pk,
        RawContent: "Use testcontainers-go for integration tests with real Postgres.",
        Tags:       []string{"fact", "testing", "database"},
        Provenance: record.ProvenanceWire{SourceID: "session-2", Confidence: 0.95},
    })
    if err != nil {
        return err
    }
    return tx.PutEmbedding(pk, vectorFromYourModel) // HNSW index maintained automatically
})

Search by meaning

db.View(func(tx *hexxladb.Tx) error {
    results, err := tx.QueryCells(ctx, hexxladb.CellQuery{
        Embedding:     queryVector,
        ExcludeTags:   []string{"preference"},
        MinConfidence: 0.5,
        MaxResults:    8,
        SortBy:        hexxladb.SortByScore,
    })
    // results: ranked cells with score, content, tags, provenance
})

Assemble a token-budgeted context window

db.View(func(tx *hexxladb.Tx) error {
    pack, err := tx.LoadContext(ctx, hexxladb.LoadContextConfig{
        Seeds:   []hexxladb.Coord{results[0].Cell.Coord, results[1].Cell.Coord},
        MaxRing: 2,
        MaxTokens: 4096,
        Assembly: hexxladb.LoadContextBudgetConfig{
            FilterSuperseded: true,
            IncludeSeams:     true, // surface contradictions for the LLM
        },
    })
    // pack.Cells: ordered context within token budget
})

Track contradictions and supersessions

db.Update(func(tx *hexxladb.Tx) error {
    // Mark that newRecord supersedes oldRecord (e.g. updated belief, revised fact, preference change)
    return tx.MarkSupersedes(newCoord, oldCoord, "revised based on new evidence")
})

All in-process, no network calls. Embed → search → filter → assemble — one library.

Use cases

The core primitives — spatial locality, provenance, contradiction tracking, budget-bounded retrieval, MVCC snapshots, hybrid search — compose into patterns that are awkward to build on top of general-purpose stores.

• Agent and LLM memory — store conversation turns, facts, and preferences at hex coordinates; retrieve token-budgeted context packs ranked by semantic similarity and recency; surface contradictions to the model automatically
• Game world state — hex-native tile storage with FOV for visibility queries, A* pathfinding over cell edges, LOD for distant regions, MVCC snapshots for save/rollback and replay
• Knowledge graphs with temporal validity — facts that expire or get superseded; belief revision via seams; time-travel to any past snapshot with ViewAt
• Spatial annotation layers — sensor readings, events, or annotations at coordinates; proximity queries via ring walks; confidence-weighted retrieval for noisy data
• Audit trails and event sourcing — append-only changelog, SnapshotDiff for incremental CDC, MVCC pinning for point-in-time views; all writes are versioned
• Personal knowledge management — notes arranged spatially by topic proximity; contradiction surfacing between linked notes; supersession chains for evolving understanding
• Simulation state — reproducible snapshots between runs, diff for regression detection, spatial queries for proximity-based interactions

Comparison

API

Full reference: docs/hexxladb/API_REFERENCE.md

Performance

make bench-api

Intel Core i9-14900HX · 16 GB · Go 1.26 · Linux · -benchtime=3s -count=1

Reads and ring traversal

Context assembly

Writes

Semantic and lexical search

MVCC and maintenance

Performance context

HexxlaDB's "write" and "read" are not equivalent to a raw KV store operation. A PutCell writes a primary record plus 3–4 secondary index rows (source, tag, validity, changelog) in a single fsync'd transaction — comparable to a multi-index SQL insert. A GetCell deserialises a structured record (provenance, tags, validity window) on top of the B+ tree lookup. The ~5 ms single-write latency reflects this; BatchPutCells amortises the fsync to ~0.09 ms/cell.

The context assembly operations (LoadContext, LoadContextFOV, LoadContextVoronoi) have no direct equivalent in general KV stores — they replace what would otherwise be multiple sequential scans, scoring passes, and manual budget accounting in application code.

Examples

The LLM example requires Ollama: ollama pull all-minilm && make demo-llm

Caveats

• Write throughput — B+ tree with single writer; not suited for high-volume random write workloads. Use batch writes (db.Update with many operations) where possible.
• In-process only — no network server; one process owns the file at a time.
• HNSW at scale — the graph is persisted in the B+ tree; very large vector sets (>10K) may hit page-split pressure. Flat-scan fallback is always available.
• Coordinates are sparse — hex grid is a logical namespace, not a dense array. No compaction of coordinate space happens automatically.
• Pre-v1 — API may change between minor versions during the v0.y.z phase.

Documentation

Projects using HexxlaDB

• Hexxla — spatial LLM memory and reasoning stack
• Mosaic — local MCP server for structured agent memory on HexxlaDB

Contributing

See CONTRIBUTING.md.

git clone https://github.com/hexxla/hexxladb.git
cd hexxladb
go mod tidy
make test

Contact

• Issues — bugs and feature requests
• Discussions — questions and ideas