yantrikdb-mcp

<!-- mcp-name: io.github.yantrikos/yantrikdb-mcp -->
# 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, [Hermes Agent](docs/hermes.md), [Prime Agent](docs/prime-agent.md), and any MCP-compatible client. Ships a portable [Agent Skills](https://agentskills.io) skill — [`skills/persistent-memory`](skills/persistent-memory/SKILL.md) — that teaches any compliant harness the memory golden path.

[![PyPI](https://img.shields.io/pypi/v/yantrikdb-mcp)](https://pypi.org/project/yantrikdb-mcp/)
[![PyPI downloads](https://img.shields.io/pypi/dm/yantrikdb-mcp)](https://pypi.org/project/yantrikdb-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/yantrikdb-mcp)](https://pypi.org/project/yantrikdb-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

**Website:** [yantrikdb.com](https://yantrikdb.com) · **Docs:** [yantrikdb.com/guides/mcp](https://yantrikdb.com/guides/mcp/) · **GitHub:** [yantrikos/yantrikdb-mcp](https://github.com/yantrikos/yantrikdb-mcp) · **Paper:** [Skill as Memory, Not Document](https://doi.org/10.5281/zenodo.20128887)

![yantrikdb-mcp demo: three memories stored over MCP, one recalled by a question that shares no words with it, then think() flagging that two stored beliefs about the same on-call lead contradict each other — the next session's recall comes back with open_conflicts: 1](docs/images/demo.gif)

*Every value on screen is the server's own answer over MCP — driver: [`docs/demo/demo.py`](docs/demo/demo.py), recorded with [`docs/demo/demo.tape`](docs/demo/demo.tape).*

## 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, [Hermes Agent](docs/hermes.md), [Prime Agent](docs/prime-agent.md), 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: Apache-2.0) |
| **Privacy** | All data on your machine. No telemetry. No external services. |

## Install

```bash
# 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](#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.

```json
{
  "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](https://github.com/yantrikos/yantrikdb-server) 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.

```json
{
  "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.

```bash
# 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
```

```json
{
  "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](#skill-substrate-v070) 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](https://github.com/yantrikos/yantrikdb-mcp/issues/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`

## Recommended agent workflow (golden path)

The server injects a golden-path playbook into the agent's system prompt. Since v0.10.0 the default is **digest-first**:

1. **Cold start — one call.** `session(action="digest")` returns a single briefing (narrative chain head, open decisions, unresolved conflicts, pending triggers, stale high-importance memories) — replacing several separate `recall`/`temporal` calls at conversation start. Then `recall` only for the specific thing the current message is about.
2. **During work — capture as you go.** New durable fact → `remember`; a stored fact changed → `correct` (keeps history, avoids contradictions); relationship learned → `graph(action="relate")`.
3. **End of substantial work — conditional.** Only when the session was long or state-changing: