YantrikDB MCP Server Setup for Claude Code, Codex, Cursor, Windsurf

YantrikDB MCP gives any MCP-compatible AI agent persistent cognitive memory across sessions. Install once and add a short config block, and the agent gains tools to recall context, store decisions, and surface contradictions.

What actually happens is up to the client. The server ships instructions that describe when memory should be used, but MCP hosts decide whether and when to call a tool. Treat recall-at-start and store-on-decision as behaviour the server encourages, not behaviour it can guarantee — the same config can behave differently in two clients.

Installation

pip install yantrikdb-mcp

Configuration

Add to your MCP client’s configuration:

Claude Code (~/.claude/mcp.json)

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

Codex

codex mcp add yantrikdb -- yantrikdb-mcp

Cursor / Windsurf / Copilot / Kilo Code

Same format — add the yantrikdb server to your MCP settings. The server communicates via stdio, compatible with any MCP client.

Environment Variables

Variable	Default	Description
YANTRIKDB_DB_PATH	~/.yantrikdb/memory.db	Database file path
YANTRIKDB_EMBEDDER	auto	auto | bundled | onnx | multilingual. auto uses the bundled potion-base-2M (64d, no download) for in-memory stores; a new file-backed store fetches potion-base-8M (256d, ~28 MB, SHA-256 pinned) once and falls back to the bundled model when offline.
YANTRIKDB_EMBEDDING_MODEL	—	Only read on the opt-in onnx path (pip install yantrikdb-mcp[onnx]), where it selects the sentence-transformers model. Not used by the default embedder.

Available Tools

The MCP server exposes a set of cognitive memory tools, listed below. (The exact count moves between releases as tools are grouped, so the sections below are the source of truth rather than a headline number.) Many use an action parameter to group related operations into a single tool.

Core Memory

Tool	Actions / Description
remember	Store a memory with importance, domain, valence, certainty, and source
recall	Search memories by semantic similarity with filters (domain, source, type). Includes confidence calibration and certainty reasons
forget	Tombstone a memory permanently
correct	Fix an incorrect memory (preserves history, transfers relationships)
memory	get — retrieve by ID, list — browse with filters, update_importance — adjust score, archive — cold storage, hydrate — restore

Knowledge Graph

Tool	Actions / Description
graph	relate — create entity relationships, edges — get relationships, search — find entities, profile — entity intelligence, depth — relationship depth score

Cognition & Conflicts

Tool	Actions / Description
think	Run a cognition pass — consolidation, conflict detection, substitution scanning, gossip triggers. Pattern mining and consolidation are opt-in flags (run_pattern_mining, run_consolidation), not part of a default pass
conflict	list — detected contradictions, get — details, resolve — keep_a/keep_b/merge/keep_both, dismiss — close without resolving, reclassify — change type and teach substitution categories, scan — force conflict detection
trigger	pending — undelivered insights, deliver/acknowledge/act/dismiss — lifecycle management, history — past triggers

Substitution Categories (V14)

Tool	Actions / Description
category	list — all categories with member counts, members — inspect a category, learn — teach new members, reset — revert to seed vocabulary

Categories contain interchangeable terms (PostgreSQL, MySQL, MariaDB → “databases”). When two memories differ only by a substitution, it’s flagged as a real conflict instead of redundancy.

Seed categories (8 built-in): databases, cloud_providers, programming_languages, frameworks, roles, infrastructure, editors_tools, llm_providers (~80 terms total).

Learning loop: seed → user corrections via reclassify → LLM suggestions via learn → categories grow over time.

Sessions & Temporal

Tool	Actions / Description
session	start — begin conversation session, end — close with summary, active — current session, history — past sessions, cleanup — abandon stale sessions
temporal	stale — memories needing verification, upcoming — time-relevant memories

Procedural Memory

Tool	Actions / Description
procedure	record — save a strategy/approach, surface — retrieve relevant procedures, reinforce — update effectiveness, stats — effectiveness by domain

Self-improving memory: tracks what strategies work and adapts over time using EMA-based scoring.

Personality & Stats

Tool	Actions / Description
personality	get — current personality traits, derive — recalculate from memories, set — override a trait
stats	Database statistics: memory counts, entities, edges, conflicts, patterns

Inspection

Tool	Actions / Description
atlas	export — render the server’s own store as a Memory Atlas and serve it on 127.0.0.1, status — report running exports. Read-only: the export runs in a child process that never loads the engine, and the server answers only the three export artifacts. Needs engine 0.23.0 or newer; refuses in cluster mode. Added in yantrikdb-mcp 0.24.0

To read one memory closely rather than see the whole store, point the terminal explorer at the same file — it snapshots before reading, so the running server is undisturbed.

How It Works

The server ships instructions that tell the agent when and how to use memory. Whether the agent follows them on any given turn is the host client’s decision, so read the list below as the intended pattern rather than a guarantee:

1. Recall at start — the agent is instructed to search memory for relevant context when a conversation begins
2. Store on decision — decisions, preferences, people, and project context are stored as they come up
3. Relate — entity relationships are created as they are discovered
4. Cognition — think() detects contradictions on recognised relations; consolidation and pattern mining run only when their flags are set
5. Substitution detection — PostgreSQL vs MySQL flagged as a real conflict, not redundancy
6. Correction — when the user corrects a fact, the old memory is tombstoned and a corrected version created
7. Feedback learning — reclassifying conflicts teaches the system new vocabulary

Why Not File-Based Memory?

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

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

Selective recall cost is O(1). File-based is O(n). At 1,000 memories, file-based memory is about 20K tokens; at 5,000 it is about 102K, exceeding 32K and 100K context windows. YantrikDB stays at ~70 tokens with precision that improves as you add more memories.

Run the benchmark: python benchmarks/bench_token_savings.py