yantrikdb-client

Python SDK for YantrikDB — a cognitive memory database with persistent typed memory, contradiction handling, and reflection.

Install

# Base (bring your own embeddings)
pip install yantrikdb-client

# Default: sentence-transformers MiniLM (384 dim). Matches the default
# YantrikDB server HNSW dim. Works on Python <= 3.12 smoothly; on Python
# 3.13 may trigger a long onnxruntime source compile via the fastembed
# dep chain.
pip install 'yantrikdb-client[embed]'

# Lightweight: model2vec static embedding (~30MB, pure numpy, no torch,
# no onnxruntime, installs in seconds on Python 3.13+). Opt-in — the
# server must be configured with a matching [embedding] dim = 256.
pip install 'yantrikdb-client[embed-tiny]'

Python 3.13 opt-in (model2vec)

If Python 3.13 makes the default [embed] install impractical, use the lightweight path:

from yantrikdb import ALT_EMBEDDER_TINY, connect
client = connect(url, token=..., embedder=ALT_EMBEDDER_TINY)

And on the server:

[embedding]
strategy = "client_only"
dim = 256   # potion-base-8M outputs 256-dim vectors

Client embedder output dim MUST match the server's HNSW dim. Otherwise remember() will return a 500 on first insert (server panics on dimension mismatch — default server dim is 384).

Quick start

from yantrikdb import connect

client = connect("http://localhost:7438", token="ydb_...")

# Basic memory
client.remember("Alice prefers dark mode", domain="preference")
results = client.recall("what does Alice prefer?")

# Character-substrate primitives (v0.2.0+)
client.remember_self("I overtrust single-source reports under time pressure")
client.remember_rule(
    condition="single-source high-stakes claim",
    action="state uncertainty and request corroboration",
)
client.remember_constraint(
    label="truthfulness_over_pleasing",
    description="Disclose uncertainty even when unwelcome",
    priority=0.95,
)

# Reflect — compose a structured meta-state view for an LLM prompt
reflection = client.reflect(
    "How should I handle this high-stakes single-source claim?",
)
print(reflection.render())

# Packs (server v0.14.0+) — inject mounted-pack knowledge into a prompt
ctx = client.pack_context()
system_prompt = base_prompt + "\n\n" + ctx.prompt
if ctx.pending:
    log.info("packs still reconciling on this node: %s", ctx.pending)

Clusters just work

Point the client at any node of a clustered YantrikDB. Writes that land on a follower are transparently followed to the leader (the token is preserved across the hop) and the client sticks to the leader afterward. Transient 503s are retried for read-only calls; writes are never silently re-sent. Catch NotLeaderError / TransientError from yantrikdb.errors if you want to handle a leadership change yourself.

What's in 0.4.0

• Cluster-correct transport: follows the not_leader (307) hint to the leader with the token re-attached, sticks to it, and re-seeds if it dies. Fixes silently-dropped writes against a follower.
• pack_context() / pack_context_prompt(): fetch mounted-pack constitution + coverage for prompt injection; pending/poisoned surface un-reconciled packs.
• remember(..., idempotency_key=...) for safe retries on single-node and clustered servers (raises IdempotencyConflict on key reuse with different text).
• Read-only retry of transient 503s; typed errors in yantrikdb.errors.

What's in 0.3.0

• [embed-tiny] extra: model2vec static embedding backend — ~30MB, pure numpy, no torch, no onnxruntime. Works on Python 3.13+. Now the default.
• Auto-routing: embedder name selects the backend automatically (model2vec for minishlab/... and *potion* names, sentence-transformers otherwise).

What's in 0.2.0

• Character-substrate primitives: remember_self, remember_rule, remember_hypothesis, remember_constraint, remember_goal, remember_arc, record_signal
• Typed recall: recall_typed(query, memory_type) for filtered retrieval
• Reflect API: reflect(question) composes parallel type-filtered recalls + open conflicts into a Reflection with .render() for LLM prompts
• Auto-embedder: client-side embedding via sentence-transformers.

API surface

• connect(url, *, token, embedder=...) — returns a YantrikClient
• YantrikClient.remember(text, ...) — store a memory
• YantrikClient.recall(query, ...) — semantic search
• YantrikClient.relate(entity, target, relationship) — knowledge graph edge
• YantrikClient.think(...) — trigger consolidation / conflict scan
• YantrikClient.reflect(question, ...) — structured meta-state view
• YantrikClient.pack_context() / pack_context_prompt() — mounted-pack constitution + coverage for prompt injection (server v0.14.0+)
• Typed helpers: remember_self/rule/hypothesis/constraint/goal/arc, record_signal, recall_typed
• YantrikClient.session(...) — context manager for cognitive sessions
• Errors: yantrikdb.errors.{YantrikError, NotLeaderError, TransientError, IdempotencyConflict}

License

MIT