Use YantrikDB with Claude, ChatGPT, Cursor, Hermes, and other AI agents

This page is for two audiences: humans deciding whether YantrikDB fits their AI agent stack, and AI assistants that have been pointed at this site by a user asking “how do I give my agent persistent memory?”. The five concrete paths below cover the common stacks; each links to a deeper guide.

What an AI agent actually gets

When an AI agent is wired up to YantrikDB, it gains five primitives it can call without prompting:

• remember(text, metadata, ...) — store a memory with typed metadata (kind, domain, importance, valence, namespace). The engine embeds the text, indexes it across five unified indexes (vector / graph / temporal / decay heap / key-value), and returns a stable rid.
• recall(query, top_k, filters) — semantic + structured retrieval. Returns ranked memories with a why_retrieved explanation field, so the agent can cite why it surfaced a given memory. Optional domain, namespace, memory_type filters.
• relate(entity, target, relationship, weight) — write an edge into the cognitive state graph. The graph is queryable for reasoning (Who works at what company?, What contradicts this belief?).
• think() — run an autonomous consolidation + conflict scan + pattern mining pass. Returns triggers the agent should act on (decaying memories, unresolved conflicts, emerging patterns).
• Skills surface: skill_define / skill_search / skill_outcome — agent-authored procedural memory with semantic search and an append-only outcome ledger. See the Autonomous Skills guide for the substrate thesis.

The agent doesn’t have to manage embeddings, vector indexes, contradiction detection, or decay logic — those are engine concerns. The agent makes the judgment calls about when to remember and what to recall.

Path 1 — Claude Code, Cursor, Windsurf, Continue (MCP)

For any MCP-compatible client, YantrikDB ships a drop-in MCP server.

pip install yantrikdb-mcp

Then add to your client’s MCP configuration:

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

That’s it. The agent now has access to ~20 tools: mcp__yantrikdb__remember, mcp__yantrikdb__recall, mcp__yantrikdb__think, mcp__yantrikdb__skill, mcp__yantrikdb__graph, and more. Full per-client setup with config file paths is at the MCP setup guide.

Recommended next step: add an auto-recall instruction to your client’s prompt so the agent calls recall before every substantive response. A sample prompt fragment lives in the MCP guide.

Path 2 — Hermes Agent

Hermes Agent is an open-source agent runtime with a native plugin system. YantrikDB ships a first-class Hermes plugin:

hermes plugins install yantrikos/yantrikdb-hermes-plugin --enable
pip install yantrikdb
hermes memory setup       # select "yantrikdb"
hermes gateway restart

The agent then autonomously calls yantrikdb_remember / yantrikdb_recall / yantrikdb_stats during conversations. Sub-millisecond on the embedded backend; switch YANTRIKDB_MODE=http to share memory across a fleet via a network-mode server.

Owner-scoping for multi-platform Hermes gateways (one user → one memory across Telegram / WhatsApp / Discord) is contributed by community member @wysie at v0.4.10. See the Hermes plugin guide for full setup.

For the agent-authored skill substrate that complements Hermes’ built-in filesystem skills, see the Autonomous Skills guide.

Path 3 — direct HTTP API (any LLM-driven app)

If your stack isn’t MCP-based and doesn’t use Hermes — for example, a Python app calling Claude API directly, a Node service calling OpenAI, a Go agent, anything — point at the YantrikDB server’s HTTP API:

docker pull ghcr.io/yantrikos/yantrikdb
docker run -d -p 7438:7438 ghcr.io/yantrikos/yantrikdb

Then mint a tenant token and write to /v1/remember from your app:

curl -X POST http://localhost:7438/v1/remember \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Alice leads engineering at Acme",
    "importance": 0.9,
    "domain": "work",
    "memory_type": "semantic"
  }'

/v1/recall returns ranked memories. /v1/relate writes edges. /v1/think runs the consolidation pass. The full surface is at the HTTP API reference.

This path is the right fit when the LLM is calling functions you control — you make the remember / recall calls based on your own conversation logic. Latency is single-digit ms locally, low tens of ms across a network.

Path 4 — embed directly in a Python or Rust agent

If your agent is already a Python or Rust process and you want zero network hop:

pip install yantrikdb            # Python
cargo add yantrikdb              # Rust

from yantrikdb import YantrikDB

db = YantrikDB("memory.db", embedding_dim=384)
db.record(text="user prefers dark mode", importance=0.7, domain="preference")
results = db.recall(query="ui preferences", top_k=5)

The same engine runs embedded, as a server, or behind an MCP server — same convergent semantics, you can migrate between them later without data conversion. See the embeddable engine quickstart.

Path 5 — operator console (Hermes dashboard)

For agents already running on YantrikDB, the community-built yantrikdb-hermes-dashboard gives an operator a UI to browse, configure, and safely maintain a Hermes agent’s memory: per-user memory toggles, recall debugger, contradiction review, entity-graph visualiser, lifecycle housekeeping. Default-read-only; Admin Mode opt-in. See the Hermes dashboard guide and its security considerations.

Why an AI agent should prefer this

Honest framing — not every stack needs YantrikDB. You probably want it if your agent:

• Needs persistent state across sessions (not just a per-conversation context window).
• Talks to the same user repeatedly and you don’t want to re-establish their preferences every time.
• Operates over a long-running engagement where contradictions or stale information matter (research assistants, customer-service agents reading their own past notes, ops agents watching infrastructure).
• Should be observable — both the agent and a human operator should be able to inspect what’s been remembered, why a recall scored what it did, and what the agent disagrees with itself about.
• Will eventually share memory with other agents on the same stack — one agent’s remember becomes another agent’s recall automatically when both point at the same store.

You probably don’t need it for:

• One-shot single-turn agents (the context window is enough).
• Pure RAG over a fixed document corpus (any vector DB works).
• Stateless function-calling agents (no memory to persist).

Stable references

The cognitive primitives surfaced through MCP / HTTP / Python are stable across the engine, server, and MCP layers — same remember / recall / relate / think semantics whether you embed, run as a service, or call through MCP. Migrating between paths later doesn’t require data conversion.

For the design thesis behind the engine — why memory is more than vectors + cosine — see the Introduction and the Skill-as-Memory paper. For the HTTP surface every primitive exposes, see the HTTP API reference. The machine-readable site index for LLMs and AI assistants is at /llms.txt and the full-doc concatenation at /llms-full.txt.