YantrikDB MCP Server

https://github.com/yantrikos/yantrikdb-mcp
Admin
YantrikDB MCP Server provides persistent cognitive memory, semantic recall, knowledge graphs, and...
Tokens:14,696
Snippets:126
Trust Score:6.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup development environment

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/CONTRIBUTING.md

Commands to create a virtual environment and install the package with development dependencies from the repository root.

```bash
python3.12 -m venv .venv   # or python3.11 / python3.13 — avoid 3.14 for now
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -U pip
pip install -e ".[dev]"
```

--------------------------------

### Install and start the YantrikDB MCP server

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/docs/prime-agent.md

Install the package and start the server using the streamable-http transport. An API key is required for network security.

```bash
pip install yantrikdb-mcp

export YANTRIKDB_API_KEY=$(openssl rand -hex 16)
yantrikdb-mcp --transport streamable-http --host 127.0.0.1 --port 8420
```

--------------------------------

### Install optional dependencies

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/CONTRIBUTING.md

Command to install additional dependencies for SentenceTransformers-based workflows.

```bash
pip install -e ".[dev,torch]"
```

--------------------------------

### Install the YantrikDB skill

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/docs/prime-agent.md

Clone the repository and copy the integration files into the Prime Agent skills directory.

```bash
git clone --depth 1 https://github.com/yantrikos/yantrikdb-mcp
cp -r yantrikdb-mcp/integrations/prime-agent/yantrikdb ~/.prime/agent/skills/
```

--------------------------------

### Verify yantrikdb-mcp installation

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/llms-install.md

Check that the entry point resolves correctly by running the help command.

```bash
yantrikdb-mcp --help
```

--------------------------------

### Install yantrikdb-mcp package

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/llms-install.md

Install the package using pip.

```bash
pip install yantrikdb-mcp
```

--------------------------------

### Installation and Configuration Commands

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/MCP_REDESIGN.md

The installation command for the YantrikDB MCP package and the requirement to update the mcp.json configuration file.

```bash
pip install yantrikdb[mcp] → add 3 lines to mcp.json → agent has persistent memory
```

--------------------------------

### Run server with SSE transport

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/CONTRIBUTING.md

Generates an API key and starts the server using SSE transport on port 8420.

```bash
export YANTRIKDB_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
yantrikdb-mcp --transport sse --port 8420
```

--------------------------------

### Skill Management Session

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

Python examples for defining a new skill, surfacing existing skills, and recording outcomes. Defining skills requires the write gate to be enabled.

```python
# Define (requires gate enabled)
skill(action="define",
      skill_id="workflow.git.commit_clean",
      body="Before commit: run pytest, run lint, write a clear subject + body.",
      skill_type="procedure",
      applies_to=["git", "release"])

# Surface relevant skills for the current task
skill(action="surface", query="how to commit cleanly", top_k=5)

# Record an outcome after using the skill (gated, append-only)
skill(action="outcome", skill_id="workflow.git.commit_clean",
      succeeded=True, note="caught a flake8 issue pre-push")
```

--------------------------------

### Start YantrikDB MCP Server

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/integrations/prime-agent/yantrikdb/SKILL.md

Command to launch the YantrikDB MCP server using the streamable-http transport. Requires a valid YANTRIKDB_API_KEY.

```bash
YANTRIKDB_API_KEY=<your-token> yantrikdb-mcp --transport streamable-http --host 127.0.0.1 --port 8420
```

--------------------------------

### Run integration tests

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/CONTRIBUTING.md

Installs torch dependencies and executes the heavy integration test script test_v14.py.

```bash
pip install -e ".[torch]"
pytest test_v14.py -v
```

--------------------------------

### Install YantrikDB MCP Server

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

Commands to install the YantrikDB MCP server with either the default bundled embedder or the optional high-quality ONNX MiniLM-L6-v2 embedder.

```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]'
```

--------------------------------

### Stats Action Output

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

Example JSON output for the stats action, showing counters for skill definitions and current configuration state.

```json
"skill_substrate": {
  "counters": {
    "skill_defines_accepted": 12,
    "skill_defines_rejected": {"content_scan:A2": 1, "namespace_not_allowed": 3},
    "skill_outcomes_recorded": 47,
    "skill_pending_review": 2
  },
  "config": {
    "writes_enabled": true,
    "write_expires_at": "2026-12-31T00:00:00+00:00",
    "allowed_namespaces": ["workflow", "review"],
    "audit_log_path": "/var/log/yantrikdb/skills.audit.jsonl",
    "rule_requires_review": true,
    "author_origin": "acme-corp-claude-prod"
  }
}
```

--------------------------------

### Handle missing ONNX dependencies error

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

This error occurs when the database requires the 384-dim ONNX model but the necessary dependencies are not installed. It provides a specific pip install command to resolve the issue.

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

--------------------------------

### Interact with YantrikDB Memory

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/integrations/prime-agent/yantrikdb/SKILL.md

Python examples for listing available tools, storing facts, performing semantic recall, and revising existing knowledge.

```python
import yantrikdb

for tool in await yantrikdb.list_tools():
    print(tool["name"], "-", tool["description"])

# Store a durable fact
await yantrikdb.remember(text="User prefers dark mode in the editor", importance=0.7)

# Retrieve by meaning, not keywords
hits = await yantrikdb.recall(query="what editor settings does the user like")
print(hits)

# Revise a fact without losing history (do NOT remember a contradiction)
await yantrikdb.correct(query="editor preference", new_text="User switched to light mode", reason="user said so")
```

--------------------------------

### Install persistent memory skill

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/docs/hermes.md

Clone the YantrikDB repository and copy the persistent-memory skill to the Hermes skills directory to enable automated memory management.

```bash
git clone https://github.com/yantrikos/yantrikdb-mcp
cp -r yantrikdb-mcp/skills/persistent-memory ~/.hermes/skills/
```

--------------------------------

### stats(action="stats")

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

Retrieves current substrate counters and configuration settings.

```APIDOC
## stats(action="stats")

### Description
Returns the current state of the skill substrate, including counters for accepted/rejected definitions and current configuration parameters.

### Response
- **skill_substrate** (object) - Contains counters and current configuration settings.
```

--------------------------------

### Run standard test suite

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/CONTRIBUTING.md

Executes the default test suite located in the tests directory.

```bash
pytest
```

--------------------------------

### Configure SSE Server Deployment Mode

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

Runs the MCP server as a long-running SSE server. Requires generating an API key and configuring the client to 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"
      }
    }
  }
}
```

--------------------------------

### Check server CLI

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/CONTRIBUTING.md

Displays help information and version for the yantrikdb-mcp command.

```bash
yantrikdb-mcp --help
yantrikdb-mcp --version
```

--------------------------------

### Declare the MCP server in settings.json

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/docs/prime-agent.md

Add the YantrikDB server configuration to your Prime Agent settings file.

```json
{
  "mcpServers": {
    "yantrikdb": {
      "type": "http",
      "url": "http://127.0.0.1:8420/mcp",
      "bearerTokenEnvVar": "YANTRIKDB_API_KEY"
    }
  }
}
```

--------------------------------

### Configure MCP server settings

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/llms-install.md

Add the yantrikdb server to the client's MCP configuration file using the default local mode.

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

--------------------------------

### Project File Structure

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/MCP_REDESIGN.md

The directory layout for the YantrikDB MCP server and core library components.

```text
src/yantrikdb/mcp/
├── __init__.py      — main() entry point
├── server.py        — FastMCP server + lifespan
├── tools.py         — tool definitions
└── resources.py     — MCP resources

src/yantrikdb/
├── __init__.py      — YantrikDB class (Rust bindings)
├── consolidate.py   — consolidation logic
├── triggers.py      — trigger evaluation
├── cli.py           — CLI commands
└── api.py           — REST API server
```

--------------------------------

### Production Configuration for YantrikDB

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

Minimum environment variables required to enable write operations in YantrikDB. Defaults are secure, with writes disabled and rate-limiting active.

```bash
YANTRIKDB_SKILLS_WRITE_ENABLED=true
YANTRIKDB_SKILLS_WRITE_EXPIRES_AT=2026-12-31T00:00:00Z
YANTRIKDB_SKILLS_ALLOWED_NAMESPACES=workflow,review,onboarding
YANTRIKDB_SKILLS_AUDIT_LOG=/var/log/yantrikdb/skills.audit.jsonl
YANTRIKDB_SKILLS_AUTHOR_ORIGIN=acme-corp-claude-prod
```

--------------------------------

### skill(action, ...)

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

The primary interface for interacting with the skill substrate, supporting definition, retrieval, and outcome recording.

```APIDOC
## skill(action, ...)

### Description
Performs operations on the skill substrate including defining new skills, surfacing relevant skills via query, and recording outcomes.

### Parameters
- **action** (string) - Required - The operation to perform: "define", "surface", or "outcome".
- **skill_id** (string) - Optional - Required for "define" and "outcome". Must be lowercase dot-separated segments (4-200 chars).
- **body** (string) - Optional - Required for "define". Content of the skill (50-5000 chars).
- **skill_type** (string) - Optional - Required for "define". Must be one of: "procedure", "reference", "lesson", "pattern", "rule".
- **applies_to** (list) - Optional - Required for "define". List of 1-10 lowercase-underscore identifiers.
- **query** (string) - Optional - Required for "surface". The search query for relevant skills.
- **top_k** (integer) - Optional - Used in "surface" to limit results.
- **succeeded** (boolean) - Optional - Required for "outcome". Indicates if the skill usage was successful.
- **note** (string) - Optional - Used in "outcome" to provide context.

### Example
```python
# Define a new skill
skill(action="define",
      skill_id="workflow.git.commit_clean",
      body="Before commit: run pytest, run lint, write a clear subject + body.",
      skill_type="procedure",
      applies_to=["git", "release"])

# Surface relevant skills
skill(action="surface", query="how to commit cleanly", top_k=5)

# Record an outcome
skill(action="outcome", skill_id="workflow.git.commit_clean",
      succeeded=True, note="caught a flake8 issue pre-push")
```
```

--------------------------------

### Configure custom database path

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/docs/hermes.md

Optionally pin the database location by setting the YANTRIKDB_DB_PATH environment variable in the Hermes configuration.

```yaml
mcp_servers:
  yantrikdb:
    command: "yantrikdb-mcp"
    env:
      YANTRIKDB_DB_PATH: "/home/you/agents/memory.db"
```

--------------------------------

### Verify YantrikDB integration

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/docs/prime-agent.md

Test the integration by remembering a fact and recalling it within the Prime Agent kernel.

```python
import yantrikdb
r1 = await yantrikdb.remember(text="deploy window is Friday 6am", importance=0.8)
r2 = await yantrikdb.recall(query="when do we deploy")
print(r1, r2)
```

--------------------------------

### YantrikDB MCP Server Instructions

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/MCP_REDESIGN.md

Standard instructions for the MCP server to manage persistent cognitive memory, including auto-recall, auto-remember, and auto-relate functions.

```text
YantrikDB is your persistent cognitive memory. Use it AUTOMATICALLY.

## Auto-recall (before responding)
- At conversation start, call `recall` with a summary of the user's first message
- When the user references past work, decisions, people, or preferences, call `recall`

## Auto-remember (during conversation)
Proactively call `remember` whenever you encounter:
- Decisions made, user preferences, people & relationships, project context, corrections, important facts

## Auto-relate (knowledge graph)
Call `relate` when you learn about entity relationships

## What NOT to remember
- Ephemeral task details, things derivable from code/git, verbatim code

## Memory quality
- Use specific, searchable text
- Set importance: 0.8-1.0 critical, 0.5-0.7 useful, 0.3-0.5 minor
- Set domain: "work", "preference", "architecture", "people", "infrastructure"
```

--------------------------------

### Configure HTTP Cluster Deployment Mode

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

Forwards tool calls to a YantrikDB HTTP cluster for shared memory and high availability.

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

--------------------------------

### Uninstall yantrikdb-mcp

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/llms-install.md

Remove the package using pip. Note that the database file remains on the system.

```bash
pip uninstall yantrikdb-mcp
```

--------------------------------

### Register YantrikDB in Hermes config

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/docs/hermes.md

Add the YantrikDB MCP server to the Hermes configuration file located at ~/.hermes/config.yaml.

```yaml
mcp_servers:
  yantrikdb:
    command: "yantrikdb-mcp"
```

--------------------------------

### Cite YantrikDB with BibTeX

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/README.md

Use this BibTeX entry to cite the YantrikDB substrate paper in academic or research contexts.

```bibtex
@misc{sarkar2026skill,
  author       = {Sarkar, Pranab},
  title        = {Skill as Memory, Not Document: A Database-Native Substrate for Agent Skill Catalogs},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.20128887},
  url          = {https://doi.org/10.5281/zenodo.20128887},
  orcid        = {0009-0009-8683-1481}
}
```

--------------------------------

### yantrikdb.list_tools

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/integrations/prime-agent/yantrikdb/SKILL.md

Retrieves a list of available tools defined by the YantrikDB MCP server.

```APIDOC
## list_tools()

### Description
Returns a list of available tools discovered from the YantrikDB MCP server.

### Signature
`await yantrikdb.list_tools()`

### Returns
- **list** - A list of dictionaries containing tool names and descriptions.
```

--------------------------------

### yantrikdb.remember

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/integrations/prime-agent/yantrikdb/SKILL.md

Stores a durable fact in the YantrikDB memory store.

```APIDOC
## remember(text, importance)

### Description
Stores a new fact in the persistent memory store.

### Parameters
- **text** (string) - Required - The fact to store.
- **importance** (float) - Required - The importance score of the fact.
```

--------------------------------

### yantrikdb.call_tool

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/integrations/prime-agent/yantrikdb/SKILL.md

Executes a specific tool by name.

```APIDOC
## call_tool(name, arguments)

### Description
Executes a tool by its identifier, useful for non-standard tool names.

### Parameters
- **name** (string) - Required - The name of the tool.
- **arguments** (dict) - Required - The arguments for the tool.
```

--------------------------------

### yantrikdb.correct

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/integrations/prime-agent/yantrikdb/SKILL.md

Revises an existing fact in the memory store.

```APIDOC
## correct(query, new_text, reason)

### Description
Updates or corrects a fact in the memory store while maintaining history.

### Parameters
- **query** (string) - Required - The query to identify the fact to correct.
- **new_text** (string) - Required - The updated fact text.
- **reason** (string) - Required - The justification for the correction.
```

--------------------------------

### yantrikdb.recall

Source: https://github.com/yantrikos/yantrikdb-mcp/blob/main/integrations/prime-agent/yantrikdb/SKILL.md

Retrieves facts from memory based on semantic similarity to the query.

```APIDOC
## recall(query)

### Description
Performs a semantic search to retrieve relevant facts from memory.

### Parameters
- **query** (string) - Required - The search query string.

### Returns
- **hits** (list) - A list of relevant memory entries.
```
Tokens:
Raw