# YantrikDB

> YantrikDB is a cognitive memory database for AI agents. It models how memory actually works — temporal decay, semantic consolidation, contradiction detection, knowledge graph, proactive triggers — instead of just storing and retrieving vectors. Open source under AGPL-3.0. Ships as an embeddable Rust/Python engine, a network database with Raft replication, and an MCP server for Claude Code / Cursor / Windsurf / any MCP-compatible agent.

The core insight is **relevance-conditioned scoring**: relevance gates every other signal multiplicatively, so a perfectly relevant old memory surfaces while an irrelevant high-importance memory doesn't. The same engine exposes a typed cognitive state graph (beliefs, goals, intents, preferences with supports/contradicts/causes edges), an append-only outcome ledger for agent-authored skills, and an autonomous `think()` pass that consolidates, detects conflicts, and mines patterns.

The codebase spans three repos:

- [`yantrikos/yantrikdb`](https://github.com/yantrikos/yantrikdb) — the Rust engine (also exposed as a Python package via PyO3)
- [`yantrikos/yantrikdb-server`](https://github.com/yantrikos/yantrikdb-server) — the multi-tenant network database with HTTP gateway, wire protocol, openraft replication
- [`yantrikos/yantrikdb-mcp`](https://github.com/yantrikos/yantrikdb-mcp) — MCP server wrapping the engine

## Quickstart

- [Get started — embeddable engine](https://yantrikdb.com/guides/quickstart/): the 60-second path. `pip install yantrikdb` or `cargo add yantrikdb`, then `db.record()` / `db.recall()` in five lines.
- [MCP setup](https://yantrikdb.com/guides/mcp/): `pip install yantrikdb-mcp`, point Claude Code / Cursor / Windsurf at it, persistent memory across sessions.
- [Server quickstart](https://yantrikdb.com/server/quickstart/): `docker pull ghcr.io/yantrikos/yantrikdb`, run as a multi-tenant database with HTTP API, replication, encryption.
- [Server install — long form](https://yantrikdb.com/server/install/): all install methods (Homebrew, Docker, cargo, manual), encryption setup, systemd service.

## Server / Operator

- [HTTP API reference](https://yantrikdb.com/server/http-api/): every `/v1/*` endpoint — `remember`, `recall`, `forget`, `relate`, `skills/*`, `memories`, `identity-scope`, `cluster`, `health`, structured error envelopes.
- [Cluster mode](https://yantrikdb.com/server/cluster/): openraft consensus, leader election, log replication, mTLS, single-binary witness daemon for 2-node tiebreaks.
- [Encryption at rest](https://yantrikdb.com/server/encryption/): master-key configuration, key rotation, env-driven setup via `YANTRIKDB_ENCRYPTION_KEY_HEX`.
- [Wire protocol](https://yantrikdb.com/server/wire-protocol/): the binary protocol the server speaks alongside the HTTP gateway.
- [YQL — interactive REPL](https://yantrikdb.com/server/yql/): `psql`-style client for poking at a running server.

## Hermes Agent integration

- [Hermes plugin guide](https://yantrikdb.com/guides/hermes/): `pip install yantrikdb-hermes-plugin`, three-line `.env` config, the agent autonomously calls `yantrikdb_remember` / `yantrikdb_recall` / `yantrikdb_stats` during conversations. Embedded backend, sub-millisecond.
- [Hermes dashboard guide](https://yantrikdb.com/guides/hermes-dashboard/): browsing, configuring, and safely maintaining a Hermes agent's YantrikDB memory. Built by community member @wysie. Read-only browsing by default; Admin Mode opt-in for mutating ops.
- [Autonomous Skills](https://yantrikdb.com/guides/autonomous-skills/): the `skill_define` / `skill_search` / `skill_outcome` substrate for agent-authored procedures. Real production data: 17 agent-authored skills on one substrate, 9 with cross-session reuse.

## Architecture & reference

- [Introduction](https://yantrikdb.com/guides/introduction/): the design thesis — why memory isn't just embeddings + cosine.
- [Cognitive memory concept](https://yantrikdb.com/concepts/cognitive-memory/): the cognitive-architecture model behind the engine.
- [Relevance-conditioned scoring](https://yantrikdb.com/concepts/scoring/): how relevance gates every other signal multiplicatively.
- [The cognitive state graph](https://yantrikdb.com/concepts/graph/): typed nodes and edges (beliefs/goals/intents with supports/contradicts/causes).
- [Proactive triggers](https://yantrikdb.com/concepts/triggers/): how `db.think()` surfaces decaying memories, unresolved conflicts, and emerging patterns.
- [FAQ](https://yantrikdb.com/faq/): common questions about installation, scaling, embedders, and the engine vs. server vs. MCP distinction.
- [Patent](https://yantrikdb.com/patent/overview/): U.S. Patent Application No. 19/573,392 (filed March 2026) — covers relevance-conditioned scoring and the cognitive state graph.
- [Cortex plugin](https://yantrikdb.com/guides/cortex/): OpenClaw / ClawDBot plugin — personality traits, bond evolution, context assembly.

## Showcase

Real experiments built on YantrikDB. Each shows a different facet of the cognitive-architecture model:

- [Multi-agent ops — which memory is stale?](https://yantrikdb.com/showcase/multi-agent/): five agents watched the same incident, two were on stale data, YDB surfaced exactly which beliefs were live.
- [Volkswagen dieselgate](https://yantrikdb.com/showcase/volkswagen/): twelve years of public record, five polarity contradictions on one tuple, preserved as coexisting claims.
- [Wirecard — the €1.9B that existed and didn't](https://yantrikdb.com/showcase/wirecard/): financial forensics as contradiction reconstruction. Eight polarity contradictions over six years.
- [Legal discovery — testimony vs logs](https://yantrikdb.com/showcase/legal-discovery/): sworn denial and forensic record as first-class structured claims.
- [Rashomon engine](https://yantrikdb.com/showcase/rashomon/): five witnesses to a breach, some lying, ground truth from badge + git logs. Memory as a reasoning substrate.
- [Watergate](https://yantrikdb.com/showcase/watergate/): fifty years of declassified sources, six polarity contradictions on Nixon alone in one query.
- [Shakespeare](https://yantrikdb.com/showcase/shakespeare/): 207 first-person memories, 288 entities auto-extracted, personality derived, character writes a letter in voice.

## Research

- [Skill-as-memory paper](https://yantrikdb.com/papers/skill-substrate/): the substrate thesis behind why agent-authored procedures want a DB surface, not a filesystem one.

## Optional

- [GitHub — engine](https://github.com/yantrikos/yantrikdb)
- [GitHub — server](https://github.com/yantrikos/yantrikdb-server)
- [GitHub — MCP](https://github.com/yantrikos/yantrikdb-mcp)
- [GitHub — Hermes plugin](https://github.com/yantrikos/yantrikdb-hermes-plugin)
- [PyPI — engine](https://pypi.org/project/yantrikdb/)
- [PyPI — MCP](https://pypi.org/project/yantrikdb-mcp/)
- [crates.io — engine](https://crates.io/crates/yantrikdb)
- [crates.io — server](https://crates.io/crates/yantrikdb-server)
- [Homebrew tap](https://github.com/yantrikos/homebrew-tap)
- [Docker images (ghcr.io)](https://github.com/yantrikos?tab=packages)
- [Issues & discussions (engine)](https://github.com/yantrikos/yantrikdb/issues)
- [Issues & discussions (server)](https://github.com/yantrikos/yantrikdb-server/issues)