YantrikDB Hermes Plugin

https://github.com/yantrikos/yantrikdb-hermes-plugin
Admin
YantrikDB Hermes Plugin is a self-maintaining memory plugin for Hermes Agent that provides duplicate...
Tokens:35,457
Snippets:288
Trust Score:6.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies and run demo scripts

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/assets/demos/skill-lifecycle/README.md

Install the required packages and execute either the deterministic scripted demo or the LLM-driven demo.

```bash
pip install yantrikdb yantrikdb-hermes-plugin openai

# Scripted (no API key, deterministic, ~25s):
python assets/demos/skill-lifecycle/demo.py

# LLM-driven (needs OPENAI_API_KEY, ~10s):
export OPENAI_API_KEY=sk-...
python assets/demos/skill-lifecycle/demo_llm.py
```

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

### Install via pip package

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

Installation using the bundled pip package, which includes both the engine and the provider source.

```bash
source ~/.hermes/hermes-agent/venv/bin/activate
pip install yantrikdb-hermes-plugin     # pulls yantrikdb engine + the provider source
yantrikdb-hermes install                # registers ~/.hermes/plugins/yantrikdb
hermes memory setup                     # → Select "yantrikdb" and press Enter
hermes memory status                    # → Provider: yantrikdb  Status: available ✓
```

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

### Install via pip package with uv

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

Installation for environments using uv where pip is not available.

```bash
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python yantrikdb-hermes-plugin
~/.hermes/hermes-agent/venv/bin/yantrikdb-hermes install
```

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

### Install via hermes plugins install with uv

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

Installation for environments using uv where pip is not available.

```bash
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python yantrikdb
```

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

### Install and Run YantrikDB Hermes Plugin Demo

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/assets/demos/skill-lifecycle/README.md

Install the required packages and execute the demo script to walk through the skill lifecycle steps.

```bash
# In any environment where yantrikdb-hermes-plugin is installed:
pip install yantrikdb-hermes-plugin yantrikdb

# Run the demo (Windows shown — on POSIX, just use `python`):
python assets/demos/skill-lifecycle/demo.py
```

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

### Install via hermes plugins install

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

Standard installation using the Hermes CLI. Requires installing the yantrikdb engine separately in the same Python environment.

```bash
source ~/.hermes/hermes-agent/venv/bin/activate
hermes plugins install yantrikos/yantrikdb-hermes-plugin
pip install yantrikdb                    # ~10 MB; in the same Python env as Hermes
hermes memory setup                      # → Select "yantrikdb" and press Enter
hermes memory status                     # → Provider: yantrikdb  Status: available ✓
```

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

### Run the self-directing memory demo

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/assets/demos/self-directing/README.md

Install the required packages and execute the demo script to observe the self-directing memory loop.

```bash
pip install "yantrikdb>=0.9.0" yantrikdb-hermes-plugin
python demos/self_directing_memory.py
```

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

### Setup Hermes memory provider

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

Use the hermes CLI to interactively select the yantrikdb memory provider.

```bash
hermes memory setup   # select "yantrikdb"
```

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

### Install YantrikDB HTTP Backend

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

Commands to run a YantrikDB container, generate an access token, and configure the environment variables for HTTP mode.

```bash
docker run -d -p 7438:7438 -v yantrikdb-data:/var/lib/yantrikdb \
  --name yantrikdb ghcr.io/yantrikos/yantrikdb:latest
docker exec yantrikdb yantrikdb token --data-dir /var/lib/yantrikdb \
  create --db default --label hermes
# → ydb_abc123...

cat >> ~/.hermes/.env <<EOF
YANTRIKDB_MODE=http
YANTRIKDB_URL=http://localhost:7438
YANTRIKDB_TOKEN=ydb_abc123...
EOF
```

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

### Verify plugin discovery with uv run

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/VERIFICATION.md

Use the hermes memory status command to verify that the yantrikdb plugin is installed and active.

```bash
$ uv run hermes memory status

Memory status
────────────────────────────────────────
  Built-in:  always active
  Provider:  yantrikdb

  Plugin:    installed ✓
  Status:    available ✓

  Installed plugins:
    • byterover  (requires API key)
    • hindsight  (API key / local)
    • holographic  (local)
    • honcho  (API key / local)
    • mem0  (API key / local)
    • openviking  (API key / local)
    • retaindb  (API key / local)
    • supermemory  (requires API key)
    • yantrikdb  (API key / local) ← active
```

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

### Update Option A

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

Updating the plugin and engine dependency for Option A installations.

```bash
source ~/.hermes/hermes-agent/venv/bin/activate
hermes plugins update yantrikdb
pip install --upgrade yantrikdb
hermes gateway restart                    # if Hermes is running as a gateway/service
hermes memory status
```

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

### Reproduce PR Validation Environment

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/tests/comparison/pr-validation/README.md

Commands to clone the PR branch, install the required yantrikdb engine, and execute the validation script.

```bash
# 1. Fresh clone of the PR branch
git clone --branch feat/yantrikdb-memory-plugin \
  https://github.com/spranab/hermes-agent.git /tmp/hermes-pr-test

# 2. Install the engine
pip install yantrikdb>=0.7.6

# 3. Run the validation script
cd /tmp/hermes-pr-test
YANTRIKDB_MODE=embedded YANTRIKDB_DB_PATH=/tmp/yhp-pr.db \
  python3 /path/to/validate.py
```

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

### Enable owner scoping via environment variables

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

Equivalent configuration using environment variables.

```bash
export YANTRIKDB_OWNER_SCOPING=true
export YANTRIKDB_IDENTITY_MAP_PATH=/path/to/identity-map.json
export YANTRIKDB_INCLUDE_BASE_NAMESPACE_RECALL=true
export YANTRIKDB_INCLUDE_LEGACY_ACTOR_NAMESPACE_RECALL=true
```

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

### Run comparison harness commands

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/tests/comparison/README.md

Commands to execute the harness against a single provider, all providers, or to generate a markdown comparison table from the results.

```bash
# Against a single provider (smoke):
python -m tests.comparison.harness --provider holographic

# Against all of them:
python -m tests.comparison.harness --all

# Regenerate the markdown comparison table from findings:
python -m tests.comparison.compare > /tmp/comparison.md
```

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

### Uninstall Option A

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

Uninstalling the plugin and engine for Option A installations.

```bash
source ~/.hermes/hermes-agent/venv/bin/activate
hermes plugins remove yantrikdb
pip uninstall yantrikdb
hermes memory setup                      # choose another provider, or disable external memory
hermes gateway restart                   # if Hermes is running as a gateway/service
```

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

### Run Idle-CPU Benchmarks

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/benchmarks/README.md

Commands to execute different idle CPU benchmark modes. Requires the psutil library.

```bash
python benchmarks/idle_cpu_bench.py curve      # idle CPU vs history depth
python benchmarks/idle_cpu_bench.py compare    # 1 engine vs N, same history
python benchmarks/idle_cpu_bench.py gate       # committed thresholds; exits 1 on fail
```

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

### Uninstall Option B

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

Uninstalling the plugin and engine for Option B installations.

```bash
source ~/.hermes/hermes-agent/venv/bin/activate
yantrikdb-hermes uninstall
pip uninstall yantrikdb-hermes-plugin yantrikdb
hermes memory setup                      # choose another provider, or disable external memory
hermes gateway restart                   # if Hermes is running as a gateway/service
```

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

### Identity map with shared groups

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

Example configuration defining actors and a shared household group.

```json
{
  "actors": {
    "whatsapp:actor-a": "owner:primary-user",
    "telegram:actor-b": "owner:primary-user",
    "whatsapp:actor-c": "owner:secondary-user"
  },
  "groups": {
    "group:household": {
      "members": ["owner:primary-user", "owner:secondary-user"],
      "conversations": ["whatsapp:family-chat", "telegram:family-chat"]
    }
  }
}
```

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

### Run Project Tests

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

Commands to execute unit tests and live integration tests for the plugin.

```bash
python -m pytest tests/                          # unit tests
YANTRIKDB_INTEGRATION_URL=http://localhost:7438 \
YANTRIKDB_INTEGRATION_TOKEN=ydb_... \
  python -m pytest tests/integration/ -v         # live integration
```

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

### Hermes Wave A reproduction steps

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/docs/v0.5-wave-a-e2e-results.md

A sequence of steps to build, configure, and test the Hermes plugin. Prerequisites include an Ollama instance with qwen3.6:27b-64k and a Portainer API key.

```bash
# Pre-reqs: ollama at 192.168.4.35:11434 has qwen3.6:27b-64k pulled,
# Portainer at 192.168.4.157:9443 has the API key, PORRAINER_API_KEY in repo .env.

# 1. Build Hermes image on Portainer host (one-time, ~10-15 min)
# 2. Spin up hermes-test container with isolated /tmp/hermes-test-data/wave-a/
# 3. Install plugin from branch
# 4. Configure custom_providers + memory.provider
# 5. Pre-seed substrate in namespace hermes:hermes:default
# 6. Drive hermes -z with the three scenario prompts
# 7. Read LLM responses for verbatim quotes of injected content

# Full orchestration scripts live under hermes-test/scripts/ when promoted from
# /var/tmp/ in the container.
```

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

### Plugin discovery status check

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/VERIFICATION.md

CLI command to verify that the YantrikDB plugin is correctly installed and available.

```bash
$ uv run hermes memory status

Memory status
────────────────────────────────────────
  Built-in:  always active
  Provider:  yantrikdb

  Plugin:    installed ✓
  Status:    available ✓

  Installed plugins:
    • yantrikdb  (API key / local) ← active
```

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

### Enable Knowledge Packs

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

Enable and optionally auto-mount knowledge packs to provide specialized expertise to the agent.

```bash
echo "YANTRIKDB_PACKS_ENABLED=true" >> ~/.hermes/.env
# optional: mount packs for every session (transient - unmounted on shutdown)
echo "YANTRIKDB_AUTO_MOUNT_PACKS=wordpress-expert-0.2.0.ydbpack" >> ~/.hermes/.env
```

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

### Update Option B

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

Updating the pip package and refreshing the registered shim for Option B installations.

```bash
source ~/.hermes/hermes-agent/venv/bin/activate
pip install --upgrade yantrikdb-hermes-plugin
yantrikdb-hermes install --force
hermes gateway restart                    # if Hermes is running as a gateway/service
hermes memory status
```

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

### Run YantrikDB server with Docker

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

Deploy a single-node YantrikDB server instance using Docker.

```bash
docker run -d -p 7438:7438 \
  -v yantrikdb-data:/var/lib/yantrikdb \
  --name yantrikdb \
  ghcr.io/yantrikos/yantrikdb:latest
```

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

### Initialize YantrikDB Environment Variables

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/assets/demos/skill-lifecycle/transcript.txt

Set the required environment variables to configure the database path, namespace, and skill enablement.

```bash
YANTRIKDB_DB_PATH = C:\Users\sync\AppData\Local\Temp\yantrikdb_hermes_demo_msmxkwkh\memory.db
YANTRIKDB_NAMESPACE = demo
YANTRIKDB_SKILLS_ENABLED = true
```

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

### Run Recall Benchmarks

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/benchmarks/README.md

Commands to execute recall quality measurements, including optional self-tuning lift analysis and output persistence.

```bash
# baseline recall quality
python benchmarks/run_recall_bench.py

# also measure the self-tuning (reinforcement) lift
python benchmarks/run_recall_bench.py --reinforce

# persist machine-readable + markdown output
python benchmarks/run_recall_bench.py --reinforce --json out.json --markdown out.md
```

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

### Re-render Demo GIF with VHS

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/assets/demos/skill-lifecycle/README.md

Use the VHS tool to generate demo.gif and demo.mp4 from the demo.tape file.

```bash
cd assets/demos/skill-lifecycle
vhs demo.tape
```

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

### Manual Hermes configuration

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

Manually configure the memory provider and set required environment variables in the .env file.

```bash
hermes config set memory.provider yantrikdb
cat >> ~/.hermes/.env <<'EOF'
YANTRIKDB_URL=http://localhost:7438
YANTRIKDB_TOKEN=ydb_...
EOF
```

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

### Regenerate the demo GIF

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/assets/demos/self-directing/README.md

Use the provided render script to generate the demo.gif file using Pillow.

```bash
pip install pillow
python assets/demos/self-directing/render.py
```

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

### Scenario 1 Pre-seed Memory

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/docs/v0.5-wave-a-e2e-results.md

Initial memory seeding for Scenario 1, establishing user preferences for git commit messages and unrelated garage door information.

```python
remember("Pranab prefers minimal commit messages with no trailing summary; never include co-author tags", importance=0.85)
remember("The garage door opener uses an iPhone-only app", importance=0.5)
```

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

### Update via uv

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

Updating dependencies in uv-only environments.

```bash
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python --upgrade yantrikdb
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python --upgrade yantrikdb-hermes-plugin
```

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

### Enable YantrikDB Skills

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

Enable the agentic skill loop by adding the environment variable to the Hermes configuration file.

```bash
echo "YANTRIKDB_SKILLS_ENABLED=true" >> ~/.hermes/.env
```

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

### Manual Uninstall

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

Manual removal of the plugin registration and pip packages.

```bash
rm -rf ~/.hermes/plugins/yantrikdb
pip uninstall yantrikdb-hermes-plugin yantrikdb
```

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

### Define Standing Rules

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

Create a constitution file to enforce guardrails that outrank recalled memory and knowledge pack rules. The agent cannot rewrite these rules.

```markdown
- Never run destructive commands without asking.
- Answer in British English.
- Never reveal internal hostnames.
```

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

### Define a New Skill

Source: https://github.com/yantrikos/yantrikdb-hermes-plugin/blob/main/assets/demos/skill-lifecycle/transcript.txt

Define a new release workflow skill and verify the operation count in the skill_substrate namespace.

```python
$ provider.handle_tool_call('yantrikdb_skill_define', { … })
 → {"rid": "019e4783-7496-747a-a2e2-8710f727cf90", "skill_id": "workflow.release.yantrikos_repo", "stored": true}

$ provider.handle_tool_call('yantrikdb_stats', {'namespace': 'skill_substrate'})
 → {"active_memories": 0, "consolidated_memories": 0, "tombstoned_memories": 0, "edges": 0, "entities": 0, "operations": 2, "open_conflicts": 0 …
```
Tokens:
Raw