YantrikDB

Pure-additive binding-surface fix for yantrikdb-hermes-agent v0.3.0 read-only skill bridge work. NO engine code changed; ~30 LOC pyo3 binding extension.

What's new

recall_text now accepts keyword-only namespace / domain / source filter args:

from yantrikdb import YantrikDB

db = YantrikDB.with_default("./mem.db")

# Existing usage works unchanged:
hits = db.recall_text("rust enthusiast", top_k=5)

# v0.7.7 — isolate retrieval to a subspace:
skills = db.recall_text(
    "how to handle JSON parsing edge cases",
    top_k=5,
    namespace="skill_substrate",
)

# Or filter by domain / source:
session_notes = db.recall_text("yesterday's discussion", domain="session/summary")
companion_only = db.recall_text("recent thoughts", source="companion")

Why

The engine had recall_text_filtered(query, top_k, namespace, domain, source) since v0.7.2, but the pyo3 binding only exposed the unfiltered recall_text(query, top_k). Python consumers couldn't isolate retrieval to a specific subspace without reaching for the full recall(query=...) surface.

The yantrikdb-hermes-agent plugin v0.3.0 needs this filter to implement yantrikdb_skill_search — YantrikDB stores skills by convention as records in namespace="skill_substrate" with metadata.record_type="skill", and skill recall must isolate to that namespace to avoid mixing skills with regular memories.

Surface design — Pythonic over symmetric

Two options were considered:

• (A) New method recall_text_filtered(query, top_k, namespace=None, domain=None, source=None) — 1:1 mirror of the Rust API.
• (B) Keyword-only kwargs on existing recall_text(query, top_k=10, *, namespace=None, domain=None, source=None) — single entry point, additive, no source breakage.

Locked on (B) per consumer-side preference (Hermes coordination msg 8994b0a1):

• Existing recall_text(query, top_k) callers unaffected — top_k still works positionally.
• Pythonic kwargs preserve future flexibility (memory_type, time_window) without surface explosion.
• 1:1 mapping with engine method is internal-implementation honesty, not consumer-facing concern.
• General principle locked for future bindings: pyo3 surface should be Pythonic, not a transcription of the Rust signature.

Compatibility

Pure-additive. All three filter args default to None which routes to the existing unfiltered behavior. recall_text(query, top_k=10) continues to work exactly as before.

Tests

1421 lib tests pass. Both feature configs (default + slim) compile.

🤖 Generated with Claude Code