YantrikDB Server Quick Start — Single-Node in 60 Seconds

Single-node mode

Spin up a YantrikDB server on your machine, create a database, mint a token, and start storing memories.

1. Create the database and a token

yantrikdb db --data-dir ./data create default
yantrikdb token --data-dir ./data create --db default
# Prints: ydb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Save that token.

2. Start the server

yantrikdb serve --data-dir ./data

The server is now listening on:

Wire protocol: 0.0.0.0:7437 (binary, multiplexed, fast)
HTTP gateway: 0.0.0.0:7438 (REST + JSON)

3. Talk to it from yql

In another terminal:

yql --host localhost -t ydb_xxxxxxxx...

yql connected to http://localhost:7438
type \h for help, \q to exit

yantrikdb> remember "Alice leads engineering at Acme" importance=0.9 domain=work
✓ stored: 019d623a-3d70-712e-9315-e1da5ee41114

yantrikdb> recall who leads engineering top=5
+---+-------+---------------------------------+--------+
| # | score | text                            | domain |
+---+-------+---------------------------------+--------+
| 1 | 1.41  | Alice leads engineering at Acme | work   |
+---+-------+---------------------------------+--------+

yantrikdb> relate Alice -> Acme as works_at
✓ edge: 019d623a-41cf-71a2 (Alice -[works_at]-> Acme)

yantrikdb> \stats
yantrikdb> \q

4. Or talk to it via HTTP

TOKEN=ydb_xxxxxxxx...

curl -X POST http://localhost:7438/v1/remember \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "First memory", "importance": 0.9, "domain": "work"}'

curl -X POST http://localhost:7438/v1/recall \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "first memory", "top_k": 5}'

5. Or talk to it from Python

pip install yantrikdb-client

from yantrikdb import connect

db = connect("http://localhost:7438", token="ydb_xxxxxxxx...")

db.remember("Alice leads engineering", importance=0.9, domain="work")
results = db.recall("who leads engineering?", top_k=5)
for r in results.results:
    print(f"[{r.score:.2f}] {r.text}")

What’s running

A single yantrikdb serve process gives you:

Multi-tenant database engine — create as many databases as you need with yantrikdb db create <name>
Built-in embeddings — all-MiniLM-L6-v2 via fastembed (no API key)
Background workers — autonomous consolidation, decay, conflict detection
HTTP + wire protocol — bring any client
Bearer token auth — per-database access control
Prometheus metrics — GET /metrics

Maturity

Read this before betting your project on it.

YantrikDB Server is v0.15.1 (versioned independently of the engine — the embeddable core is at v0.14.0). The v0.8–0.10 line shipped the RFC 010 commit substrate (mutation commit log), RFC 011-A forget, RFC 009 admission control, RFC 013-A HNSW manifest, RFC 019 durable jobs, and engine-atomic idempotency keys. The v0.11–0.12 line replaced the library-based cluster path with YRP native replication (RFC 028): a Raft-shaped, simulator-verified safety core plus quorum-durable writes, exactly-once keyed writes, linearizable reads, quarantine-not-wedge recovery, beyond-GC engine backfill, and a chaos gate that blocks any release regressing cluster safety (v0.12.0 removed the openraft path entirely). The v0.13–0.14 line added server-side clustered packs (RFC 031) — a fleet shares one mounted corpus instead of each agent carrying its own copy. Running live on a 4-member Proxmox homelab cluster with a benchmarked ~3-second failover.

What’s stable

✅ The embeddable engine (yantrikdb crate / pip install yantrikdb) — used in production since early 2026
✅ The wire protocol and HTTP gateway — 45+ tests including integration, compatibility, and crash recovery
✅ YRP native replication (RFC 028, v0.11+) — leader election, quorum-durable writes, exactly-once keyed writes, linearizable reads, engine backfill; chaos-gated, live on a 4-member cluster
✅ Single-node mode — no replication overhead, drop-in for any HTTP-speaking client
✅ At-rest encryption (AES-256-GCM) — uses the engine’s audited crypto path
✅ Cluster peer auth — YRP wire messages ride the HTTP plane authenticated by a shared cluster secret (serve over HTTPS to encrypt peer traffic)
✅ Admission control (RFC 009) — per-tenant quotas + circuit breaker, fail-degraded-conservative
✅ Mutation commit log (RFC 010-A) — total-ordered, content-addressed substrate behind every write
✅ Read-connection pool (v0.8.9) — concurrent recall scales linearly with cores instead of serialising
✅ Eager engine warm-up at startup (v0.8.8) — first recall hits a loaded engine, no 8-second cold-load timeout
✅ parking_lot mutexes everywhere — runtime deadlock detection (10s cadence)
✅ Per-handler Prometheus metrics (latency histograms, lock-hold histograms, request counters)

Performance (v0.8.9, Docker on Windows host, 1 vCPU)

Workload	Result
10 concurrent recall	10/10 succeed, p99 143 ms
50 concurrent recall	33×200, 17×503 admission shed, 0 timeouts
Forget invariant under race	0 stale reads (5 readers × 5 probes)

What’s not done yet

❌ Performance benchmarks at scale (10M+ memories)
❌ LongMemEval head-to-head vs Zep / Memento / Mastra (tracked, M5)
❌ Encrypted-cluster embedding backfill on followers (engine method encrypt_embedding is pub(crate); workaround: don’t enable encryption + replication together)
❌ Reference deployments outside the maintainer’s homelab

When to use it

Use case	Recommendation
Personal agent memory, single user	✅ Go for it
Self-hosted homelab cluster	✅ Go for it — hardened and chaos-tested
Backend for an open-source AI tool	✅ Single-node mode is solid
Production SaaS with thousands of users	⏸ Wait for v1.0, or be the lead user
Mission-critical, customer-facing data	⏸ Not yet — pin to a release, run it in parallel with your existing stack first

We’d rather you trust us in the long run than deploy it now and get burned. If you’re an early adopter looking for a real cognitive memory database to grow with — welcome. File issues, file PRs, run it on your homelab, tell us what breaks.

Next steps

Cluster Deployment — add replication and auto-failover
yql REPL — full command reference
HTTP API — REST endpoint reference
Encryption — at-rest AES-256-GCM