recall() is one call, and five things happen inside it. Every number here was
measured end-to-end on a labelled clone of a production store, not on a
synthetic set.
BM25 keyword scoring is fused into the vector lane, then an optional cross-encoder reranks the survivors. MRR on the labelled clone moved **0.519 → 0.600 → 0.762** across the two stages — past the embedding model's own exact-cosine ceiling. A verbatim phrase is findable again instead of being averaged into a long record's dominant topic.
There is no additive recency wall; MMR diversity and re-tuned scoring do the work instead. End-to-end MRR on a production clone moved **0.054 → 0.541** when that changed. A relevant old memory beats a fresh irrelevant one, which is the entire premise of relevance-conditioned scoring.
Records longer than the embedder's window are chunked and indexed per window, so a long note is findable by *any* part of it rather than blurred into one averaged vector.
Recall returns the window that actually matched, not the whole record — **~58% fewer characters** across a 400-hit run with the ranking unchanged — plus a *relative* score cutoff that trims the weak tail. The token saving grows with your record length.
`recall(explain=True)` returns the candidate **pool**: every record that entered selection, each with a stable id, the lanes that admitted it, its bm25 strength, and its rank *before and after* fusion. A lane that didn't run says **why** (`never_ran: expand_entities=false`) instead of reporting an ambiguous zero. You can see why a result came back — and why one didn't.
Most memory systems will store a lie, count a retry as new evidence, and leave
half a write behind after a crash. Each of those is closed here, and each
guarantee is enforced by a release-blocking trace contract — 13 of 13
implemented — and proven by crash-kill tests that run in CI.
A write that declares `source=inference` cannot claim `kind=fact` without a verification basis — refused at write time, before any side effect, on **every** write path (record, batch, corrections, replication apply). An agent's guess cannot quietly become your ground truth.
Durable idempotency keys: the same write retried returns the original record — no duplicate, no importance inflation, no certainty bump — even mid-crash, even under full backpressure. A different payload under the same key is a typed conflict, never a silent merge.
A rejected write — backpressure, gate refusal, failed transaction — leaves the engine byte-for-byte untouched: no row, no oplog entry, no calibration drift, no counters. Proven by crash-kill tests in CI, not by comments.
Two read behaviours worth knowing before you branch on them: recall()excludes superseded records by default (pass include_superseded=True for
history — current truth is what an agent should act on), and errors worth
handling arrive as typed exceptions (yantrikdb.IdempotencyConflict,
.Backpressure, .RecallContended, …), all subclassing RuntimeError so
existing handlers keep working.
AES-256-GCM with per-database keys, in the engine and in the server. The
write-ahead oplog is sealed and its freed pages are erased, so “encrypted”
means no record content anywhere in the raw file — enforced by a byte-scan
test that ships in CI alongside a plaintext control that must fail the same
scan. That gap was reported and fixed under
GHSA-84vx-5fgq-5p59,
which names the affected versions if you are pinned to an old one.
A pack is a sealed, signed, measured YantrikDB file. Your local model mounts
it and gains the knowledge, rules and skills inside — then gives them back,
leaving your own memory byte-for-byte as it was.
First-party packs live at [packs.yantrikdb.com](https://packs.yantrikdb.com)
— post-cutoff APIs, breaking releases, domain corpora — all
`official`, `signed`, and measured against control questions before
publication.
[Browse packs →](https://packs.yantrikdb.com)
The sealed manifest carries the retrieval settings its author measured
(`recommended_top_k`, `recommended_min_similarity`), signed with
everything else — a consumer never has to guess a similarity floor for
a corpus they didn't write.
RFC 031: packs mount server-side on a replicated cluster, so a fleet of
agents shares one mounted corpus instead of each carrying its own copy.
The **Ask** button on this site and on the marketplace is
[yantrikdb-assistant](/guides/assistant/) — a support widget that
answers **only** from mounted packs, and refuses before any model is
called when the packs don't cover the question.
