Configuration¶

Configuration is a Rust value, not a config server. Because uniko runs entirely in-process, every model, threshold, and pipeline cadence is a field on one struct — UnikoConfig, in uniko-store — that you set before the KnowledgeBase opens. Start from UnikoConfig::default(), override what you care about, and call validate() to catch constraint violations before they reach the database.

use uniko_store::config::{UnikoConfig, EmbeddingConfig};

let mut config = UnikoConfig::default();
config.embedding = EmbeddingConfig::nomic_v15(); // swap the embedder
config.recall_limit = 20;                        // widen the recall bundle
config.validate()?;                              // fail fast on bad combos

Swappable models¶

uniko's NLP, embedding, and reranking models all resolve through the uni-xervo provider layer. A model is named by a provider id (e.g. local/onnx, local/mistralrs, remote/openai) plus a model id; xervo loads and warms it. Because the model selection is data, not code, you swap a model by editing config fields — no recompile of the pipeline.

flowchart LR
    UC[UnikoConfig] --> E[embedding: EmbeddingConfig]
    UC --> N[nlp: NlpConfig]
    UC --> R[reranker: RerankerConfig]
    E --> X[uni-xervo provider layer]
    N --> X
    R --> X
    X --> ONNX[local/onnx]
    X --> MRS[local/mistralrs]
    X --> REMOTE[remote/openai · remote/voyageai · ...]

The embedder¶

The embedder controls auto-embedding (Message, Chunk, Observation, Summary) and the computed embeddings on Entity, Fact, Topic, Session, and the rest of the graph. The default is BGE-small-en-v1.5 at 384 dimensions, served by the bundled local/onnx provider.

EmbeddingConfig ships several presets as constructor functions, plus a preset(name) lookup for string-keyed selection:

use uniko_store::config::EmbeddingConfig;

// 384d, BERT-based, query-side prefix only — the default.
let embed = EmbeddingConfig::bge_small_en_v15();

// 768d, 8192 context. Adds search_document:/search_query: prefixes.
let embed = EmbeddingConfig::nomic_v15();

// Returns None for an unknown name — callers print the canonical list.
let embed = EmbeddingConfig::preset("bge-large")
    .expect("known preset");

The presets and their key properties, all defined in uniko-store::config:

Each preset also sets the right task prefixes. Nomic uses document_prefix = "search_document: " and query_prefix = "search_query: "; BGE uses a query-only prefix ("Represent this sentence for searching relevant passages: "); MiniLM uses none. These are baked into the preset because the retriever was trained on those literal strings.

By default the embedder resolves through local/onnx. To route embeddings to an OpenAI-compatible endpoint instead, set the provider to "remote/openai" and pass provider_options (this is where a base_url lands):

let mut embed = EmbeddingConfig::bge_small_en_v15();
embed.provider = "remote/openai".into();
embed.provider_options = Some(serde_json::json!({
    "base_url": "http://litellm-cloud:4000/v1"
}));

The NLP cascade¶

NER and observation extraction run through a single ONNX cascade model, kniv-deberta. NlpConfig exposes the model id, the ONNX artifact to load, and a batch size:

use uniko_store::config::NlpConfig;

let nlp = NlpConfig::default();
// model_id:        "dragonscale-ai/kniv-deberta-nlp-base-en-xsmall"
// artifact:        "onnx/cascade-int8.onnx"
// max_batch_size:  16

Swapping the cascade variant (xsmall ↔ small, INT8 ↔ FP32) is a config edit — change model_id or artifact and the loader picks it up.

The cascade's SRL (semantic-role-labelling) head is gated separately on the main config:

config.nlp_srl_enabled = true; // default: true

When true, the pipeline computes SRL frames (one extra ONNX forward per VERB per sentence) and downstream extraction uses them. Set it to false if profiling shows the per-verb re-forward cost is unacceptable for a workload; NlpResult.srl_frames then stays empty and extraction behaves as before.

The reranker¶

After hybrid recall fuses candidates with reciprocal rank fusion, an optional cross-encoder re-scores the top top_n items. The reranker is enabled by default with cross-encoder/ms-marco-MiniLM-L-6-v2:

use uniko_store::config::RerankerConfig;

let rr = RerankerConfig::default();
// enabled:       true
// model_id:      "cross-encoder/ms-marco-MiniLM-L-6-v2"
// top_n:         50
// apply_sigmoid: true
// style:         "cross-encoder"

RerankerConfig ships two presets: RerankerConfig::minilm_l6() (22M params, the default model) and RerankerConfig::bge_base() (BAAI/bge-reranker-base, 278M params, more accurate, CPU-feasible). Both construct with enabled: false; the Default impl flips MiniLM on.

config.reranker = RerankerConfig { enabled: false, ..Default::default() };

Tunable thresholds¶

UnikoConfig exposes the numeric knobs that govern the recall cascade, hybrid fusion, consolidation, and memory decay. All defaults below are from UnikoConfig::default().

Recall and fusion¶

Cascade phase gates¶

The recall cascade runs in phases and exits early once a phase covers the query. Coverage gates and the Phase 1 strategy live here:

| phase2_mmr_lambda | 0.7 | MMR relevance-vs-diversity for Phase 2 dedup (1.0 = pure relevance, 0.0 = pure diversity). | | phase2_mmr_duplicate_threshold | 0.85 | Token-overlap threshold above which a Phase 2 candidate is dropped as a hard duplicate. | | phase2_temporal_enabled | true | Temporal-interval channel; fires only when the query has a parsed temporal phrase. | | phase2_graph_enabled | true | Graph spreading-activation channel; fires only when the query has a resolvable entity seed. | | phase2_graph_damping | 0.85 | PPR damping factor for the graph channel. | | phase2_graph_max_iter | 30 | PPR power-iteration cap for the graph channel. | | phase2_graph_edge_weights | {} | Per-edge-type weight multipliers for graph propagation; empty map uses the built-in default_phase2_graph_edge_weights. |

Entity admission¶

Strict admission keeps NER noise out of the :Entity graph at ingest time — temporal, measurement, and quoted-string spans (already captured as observations) and greeting/discourse fragments mis-tagged as people are dropped, and the low-confidence catch-all is gated:

Consolidation¶

Consolidation (P4) collapses near-duplicate Facts and refreshes their embeddings:

Memory decay¶

Importance decays exponentially and low-importance nodes are pruned:

config.half_life_days = 30.0; // importance * exp(-ln(2)/half_life * age_days)
config.prune_below   = 0.05;  // prune nodes below this importance

Chunking and sessions¶

The chunking thresholds match the ingest pipeline's content router:

Vector index¶

The index algorithm and distance metric are set once at database creation:

use uniko_store::config::{VectorAlgorithm, VectorMetricChoice};

config.vector_algorithm = VectorAlgorithm::HnswSq { m: 16, ef_construction: 100 };
config.vector_metric    = VectorMetricChoice::Cosine;

The default is HnswSq { m: 16, ef_construction: 100 } with Cosine distance. Other variants cover HnswFlat, HnswPq, IvfSq, IvfPq, and IvfRq for different scale / recall / memory trade-offs.

Pipelines, retries, and circuit breaker¶

validate() requires retry_initial_delay_ms <= retry_max_delay_ms.

Blob storage and external files¶

Sparse + ColBERT hybrid retrieval¶

By default recall fuses dense vector search with BM25. A hybrid embedder adds two more channels: a learned-sparse vector (a term-weight distribution over the model vocabulary, better than BM25 at exact-term matching) and a ColBERT multi-vector (one vector per token, scored by late-interaction MaxSim). Both are off unless you choose a hybrid embedder.

The bge-m3 preset is the supported one:

use uniko_store::config::{EmbeddingConfig, RerankerConfig};

let mut config = UnikoConfig::default();
config.embedding = EmbeddingConfig::bge_m3();  // 1024-dim dense
                                               // + 250,002-dim sparse
                                               // + 1024-dim ColBERT
config.recall_sparse_enabled = true;           // turn on the sparse channel
config.reranker = RerankerConfig {
    enabled: true,
    style: "colbert".to_string(),              // MaxSim instead of a cross-encoder
    ..Default::default()
};

Three validate() gates catch the invalid combinations at open time:

• recall_sparse_enabled without sparse_dimensions is an error.
• reranker.style = "colbert" without multivector_dimensions is an error.
• reranker.top_n must be >= recall_limit whenever the reranker is enabled.

Aliases each channel uses¶

The two channels reach the model through different xervo aliases, because the write and query sides need different capabilities:

That is not free historically. A sparse query asks the runtime for a SparseEmbeddingModel and a ColBERT query for a MultiVectorEmbeddingModel, while an EmbedHybrid alias loads a HybridEmbeddingModel — a different trait object. Before uni-xervo 0.18.1 those lookups failed and both channels returned nothing on every query while ingest kept populating the columns normally, so the failure was query-only and silent (rustic-ai/uni-xervo#49). 0.18.1 adapts the hybrid handle to each narrow facade (hybrid_adapter::HybridAsSparse / HybridAsMultiVector), so one alias now covers everything.

If you are pinned below 0.18.1, register separate EmbedSparse / EmbedMultiVector aliases against the same model_id — the per-task preset tables resolve the bare repo id for each head.

What they measure on LoCoMo¶

Both channels were returning nothing until their query paths were fixed (2026-09-19), so no earlier number from them measured anything. The first real measurement, on LoCoMo conv-30 (105 questions, bge-m3, retrieval-only, CPU, all four arms over one shared knowledge base so only the retrieval channel varies):

Read with care:

• Sparse is a regression on this workload. −4.58 pp is well outside the ~0.76 pp run-to-run ingest variance measured on the same conversation, the loss is uniform across Single-hop / Multi-hop / Temporal, and enabling both channels lands below sparse alone. Adversarial questions are the one category that gains (+4.0 pp), which fits a lexical channel being better at "this term never appears" judgements.
• ColBERT is a null result, not a win. +0.76 pp sits exactly on the noise floor and comes from a single question flipping; every category except Single-hop is identical to dense-only. The defensible claim is that its quality effect here is indistinguishable from zero at +27% latency.
• One conversation, no LLM judge, CPU. Enough to say neither channel is free; not enough to generalise across the corpus. Re-measure on your own workload before enabling either.

Verifying a channel is actually live¶

Both channels fail silently if misconfigured. run_sparse_source logs a failed uni.sparse.query at debug and returns an empty hit list, and colbert_rerank logs at warn and keeps the RRF order. In both cases recall still returns results, so an enabled-but-broken channel looks exactly like one that simply did not change the ranking — while still costing a query per variant.

ColBERT fails the same way and is even easier to miss: colbert_rerank warns once per query and keeps the RRF order, so the bundle is still returned, merely un-reranked.

Check, rather than assume:

# The channel prints one line per query on the success path only.
RUST_LOG=uniko_memory=debug <your binary> 2>&1 | grep -E "sparse_source|sparse query failed"

• RECALL_PROF sparse_source label=Chunk rows=N — the channel ran and returned N hits.
• sparse query failed … — it errored; the channel is contributing nothing.
• Neither line — recall_sparse_enabled never took effect.

For ColBERT, grep at warn level instead — one line per query means the reranker is inert:

<your binary> 2>&1 | grep -E "colbert query embed failed|colbert maxsim query failed"

The decisive check for either channel is a differential run: same KB, the channel on and off, comparing per-question results. If the two arms agree on every question, the channel changed nothing — which is what a silent failure looks like.

A quick end-to-end check of the storage layer, independent of recall, lives in crates/uniko-store/tests/sparse_query_alias_repro.rs. It is #[ignore]d because it loads bge-m3 (~2 GB):

cargo nextest run -p uniko-store --test sparse_query_alias_repro \
  --run-ignored all --no-capture

It asserts the columns are populated, the raw uni.sparse.query returns ranked rows, and both recall_sparse_search and recall_colbert_maxsim project them without error.

OCR for scanned PDFs¶

UnikoConfig::ocr configures the OCR model behind tiered PDF extraction — the path that produces :Page / :Block document structure rather than a flat text dump.

Cargo feature flags¶

A few capabilities are gated behind Cargo features so a CPU-only or offline build stays lean. Enable them per crate.

uniko-api forwards exactly five features — onnx, gpu-cuda, gpu-metal, mistralrs, candle. It does not forward llm or pdf-ocr; enable those on uniko-memory / uniko-extract directly.

See also¶

• Architecture — how the layers and the KnowledgeBase fit together.
• Recall — what the cascade phases and fusion weights actually do.