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.8.9 — substrate-batch alpha. The v0.8 line shipped the full RFC 010 commit substrate (mutation commit log + openraft consensus + Jepsen debug history), RFC 014-A cluster mTLS, RFC 011-A forget interface, RFC 009 admission control, RFC 013-A HNSW manifest, and RFC 019 durable jobs/leases. v0.8.9 added a read-connection pool that eliminates recall serialisation (single-AGI clients no longer clog one CPU core). Running live on a 3-node Proxmox cluster with multiple tenants.

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
• ✅ openraft consensus (replaces raft-lite from v0.5.x) — proper leader election, log replication, snapshots
• ✅ 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 mTLS (RFC 014-A) — encrypted + mutually-authenticated cluster transport
• ✅ 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