YantrikDB MCP Server

YantrikDB — Cognitive memory for AI agents. Persistent semantic recall, knowledge graph, contradiction detection, and procedural learning. Ships as embeddable engine, network database, or MCP server.

Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

Website: yantrikdb.com · Docs: yantrikdb.com/guides/mcp · GitHub: yantrikos/yantrikdb-mcp · Paper: Skill as Memory, Not Document

At a glance

What it is	An MCP server that gives any MCP-compatible AI agent persistent, structured, queryable memory across sessions
Install	pip install yantrikdb-mcp
Works with	Claude Code, Cursor, Windsurf, Continue, Claude Desktop, any MCP client
Storage	Local SQLite at ~/.yantrikdb/memory.db (or any path; or HTTP cluster)
Embedder	Bundled 64-dim Rust embedder (default), 384-dim ONNX MiniLM ([onnx] extra), 256-dim multilingual (101 languages)
Tools	19 — remember, recall, forget, correct, think, memory, graph, conflict, trigger, session, temporal, procedure, category, personality, stats, skill, gaps, conversation, task
License	MIT (engine: AGPL-3.0)
Privacy	All data on your machine. No telemetry. No external services.

Install

# Default — uses the engine's bundled 64-dim embedder. ~10 MB install,
# ~80 ms cold start, no native ML deps.
pip install yantrikdb-mcp

# Optional: higher-quality 384-dim ONNX MiniLM-L6-v2 embedder (~150 MB install).
# Auto-used when an existing pre-v0.6 database is detected.
pip install 'yantrikdb-mcp[onnx]'

Upgrading from v0.5.x? Your existing database stays at 384 dim — install the [onnx] extra to keep using it transparently. New installs default to the lean bundled embedder. v0.7.0+ pins the engine migration fix automatically. See Embedder backends below.

Configure

The MCP server has three deployment modes. Pick the one that fits your setup.

Mode 1 — Local (default, recommended for single user)

The MCP server runs the engine in-process with a local SQLite database. Fast, private, zero dependencies.

{
  "mcpServers": {
    "yantrikdb": {
      "command": "yantrikdb-mcp"
    }
  }
}

That's it. The agent auto-recalls context, auto-remembers decisions, and auto-detects contradictions — no prompting needed.

Mode 2 — HTTP Cluster (recommended for shared/multi-machine setups)

Forward all tool calls to a YantrikDB HTTP cluster instead of using an embedded engine. The MCP server is a thin stateless client — all memories live on the cluster, accessible from any machine.

Benefits: shared memory across machines, high availability, no local embedder download, no local database.

{
  "mcpServers": {
    "yantrikdb": {
      "command": "yantrikdb-mcp",
      "env": {
        "YANTRIKDB_SERVER_URL": "http://node1:7438,http://node2:7438",
        "YANTRIKDB_TOKEN": "ydb_your_database_token"
      }
    }
  }
}

• Comma-separate multiple nodes for Raft cluster auto-discovery
• Automatic leader-following on failover
• 15s request timeout
• Get the token from the cluster: yantrikdb token create --db your_database

Mode 3 — SSE Server (legacy, single remote instance)

Run the MCP server itself as a long-running SSE server with its own embedded database. Clients connect via HTTP streaming.

# Generate a secure API key
export YANTRIKDB_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")

# Start SSE server
yantrikdb-mcp --transport sse --port 8420

{
  "mcpServers": {
    "yantrikdb": {
      "type": "sse",
      "url": "http://your-server:8420/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Supports sse and streamable-http transports. Note: SSE connections can drop on idle — Mode 2 (HTTP Cluster) is more reliable for shared deployments.

Environment Variables

Variable	Used in Mode	Default	Description
YANTRIKDB_SERVER_URL	Cluster	(unset → local mode)	Comma-separated cluster node URLs
YANTRIKDB_TOKEN	Cluster	(none)	Bearer token for the cluster database
YANTRIKDB_DB_PATH	Local	~/.yantrikdb/memory.db	Database file path
YANTRIKDB_EMBEDDER	Local	auto	Backend selector: auto | bundled | onnx | multilingual
YANTRIKDB_EMBEDDING_MODEL	Local	all-MiniLM-L6-v2	ONNX model name (only used when YANTRIKDB_EMBEDDER=onnx)
YANTRIKDB_SKILLS_WRITE_ENABLED	All	false	Set true to allow agents to author skills via skill(action="define") (see Skill substrate below)
YANTRIKDB_OUTCOMES_WRITE_ENABLED	All	true	Outcome tracking via skill(action="outcome"). Defaults on so the feedback loop works out of the box; set false to lock the outcome substrate. Added in v0.8.1 per #8
YANTRIKDB_API_KEY	SSE server	(none)	Bearer token when serving SSE/HTTP

Embedder backends

Local mode ships three embedders. The MCP picks one automatically; override with YANTRIKDB_EMBEDDER.

Backend	Dim	Cold start	Install size	Language coverage	When it's used
bundled (engine default)	64	~80 ms	~10 MB	English-only	New / empty databases (auto-selected)
onnx (MiniLM-L6-v2)	384	~2 s	~150 MB	English (higher recall)	Existing pre-v0.6 databases (auto-selected), or when set explicitly
multilingual (potion-multilingual-128M)	256	~2 s + ~460 MB download on first use	~10 MB pip + ~500 MB model cache	101 languages (BGE-M3 tokenizer)	Opt-in only via YANTRIKDB_EMBEDDER=multilingual

auto (default) reads the SQLite file at YANTRIKDB_DB_PATH and picks onnx if it already contains memories — preserving recall quality on upgrades — and bundled otherwise. Multilingual is never auto-selected because its 256-dim vectors are incompatible with existing bundled (64-dim) or ONNX (384-dim) databases; opt-in only on fresh databases.

Set YANTRIKDB_EMBEDDER=bundled|onnx|multilingual to override. If you set YANTRIKDB_EMBEDDER=onnx (or auto-detection picks it) without installing the extras, the server fails fast with an install hint:

RuntimeError: Existing DB has memories embedded with the 384-dim ONNX
model, but ONNX deps are missing.
  Install with:  pip install 'yantrikdb-mcp[onnx]'

For the multilingual backend, the engine downloads potion-multilingual-128M (~460 MB tarball) from github.com/yantrikos/yantrikdb-models on first use. The download is SHA-256 verified, extracted into the engine's cache dir, and reused on subsequent starts. No extra Python deps required — the model runs entirely inside the Rust engine.

Why Not File-Based Memory?

File-based memory (CLAUDE.md, memory files) loads everything into context every conversation. YantrikDB recalls only what's relevant.

Benchmark: 15 queries × 4 scales

Memories	File-Based	YantrikDB	Savings	Precision
100	1,770 tokens	69 tokens	96%	66%
500	9,807 tokens	72 tokens	99.3%	77%
1,000	19,988 tokens	72 tokens	99.6%	84%
5,000	101,739 tokens	53 tokens	99.9%	88%

Selective recall is O(1). File-based memory is O(n).

• At 500 memories, file-based exceeds 32K context windows
• At 5,000, it doesn't fit in any context window — not even 200K
• YantrikDB stays at ~70 tokens per query, under 60ms latency
• Precision improves with more data — the opposite of context stuffing

Run the benchmark yourself: python benchmarks/bench_token_savings.py

Tools

19 tools, full engine coverage (added gaps, conversation, task in v0.9.0):

Tool	Actions	Purpose
remember	single / batch	Store memories — decisions, preferences, facts, corrections
recall	search / refine / feedback	Semantic search, refinement, and retrieval feedback
forget	single / batch	Tombstone memories
correct	—	Fix incorrect memory (preserves history)
think	—	Consolidation + conflict detection + pattern mining
memory	get / list / search / update_importance / archive / hydrate	Manage individual memories + keyword search
graph	relate / edges / link / search / profile / depth	Knowledge graph operations
conflict	list / get / resolve / reclassify	Handle contradictions and teach substitution patterns
trigger	pending / history / acknowledge / deliver / act / dismiss	Proactive insights and warnings
session	start / end / history / active / abandon_stale	Session lifecycle management
temporal	stale / upcoming	Time-based memory queries
procedure	learn / surface / reinforce	Procedural memory — learn and reuse strategies
category	list / members / learn / reset	Substitution categories for conflict detection
personality	get / set	AI personality traits from memory patterns
stats	stats / health / weights / maintenance	Engine stats, health, weights, and index rebuilds
skill	define / surface / outcome / get / list	Substrate-native agent skill catalog (writes off by default — see Skill substrate)
gaps	—	v0.9.0 — surface frequently-asked, poorly-answered queries (substrate's known unknowns)

Plus new actions on existing tools in v0.9.0:

• session(action="digest") — one-call boot-time briefing (narrative chain head + open decisions + conflicts + triggers)
• think(maintenance_cycle=True) — autonomous hygiene sleep cycle
• think(last_cycle_only=True) — read the last cycle summary without running
• stats(action="audit_leak") — privacy / leak-candidate audit
• stats(action="skill_outcomes") — durable skill-outcome count
• graph(action="auto_relate" / "record_link" / "record_unlink" / "linked_records" / "recall_with_links") — co-occurrence edges + record-to-record links + link-expanded recall
• conflict(action="auto_resolve") — burn down unambiguous conflicts in one pass
• memory(action="chain_head" / "history") — chain-namespace head + revision history
• trigger(action="prune") — bound the pending-trigger backlog
• remember(summary=...) — draft mode: engine atomizes a long summary into linked semantic facts (end-of-session auto-capture)

See yantrikdb.com/guides/mcp for full documentation.

Skill substrate (v0.8.0+)

YantrikDB exposes a structured agent skill catalog — separate from loose procedure memories. Skills have schema (skill_id, applies_to, triggers, body, type) and are stored in the dedicated skill_substrate namespace so multiple consumers (this MCP, yantrikdb-hermes-plugin, Lane B SDK, WisePick, yantrikdb-server's /v1/skills/* endpoints) all read and write the same substrate. Background: Sarkar 2026 — Skill as Memory, Not Document.

Security model

Skill writes shape future agent behavior across sessions, so the MCP server implements defense-in-depth. Every control has an env-var knob (locked once at startup — C2) and the full state is exposed via stats(action="stats") and the audit log.

Layered controls (