jeffhajewski/latticedb

LatticeDB – an embedded graph‑plus‑vector database

What it is – LatticeDB is a single‑file, embedded property‑graph database that also stores dense vectors and full‑text indexes. It lets a local program query the same data by relationship traversal, vector similarity, and BM25 text search using a single Cypher‑style query language.

Why it matters for AI – Modern AI applications (RAG pipelines, agent memory, local knowledge bases) often need three things together:

1. Graph structure to model entities and their relationships.
2. Semantic embeddings for similarity search.
3. Keyword search for precise text matching. LatticeDB provides all three in one engine, eliminating the need to stitch together separate graph, vector‑DB, and search services.

Key features (from the README)

• One‑file storage – the whole database lives in a portable file; no server, no config.
• Unified query layer – Cypher supports MATCH, WHERE, RETURN plus two new operators:
  • <=> for cosine distance on vector properties.
  • @@ for BM25 full‑text search.
• Native HNSW ANN – approximate nearest‑neighbor search with configurable parameters, delivering sub‑millisecond 10‑NN queries on 1 M vectors with 100 % recall.
• BM25 inverted index – fast lexical search (≈19 µs on 100 docs) with fuzzy matching.
• ACID transactions – write‑ahead log, crash recovery, commit/rollback.
• Durable event streams – named change‑feeds share the same WAL, useful for reactive agents.
• Bindings – clean C API wrapped for Python, TypeScript/Node, Go, and Java (JDK 21+).
• Zero‑config, single‑writer model – ideal for local‑first apps where only one process writes.

Performance highlights (benchmarks supplied)

Operation	Latency	Throughput
Node lookup	0.13 µs	7.9 M ops/s
10‑NN vector search (1 M vectors)	0.83 ms (mean)	1.2 k queries/s
2‑hop graph traversal (100 K nodes)	39 µs	–
BM25 full‑text search (100 docs)	19 µs	53 k ops/s
These numbers are comparable to or better than popular alternatives (FAISS, Weaviate, SQLite‑FTS5, Neo4j) for the same workload, while staying fully embedded.

Installation

• CLI – curl …/install.sh | bash
• Python – pip install latticedb
• Node – npm install @hajewski/latticedb
• Java – Maven/Gradle via the bindings/java module (requires JDK 21)
• Go – go get then follow bindings/go/README.md

Quick example (Python)

from latticedb import Database
from latticedb.embedding import hash_embed

with Database('knowledge.db', create=True, enable_vectors=True, vector_dimensions=128) as db:
    db.create_node_fts_index('Chunk', 'text')
    with db.write() as txn:
        alice = txn.create_node(labels=['Person'], properties={'name':'Alice'})
        doc   = txn.create_node(labels=['Document'], properties={'title':'Attention Is All You Need'})
        chunk = txn.create_node(labels=['Chunk'], properties={'text':'The transformer architecture uses self‑attention...'})
        txn.set_vector(chunk.id, 'embedding', hash_embed('transformer self‑attention', 128))
        txn.create_edge(chunk.id, doc.id, 'PART_OF')
        txn.create_edge(doc.id, alice.id, 'AUTHORED_BY')
        txn.commit()

    results = db.query(
        """MATCH (c:Chunk)-[:PART_OF]->(d:Document)-[:AUTHORED_BY]->(a:Person)
           WHERE c.embedding <=> $q < 0.5
           RETURN d.title, c.text, a.name
           ORDER BY c.embedding <=> $q LIMIT 5""",
        parameters={'q': hash_embed('attention mechanism', 128)}
    )
    for row in results:
        print(row['d.title'], 'by', row['a.name'])

The same pattern works in TypeScript, Go, and Java, using the language‑specific bindings.

Typical use cases

• Local knowledge graphs – notes, research papers, citation networks where you also want semantic search.
• Agent memory / RAG – store chunks of text with embeddings; agents can retrieve relevant pieces via a single query.
• Prototyping – replace heavyweight client‑server stacks (Neo4j + Weaviate) when developing on a single machine.
• Embedded apps – desktop or mobile tools that need graph‑structured data without a server.

When to look elsewhere

• You need concurrent writers or a networked service – LatticeDB is single‑writer only.
• Your workload is primarily tabular – a relational DB (SQLite, PostgreSQL) will be simpler.
• You must scale across many machines – LatticeDB is designed for a single‑process, single‑machine scenario.

Bottom line – LatticeDB is a genuine, open‑source project that merges graph, vector, and full‑text search into an ultra‑lightweight embedded engine, making it a handy building block for local AI‑augmented applications.