# Urna docs

> Documentation for Urna, a vector database in a single .urna file: install it, build a corpus, ask it questions and verify every citation, offline.

- Docs: Install, learn the model, build and query corpora

  - **Get started**
  - [Introduction](https://docs.urna.dev/): urna is a vector database in one memory-mapped file that checks its own hashes, scores hits by exact cosine and cites each one with a stable urna:// id.
  - [Installation](https://docs.urna.dev/installation): Install the urna binary from Cargo, Homebrew, npm, pip or the one-liners, see what works after each channel, then run urna setup once.
  - [Quickstart](https://docs.urna.dev/quickstart): Build the twelve-paragraph example corpus from a checkout, ask it a question, read the route it took, then cite, validate and open it in the terminal.
  - [Your first corpus](https://docs.urna.dev/first-corpus): Turn your own JSONL rows into a .urna file with urna build, ask it a question, and resolve the citation back to the stored text.

  - **Concepts**
  - [The .urna file](https://docs.urna.dev/concepts/file): What a .urna file holds, how its header, section table and footer fit together, and what the runtime checks before it answers a query.
  - [Citations and hashes](https://docs.urna.dev/concepts/citations): How a urna:// citation is built from content_hash and chunk_id, which changes move it, what the offsets mean, and what file_hash covers.
  - [Search paths and the exact rerank](https://docs.urna.dev/concepts/search): The exact, HNSW, hybrid, graph and named-space search paths in urna, how ask and retrieve pick one, and why every returned score is a real cosine.
  - [The model gate](https://docs.urna.dev/concepts/model-gate): Why urna refuses a text query embedded by a different model than the corpus, what model_hash covers, and where the check runs or does not.
  - [Offline by construction](https://docs.urna.dev/concepts/offline): Where urna touches the network and where it cannot: the runtime has no network stack, queries embed offline, and only installers and setup download.
  - [Presets and stored precision](https://docs.urna.dev/concepts/presets): How urna stores vectors as float32, float16, int8 or int4, what that costs in recall, and how every score discloses its rerank precision.
  - [Reproducible builds](https://docs.urna.dev/concepts/reproducibility): What makes two urna builds byte-identical, the L1, L2 and L3 reproduction levels, the build lock, the embed cache keyed by three hashes, and --rebuild-only.
  - [Media and named spaces](https://docs.urna.dev/concepts/multimodal): How a .urna file carries media blobs and extra named vector spaces, each space with its own model_hash and dim, and how to query one.

  - **Guides**
  - [Build from your own rows](https://docs.urna.dev/guides/build-spec): Build a .urna from SQLite, CSV, JSONL or an image folder with urna build --spec: sources, models, dry runs, pilots, resume and common errors.
  - [Ask and retrieve from the terminal](https://docs.urna.dev/guides/query-cli): Ask a .urna corpus questions from the shell, tune k and candidates, read explain mode, script retrieve with jq, and verify each citation with cite.
  - [Use urna from Python](https://docs.urna.dev/guides/python): Install the urna wheel, build a small .urna file from Python, embed a query offline with potion, search, retrieve cited chunks and resolve a citation.
  - [Open a corpus you downloaded](https://docs.urna.dev/guides/use-a-corpus): Check a .urna file you did not build: validate it, read which embedding model it needs, and set up the query side for potion or registry models.
  - [Give a corpus to an agent](https://docs.urna.dev/guides/agents): Wire a .urna corpus into an LLM agent as a tool: urna retrieve JSONL as the tool result, urna cite as verification, and rules for quoting stored text.
  - [Air-gapped install and queries](https://docs.urna.dev/guides/offline): Install urna on a machine with no network: copy the release files, point the installers at file://, build the Python env from a local wheelhouse.
  - [Verify what you installed](https://docs.urna.dev/guides/verify): Check urna release files with SHA-256 digests, GitHub attestations and the signed tag, and see which checks each channel and artifact actually has.
  - [The terminal explorer](https://docs.urna.dev/guides/tui): Open a .urna file in urna tui, read its manifest and sections, ask it questions offline, check the install, and learn every key binding.
  - [Choose and bring embedding models](https://docs.urna.dev/guides/models): Pick an embedding model from the urna registry, keep the build and query sides on the same model, run fully offline with --model-path, and load heavy presets.
  - [Images and PDFs](https://docs.urna.dev/guides/images): Build an image corpus from a directory or from rows with image paths using urna build, embed pixels into a named space, and index PDF pages.
  - [Tune media compression](https://docs.urna.dev/guides/media-compression): Choose a media profile for an urna image corpus, override single knobs, let the crf gate pick the AV1 rate, or keep JPEGs byte-reversible.
  - [Serve a corpus over HTTP](https://docs.urna.dev/guides/http): Run the FastAPI and Flask examples from the urna repo to answer questions over HTTP with cited chunks, and what to change before serving a real corpus.
  - [Run in Docker](https://docs.urna.dev/guides/docker): Build the urna Docker image from the repository's Dockerfile, a static binary in a scratch image, and run the engine verbs on a mounted corpus.

  - **Project**
  - [Benchmarks](https://docs.urna.dev/benchmarks): urna against hnswlib, usearch, sqlite-vec and lancedb, the size and recall of each build preset, and 38,627 card images in one file, with every condition.
  - [Known limits](https://docs.urna.dev/limits): Where urna 0.5.1 behaves differently from what you might expect, grouped by building, querying, file format and install, with a workaround for each.
  - [Security](https://docs.urna.dev/security): Supported versions, how to report a vulnerability, what the urna hashes prove, how to treat a downloaded .urna file, and where network access exists.
  - [Data governance](https://docs.urna.dev/data-governance): What a .urna file stores, what it leaves out, how to remove or correct content, where processing runs, and which files a build leaves on disk.
  - [Architecture](https://docs.urna.dev/architecture): How urna is built: the four Rust crates, the Python forge, how a build becomes a .urna file, and how a query flows through the runtime to a citation.
  - [Contributing](https://docs.urna.dev/contributing): Set up a urna checkout, run the release gate, pass CI, fuzz the decoders and open a pull request that follows the repository rules.
  - [Changelog](https://docs.urna.dev/changelog): Release history of urna from 0.1.0 to 0.5.1, newest first, with the user-visible changes of each release and the work on main since 0.5.1.
  - [Glossary](https://docs.urna.dev/glossary): Short definitions of the terms used across the urna docs, from blob and BM25 to top-k and vector database, each linked to the page that explains it.
- Reference: Every command, spec key, API and file format detail
  - [Reference overview](https://docs.urna.dev/reference): What the urna reference covers (CLI verbs, build spec, models, Python, Rust, file format, environment) and the conventions every verb follows.

  - **CLI**
  - [CLI overview](https://docs.urna.dev/reference/cli): The 17 verbs of the urna command line in three groups, the five that cover the whole loop, the global flags, and what a bare urna does on a terminal.
  - [urna ask](https://docs.urna.dev/reference/cli/ask): Ask a .urna file a question in plain text and get the stored text of each hit with its urna:// citation, embedded offline and model-gated.
  - [urna retrieve](https://docs.urna.dev/reference/cli/retrieve): Query a .urna file with text and get JSON or JSONL of cited spans, each with its exact cosine score, stored text, citation and file hashes.
  - [urna build](https://docs.urna.dev/reference/cli/build): Reference for urna build, the launcher of the declarative corpus build: flags, how it finds the forge and Python, stages, output and exit codes.
  - [urna search](https://docs.urna.dev/reference/cli/search): Reference for urna search, the exact search verb that takes a query vector as a JSON array and prints every hit with its cosine score and citation.
  - [urna search-text](https://docs.urna.dev/reference/cli/search-text): Search a .urna file by raw text through the sentence-transformers query embedder, with the model gate, and print every hit field for inspection.
  - [urna search-ann](https://docs.urna.dev/reference/cli/search-ann): Reference for urna search-ann, which forces the HNSW path with a JSON query vector, reranks the candidates by exact cosine, and falls back to exact.
  - [urna search-graph](https://docs.urna.dev/reference/cli/search-graph): Reference for urna search-graph, which seeds from the exact top ef, expands over the chunk graph for a number of hops, and reranks the union by cosine.
  - [urna search-space](https://docs.urna.dev/reference/cli/search-space): Reference for urna search-space, the exact search over one named embedding space of a multimodal .urna file, with an optional model_hash assertion.
  - [urna cite](https://docs.urna.dev/reference/cli/cite): Reference for urna cite, which resolves a urna://content_hash/chunk_id citation into the chunk's stored text and source span after checking the content_hash.
  - [urna validate](https://docs.urna.dev/reference/cli/validate): Reference for urna validate, which checks a .urna file's header, section checksums, manifest, footer hash, contract, embedding values and inlined blobs.
  - [urna inspect](https://docs.urna.dev/reference/cli/inspect): Reference for urna inspect, which prints a .urna file's header, section table with checksums, manifest and hashes, as text or as JSON with blobs and spaces.
  - [urna stats](https://docs.urna.dev/reference/cli/stats): Reference for urna stats, which prints a .urna file's size, chunk count, dim, dtype, search contract, model, sections, named spaces and hashes.
  - [urna media](https://docs.urna.dev/reference/cli/media): Reference for urna media, which lists the media blobs a .urna corpus references and exports the inlined ones to files after checking each SHA-256.
  - [urna benchmark](https://docs.urna.dev/reference/cli/benchmark): Reference for urna benchmark, which times exact search on random query vectors, and optionally HNSW with recall@k, a cold-cache pass, or a named space.
  - [urna doctor](https://docs.urna.dev/reference/cli/doctor): Reference for urna doctor, the offline install check that tests the Python env, the potion embedder and one real embed, and exits with a typed code.
  - [urna setup](https://docs.urna.dev/reference/cli/setup): Reference for urna setup, the installer that lays down the offline embedder payload and a Python env, then proves the install with the doctor checks.
  - [urna tui](https://docs.urna.dev/reference/cli/tui): Reference for urna tui, the full-screen terminal explorer that opens a .urna file, shows its sections, asks it questions and runs the install checks.

  - **Build spec**
  - [The spec file](https://docs.urna.dev/reference/spec): Reference for the urna build spec file: TOML, JSON and YAML formats, the seven tables, ${VAR} expansion, path resolution, validation and [corpus].
  - [\[source\]](https://docs.urna.dev/reference/spec/source): Reference for [source] in a urna build spec: sqlite, csv, jsonl and image_dir sources, text and image templates, joins, derive, and row identity.
  - [\[\[models\]\]](https://docs.urna.dev/reference/spec/models): Reference for [[models]] in a urna build spec: model roles, dims, space_dtype, per-model knobs, and which vector spaces each model writes into the file.
  - [\[media\]](https://docs.urna.dev/reference/spec/media): Reference for [media] in a urna build spec: backends, every knob, profiles and their resolved values, the crf gate, ordering, and jxl transcoding.
  - [\[build\] and \[output\]](https://docs.urna.dev/reference/spec/build-output): Reference for [build] and [output] in a urna build spec: the engine preset, dtype, graph and mrl_dim of space 0, output modes, provenance and the cache.
  - [Build artifacts](https://docs.urna.dev/reference/spec/artifacts): Reference for what urna build writes: the .urna files, manifest.json, build.lock.json, the shared embed cache, reproduction levels and every build error.

  - **Models**
  - [Model registry](https://docs.urna.dev/reference/models): Every embedding model preset in the urna forge registry: model id, dims, MRL ladder, dependencies, device rules, model_hash and query contract.
  - [Build presets](https://docs.urna.dev/reference/presets): The storage presets of urna.build (exact, compressed, tiny, nano, hybrid) and the micro recipe: dtype, text encoding, indexes and measured size.

  - **Python**
  - [Module urna](https://docs.urna.dev/reference/python): The urna Python package in 0.5.1, its seven public names, what the pip wheel ships, what needs a repo checkout, and how to install it.
  - [UrnaFile](https://docs.urna.dev/reference/python/urna-file): Reference for urna.UrnaFile, the read-only handle on a .urna file, with its 13 properties and 11 methods for search, retrieve, blobs and validation.
  - [SearchHit and RetrieveHit](https://docs.urna.dev/reference/python/hits): Fields of urna.SearchHit and urna.RetrieveHit, the hit objects urna returns from Python, what each field means, and how to turn a hit into a dict.
  - [urna.build](https://docs.urna.dev/reference/python/build): Reference for urna.build, which writes a .urna file from chunks you already embedded, with all 29 parameters, the presets, the chunk schema and its checks.
  - [Embedders](https://docs.urna.dev/reference/python/embedders): The offline potion embedder in the urna wheel, the lexical floor and registry adapters in the repo checkout, and the two embedder protocols they follow.
  - [Builder pipeline (checkout only)](https://docs.urna.dev/reference/python/builder): The Python modules that live only in the urna repo checkout, the builder pipeline, model fingerprint, forge.retrieve, graph context and manifest readers.
  - [Errors](https://docs.urna.dev/reference/python/errors): The exceptions urna raises in Python, when each one happens, and the exact messages for opening, querying, the model gate and urna.build.
  - [The wheel's urna command](https://docs.urna.dev/reference/python/cli): The urna console command installed by the Python wheel, its four read-only verbs, how it differs from the Rust binary, and the PATH collision between the two.

  - **Rust**
  - [Rust crates](https://docs.urna.dev/reference/rust): The urna-format and urna-runtime crates: what to depend on, the builder, the reader, MmapUrnaFile, its search functions, result types and a runnable example.

  - **File format v1**
  - [Layout](https://docs.urna.dev/reference/format): Byte layout of a .urna v1 file: the 128-byte header, 32-byte section table entries, the manifest, 64-byte aligned payloads and the 40-byte footer.
  - [Sections](https://docs.urna.dev/reference/format/sections): Every section id of the .urna v1 format, which are required, who writes each one, the encodings a reader accepts and the byte layout of each payload.
  - [Encodings](https://docs.urna.dev/reference/format/encodings): The wire encoding registry of .urna v1: ids 0 to 10, zstd limits, the float16, int8 and int4 embedding layouts, the text-codec chooser and intpack.
  - [Hashes and citations](https://docs.urna.dev/reference/format/hashes): Exact preimages of every integrity value in a .urna file: header and section checksums, the footer hash, file_hash, content_hash, chunk_id and the citation id.
  - [Manifest](https://docs.urna.dev/reference/format/manifest): Every field of the .urna v1 manifest, the Capabilities and CapabilitiesExt flags, validation rules, JSON serialization and the additivity rule for new fields.
  - [Compatibility](https://docs.urna.dev/reference/format/compatibility): Which .urna files a 0.5.1 reader accepts, how format v1 grows without breaking old files, legacy NEST files and what makes two builds byte-identical.

  - **Environment**
  - [Environment variables](https://docs.urna.dev/reference/environment): Every URNA_* environment variable urna reads, plus the other variables that change its behavior, with the component that reads each, its default and effect.
  - [Paths and resolution order](https://docs.urna.dev/reference/paths): Where urna keeps the embedder payload, the setup venv and the embed cache, and the exact order it searches for data directories, scripts and Python.
  - [Exit codes](https://docs.urna.dev/reference/exit-codes): Exit codes of every urna command: the typed codes of doctor, setup and build, the engine and agent verbs, the explorer, the installers and the wheel's command.
  - [Typed errors](https://docs.urna.dev/reference/errors): Every error the urna Rust crates return: the 38 UrnaError variants, the 10 RuntimeError variants, and the public functions that panic on misuse.
  - [Query embedder protocol](https://docs.urna.dev/reference/embedder-protocol): How the urna CLI finds, runs and checks the Python scripts that embed a text query: arguments, the JSON on stdout, exit status and lookups.

## Also

- [Every page in one file](https://docs.urna.dev/llms-full.txt): the full docs as markdown
- [Product overview for agents](https://urna.dev/llms.txt): what urna is, install channels, limits
- [Repository](https://github.com/hoffresearch/urna): source, README and the usage guide