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.

Documentation: docs.urna.dev, with install, a quickstart, the concepts, the guides and the full CLI, build spec, Python and file format reference. Project site: urna.dev.

Install

brew tap hoffresearch/urna
brew install urna

npm install -g @urna/cli

bun, pnpm and yarn install the same package: bun add -g @urna/cli, pnpm add -g @urna/cli, yarn global add @urna/cli.

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. A corpus built with a heavier model, like the pt-BR MiniLM, needs that model on the machine: urna setup --model minilm-multilingual installs it (or m on the plan screen), and the ask tab of urna tui offers the same install when a query needs it. Nothing is downloaded until you say so.

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(), query_text="can I use this offline")
print(hits[0].citation_id, hits[0].score, hits[0].text)

db.search(qvec, 5)                                     # exact
db.search_ann(qvec, 5, 400)                            # hnsw beam (floor: the build's ef_construction), 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; two of them run Python (search-text for its embedder, doctor to probe the environment), the other ten never do. The agent verbs (ask, retrieve, build) take text and use the offline embedder; ask and retrieve search by what the file carries: BM25 plus vectors when the file has a BM25 index, HNSW when it has one, exact otherwise. 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 800   # the beam floor is the build's ef_construction (400)

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/BENCH.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.

Real-query quality is in fakenews-ptbr-urna-benchmark: seven public pt-BR fake-news datasets deduplicated into 23,335 documents, 2,601 queries with relevance judgments, three embedders and three presets each, rebuildable from pinned sources. On the exact preset, nDCG@10 is 0.528 for mpnet, 0.503 for the multilingual MiniLM and 0.326 for potion. The files are on Hugging Face.

The profile names are the forge's ([media] profile = "...", usage section 14). Text-to-image hit@1 over every card: SigLIP2 0.750, wemm-2b 0.744, Jina 0.336, CLIP 0.098. The benchmark is mtg-urna-benchmark, and the .urna files are on Hugging Face; the recipes the forge uses are recorded in python/forge/media_profiles.py and docs/CHANGELOG.

Reference

• docs.urna.dev: the documentation site, with guides, concepts and the full reference
• docs/USAGE.md: every verb, presets, models, builds, install channels
• docs/BENCH.md: how the numbers were measured
• fakenews-ptbr-urna-benchmark and mtg-urna-benchmark: the text and image benchmarks, with their files on Hugging Face
• 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