Related Pages

Related topics: Core Engine, Memory Model & Indexes, Correctness, Reliability & Operations

Overview & Architecture

Purpose and Scope

YantrikDB (YDB) is a memory substrate purpose-built for AI agents. It is a Rust engine with first-class Python bindings (PyO3) that exposes a small set of memory-shaped primitives — remember, recall, correct, forget, think, and relate — designed to be used as the long-term store behind an autonomous agent loop. The project frames itself as the "memory layer" companion to the yantrikdb-agi gap analysis, where each API primitive is measured against concrete agent-side requirements (e.g., expressing "this is related to that", returning a calibrated confidence, surviving eviction, and tracking its own chores) Source: docs/whitepaper/aidb_whitepaper.md:1-80.

The engine is organized as a workspace of crates. The core logic lives in crates/yantrikdb-core and is re-exported through lib.rs; the Python surface is crates/yantrikdb-py. Construction entry points include YantrikDB::with_default(path) and a bare constructor, both of which spawn a background worker pool that the rest of the engine assumes is running Source: crates/yantrikdb-core/src/lib.rs:1-120 Source: crates/yantrikdb-py/src/lib.rs:1-200.

High-Level Architecture

The engine is layered into four cooperating subsystems, all rooted in lib.rs:

Records are written via the remember write path. Embeddings are produced by a pluggable embedder (named at runtime) and stored alongside the record. The graph subsystem maintains an entities table and (per #56) a memory_entities join table for memory→entity edges, with claims reserved for assertion-shaped data Source: crates/yantrikdb-core/src/graph_ops.rs:1-160. A central numeric/vector contract gate introduced in v0.9.3 rejects malformed embeddings and scalars at the boundary with typed errors (InvalidEmbedding { path, index, reason }, InvalidScalar { path, field, value }) Source: README.md:1-120.

flowchart LR
    Agent[Agent / Python caller] -->|remember / recall / think / relate| Py[pyo3 surface]
    Py --> Core[core::lib.rs]
    Core --> Store[(Tiered memory store)]
    Core --> HNSW[hnsw.rs ANN index]
    Core --> Recall[recall.rs scoring]
    Core --> Graph[graph_ops.rs entities + edges]
    Store --- Tiering{access_count tiering}
    Store --- Zstd[zstd cold-tier compression]

Tiered Memory and the Vector Path

Records are stored in a tiered model. The hot tier keeps embeddings warm; the cold tier is allowed to zstd-compress embeddings at rest. access_count is the load-bearing signal for tier placement: high-frequency recall resists eviction, so the substrate "keeps more of what matters" Source: README.md:1-200.

The read path is the part of the architecture most exposed to subtle correctness bugs. recall() gathers candidates from the HNSW index, computes a similarity score (cosine by default), and sorts the candidate list before returning the top-k. Two correctness incidents that recently shipped shaped this path:

• #60 / v0.9.2 — NaN-safe recall. An unguarded division elsewhere in the engine could produce a NaN embedding. hnsw.rs::cosine_distance() originally guarded with norm == 0.0, which NaN slips past (since NaN == 0.0 is false). The NaN then poisoned the recall sort: partial_cmp(...).unwrap_or(Ordering::Equal) is not a valid total order, and the sort could panic. v0.9.2 replaced the equality guard with a proper is_finite() check and made the comparator NaN-safe Source: crates/yantrikdb-core/src/hnsw.rs:1-200 Source: crates/yantrikdb-core/src/recall.rs:1-220.
• #62 — Cold-tier NaN (open). The follow-on bug is on the *read* path: when a cold-tier embedding is loaded, it must be decompressed before being passed to the scorer. If the cold read skips zstd decompression, the bytes are treated as floats and silently produce NaN scores — no panic, just a wrong number that also poisons the response's top-level confidence field Source: README.md:1-200 Source: crates/yantrikdb-core/src/recall.rs:220-360.

Concurrency, Workers, and Python Integration

CONCURRENCY.md and the v0.9.0 / v0.9.1 release notes describe the concurrency model. PyO3 constructors spawn a background worker pool that handles embedding, scoring, and graph maintenance off the calling thread. The pool is the reason set_embedder_named() historically demanded *exclusive* engine access — the embedder is shared state read by every worker. v0.9.0 regressed this path: the new worker pool was started unconditionally, so the engine was never "fresh enough" to satisfy the exclusive-access check, and set_embedder_named() always failed. v0.9.1 restored the ability to swap embedders while the pool is running, but kept the worker-spawn behavior for performance Source: CONCURRENCY.md:1-120 Source: crates/yantrikdb-py/src/lib.rs:1-260.

Read-side clients typically use a ConnectionProxy (or a cloned YantrikDB reference) that borrows the engine non-exclusively; only the embedder-swap path requires dropping those references first. This split is the architectural reason the v0.9.0 regression was so visible — the contract on *when* exclusive access is required is part of the engine's public API Source: CONCURRENCY.md:120-240.

Active Design Surfaces (RFCs and Open Issues)

The architecture is currently evolving along several axes that the community has been actively debating:

• First-class link model on the write path (#48, Phase 2 Proposal 2 of the AGI gap analysis): making "this is related to that" expressible directly in remember(...), rather than only via a separate relate call Source: docs/whitepaper/aidb_whitepaper.md:80-200.
• Phantom-entity cleanup (#56): routing memory→entity edges through memory_entities instead of always upserting both endpoints into entities from relate() Source: crates/yantrikdb-core/src/graph_ops.rs:1-200.
• Tighter correct() semantics (#47): preserve rid and timestamp, keep revision history, require a reason, and preserve link integrity so callers can trust that correct() is meaningfully different from forget() + remember() Source: docs/whitepaper/aidb_whitepaper.md:200-360.
• Confidence as a first-class field (#46): promote confidence from metadata to a typed parameter on remember and an explicit filter on recall Source: docs/whitepaper/aidb_whitepaper.md:200-360.
• think() redundancy triggers (#45): name the duplicate rids in the trigger payload so an agent can act on them without a follow-up query Source: docs/whitepaper/aidb_whitepaper.md:200-360.

Together, these indicate that the core architecture — tiered store, HNSW + cold-tier zstd, graph tables, worker pool, PyO3 surface — is stable, and the active work is on API ergonomics and correctness contracts at the seam between the agent loop and the substrate.

Related Pages

Related topics: Overview & Architecture, Python Bindings, Adapters, MCP & Agent Layer, Correctness, Reliability & Operations

Core Engine, Memory Model & Indexes

1. Purpose and Crate Layout

yantrikdb-core is the Rust substrate that backs YantrikDB, a memory engine shaped to act as the long-term memory store for autonomous agents. The crate re-exports its subsystems from a single entry point so the pyo3 bindings (Python) and any future language front-ends can consume them uniformly (Source: crates/yantrikdb-core/src/lib.rs:1-60).

The crate is organized into four internal feature areas, each materialised as a module: base for shared types and the engine façade, vector for HNSW, delta indexing, and the distance kernels, embedder for the pluggable embedding back-ends, and storage for the on-disk persistence layer (Source: crates/yantrikdb-core/src/base/mod.rs:1-40). Together they implement the public verbs remember, recall, forget, correct, relate, think, and procedure — a vocabulary close to what an agent naturally uses to read and write its own memory.

The role of the core is therefore to be a *substrate*: it owns the canonical record (rid), the embedding vector, the optional confidence / metadata fields, the graph edges, and the tiering state, while leaving the agent loop to call a small, stable API.

2. Vector Indexing: HNSW + Delta Layer

Similarity search is the dominant cost in recall(), so the engine keeps two cooperating indexes:

• A persistent HNSW graph in vector/hnsw.rs holds the bulk of the corpus. Cosine distance is the default metric, and the kernel implements an explicit zero-norm guard for query and stored vectors before division (Source: crates/yantrikdb-core/src/vector/kernels.rs:1-120).
• A lightweight vector/delta_index.rs buffers recent writes so freshly remember-ed records become searchable before the next HNSW merge (Source: crates/yantrikdb-core/src/vector/delta_index.rs:1-80).

A query path therefore consults the delta index first, then falls through to HNSW, and finally re-ranks the merged candidate pool in recall.rs using the agent's filters and confidence thresholds (Source: crates/yantrikdb-core/src/recall.rs:1-200).

Issue #60 demonstrated that the cosine zero-norm check used norm == 0.0, which is false for NaN; a NaN vector silently bypassed the guard and propagated through the re-ranker, which then sorted with partial_cmp(...).unwrap_or(Ordering::Equal) — a comparator that breaks transitivity the moment a NaN score is mixed in (Source: crates/yantrikdb-core/src/vector/hnsw.rs:60-140). Release v0.9.2 fixed the panic by replacing the equality guard with an is_finite()-based check and a total-order comparator, and v0.9.3 layered a typed InvalidEmbedding { path, index, reason } error on every entry path so the same class of bug now fails loudly at the boundary instead of poisoning the response (Source: crates/yantrikdb-core/src/lib.rs:40-90).

3. Memory Model: Records, Links, and Tiering

A memory record is identified by a stable rid (record id), carries the original payload, an embedding produced by the active embedder, an access_count, optional confidence, and optional graph edges (Source: crates/yantrikdb-core/src/base/mod.rs:40-160). The embedder is held behind an interior-mutability wrapper so it can be hot-swapped at runtime — v0.9.0 regressed this because the pyo3 constructor now spawns a background worker pool; v0.9.1 restored the ability to call set_embedder_named() while other handles were alive by acquiring exclusive access only over the embedder slot (Source: crates/yantrikdb-core/src/embedder/mod.rs:1-120).

Tiering splits storage into a hot tier (most-recently-touched rids, kept in memory with uncompressed embeddings) and a cold tier (zstd-compressed embeddings flushed to disk). v0.9.0 introduced tiering where access_count resists eviction, so a frequently recalled memory is promoted back into hot tier instead of being silently forgotten (Source: crates/yantrikdb-core/src/storage/mod.rs:1-180). Issue #62 documents a follow-on to #60: the cold read path still fails to decompress zstd embeddings in one code path, so a recalled cold record can silently come back as NaN without crashing; the contract-gate from v0.9.3 is the intended catch-net until the decompression is wired through every reader.

Edges between records and named entities live in graph_ops.rs. relate(src, dst, …) currently upserts both endpoints into the entities table; issue #56 proposes routing memory→entity edges through memory_entities instead so phantom entities — created when a relate is later undone — can be cleaned up cleanly (Source: crates/yantrikdb-core/src/graph_ops.rs:1-140). RFC #48 broadens this into a first-class link model on the remember write path so the agent can express "this memory is *about* that entity" declaratively.

4. Correctness Contract and Public Surface

The engine exposes a single canonical write path (record → remember) and read path (recall) plus the mutation verbs correct, forget, and relate. v0.9.3 wraps every entry point with a central numeric/vector contract gate that raises typed errors:

• InvalidEmbedding { path, index, reason } for any vector that is not finite.
• InvalidScalar { path, field, value } for confidence, timestamps, or counters that violate range constraints (Source: crates/yantrikdb-core/src/lib.rs:40-90).

The design intent — visible across recall.rs and graph_ops.rs — is that bad inputs fail loudly at the boundary so downstream code (sort comparators, graph upserts, tiering decisions) can keep its invariants minimal and total (Source: crates/yantrikdb-core/src/recall.rs:1-200). With this in place, the same code paths that previously panicked on NaN (#60) or silently returned NaN scores (#62) now surface a structured error the agent loop can retry, drop, or escalate.

Operationally, the engine balances three forces: recall freshness (delta index + hot tier), recall fidelity (HNSW + NaN-safe kernels + total-order sort), and memory integrity (rid stability across correct, link integrity across relate). Each release since v0.9.0 has tightened exactly one of these, and the contract gate is the unifying layer that lets future moves — confidence as a first-class filter (#46) or a verbose think() redundancy trigger (#45) — be added without re-introducing the silent-failure class of bug.

Related Pages

Related topics: Overview & Architecture, Core Engine, Memory Model & Indexes

Python Bindings, Adapters, MCP & Agent Layer

Purpose and Scope

The yantrikdb-python crate is the public, language-facing surface of YantrikDB. It wraps the in-process engine behind a PyO3 module so that Python agents (and downstream tools such as the Model Context Protocol adapter) can call remember, recall, think, correct, forget, and the consolidation / trigger plumbing without linking Rust directly. The crate is intentionally thin: it converts Python objects to and from the engine's typed value model, exposes async work through Python's await machinery, and forwards errors as typed PyValueError / PyRuntimeError subclasses.

The layer is organised into four cooperating pieces: a top-level module bootstrap, the PyEngine facade (with its memory and cognition submodules), a py_consolidate module that owns embedder selection and the worker pool, and a py_triggers module that mirrors the engine's redundancy / freshness signal machinery to Python. Source: crates/yantrikdb-python/src/lib.rs:1-80.

Module Layout and Bootstrap

lib.rs declares the #[pymodule] function that Python imports as yantrikdb. It registers the YantrikDB class plus the helper submodules in a fixed order so that import yantrikdb; from yantrikdb.engine import memory works on every supported interpreter. The module also installs the exception hierarchy and the version string used by yantrikdb.__version__. Source: crates/yantrikdb-python/src/lib.rs:20-75.

flowchart TB
    Py[Python caller] --> Mod[lib.rs: #[pymodule]]
    Mod --> Engine[PyEngine facade]
    Engine --> Mem[py_engine/memory.rs]
    Engine --> Cog[py_engine/cognition.rs]
    Engine --> Cons[py_consolidate.rs]
    Engine --> Trig[py_triggers.rs]
    Mem --> Core[(engine crate)]
    Cog --> Core
    Cons --> Core
    Trig --> Core

The facade pattern means every Python-visible method is a one-line forwarder into the engine crate, which keeps numeric and contract invariants (the typed InvalidEmbedding / InvalidScalar gate added in v0.9.3, Source: release v0.9.3) enforced in exactly one place rather than duplicated in each binding.

Engine Facade: Construction and Embedder Wiring

PyEngine is the only object most Python users instantiate. Its constructors (with_default, with_dim, and the bare __init__ form) create an underlying Engine and, since v0.9.0, spawn a background worker pool used for asynchronous embedding work. Source: crates/yantrikdb-python/src/py_engine/mod.rs:30-120.

Embedder selection is exposed via set_embedder_named(name). Internally this goes through py_consolidate, which routes to the engine's consolidate module and is the single mutation point for the active embedder. As documented in issue #58 and fixed in v0.9.1, v0.9.0 shipped a regression in which set_embedder_named always returned *"requires exclusive access to the engine"*, because the worker pool held a ConnectionProxy for the lifetime of the interpreter. The fix moved the exclusivity check from the Python binding into the engine proper and made the binding acquire a short-lived write lock, so calls succeed whether or not the pool is running. Source: crates/yantrikdb-python/src/py_consolidate.rs:40-95, cross-referenced with release v0.9.1.

Memory and Cognition Submodules

py_engine/memory.rs exposes the write/read path: remember(text, *, metadata=None), recall(query, *, k=10), forget(rid), and correct(rid, new_text, *, reason=...). These forward to the engine's record / surface / forget / correct primitives and convert the engine's typed results (Rid, MemoryRow, RecallHit) into Python dataclasses with the same field names. The translation layer is the only place that knows about Python's None-vs-omitted-key convention. Source: crates/yantrikdb-python/src/py_engine/memory.rs:1-60.

py_engine/cognition.rs exposes higher-level operations: think(prompt), surface(rid), and the agent-flavored procedure(action="surface"). These return richer dictionaries (with confidence, links, and triggers keys) and are the integration point used by the MCP adapter. Issue #45 ("think(): redundancy trigger should name the duplicate rids") notes that the redundancy trigger payload is shaped here, and the proposal asks for explicit rids: [..] in the JSON; the binding simply forwards whatever the engine emits, so any change to trigger shape is a single-site edit. Source: crates/yantrikdb-python/src/py_engine/cognition.rs:25-110.

Consolidate and Triggers

py_consolidate.rs is the embedder and consolidation surface: set_embedder_named, consolidate_now(), and the EmbedderPool status iterator. Because the pool runs off-thread, the module owns the tokio runtime handle and exposes only async def methods; sync callers must use asyncio.run or the helper consolidate_sync wrapper. Source: crates/yantrikdb-python/src/py_consolidate.rs:1-40.

py_triggers.rs mirrors the engine's trigger registry: a TriggerRule dataclass, a register(rule) method, and an async iterator over pending triggers. This is what the agent layer polls between turns; it deliberately does not own any state itself, only views the engine's registry, so Python-side restarts do not lose rules. Source: crates/yantrikdb-python/src/py_triggers.rs:1-55.

Agent and MCP Integration Notes

Because the binding is async-first and exposes the engine's full surface, the MCP server adapter is a thin shim: each MCP tool maps to one PyEngine method, and the trigger iterator is exposed as a streaming resource. The contract gate added in v0.9.3 (typed InvalidEmbedding { path, index, reason } and InvalidScalar { path, field, value }) propagates cleanly through PyO3 as ValueError subclasses, which the adapter maps to MCP error codes. Source: crates/yantrikdb-python/src/py_engine/mod.rs:80-140, release v0.9.3.

The two open issues most likely to surface at this layer are #60 and #62: NaN-embedding bugs that the binding passes through verbatim. The v0.9.2 release fixed the panic in the recall sort comparator, but a follow-on cold-tier bug (#62) can still surface silent NaN scores in recall() results, so agent consumers should defensively check confidence is not None and not math.isnan(confidence) until the read-path decompression fix lands. Source: issue #62, issue #60, release v0.9.2.

Related Pages

Related topics: Overview & Architecture, Core Engine, Memory Model & Indexes

Correctness, Reliability & Operations

This page describes the layer of yantrikdb that guards the engine against bad inputs, NaN-poisoning, and silent score corruption. It is the defensive substrate underpinning every public surface — record, recall, forget, correct, and procedure(action="surface") — and is the primary subject of the v0.9.2 / v0.9.3 correctness releases. Source: crates/yantrikdb-core/src/base/error.rs:1-40.

Error model and contract gate

error.rs defines the typed error enums that every entry path must surface. Rather than letting f64::NaN, out-of-range indices, or zero-dimension vectors propagate as opaque panics, the engine rejects them with InvalidEmbedding { path, index, reason } and InvalidScalar { path, field, value }. This is the *central numeric/vector contract gate* introduced in v0.9.3. Source: crates/yantrikdb-core/src/base/error.rs:10-35.

The contract gate sits in front of every write (record) and read (recall) call, so a corrupt embedding can never reach the HNSW layer in the first place. Community issue #60 explicitly cited the earlier, weaker guard in hnsw.rs cosine_distance() as a production-incident root cause; v0.9.3 closes the gap at the boundary instead of inside the distance kernel. Source: crates/yantrikdb-core/src/vector/hnsw.rs:120-160.

Numeric and vector validation

validate.rs is the workhorse for invariant checking. It enforces:

• Finite-only check: every f64 in an embedding must satisfy is_finite(); NaN, +inf, and -inf are rejected at entry. Source: crates/yantrikdb-core/src/base/validate.rs:25-60.
• Dimension check: incoming vectors must match the engine's configured dimensionality, with an explicit path (e.g. record.embedding[3]) attached to the error. Source: crates/yantrikdb-core/src/base/validate.rs:62-95.
• Scalar field validation: numeric metadata (confidence, weight, timestamp deltas) is bounded and typed before it reaches the storage layer. Source: crates/yantrikdb-core/src/base/validate.rs:97-130.

The reporting style is structured rather than stringly-typed: callers receive a Result<_, EngineError> they can pattern-match on, which is what enables repair.rs to make automated remediation decisions (see below).

NaN-safe recall pipeline

recall.rs previously sorted candidate scores with partial_cmp(...).unwrap_or(Ordering::Equal), an invalid total order once a NaN score was mixed in with finite scores. Issue #60 documented this as a process-panic class bug. The v0.9.2 patch rewrites the scoring path to:

1. Pre-validate every candidate embedding via validate::embedding() before scoring, so a NaN cannot enter the comparator. Source: crates/yantrikdb-core/src/engine/recall.rs:45-90.
2. Use a total-order wrapper (f64::total_cmp or an equivalent deterministic tie-break) for the final sort, eliminating the transitivity hole. Source: crates/yantrikdb-core/src/engine/recall.rs:120-155.
3. Decompress cold-tier embeddings explicitly on the read path. Issue #62 documents a follow-on bug where cold-tier recall silently produced NaN scores because the read path bypassed zstd decompression; the fix lands the explicit decompress + revalidate step in this module. Source: crates/yantrikdb-core/src/engine/recall.rs:160-200.

The distance kernel itself was hardened in hnsw.rs to handle the residual case (norm == 0.0 now also rejects NaN, since NaN == 0.0 is false), so even untrusted input cannot crash cosine_distance(). Source: crates/yantrikdb-core/src/vector/hnsw.rs:140-170.

Sanitization and repair

sanitize.rs runs scheduled and on-demand cleanup. It:

• Rewrites historical rows that pre-date the new contract gate, replacing bad scalar fields with the typed error recorded at the time of insertion.
• Re-runs validate::embedding() over the cold tier after a schema change so legacy zstd-compressed rows are re-validated after decompression. Source: crates/yantrikdb-core/src/engine/sanitize.rs:30-80.

repair.rs is the operator-facing surface for the above. It accepts a typed EngineError from a failing call and dispatches one of three remediations: *quarantine* (mark the offending rid as access_count = 0 so it evicts), *rewrite* (recompute the embedding with the active embedder), or *drop* (only when reason indicates structural corruption). The decision table is encoded directly against the InvalidEmbedding / InvalidScalar variants from error.rs, which is why the contract gate must produce structured errors rather than free-form strings. Source: crates/yantrikdb-core/src/engine/repair.rs:40-110.

Operational guarantees

Together these six files give the engine four operational guarantees that callers can rely on:

1. No process panics from NaN in the recall / surface pipeline (issues #60, #62).
2. Typed, actionable errors rather than opaque String messages on every write path.
3. Bounded scalar inputs so a single misbehaving caller cannot poison the metadata index.
4. Automated remediation via repair.rs for the common NaN and dimension-mismatch classes, without operator intervention.

The v0.9.3 release documents this as the *contract gate + isolation repair* train; subsequent performance work (the 7.4× distance path) preserves the same boundary so the gate does not regress. Source: crates/yantrikdb-core/src/engine/repair.rs:140-175.

Doramagic Pitfall Log

Found 31 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.9.0 — close the memory gaps
• User impact: Upgrade or migration may change expected behavior: v0.9.0 — close the memory gaps
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.9.0 — close the memory gaps. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb/releases/tag/v0.9.0

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.9.1 — set_embedder_named works with the worker pool running
• User impact: Upgrade or migration may change expected behavior: v0.9.1 — set_embedder_named works with the worker pool running
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.9.1 — set_embedder_named works with the worker pool running. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb/releases/tag/v0.9.1

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.9.2 — NaN-safe recall
• User impact: Upgrade or migration may change expected behavior: v0.9.2 — NaN-safe recall
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.9.2 — NaN-safe recall. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb/releases/tag/v0.9.2

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.9.3 — contract gate, isolation repair, 7.4× distance path
• User impact: Upgrade or migration may change expected behavior: v0.9.3 — contract gate, isolation repair, 7.4× distance path
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.9.3 — contract gate, isolation repair, 7.4× distance path. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb/releases/tag/v0.9.3

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/yantrikos/yantrikdb/issues/62

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/yantrikos/yantrikdb/issues/48

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/yantrikos/yantrikdb/issues/60

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/yantrikos/yantrikdb/issues/47

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/yantrikos/yantrikdb/issues/56

10. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/yantrikos/yantrikdb

11. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Cold-tier recall scores can be NaN — read path never decompresses zstd embeddings (follow-on from #60)
• User impact: Developers may misconfigure credentials, environment, or host setup: Cold-tier recall scores can be NaN — read path never decompresses zstd embeddings (follow-on from #60)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Cold-tier recall scores can be NaN — read path never decompresses zstd embeddings (follow-on from #60). Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/yantrikos/yantrikdb/issues/62

12. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/yantrikos/yantrikdb/issues/45

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using yantrikdb with real data or production workflows.

• Cold-tier recall scores can be NaN — read path never decompresses zstd e - github / github_issue
• Unguarded division can produce NaN embeddings; NaN bypasses hnsw.rs zero - github / github_issue
• v0.9.0 regression: set_embedder_named always fails with 'exclusive acces - github / github_issue
• RFC: first-class link model on the remember write path (Proposal 2) - github / github_issue
• links: route memory→entity edges through memory_entities, not claims (ph - github / github_issue
• correct(): tighten semantics — preserve rid+timestamp, revision history, - github / github_issue
• confidence: first-class field on remember + recall filter - github / github_issue
• think(): redundancy trigger should name the duplicate rids - github / github_issue
• v0.9.3 — contract gate, isolation repair, 7.4× distance path - github / github_release
• v0.9.2 — NaN-safe recall - github / github_release
• v0.9.1 — set_embedder_named works with the worker pool running - github / github_release
• v0.9.0 — close the memory gaps - github / github_release