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

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

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

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

### 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"]
    }
  }
}
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Search skills for staging service deployment issues

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

The agent queries the skill substrate using yantrikdb_skill_search to identify relevant lessons for a deployment-related incident.

```json
⚙  gpt-4o-mini → yantrikdb_skill_search(
        query="staging service stopped responding after deploy"
        top_k=3
     )
  ← plugin:
        {
          "count": 3,
          "skills": [
            {
              "rid": "019e47e4-e141-7459-8e65-848d2fdde181",
              "skill_id": "deploy.allowed_kinds.extension_order",
              "skill_type": "lesson",
              "applies_to": [
                "deployment",
                "incident",
                "review"
              ],
              "body": "When extending an ALLOWED_KINDS list (or any similar allow-list) that's checked in BOTH a polling watcher AND a downstream ingest service, the deploy ORDER matters: ingest must accept the new kind FIRST, then the watch …
```

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

### Run Recall Benchmarks

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

Executes the recall benchmark script to evaluate memory-QA performance, with an optional self-tuning reinforcement mode.

```bash
python benchmarks/run_recall_bench.py            # baseline
python benchmarks/run_recall_bench.py --reinforce  # + self-tuning lift
```

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

### Check Initial Database Stats

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

Verify the initial state of the database using the yantrikdb_stats tool call.

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

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

### Update Option A via force reinstall

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

Alternative update method if the hermes plugins update command is unavailable.

```bash
hermes plugins install yantrikos/yantrikdb-hermes-plugin --force
```

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

### Skill Tools

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

Opt-in tools for managing agent skills.

```APIDOC
## Skill Tools

### Description
Optional tools for skill management.

### Available Tools
- `yantrikdb_skill_search`: Search for defined skills.
- `yantrikdb_skill_define`: Define a new skill.
- `yantrikdb_skill_outcome`: Record the outcome of a skill execution.
```

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

### Search for Skills

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

Search the skill substrate for relevant procedures before performing a task.

```python
$ provider.handle_tool_call('yantrikdb_skill_search', {'query': 'how to ship a release', 'top_k': 3})
 → {"count": 1, "skills": [{"rid": "019e4783-7496-747a-a2e2-8710f727cf90", "skill_id": "workflow.release.yantrikos_repo", "skill_type": "procedure", "applies_to": ["release", "workflow", "yantrikos"], "body": "For every release on a yantrikos repo with branch protection: (1) feature …
```

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

### Enable Owner Scoping

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

Turn on owner scoping to provide each user with their own memory namespace, preventing cross-user fact attribution.

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

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

### Search skills for ALLOWED_KINDS deployment issues

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

A refined search query focused on the specific configuration key identified in the incident report.

```json
⚙  gpt-4o-mini → yantrikdb_skill_search(
        query="ALLOWED_KINDS deployment issue"
        top_k=3
     )
  ← plugin:
        {
          "count": 3,
          "skills": [
            {
              "rid": "019e47e4-e141-7459-8e65-848d2fdde181",
              "skill_id": "deploy.allowed_kinds.extension_order",
              "skill_type": "lesson",
              "applies_to": [
                "deployment",
                "incident",
                "review"
              ],
              "body": "When extending an ALLOWED_KINDS list (or any similar allow-list) that's checked in BOTH a polling watcher AND a downstream ingest service, the deploy ORDER matters: ingest must accept the new kind FIRST, then the watch …
```

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

### Configure self-directing memory environment variables

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

Set these environment variables to enable automatic gap-to-task conversion and agenda surfacing. Adjust YANTRIKDB_GAP_MAX_AVG_TOP_SCORE based on your specific embedder performance.

```bash
YANTRIKDB_AUTO_GAP_TASKS=true        # gaps -> tasks on session end
YANTRIKDB_SURFACE_AGENDA=true        # surface the agenda each session
YANTRIKDB_GAP_MAX_AVG_TOP_SCORE=0.5  # gap threshold (tune per embedder)
```

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

### Session API call logs

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

Verbatim logs of the DeepSeek-driven session demonstrating memory operations and statistics retrieval.

```text
🔧 API call #1/6 — 3 yantrikdb_remember calls in ONE response:
  Tool 1: yantrikdb_remember({"text": "My name is Pranab Sarkar", ...})
    → {"rid": "019e0abf-b90b-..."} in 0.08s   ← includes one-time
                                                 YantrikDB.with_default()
                                                 engine warmup
  Tool 2: yantrikdb_remember({"text": "I prefer Rust for systems code", ...})
    → {"rid": "019e0abf-bcf5-..."} in 0.00s   ← sub-ms
  Tool 3: yantrikdb_remember({"text": "I am building YantrikDB ...", ...})
    → {"rid": "019e0abf-c0df-..."} in 0.00s   ← sub-ms

🔧 API call #2/6 — recall + stats:
  yantrikdb_recall({"query": "Pranab Rust", "top_k": 5})
    → {"count": 3, ...} in 0.00s
  yantrikdb_stats({})
    → {"active_memories": 3, "edges": 0, "open_conflicts": 0, ...} in 0.00s

🎉 Conversation completed after 3 OpenAI-compatible API calls.
```

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

### Enable owner scoping in yantrikdb.json

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

Configure owner scoping settings in the $HERMES_HOME/yantrikdb.json file.

```json
{
  "owner_scoping": true,
  "identity_map_path": "/path/to/identity-map.json",
  "include_base_namespace_recall": true,
  "include_legacy_actor_namespace_recall": true
}
```

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

### Configure custom provider for Ollama in Hermes

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

Use this YAML configuration to correctly route the qwen3.6 model to a local Ollama instance by defining a custom provider.

```yaml
memory:
  provider: yantrikdb
custom_providers:
  - name: ollama-local
    base_url: http://192.168.4.35:11434/v1
    transport: openai_chat
    api_key_env: OPENAI_API_KEY
model: qwen3.6:27b-64k
provider: custom:ollama-local
```

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

### Configure Agent Fleet

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

Enable shared memory namespaces and fleet visibility for multiple agents. Fleet view is disabled if owner scoping is active.

```bash
# agents learn from each other: explicit `remember` writes become shared
echo "YANTRIKDB_SHARED_BRAIN_NAMESPACE=team-brain" >> ~/.hermes/.env
# an agent can see its siblings: memory counts, last activity, open tasks
echo "YANTRIKDB_FLEET_VIEW=true" >> ~/.hermes/.env
```

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

### Define new lessons using yantrikdb_skill_define

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

The agent creates a new persistent lesson in the substrate to prevent future recurrence of the identified incident pattern.

```text
⚙  gpt-4o-mini → yantrikdb_skill_define(
        skill_id="incident.ingest.allowed_kinds_deploy_race"
        body="When deploying a new event type
        ensure that the ingest service is deployed and fully accepting the new kind before the polling watcher ...
        skill_type="lesson"
        applies_to=["deployment"
        "incident"
        "ingest"
        "watcher"]
        triggers=["deploy new event type"
        "ingest service hangs"
        "polling watcher emits new kind"]
        version="1.0.0"
     )
  ← plugin:
        {
          "rid": "019e47e5-e069-74a4-a653-edcc5d15edac",
          "skill_id": "incident.ingest.allowed_kinds_deploy_race",
          "stored": true
        }
```

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

### Restart Agent Session

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

Simulate a session restart by creating a new instance of the YantrikDBMemoryProvider.

```python
$ provider = YantrikDBMemoryProvider()   # new instance
 → provider ready, substrate has the skill from session 1
```

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

### Configure YantrikDB Embedder

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

Set the YANTRIKDB_EMBEDDER environment variable in your .env file to choose a specific model. Options include potion-base-8M, potion-base-32M, or custom models via model2vec or sentence-transformers.

```bash
echo "YANTRIKDB_EMBEDDER=potion-base-8M" >> ~/.hermes/.env     # 28 MB, dim=256, ~92% MiniLM
# or potion-base-32M for 121 MB, dim=512, ~95% MiniLM
# or multilingual via the v0.4.2 model2vec path:
echo "YANTRIKDB_EMBEDDER_MODEL2VEC=minishlab/potion-multilingual-128M" >> ~/.hermes/.env
# or the broader HF ecosystem via sentence-transformers:
echo "YANTRIKDB_EMBEDDER_HF=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2" >> ~/.hermes/.env
```

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

### Mint a YantrikDB token

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

Generate a bearer token for the Hermes plugin using the docker exec command.

```bash
docker exec yantrikdb yantrikdb token \
  --data-dir /var/lib/yantrikdb \
  create --db default --label hermes
# → ydb_abc123...
```

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

### Memory Management Tools

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

Core tools for managing agent memory, including remembering, recalling, forgetting, and relating facts.

```APIDOC
## Memory Management Tools

### Description
Tools for interacting with the YantrikDB memory store.

### Available Tools
- `yantrikdb_remember`: Store a new fact.
- `yantrikdb_recall`: Retrieve memories with recency-aware ranking and retrieval reasons.
- `yantrikdb_forget`: Remove a memory.
- `yantrikdb_think`: Canonicalize facts and identify conflicts.
- `yantrikdb_conflicts`: List current memory contradictions.
- `yantrikdb_resolve_conflict`: Resolve a specific memory conflict.
- `yantrikdb_relate`: Create graph edges between memories.
- `yantrikdb_stats`: Retrieve memory statistics.
```

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

### Scenario 3 Conflicting Memory Pre-seed

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

Seeding conflicting preferences for Python indentation to test the engine's conflict detection capabilities.

```python
remember("Pranab prefers tabs for Python indentation", importance=0.7)
remember("Pranab prefers spaces for Python indentation", importance=0.7)
think(run_pattern_mining=False)
```

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

### Search for skills using yantrikdb_skill_search

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

The agent queries the skill substrate to find relevant lessons or patterns based on the current incident description.

```text
⚙  gpt-4o-mini → yantrikdb_skill_search(
        query="ingest service hangs after deploying new event type"
        top_k=5
     )
  ← plugin:
        {
          "count": 5,
          "skills": [
            {
              "rid": "019e47e4-e141-7459-8e65-848d2fdde181",
              "skill_id": "deploy.allowed_kinds.extension_order",
              "skill_type": "lesson",
              "applies_to": [
                "deployment",
                "incident",
                "review"
              ],
              "body": "When extending an ALLOWED_KINDS list (or any similar allow-list) that's checked in BOTH a polling watcher AND a downstream ingest service, the deploy ORDER matters: ingest must accept the new kind FIRST, then the watch …
```

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

### Identity map format: owner-centric

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

Define actor mappings grouped by owner.

```json
{
  "owners": {
    "owner:primary-user": {
      "actors": ["whatsapp:actor-a", "telegram:actor-b"]
    }
  }
}
```

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

### Hermes .env configuration for embedded mode

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

The required environment variables to enable the embedded YantrikDB backend in Hermes.

```text
YANTRIKDB_MODE=embedded
YANTRIKDB_DB_PATH=/root/.hermes/yantrikdb-memory.db
YANTRIKDB_NAMESPACE=hermes-demo
```

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

### Identity map format: actor-centric

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

Define owner mappings grouped by actor.

```json
{
  "actors": {
    "whatsapp:actor-a": "owner:primary-user",
    "telegram:actor-b": "owner:primary-user"
  }
}
```

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

### Trigger Lifecycle Tools

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

Tools for managing triggers generated by the think process, such as redundancies or cross-domain connections.

```APIDOC
## Trigger Lifecycle Tools

### Description
Tools to inspect and resolve triggers generated by `yantrikdb_think`.

### Available Tools
- `yantrikdb_pending_triggers`: List waiting triggers with urgency and suggested actions.
- `yantrikdb_acknowledge_trigger`: Mark a trigger as seen.
- `yantrikdb_dismiss_trigger`: Remove a false positive or out-of-scope trigger.
- `yantrikdb_act_on_trigger`: Record an audit-trail entry for an action taken on a trigger.
```

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

### Execute memory storage and stats retrieval

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

Perform three yantrikdb_remember tool calls to store memories, followed by a yantrikdb_stats call to retrieve the database operational snapshot.

```text
🔄 API call #1/6
🤖 I'll store those three memories and then check the database stats.
🔧 3 tool calls:
  yantrikdb_remember(text="My name is Pranab Sarkar", domain="people", importance=0.9)
    → {"rid": "019d8eac-f59b-712b-bae7-f7e38326a16e", "stored": true}
  yantrikdb_remember(text="I prefer Rust for systems code", domain="preference", importance=0.8)
    → {"rid": "019d8eac-f999-7c24-b066-f2c710a38111", "stored": true}
  yantrikdb_remember(text="I am building YantrikDB a cognitive memory database for AI agents", domain="work", importance=0.9)
    → {"rid": "019d8eac-fda4-710b-b84f-c6a427dcec4c", "stored": true}

🔄 API call #2/6
🔧 1 tool call:
  yantrikdb_stats()
    → {"active_memories": 1795, "consolidated_memories": 7, "tombstoned_memories": 4,
       "edges": 1, "entities": 2, "operations": 75068, "open_conflicts": 3, "pending_triggers": 98}

🎯 Final: Stored 3 memories with RIDs [...]. Database stats: 1795 active memories, 0 open conflicts, 98 pending triggers.
```

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

### Scenario 2 Skill Definition

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

Definition of a git-related skill used to test automatic skill attachment in Scenario 2.

```python
skill_define(
    skill_id="git.commit_clean",
    body="Always rebase before merge so history stays linear and reviewable. No co-author tags. No marketing voice in commit messages.",
    skill_type="procedure",
    applies_to=["git", "workflow"],
)
```

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

### Run integration tests with pytest

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

Executes integration tests from the workspace root. Requires YANTRIKDB_INTEGRATION_URL and YANTRIKDB_INTEGRATION_TOKEN environment variables to be set.

```bash
# From the workspace root, after a yantrikdb-server is running at $YDB_URL:
YANTRIKDB_INTEGRATION_URL=$YDB_URL \
YANTRIKDB_INTEGRATION_TOKEN=$YDB_TOKEN \
python -m pytest tests/integration/ -v
```

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

### Log skill outcome for deployment order

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

The agent records a successful outcome for the identified skill after clarifying the deployment order requirements.

```json
⚙  gpt-4o-mini → yantrikdb_skill_outcome(
        skill_id="deploy.allowed_kinds.extension_order"
        succeeded=true
        note="Clarified the importance of deployment order for ALLOWED_KINDS."
     )
  ← plugin:
        {
          "rid": "019e47e5-6750-73a6-baf5-f1790819bd60",
          "skill_id": "deploy.allowed_kinds.extension_order",
          "recorded": true
        }
```

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

### Tool response envelope structure

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

Standardized JSON response format for all tools, ensuring consistent status reporting for LLM agents.

```json
{
  "status": "ok" | "failed",
  "ok": true | false,
  "tool": "yantrikdb_remember",
  "ts": 1748394801.42,
  ...tool-specific keys preserved verbatim (rid, stored, results, ...)
}
```

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

### Suppress HuggingFace Output

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

Add these variables to your .env file to prevent sentence-transformers and huggingface_hub from polluting the agent's stdout stream.

```bash
HF_HUB_DISABLE_PROGRESS_BARS=1
TRANSFORMERS_VERBOSITY=error
# Optional, when running fully offline after the first download:
HF_HUB_OFFLINE=1
```

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

### Record Skill Outcome

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

Record the outcome of the executed skill to update the ledger.

```python
$ provider.handle_tool_call('yantrikdb_skill_outcome', { … })
 → {"rid": "019e4783-b436-7a18-9b8f-daa6ad818010", "skill_id": "workflow.release.yantrikos_repo", "recorded": true}
```

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

### Search skills for polling watcher and ingest service issues

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

A search query targeting the specific components mentioned as failing in the incident report.

```json
⚙  gpt-4o-mini → yantrikdb_skill_search(
        query="polling watcher ingest service deploy issue"
        top_k=3
     )
  ← plugin:
        {
          "count": 3,
          "skills": [
            {
              "rid": "019e47e4-e141-7459-8e65-848d2fdde181",
              "skill_id": "deploy.allowed_kinds.extension_order",
              "skill_type": "lesson",
              "applies_to": [
                "deployment",
                "incident",
                "review"
              ],
              "body": "When extending an ALLOWED_KINDS list (or any similar allow-list) that's checked in BOTH a polling watcher AND a downstream ingest service, the deploy ORDER matters: ingest must accept the new kind FIRST, then the watch …
```

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

### Explainable recall result structure

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

The yantrikdb_recall tool returns results including a why_retrieved list to allow agents to audit ranking and debug memory retrieval.

```json
{
  "rid": "019d…",
  "text": "User lives in Seattle since 2024",
  "score": 1.1576,
  "importance": 0.9,
  "why_retrieved": [
    "semantic_match",
    "important (decay=0.91)",
    "graph-connected via User"
  ]
}
```

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

### yantrikdb_recall

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

Retrieves memories with explainable reasoning for each result.

```APIDOC
## yantrikdb_recall

### Description
Explainable recall — each result includes a `why_retrieved` reason list.

### Response
- **rid** (string) - Unique memory identifier.
- **text** (string) - The memory content.
- **score** (float) - Retrieval score.
- **importance** (float) - Importance score.
- **why_retrieved** (array) - List of reasons for retrieval (e.g., semantic_match, graph-connected).
```

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

### Conflict detection output

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

The yantrikdb_conflicts tool surfaces contradictions detected during the think() maintenance pass.

```json
{"count": 1, "conflicts": [
  {"conflict_id": "cf_1",
   "memory_a": {"rid": "r1", "text": "CEO is Alice"},
   "memory_b": {"rid": "r2", "text": "CEO is Bob"},
   "detection_reason": "entity_collision: CEO",
   "priority": "high"}
]}
```

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

### yantrikdb_think

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

Executes the bounded maintenance pass to canonicalize duplicates and flag contradictions.

```APIDOC
## yantrikdb_think

### Description
Run the bounded maintenance pass. Canonicalizes near-duplicates, flags contradictions, and optionally mines patterns.

### Response
- **consolidated** (integer) - Number of memories consolidated.
- **conflicts_found** (integer) - Number of contradictions detected.
- **duration_ms** (integer) - Execution time in milliseconds.
- **triggers** (array) - List of maintenance triggers.
```

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

### Text Hygiene Configuration

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

The YANTRIKDB_MAX_TEXT_LEN constant defines the maximum character limit for memory bodies, defaulting to 25000 characters.

```text
YANTRIKDB_MAX_TEXT_LEN
```

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

### Findings YAML Schema Structure

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

The findings.yaml file is a flat structured record used to document provider verification results. Fields like contract, response_shape, and maintenance are used to track specific capabilities and behaviors.

```yaml
provider: hindsight
version_under_test: "1.2.3"        # what we actually pip-installed / cloned
verified_at: 2026-05-13            # UTC date the harness was last run against this provider
verified_against: "Hermes 0.9.0 in LXC 129 / 192.168.4.x"

backend:                            # observable, not declared
  hosting: cloud | self-hosted | embedded
  requires_account: true | false
  requires_separate_server: true | false
  pip_footprint_mb: 12              # measured via `du -sm`

contract:
  initialize_ok: true | false
  remember_ok: true | false
  recall_ok: true | false
  recall_returned_results: 3        # actual count for the canonical query
  notes: ""

response_shape:
  why_retrieved_field: true | false        # is there a top-level field on each result that names *why* it ranked?
  why_retrieved_field_name: "reasoning"    # the actual key in their response (empty when false)
  per_result_score: true | false
  per_result_metadata: true | false

maintenance:
  duplicate_canonicalized: true | false | unknown   # did writing the same fact twice merge or duplicate?
  contradiction_surfaced: true | false | unknown    # does writing a conflicting fact produce a conflict record?
  contradiction_api: ""                              # tool name if surfaced; empty otherwise

skills:
  skill_tools_in_schema: true | false
  skill_tool_names: []                                # the actual *_skill_* tool names exposed

evidence:
  transcript_file: providers/hindsight/transcript.md  # human-readable session log
  raw_responses: providers/hindsight/raw/             # captured JSON of every response

couldnt_verify:
  reason: ""                                          # only populated when we explicitly skipped (e.g., cloud account unavailable)
  what_we_know_anyway: ""                             # plugin.yaml description + repo URL
```

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

### yantrikdb_recall API call and JSON response

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

Executes a recall query for 'Pranab Sarkar Rust' with top_k=5 and displays the full JSON response, including the why_retrieved reason codes for each result.

```json
🔄 API call #1/4
🔧 1 tool call:
  yantrikdb_recall(query="Pranab Sarkar Rust", top_k=5)
    → {"count": 5, "results": [
        {"rid": "019d8eac-f59b-712b-bae7-f7e38326a16e",
         "text": "My name is Pranab Sarkar",
         "score": 1.404,
         "importance": 0.9,
         "domain": "people",
         "created_at": 1776215192.987,
         "why_retrieved": ["semantically similar (0.59)", "recent",
                           "important (decay=0.76)", "keyword_match"]},

        {"rid": "019d8eac-f999-7c24-b066-f2c710a38111",
         "text": "I prefer Rust for systems code",
         "score": 1.195,
         "importance": 0.8,
         "domain": "preference",
         "created_at": 1776215194.009,
         "why_retrieved": ["recent", "important (decay=0.68)", "keyword_match"]},

        {"rid": "019d8ead-1f24-74c6-9580-a2b0f095c1bb",
         "text": "Use the yantrikdb_remember tool three separate times ...",
         "score": 1.017,
         "importance": 0.6,
         "domain": "",
         "created_at": 1776215203.620,
         "why_retrieved": ["recent", "important (decay=0.53)",
                           "keyword_match", "fts_sourced"]},

        {"rid": "019d8902-0d94-79cb-a342-a76311a48ca6",
         "text": "benchmark memory number 644 about topic 44 ...",
         "score": 0.405,
         "importance": 0.5,
         "domain": "benchmark",
         "why_retrieved": ["recent"]},

        {"rid": "019d8902-125d-7721-97d1-6738e7294318",
         "text": "benchmark memory number 663 about topic 13 ...",
         "score": 0.394,
         "importance": 0.5,
         "domain": "benchmark",
         "why_retrieved": ["recent"]}
      ]}
```

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

### yantrikdb_remember

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

Stores a memory entry with associated importance and optional domain.

```APIDOC
## yantrikdb_remember

### Description
Stores a memory with importance and optional domain.

### Parameters
- **text** (string) - Required - The memory content to store.
- **importance** (float) - Required - Importance score of the memory.
- **domain** (string) - Optional - The domain category for the memory.
```

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

### Circuit Breaker State Machine

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

Visual representation of the circuit breaker states (CLOSED, OPEN, HALF-OPEN) and transition triggers based on failure counts and cooldown periods.

```text
                ┌──────────────┐
                │   CLOSED     │  (normal operation)
                │              │
                │ fail_count<5 │
                └──────┬───────┘
                       │  5th transient/server/auth failure
                       ▼
                ┌──────────────┐
                │    OPEN      │  (short-circuit all calls)
                │              │
                │  cooldown    │
                │   = 120 s    │
                └──────┬───────┘
                       │  cooldown elapsed
                       ▼
                ┌──────────────┐
                │  HALF-OPEN   │  (next call tries; reset on success)
                │              │
                └──────────────┘
```

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

### Record skill outcomes using yantrikdb_skill_outcome

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

The agent records whether a specific skill application succeeded or failed during the troubleshooting process.

```text
⚙  gpt-4o-mini → yantrikdb_skill_outcome(
        skill_id="deploy.allowed_kinds.extension_order"
        succeeded=true
        note="The deployment order was likely incorrect
        with the watcher deployed before the ingest service accepted the new event type."
     )
  ← plugin:
        {
          "rid": "019e47e5-be90-7684-a81e-ea679e336e54",
          "skill_id": "deploy.allowed_kinds.extension_order",
          "recorded": true
        }
```

```text
⚙  gpt-4o-mini → yantrikdb_skill_outcome(
        skill_id="incident.service.silent_deadlock_check"
        succeeded=false
        note="Need to investigate the service state further
        as the health check is returning ok but operational requests are hanging."
     )
  ← plugin:
        {
          "rid": "019e47e5-c72c-769b-8a78-d99655190d19",
          "skill_id": "incident.service.silent_deadlock_check",
          "recorded": true
        }
```

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

### yantrikdb_resolve_conflict

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

Resolves detected contradictions using specified strategies.

```APIDOC
## yantrikdb_resolve_conflict

### Description
Close a contradiction via `keep_winner` / `merge` / `keep_both` / `dismiss`.

### Parameters
- **conflict_id** (string) - Required - The ID of the conflict to resolve.
- **strategy** (string) - Required - Resolution strategy (keep_winner, merge, keep_both, dismiss).
- **winner_rid** (string) - Optional - The RID to keep if using keep_winner.
- **resolution_note** (string) - Optional - Note regarding the resolution.
```

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

### Conflict resolution invocation

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

The agent resolves detected conflicts explicitly using the yantrikdb_resolve_conflict tool with a specified strategy.

```python
yantrikdb_resolve_conflict(
    conflict_id="cf_1",
    strategy="keep_winner",
    winner_rid="r2",
    resolution_note="Bob succeeded Alice in March 2026",
)
```

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

### Log skill outcome for silent deadlock check

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

The agent records a successful outcome for the incident service deadlock check skill.

```json
⚙  gpt-4o-mini → yantrikdb_skill_outcome(
        skill_id="incident.service.silent_deadlock_check"
        succeeded=true
        note="Provided insights into potential causes for hanging endpoints."
     )
  ← plugin:
        {
          "rid": "019e47e5-6feb-792a-814c-6ebb232adf96",
          "skill_id": "incident.service.silent_deadlock_check",
          "recorded": true
        }
```