Glossary

The jargon used across hvec, its code and this site, with a note on how each term shows up in the tool. Papers are linked by key into the references.

Vectors and similarity

Embedding: A fixed-length list of numbers produced by a model from a piece of text (or an image, or audio) so that similar inputs land near each other. In hvec every chunk of an ingested document becomes one embedding, computed by the collection’s embedding model. See reimers2019sbert.
Vector, dimension: An embedding is a vector; its dimension is how many numbers it has. bge-small-en-v1.5 produces 384 dimensions, text-embedding-3-small produces 1536. Dimension is recorded on every collection because compression behaviour depends on it.
Embedding model versus chat model: Two different models in every RAG pipeline. The embedding model turns text into vectors for retrieval. The chat model (Claude, GPT, Llama) reads the retrieved text and writes the answer. hvec keeps them on separate axes of the benchmark: compression depends on the first, tolerance to degraded retrieval depends on the second.
Metric: The function that scores how close two vectors are. hvec supports three: dot product (inner product, higher is closer), cosine similarity (dot product of the unit-length vectors, so only the angle matters) and L2 (squared Euclidean distance, lower is closer). Set in config as metric and stored per collection.
Normalisation: Scaling a vector to unit length. For normalised vectors dot product and cosine are the same thing, and binary quantization works much better. Most sentence-embedding models already emit normalised vectors.
Nearest-neighbour search, top-k: Finding the k stored vectors closest to a query under the metric. k is the --k flag and the /k command. Exact search scores every stored vector; approximate (ANN) search uses an index to skip most of them.
Index: A data structure (HNSW graph, inverted file, tree) that makes ANN search fast by not scoring every vector. hvec deliberately has none: it scans everything so that any loss it measures comes from the codec and not from the index. See malkov2020hnsw.
Brute-force scan: Scoring every stored vector against the query. Exact, simple and what hvec’s store does.

Compression

Codec: Short for coder-decoder: a pair of functions that compress a vector to bytes and reconstruct it. In hvec a codec is the Codec trait: encode, decode, and crucially score, which computes the metric directly on the compressed bytes. Every collection is stored through one codec and records its name (f32, int8, binary, binary-centred, later pq).
Trained codec, stateless codec: A stateless codec encodes each vector on its own: f32, int8 and binary. A trained codec first learns statistics from the corpus (a mean, a codebook) and encodes relative to them: binary-centred, and PQ when it arrives. In hvec a trained codec is fitted on the first ingest into a collection and its parameters are stored with the collection, so later ingests and every query use the same ones. The parameters are stored once, not per vector, so they do not count towards the compression ratio.
Embedding as compression: An embedding model is itself a lossy codec: it keeps one operation, semantic similarity, and discards the rest, including easy readability. It does not save bytes. A 200-word chunk is about 1 KB of text; its 1536-dimension f32 embedding is 6 KB. What it compresses is the cost of comparing two passages, from “read both” to one dot product. Embeddings are more reversible than they look (morris2023vec2text). hvec’s codecs are a second layer applied to this first one, preserving the same operation while giving the bytes back.
Key versus payload: In retrieval the key is what you search by (the vector) and the payload is what you get back (the chunk text). hvec compresses the key only. The agent never reads a vector, compressed or not; it reads the payload text that the retrieval step returns, uncompressed, into its context window. Compressing the payload itself (summarising or pruning passages before the model reads them, as in jiang2023llmlingua or the production tool headroom2026) is a separate layer that changes what the agent sees rather than what it finds. hvec does not implement payload compression; measuring it as a pipeline stage is on the roadmap.
Homomorphic compression: A compression scheme is homomorphic with respect to an operation when you can apply the operation to the compressed form and get the same result, or a controlled approximation, as on the original. For vector search the operation is the metric. Product quantization with asymmetric distance is the canonical example. The term is borrowed from homomorphic encryption, where the operation is applied to ciphertext.
Baseline: The uncompressed f32 representation. It is exact, so every other codec is measured as a deviation from it. hvec’s f32 codec exists for this reason and is the only codec in milestone 1.
Compressed-domain, asymmetric distance computation (ADC): Scoring where the query stays uncompressed and the stored vector stays compressed. Introduced for PQ in jegou2011pq. The score method on the codec trait is ADC. Symmetric distance compresses both sides and is cheaper but lossier.
Quantization: Mapping continuous values onto a finite set of levels. Every lossy vector codec is a form of it. The classic treatment is gray1984vq.
Scalar quantization, int8: Quantizing each dimension independently, usually to 8 bits with a per-vector or per-dimension scale. About 4× smaller than f32 with small error. The first codec hvec will add.
Binary quantization, 1-bit: Keeping only the sign of each dimension. 32× smaller than f32. Hamming distance between the bit strings estimates the angle between normalised vectors, per charikar2002simhash. Large error on its own, often used as a first pass before re-ranking. gao2024rabitq gives a version with error bounds.
Mean-centred binary, centring: Subtracting the corpus mean from every vector before taking sign bits. Embedding models often emit vectors with a strong shared component, so many dimensions have the same sign across the whole corpus and their bits discriminate nothing; centring spends every bit on how a vector differs from the rest. It is the first step of gong2013itq and of most practical binary schemes. In hvec it is the binary-centred codec, and the SciFact experiments measure what it recovers.
Product quantization (PQ): Split the vector into m sub-vectors, cluster each subspace into 256 centroids with k-means, and store one byte per sub-vector. Distances come from m table lookups. 8× to 64× compression with tunable error. See jegou2011pq and its optimised form ge2014opq.
Codebook, centroid: A codebook is the table of representative vectors a quantizer maps onto; each entry is a centroid. PQ has one codebook per subspace. Codebooks are trained with k-means (lloyd1982kmeans).
Sketch, random projection: Multiplying by a random matrix to reduce dimension while preserving distances within a provable bound (johnson1984jl). A homomorphic codec for L2 with theory attached.
Matryoshka embeddings: Embeddings trained so that the first n dimensions work on their own. Truncation becomes a nearly free codec. See kusupati2022mrl. In hvec, mrl<k> keeps the first k dimensions and composes with any other codec (mrl256+int8); on a model not trained this way the same truncation is a plain lossy projection, which is what the native-versus-post-hoc experiment measures.
Native low-precision embeddings versus post-hoc quantization: A model trained to be truncated or binarised (Matryoshka training, binary-aware training) produces vectors whose small forms were part of the objective. Post-hoc quantization applies a codec to a model that was never trained for it. The question is which gives more retrieval quality per byte; if native wins, the right codec is a different embedding model.
Task prefix: A marker some retrieval models expect in front of the text (search_query: , search_document: for nomic-embed; query: , passage: for E5). Configured per embedding profile in hvec as query_prefix and document_prefix.
Compression ratio: Bytes of the uncompressed f32 vector divided by bytes of the encoded one. The Codec trait reports it; f32 is 1.0, int8 about 4, binary and binary-centred 32.
Homomorphic encryption (HE, FHE), CKKS, ciphertext: Encryption schemes where arithmetic on ciphertext corresponds to arithmetic on the plaintext. Fully homomorphic encryption supports arbitrary computation (gentry2009fhe); CKKS supports approximate real-number arithmetic, which fits inner products on embeddings (cheon2017ckks). An exploration track in hvec, not part of milestone 1.

Retrieval-augmented generation

RAG: Retrieval-augmented generation. Retrieve relevant passages for a question, put them in the prompt, and let a chat model answer from them. Named in lewis2020rag. hvec’s query and shell turns are a RAG pipeline with the codec in the retrieval step.
Chunk, chunking: A passage of a document small enough to embed and retrieve on its own. hvec splits text into overlapping windows of words (--chunk-words, --overlap-words). The chunker is part of the pipeline under test, so it is deterministic and recorded.
Collection: A named set of chunks embedded with one embedding model and stored through one codec. Created by ingest or /new. A collection refuses to mix embedding models.
Context, passages: The retrieved chunks placed in the prompt. --show-context and /context print them.
Prompt version: An identifier for the fixed RAG prompt template. Changing the prompt changes every result, so the version is recorded on each run.
Session: A persisted conversation. Each shell launch creates one; -s name resumes it. Earlier turns are replayed as plain history while each new question retrieves fresh context.
Profile: A named model configuration in config.toml: provider, model id, endpoint, key variable. Chat profiles and embedding profiles are separate. --chat, --embedder and /model select them.
Token: The unit a chat model reads and writes, roughly three quarters of a word. Input and output token counts are recorded per turn because they are the cost.

Measurement

Run, run log: One recorded pipeline execution: setup (collection, embedding model, dimension, codec, metric, chat model) plus outcome (timings, tokens, retrieved chunk ids and scores, question, answer). Stored in SQLite; inspect with runs list and runs show.
KPI: Key performance indicator. The metrics hvec collects to rank codecs: retrieval-side (recall, distance error, bytes per vector, latency) and generation-side (answer correctness, faithfulness, tokens, latency).
Recall@k: Of the k nearest neighbours under exact f32 search, the fraction that a codec’s top-k also contains. 1.0 means the compressed ranking agrees perfectly with the baseline. The standard retrieval metric, used by aumuller2020annb. It measures agreement with f32, not retrieval quality: a codec that swaps two equally relevant passages is penalised as if it had lost one.
Relevance judgments, qrels: Human labels saying which documents are relevant to which queries, the BEIR format being query-id, corpus-id, score (thakur2021beir). hvec question sets carry them as relevant lists; hvec questions import-beir builds them.
nDCG@k, document recall@k: Retrieval quality against relevance judgments. nDCG (normalised discounted cumulative gain) rewards relevant documents near the top of the ranking, each document counted once at the rank of its first chunk. Document recall@k is the fraction of a query’s relevant documents among the top-k chunks’ documents. Both are reported next to recall@k so that agreement with f32 and quality against the labels can be read side by side.
Distance error: The difference between a codec’s estimated score and the exact f32 score for the same pair. hvec reports the mean absolute error.
Answer correctness: Whether the chat model’s answer matches a known gold answer, by exact match or by a judge. The generation-side headline KPI.
Faithfulness: Whether the answer is supported by the retrieved passages rather than invented. Defined as an LLM-scored metric in es2023ragas.
LLM-as-judge: Using a language model to grade another model’s answers. Scales better than humans and has known biases; see zheng2023judge. hvec judge run grades recorded answers for correctness and faithfulness; hvec judge agreement reports how often the judge and the cheap exact / contains rules disagree, and in which direction.
Payload stage: What happens to the retrieved passages between retrieval and the prompt: nothing (none), a naive word truncation, or an external compressor such as Headroom reached over HTTP. Recorded per run with the context size before and after, so that key and payload compression can be crossed in one batch.
Memory loop, memory script: An agent that writes tool results and turns into its store and reads them back on later steps. hvec bench memory replays a script of write and ask steps once per codec, measuring bytes stored, latency and answer quality at every step.
Benchmark matrix: The grid hvec runs: embedding model × codec × payload stage × chat model × dataset. One run per cell.
Experiment: A directory under experiments/ with a hypothesis, a reproducible command, raw results and a write-up. Negative results are kept. Finished write-ups are published on this site.
Gold answers, dataset: A question set with known correct answers, used to score answer correctness. BEIR (thakur2021beir) is a likely source.

Tooling

ONNX, ONNX Runtime, fastembed: ONNX is a portable model format; ONNX Runtime executes it; fastembed is the Rust crate that wraps both to run embedding models locally. hvec’s local embedding provider uses it so benchmarks are free and offline.
OpenAI-compatible: Any server that speaks OpenAI’s /chat/completions and /embeddings HTTP protocol: OpenAI itself, Ollama, vLLM, LM Studio. One hvec provider covers all of them.
SQLite: The single-file database hvec stores everything in: chunks and their encoded vectors, sessions, and the run log. One file means a run, its context and its conversation can be joined later.

Missing a term? Open an issue or edit docs/glossary.md.