Urna

A vector database in one file, with citations that stay valid.

A .urna file holds the chunks, the embeddings, the source spans, the indices and the search contract. The rust runtime maps it into memory, checks its hashes, and answers with exact cosine scores and a urna://content_hash/chunk_id citation for every hit. It works offline and rebuilds byte for byte. Python builds the file, rust serves it.

Install

brew install hoffresearch/urna/urna

npm install -g urna

cargo install urna

curl -sSf https://raw.githubusercontent.com/hoffresearch/urna/main/scripts/install.sh | sh

Then run setup once. It downloads the offline embedder, prepares a python env and checks the install:

urna setup

Python only, no setup step needed:

pip install "urna[embed]"

Windows, docker, cargo binstall and how to verify a download are in the install reference.

In the terminal

urna setup shows the plan before it writes anything and ends on the doctor checks.

urna tui opens a corpus, validates it, and lets you ask it questions. Each hit shows its score, the stored text and its citation.

urna tui my_corpus.urna

Quickstart

examples/quickstart/ has twelve short paragraphs and the spec that builds them. From a checkout:

urna build --spec examples/quickstart/corpus.toml

urna ask examples/quickstart/out/quickstart.urna "can I use this offline" -k 1

urna retrieve examples/quickstart/out/quickstart.urna "how do citations work" -k 2 --format jsonl

urna cite examples/quickstart/out/quickstart.urna 'urna://sha256:1147b256.../sha256:b5dfeb09...'

urna validate examples/quickstart/out/quickstart.urna

ask prints the answer with its citation, retrieve prints json for another program, cite turns a citation back into the stored text, and validate checks every hash. To build from your own rows, see usage section 13.

What the file guarantees

Python

import urna
from urna.embed_potion import potion_embedder

emb = potion_embedder()
db = urna.open("my_corpus.urna")
qvec = emb.embed_texts(["can I use this offline"])[0]

hits = db.retrieve(qvec, 5, expected_model_hash=emb.model_hash())
print(hits[0].citation_id, hits[0].score, hits[0].text)

db.search(qvec, 5)                                     # exact
db.search_ann(qvec, 5, 100)                            # hnsw, then exact rerank
db.search_hybrid(qvec, "vacina contra covid", 5, 100)  # bm25 + vectors, exact rerank
db.search_graph(qvec, 5, hops=2, ef=100)               # chunk graph from the seeds
db.search_space("clip-vit-b32", ivec, 5)               # one named multimodal space

assert db.validate() is True
info = db.inspect()

Each chunk is a dict with canonical_text, source_uri, byte_start, byte_end and embedding:

urna.build(
    output_path="my_corpus.urna",
    embedding_model="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
    embedding_dim=384,
    chunker_version="fixed-512/1",
    model_hash=model_hash,
    chunks=chunks,
    reproducible=True,
    preset="hybrid",
)

python examples/quickstart/quickstart.py runs the whole loop, build to cited hits, with no network.

CLI

The engine verbs take a file and a vector and never run python. The agent verbs (ask, retrieve, build) take text and use the offline embedder. setup and tui are the terminal ui. urna --help lists all three groups.

urna ask my_corpus.urna "can I use this offline" -k 3

urna retrieve my_corpus.urna "can I use this offline" -k 5 --format jsonl

urna build --spec corpus.toml --dry-run

build reads one toml: the source (sqlite, csv, jsonl, an image dir), the media settings, and one or more embedding models from the registry (potion, clip-vit-b32, siglip2, wemm-2b, ...). Each model becomes a named vector space in the same file. The full spec is in usage section 13.

urna search my_corpus.urna "[0.1, 0.2, ...]" -k 10

urna search-ann my_corpus.urna "[0.1, 0.2, ...]" -k 10 --ef 200

urna search-graph my_corpus.urna "[0.1, 0.2, ...]" -k 10 --hops 2 --ef 100

urna search-space my_corpus.urna "[0.1, ...]" --space "wemm-2b@256" -k 5

urna search-text my_corpus.urna "vacina contra covid funciona" -k 5

urna inspect my_corpus.urna --json

urna validate my_corpus.urna

urna stats my_corpus.urna

urna cite my_corpus.urna 'urna://sha256:1aa9.../sha256:8f314...'

urna media my_corpus.urna --export DIR

urna benchmark my_corpus.urna -q 100 -k 10 --ann 100 --madvise-cold

urna doctor

Benchmarks

100,000 x 384 rows, k=10, one thread, same machine for every store.

Both urna rows return recall@10 = 1.000. Urna's cold open includes checking every section hash before the first answer. Urna does not do updates, filters or concurrent writers. Method and the full table: docs/benchmarks.md.

Measured on a 30,725-chunk pt-br corpus. Recall here is rank stability under quantization, not real-query quality. Details in usage section 6.

Text-to-image hit@1 over every card: siglip2 0.750, wemm-2b 0.744, jina 0.336, clip 0.098. Code and data: mtg-urna-benchmark.

Reference

• docs/usage.md: every verb, presets, models, builds, install channels
• docs/benchmarks.md: how the numbers were measured
• docs/SECURITY.md: reporting, hardening, data governance
• docs/CHANGELOG: releases with measured numbers
• docs/arc/arc.toml: the architecture map
• AGENTS.md: notes for contributors and agents

The crates are urna-format (the container), urna-runtime (search), urna (the binary) and urna-python (the bridge).

Renamed from nest after 0.4.0. A .nest file written by 0.4.0 still opens.

License

MIT, see docs/LICENSE. Hoff Research

Made it simple, but significant (∂μfμν = jν)

Author: Brenner Cruvinel