Skip to content
YantrikDB

Server Quick Start

Single-node mode

Section titled “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

Section titled “1. Create the database and a token”
Terminal window
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

Section titled “2. Start the server”
Terminal window
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

Section titled “3. Talk to it from yql”

In another terminal:

Terminal window
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

Section titled “4. Or talk to it via HTTP”
Terminal window
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

Section titled “5. Or talk to it from Python”
Terminal window
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

Section titled “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

Section titled “Maturity”

Read this before betting your project on it.

YantrikDB Server is v0.5.5 — alpha. The architecture is solid and the code is tested, but it has a few hours of cluster runtime, not years. Be honest with yourself about which column you’re in:

What’s stable

Section titled “What’s stable”
  • ✅ The embeddable engine (yantrikdb crate / pip install yantrikdb) — used in production by the YantrikOS ecosystem since early 2026
  • ✅ The wire protocol and HTTP gateway — covered by 40 tests and end-to-end verified
  • ✅ The CRDT replication semantics — built on the engine’s existing oplog with idempotent apply
  • ✅ 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

What’s new and watching

Section titled “What’s new and watching”
  • 🟡 Multi-node Raft-lite leader election — works in tests and on a real homelab cluster, but hasn’t seen Byzantine failures or network jitter at scale
  • 🟡 The witness daemon — clean tiebreaker design, only deployed once
  • 🟡 Auto-failover — verified happy path, hasn’t survived a chaos-test pass
  • 🟡 Multi-DB replication — works for the default database, less exercised for many databases at once

What’s not done yet

Section titled “What’s not done yet”
  • ❌ Performance benchmarks at scale (10M+ memories)
  • ❌ Schema migration story for engine version bumps
  • ❌ Snapshot transfer for far-behind replicas (oplog catch-up only)
  • ❌ Encrypted-cluster embedding backfill (workaround: don’t enable encryption + replication together until v0.6)
  • ❌ Online resize, hot upgrades, online backups
  • ❌ Reference deployments outside the maintainer’s homelab

When to use it

Section titled “When to use it”
Use caseRecommendation
Personal agent memory, single user✅ Go for it
Self-hosted homelab cluster✅ Go for it — ping us, we’d love feedback
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

Section titled “Next steps”