Installation¶

There is nothing to deploy. uniko is a Rust library: you add a crate to Cargo.toml, build a Uniko instance, and the entire memory system — storage, vector and hybrid search, local NLP extraction, and the recall cascade — runs inside your process, backed by the embedded uni-db engine and the uni-xervo model runtime. No server, no daemon, no external vector store.

This page gives you the standard install first, then the advanced knobs — feature flags, model selection, and GPU acceleration — that you reach for only when you need them.

Add the dependency¶

uniko publishes six crates to crates.io. Depend on the uniko-api facade and you get the whole stack; the lower layers are published too if you want to reach one directly.

Requires Rust >= 1.91 (edition 2024) — the workspace's rust-version.

# Cargo.toml
[dependencies]
uniko-api = { version = "0.2.0", features = ["onnx"] }
# ...or depend on a specific layer directly:
uniko-memory = { version = "0.2.0", features = ["onnx"] }
uniko-store  = "0.2.0"

# Cargo.toml
[dependencies]
uniko-api = { git = "https://github.com/rustic-ai/uniko", features = ["onnx"] }

# For working against a local checkout of the workspace.
[dependencies]
uniko-api = { path = "../uniko/crates/uniko-api", features = ["onnx"] }

Build prerequisites¶

Building uniko compiles ONNX Runtime and a large native dependency tree from source, so a few tools must be present before cargo build:

None of this applies if you install the Python wheels — they ship prebuilt.

Python¶

Prebuilt wheels ship on PyPI for CPython 3.10+ (abi3). Install one of these — they all provide the same uniko import and cannot coexist:

pip install uniko          # CPU (Linux x86_64/aarch64, macOS arm64, Windows x64)
pip install uniko-cuda     # NVIDIA CUDA, Linux x86_64
pip install uniko-metal    # Apple Silicon, macOS arm64

The GPU variants are large and may exceed PyPI's per-file limit. If an install fails for that reason, use the project's own PEP 503 index, which serves the same artifacts from the GitHub Release assets:

pip install uniko-cuda --extra-index-url https://rustic-ai.github.io/uniko/packages/

Build a Uniko instance¶

The Uniko facade is the entry point. Everything else hangs off the handle — memory.agent(id) for an agent, agent.session(id) for a conversation:

use uniko_memory::Uniko;

# async fn demo() -> Result<(), uniko_store::UnikoError> {
// Persistent on disk, zero-config defaults. Registers the schema
// (idempotent) and eagerly warms the embedding / NLP models.
let memory = Uniko::open("./memory.db").await?;

// Or ephemeral, e.g. for tests:
let memory = Uniko::in_memory().await?;
# Ok(())
# }

Reach for the builder to tune capabilities — the embedder, an LLM for answer(), streaming ingest, or a fully custom config:

use uniko_memory::{EmbeddingConfig, LlmSpec, Uniko};

# async fn demo() -> Result<(), uniko_store::UnikoError> {
let memory = Uniko::builder()
    .path("./memory.db")
    .embedding(EmbeddingConfig::bge_small_en_v15())
    .llm(LlmSpec::openai("llm/default", "gpt-4o-mini", None))
    .build()
    .await?;
# Ok(())
# }

That is the whole standard install. The sections below are for when you want to understand the crate layering, accelerate on a GPU, or swap models.

The crates¶

uniko is organized as a layer stack where the layer numbers rank meaning, not dependency direction. Most crates depend only on lower layers, with one deliberate exception: L4 uniko-memory depends on L5 uniko-cortex, because cortex's P5/P6 sweeps subscribe to memory's consolidation. The graph database (uni-db) is sealed behind the bottom layer so higher crates never touch it directly.

flowchart TB
    api["uniko-api (facade)"]
    cortex["uniko-cortex (L5)"]
    memory["uniko-memory (L4)"]
    extract["uniko-extract (L3)"]
    pipes["uniko-pipes (L2)"]
    store["uniko-store (L1)"]
    unidb["uni-db + uni-xervo"]

    api --> cortex
    api --> memory
    memory --> cortex
    memory --> extract
    memory --> pipes
    memory --> store
    cortex --> store
    extract --> pipes
    extract --> store
    pipes --> store
    store --> unidb

Advanced: Cargo feature flags¶

The defaults are tuned for a CPU-only build. The flags below turn on optional content-processing paths and hardware acceleration.

uniko-extract¶

[dependencies]
uniko-extract = { path = "../uniko/crates/uniko-extract", features = ["onnx"] }

uniko-memory¶

uniko-store¶

uniko-api¶

The facade forwards exactly five features: onnx, gpu-cuda, gpu-metal, mistralrs, and candle. It does not forward llm or pdf-ocr — enable those on uniko-memory and uniko-extract directly if you need them.

Advanced: models used at runtime¶

uniko registers up to five model aliases in the uni-xervo catalog when a knowledge base opens — two unconditionally (embed/default, nlp/default), three only when the matching capability is configured. Each resolves to a model that uni-xervo loads and runs in-process. With the default configuration the catalog warms models lazily on first use; open eagerly pre-warms them so the first query doesn't pay cold-start latency.

Embedding¶

Embeddings power vector search across every semantically indexed node — Message, Chunk, Observation, Summary, Entity, Fact, and more. The default embedder is BGE-small-en-v1.5 at 384 dimensions. Other presets ship in EmbeddingConfig (e.g. bge_large_en_v15() at 1024-dim, minilm_l6_v2() at 384-dim) and are selectable by short name via EmbeddingConfig::preset(...).

NLP¶

NER and observation extraction route through the nlp/default alias: a multi-task kniv-deberta cascade running through uni-xervo's local/onnx provider. The default artifact is INT8-quantized (onnx/cascade-int8.onnx) for CPU-feasible inference. SRL (semantic role labelling) is gated by UnikoConfig.nlp_srl_enabled; the remaining tasks (POS, NER, DEP, CLS) always run. Extraction adapts gracefully: if the runtime or alias is unavailable, a rule-based path keeps extraction working end-to-end instead of failing.

Reranker¶

The cross-encoder reranker (rerank/default) is enabled by default and re-scores the top recall candidates. It is the cheapest BERT-family option in the box (MS-MARCO MiniLM-L-6-v2, 22M params); disable it by constructing RerankerConfig { enabled: false, ..Default::default() }.

System prerequisites¶

uniko's runtime dependencies are pulled in as crates and built with your application — there is nothing to install separately for the default CPU build.

• ONNX Runtime — the local inference path (embeddings, NLP, reranker) uses ort (ONNX Runtime bindings) through uni-xervo. The default ort configuration downloads/links a prebuilt runtime at build time.
• Model downloads — the default embedding, NLP, and reranker models are pulled from their model repositories on first use (and pre-warmed on open). A fresh machine downloads the default models once, then caches the weights. Use KnowledgeBase::open_with_xervo_no_prefetch for read-only tooling that never embeds or generates, to skip the warm-up cost.
• GPU toolchains (optional) — only required when building with gpu-cuda (CUDA toolkit) or gpu-metal (macOS / CoreML).

Next steps¶