{"id":49967106,"url":"https://github.com/yantrikos/yantrikdb-hermes-plugin","last_synced_at":"2026-05-29T04:01:24.337Z","repository":{"id":356652752,"uuid":"1211008223","full_name":"yantrikos/yantrikdb-hermes-plugin","owner":"yantrikos","description":"YantrikDB memory provider for NousResearch/hermes-agent — self-maintaining memory with canonicalization, contradiction tracking, recency ranking, and explainable recall.","archived":false,"fork":false,"pushed_at":"2026-05-18T04:48:55.000Z","size":334,"stargazers_count":19,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T05:40:43.174Z","etag":null,"topics":["ai-memory","hermes-agent","knowledge-graph","llm-agent","memory","plugin","yantrikdb"],"latest_commit_sha":null,"homepage":"https://yantrikdb.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yantrikos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T01:27:58.000Z","updated_at":"2026-05-18T04:44:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yantrikos/yantrikdb-hermes-plugin","commit_stats":null,"previous_names":["yantrikos/yantrikdb-hermes-plugin"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/yantrikos/yantrikdb-hermes-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yantrikos%2Fyantrikdb-hermes-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yantrikos%2Fyantrikdb-hermes-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yantrikos%2Fyantrikdb-hermes-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yantrikos%2Fyantrikdb-hermes-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yantrikos","download_url":"https://codeload.github.com/yantrikos/yantrikdb-hermes-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yantrikos%2Fyantrikdb-hermes-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33167432,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T05:43:36.989Z","status":"ssl_error","status_checked_at":"2026-05-18T05:43:19.133Z","response_time":71,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","hermes-agent","knowledge-graph","llm-agent","memory","plugin","yantrikdb"],"created_at":"2026-05-18T06:14:29.193Z","updated_at":"2026-05-29T04:01:24.326Z","avatar_url":"https://github.com/yantrikos.png","language":"Python","funding_links":[],"categories":["Memory Providers","🌟 Community Skills","Skills, Plugins, and Extensions","Integrations \u0026 Bridges"],"sub_categories":["Skill Registries \u0026 Discovery","🧠 Memory \u0026 Knowledge","Skills and skill ecosystems","Deployment"],"readme":"# yantrikdb-hermes-plugin\n\n[![CI](https://github.com/yantrikos/yantrikdb-hermes-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/yantrikos/yantrikdb-hermes-plugin/actions/workflows/ci.yml)\n[![Tests](https://img.shields.io/badge/tests-128%20passing-brightgreen)](https://github.com/yantrikos/yantrikdb-hermes-plugin/actions)\n[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://github.com/yantrikos/yantrikdb-hermes-plugin)\n[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![YantrikDB](https://img.shields.io/badge/yantrikdb-%E2%89%A50.7.6-orange)](https://github.com/yantrikos/yantrikdb-server)\n[![Hermes Agent](https://img.shields.io/badge/hermes--agent-plugin-8a2be2)](https://github.com/NousResearch/hermes-agent)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![mypy](https://img.shields.io/badge/mypy-checked-2a6db2)](https://mypy-lang.org/)\n\n\u003e **YantrikDB as a memory provider for [Hermes Agent](https://github.com/NousResearch/hermes-agent).** Self-maintaining memory — canonicalizes duplicates, surfaces contradictions, explains recall — in a drop-in plugin. As of **v0.2.0** the default backend is **in-process** (`pip install` and go, no separate server).\n\nThis repository **is** the canonical distribution. Per Hermes maintainer guidance, new memory providers aren't being merged upstream — the recommended pattern is standalone plugins that users install via `pip` and register with their Hermes home directory. That keeps the version cadence, CI gating, issue triage, and review cycle on the plugin author's side, so fixes ship the same day they're ready instead of waiting on upstream review bandwidth.\n\n## Why this exists\n\nTwo recurring observations from the Hermes community map directly to what yantrikdb does:\n\n\u003e \"Compression was silently dropping earlier constraints by turn 50.\" — Hermes developer building a long-running coding agent ([user-stories](https://hermes-agent.nousresearch.com/docs/user-stories))\n\nThe `on_pre_compress` hook injects the highest-salience memories before Hermes compresses, so constraints survive long sessions. Recency-aware ranking + `conflicts()` makes superseded claims visible instead of letting them silently outrank their replacements.\n\n\u003e \"Spent 200-400 hours building a memory kernel because standard vector approaches dropped important constraints; successful implementations used temporal context graphs with lifecycle management — promotion / demotion / supersession — rather than vector similarity alone.\" — Hermes developer who built their own memory layer after vector approaches failed ([user-stories](https://hermes-agent.nousresearch.com/docs/user-stories))\n\nThis is the substrate yantrikdb already ships: temporal context graph via `relate()`, lifecycle via `consolidation_status` + `forget()` + the `think()` maintenance pass, recency ranking, first-class conflicts/canonicalization. Drop-in via `hermes plugins install`. The 200-400 hours are someone else's; you get the substrate.\n\n### And what other Hermes memory providers don't have\n\n| Capability | yantrikdb-hermes-plugin | Most others |\n|---|---|---|\n| Agent-authored skills with outcome ledger (`yantrikdb_skill_define` / `_search` / `_outcome`) | ✓ first-class, DB-native peer to Hermes' filesystem Markdown skills | filesystem-only (Hermes built-in) |\n| Contradiction tracking (`conflicts()` + `resolve_conflict()`) | ✓ first-class primitive | not in [mem0's 2026 taxonomy](https://docs.mem0.ai) |\n| Explainable recall (`why_retrieved` per result) | ✓ list of scoring reasons returned with every result | rarely surfaced |\n| Owner-scoping for multi-platform Hermes (Telegram + WhatsApp + Discord routed by canonical owner) | ✓ v0.4.10 identity-map + v0.4.11 shared group spaces | one shared namespace, manual scoping |\n| Embedded mode default (no server, no token, no GPU) | ✓ v0.2.0+ | varies |\n| HTTP backend for HA clusters | ✓ v0.5.0 (against yantrikdb-server) | varies |\n\n## End-to-end demo — substrate growing through the skill lifecycle\n\n![Constellation animation of the substrate growing](./assets/demos/skill-lifecycle/demo_visual.gif)\n\nSix skills from prior sessions, color-coded by type. Session 1: the agent adds a 7th (pink, just-created). Session 2 search highlights the relevant node, outcome recorded turns it green. Source: [`demo_visual.py`](./assets/demos/skill-lifecycle/demo_visual.py).\n\n### What's actually running underneath\n\n![LLM-driven skill lifecycle](./assets/demos/skill-lifecycle/demo_llm.gif)\n\n`gpt-4o-mini` receives the plugin's 15 tool schemas via OpenAI's chat-completions API and chooses when to call each one. In session 1 it autonomously picks the `skill_id` (`release.yantrikos.clean`), `applies_to` tags, and body for a workflow it just learned. In session 2 — fresh provider instance, same substrate — it searches the substrate, finds the skill, follows it, and records an outcome. Two real rids land. The autonomy loop closes in ~10 seconds.\n\nSources: [`demo_llm.py`](./assets/demos/skill-lifecycle/demo_llm.py) + [`transcript-llm.txt`](./assets/demos/skill-lifecycle/transcript-llm.txt) + [`demo_llm.tape`](./assets/demos/skill-lifecycle/demo_llm.tape) for rendering. A scripted (no API key required) deterministic version is also included: [`demo.py`](./assets/demos/skill-lifecycle/demo.py) / [`demo.gif`](./assets/demos/skill-lifecycle/demo.gif).\n\nThe plugin's `handle_tool_call` dispatch path you see in both demos is the same entry point Hermes invokes internally. For larger-scale evidence of LLM-driven autonomy: [`yantrikdb.com/guides/autonomous-skills/`](https://yantrikdb.com/guides/autonomous-skills/) documents 17 skills authored by Claude across many sessions on one production substrate, with 9 showing cross-session reuse via the outcome ledger.\n\n## Install (default — embedded backend)\n\nThe v0.2.0 default backend is **in-process**: no separate server, no token, no GPU, no network. Bundled `potion-base-2M` static embedder (~8 MB, dim=64) loads on first call (~80 ms one-time warmup) and stays in-process.\n\n### Option A — `hermes plugins install` (v0.4.5+, one command for the plugin source)\n\n```bash\nsource ~/.hermes/hermes-agent/venv/bin/activate\nhermes plugins install yantrikos/yantrikdb-hermes-plugin\npip install yantrikdb                    # ~10 MB; in the same Python env as Hermes\nhermes memory setup                      # → Select \"yantrikdb\" and press Enter\nhermes memory status                     # → Provider: yantrikdb  Status: available ✓\n```\n\n`hermes plugins install` clones the repo into `~/.hermes/plugins/yantrikdb/` based on `plugin.yaml`'s `name:` field. The `pip install yantrikdb` step gets the engine — `hermes plugins install` doesn't auto-install pip dependencies, so this is a separate step. **Crucially: pip-install into the same Python environment Hermes runs from.** If Hermes was installed via `pipx`, use `pipx inject hermes-agent yantrikdb`. If you're using a regular venv, source it first.\n\nIf your Hermes environment uses `uv` and does not have `pip` available, install with the Hermes Python explicitly:\n\n```bash\nuv pip install --python ~/.hermes/hermes-agent/venv/bin/python yantrikdb\n```\n\n### Option B — `pip install yantrikdb-hermes-plugin` (bundled package path)\n\n```bash\nsource ~/.hermes/hermes-agent/venv/bin/activate\npip install yantrikdb-hermes-plugin     # pulls yantrikdb engine + the provider source\nyantrikdb-hermes install                # registers ~/.hermes/plugins/yantrikdb\nhermes memory setup                     # → Select \"yantrikdb\" and press Enter\nhermes memory status                    # → Provider: yantrikdb  Status: available ✓\n```\n\nIf your Hermes environment uses `uv` and does not have `pip` available, install with the Hermes Python explicitly:\n\n```bash\nuv pip install --python ~/.hermes/hermes-agent/venv/bin/python yantrikdb-hermes-plugin\n~/.hermes/hermes-agent/venv/bin/yantrikdb-hermes install\n```\n\n`yantrikdb-hermes install` registers the pip-installed provider with Hermes by creating a lightweight shim at `~/.hermes/plugins/yantrikdb` (or `$HERMES_HOME/plugins/yantrikdb`). The shim imports the real provider from the installed `yantrikdb-hermes-plugin` package, so future package upgrades are picked up without copying the whole provider tree. Use `yantrikdb-hermes install --copy` if your environment prefers a physical copy instead of the default shim.\n\n### Updating\n\nOption A updates the plugin checkout and the engine dependency separately:\n\n```bash\nsource ~/.hermes/hermes-agent/venv/bin/activate\nhermes plugins update yantrikdb\npip install --upgrade yantrikdb\nhermes gateway restart                    # if Hermes is running as a gateway/service\nhermes memory status\n```\n\nIf your Hermes CLI does not have `hermes plugins update`, reinstall the plugin source in place:\n\n```bash\nhermes plugins install yantrikos/yantrikdb-hermes-plugin --force\n```\n\nOption B updates the pip package, then refreshes the registered shim:\n\n```bash\nsource ~/.hermes/hermes-agent/venv/bin/activate\npip install --upgrade yantrikdb-hermes-plugin\nyantrikdb-hermes install --force\nhermes gateway restart                    # if Hermes is running as a gateway/service\nhermes memory status\n```\n\nFor uv-only environments, target the Hermes Python explicitly:\n\n```bash\nuv pip install --python ~/.hermes/hermes-agent/venv/bin/python --upgrade yantrikdb\nuv pip install --python ~/.hermes/hermes-agent/venv/bin/python --upgrade yantrikdb-hermes-plugin\n```\n\n`--force` replaces the registered plugin directory. Back up any plugin-local files first if you keep custom files under `~/.hermes/plugins/yantrikdb/`; normal YantrikDB settings belong in `~/.hermes/.env` and are not touched.\n\n### Uninstalling\n\nOption A uses Hermes' plugin manager for the plugin source, plus pip for the engine dependency:\n\n```bash\nsource ~/.hermes/hermes-agent/venv/bin/activate\nhermes plugins remove yantrikdb\npip uninstall yantrikdb\nhermes memory setup                      # choose another provider, or disable external memory\nhermes gateway restart                   # if Hermes is running as a gateway/service\n```\n\nOption B removes the user-plugin registration, then optionally removes the pip packages:\n\n```bash\nsource ~/.hermes/hermes-agent/venv/bin/activate\nyantrikdb-hermes uninstall\npip uninstall yantrikdb-hermes-plugin yantrikdb\nhermes memory setup                      # choose another provider, or disable external memory\nhermes gateway restart                   # if Hermes is running as a gateway/service\n```\n\nIf your installed version does not yet have `yantrikdb-hermes uninstall`, remove the registration manually:\n\n```bash\nrm -rf ~/.hermes/plugins/yantrikdb\npip uninstall yantrikdb-hermes-plugin yantrikdb\n```\n\n### Same-venv guidance (both options)\n\n`yantrikdb` and `yantrikdb-hermes-plugin` must be importable from whatever Python interpreter Hermes uses:\n\n- **`pipx install hermes-agent`** → `pipx inject hermes-agent yantrikdb yantrikdb-hermes-plugin`\n- **Default Hermes venv** → `source ~/.hermes/hermes-agent/venv/bin/activate` first, then `pip install ...`\n- **Other plain venv** → `source path/to/hermes-venv/bin/activate` first, then `pip install ...`\n- **uv-only venv** → `uv pip install --python path/to/hermes-venv/bin/python ...`\n- **System Python** → just `pip install`\n\nIf `hermes memory status` shows `Status: not available ✗` after install, the most common cause is the plugin landed in a different Python than Hermes is using. `which hermes \u0026\u0026 which python` will confirm.\n\n### Optional: tier up the embedder\n\n```bash\necho \"YANTRIKDB_EMBEDDER=potion-base-8M\" \u003e\u003e ~/.hermes/.env     # 28 MB, dim=256, ~92% MiniLM\n# or potion-base-32M for 121 MB, dim=512, ~95% MiniLM\n# or multilingual via the v0.4.2 model2vec path:\necho \"YANTRIKDB_EMBEDDER_MODEL2VEC=minishlab/potion-multilingual-128M\" \u003e\u003e ~/.hermes/.env\n# or the broader HF ecosystem via sentence-transformers:\necho \"YANTRIKDB_EMBEDDER_HF=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2\" \u003e\u003e ~/.hermes/.env\n```\n\n### Optional: quiet the HuggingFace embedder\n\n`YANTRIKDB_EMBEDDER_HF` uses `sentence-transformers`, which by default emits noise to stdout — tqdm progress bars on every encode and a one-time HF Hub auth warning at startup. The plugin disables the per-encode progress bars internally (v0.4.12+). For the rest, add to your `.env`:\n\n```bash\nHF_HUB_DISABLE_PROGRESS_BARS=1\nTRANSFORMERS_VERBOSITY=error\n# Optional, when running fully offline after the first download:\nHF_HUB_OFFLINE=1\n```\n\nWithout these, sentence-transformers / huggingface_hub output can pollute the agent's own stdout stream.\n\n## Install (alternative — HTTP backend, for HA cluster setups)\n\nIf you run multiple Hermes instances that need to share one memory store, or you want HA via raft:\n\n```bash\ndocker run -d -p 7438:7438 -v yantrikdb-data:/var/lib/yantrikdb \\\n  --name yantrikdb ghcr.io/yantrikos/yantrikdb:latest\ndocker exec yantrikdb yantrikdb token --data-dir /var/lib/yantrikdb \\\n  create --db default --label hermes\n# → ydb_abc123...\n\ncat \u003e\u003e ~/.hermes/.env \u003c\u003cEOF\nYANTRIKDB_MODE=http\nYANTRIKDB_URL=http://localhost:7438\nYANTRIKDB_TOKEN=ydb_abc123...\nEOF\n```\n\nSame plugin, same 8 tools, same hooks, same provider contract — just talks HTTP to a separately-managed server instead of running the engine in-process.\n\nFull config, tool reference, troubleshooting: **[yantrikdb/README.md](yantrikdb/README.md)**.\n\n## What it does\n\nThe differentiator versus other Hermes memory plugins is not the vector store — it's what happens *after* the write:\n\n| Feature | Plain vector memory | YantrikDB |\n|---|---|---|\n| Duplicate facts | pile up | canonicalized by `think()` |\n| Contradictions | silently overwrite | surfaced via `conflicts()`, closed via `resolve_conflict()` |\n| Stale facts | outrank fresh ones | recency-aware ranking without deletion |\n| Why did a memory rank? | ¯\\\\_(ツ)_/¯ | every `recall()` result carries a `why_retrieved` reason list |\n| Cross-entity recall | semantic-only | graph edges from `relate()` boost related memories |\n\nTwelve tools exposed to the agent by default: `yantrikdb_remember`, `_recall`, `_forget`, `_think`, `_conflicts`, `_resolve_conflict`, `_relate`, `_stats`, plus the trigger-lifecycle consumers `_pending_triggers`, `_acknowledge_trigger`, `_dismiss_trigger`, `_act_on_trigger` (v0.4.13+). Three additional **opt-in** skill tools (v0.3.0+): `_skill_search`, `_skill_define`, `_skill_outcome` — see [Skills](#skills-opt-in-v030) below.\n\n### Tool response envelope (v0.4.16+)\n\nEvery tool response carries the same four envelope fields so an LLM later asked \"what did I just do?\" can't confabulate success on a silent failure:\n\n```json\n{\n  \"status\": \"ok\" | \"failed\",\n  \"ok\": true | false,\n  \"tool\": \"yantrikdb_remember\",\n  \"ts\": 1748394801.42,\n  ...tool-specific keys preserved verbatim (rid, stored, results, ...)\n}\n```\n\nFailure responses additionally carry `error` (legacy key) and `reason` (alias). The envelope is purely additive — existing agent code that reads `rid` / `stored` / `results` / etc. continues working unchanged.\n\nWhy this matters: tool failures used to be communicated as `{\"error\": \"...\"}` only. When the agent's narrative LLM was later asked to summarize the session, it could confabulate plausible completion because the failure wasn't loudly present in machine-readable form. The new `status: \"failed\"` + `ok: false` are intentionally redundant — the word \"failed\" lands during narrative summarization, the boolean lands for programmatic consumers. Pattern documented by yantrikdb-agi after a real incident where the agent described a `telegram_send` that never happened.\n\n### Trigger lifecycle (v0.4.13+)\n\n`yantrikdb_think` flags redundancies, conflicts, and surprise cross-domain connections as **triggers** — substrate signals the agent can inspect and close out:\n\n- `yantrikdb_pending_triggers` — list what's waiting (with `urgency`, `reason`, `suggested_action`, and the `source_rids` that produced it).\n- `yantrikdb_acknowledge_trigger` — agent saw it, no follow-up needed.\n- `yantrikdb_dismiss_trigger` — false positive or out of scope.\n- `yantrikdb_act_on_trigger` — agent took action; records an audit-trail entry.\n\nAll three closers remove the trigger from `pending_triggers`. Without these tools (pre-v0.4.13) the pending queue grew indefinitely because the producer (`think()`) had no matching consumer surface.\n\n### Compared to other Hermes memory providers\n\nEach row in the table below is backed by [`tests/comparison/findings_scale_lxc/\u003cprovider\u003e/`](tests/comparison/findings_scale_lxc/) — the actual `findings_scale.yaml`, `transcript.md`, and `raw/` response capture from running a 1000-fact + 20-query probe against that provider on a real Hermes 0.9.0 install (LXC 129, commit `4610551`). The corpus is deterministic (`fixtures/corpus_1k.json`, seed=20260512: 600 realistic agent-memory facts + 300 noise + 50 planted duplicates + 50 planted contradictions); the probe is provider-agnostic and reproducible. Methodology details in [`tests/comparison/README.md`](tests/comparison/README.md).\n\n| Provider | Hosting | Verified at 1000 scale | Writes (ok/attempted; latency) | Recall latency | Precision@5 | `why_retrieved` field | Maintenance behaviour observed |\n|---|---|---|---|---|---|---|---|\n| **yantrikdb** (this) | embedded | yes — 256/1000 writes [^queuecap] | 256/1000; p50 0.48 ms / p99 5.13 ms | p50 3.78 ms / p99 32.94 ms | **0.80** (16/20) | yes — `why_retrieved` per result | contradiction API: `yantrikdb_conflicts`; duplicates kept separate (canonicalisation via explicit `think()`) |\n| [byterover](https://github.com/NousResearch/hermes-agent/tree/main/plugins/memory/byterover) | cloud | couldn't verify — requires `brv` CLI auth | — | — | — | — | — |\n| [hindsight](https://github.com/NousResearch/hermes-agent/tree/main/plugins/memory/hindsight) | cloud-default (local-stub mode used) | yes — 1000/1000 writes | 1000/1000; p50 0.27 ms / p99 0.31 ms | p50 0.28 ms / p99 0.30 ms | **0.00** (0/20) [^localstub] | no | — |\n| [holographic](https://github.com/NousResearch/hermes-agent/tree/main/plugins/memory/holographic) | embedded (SQLite + FTS5) | yes — 1000/1000 writes [^hrrcap] | 1000/1000; p50 23.43 ms / p99 68.52 ms | p50 0.06 ms / p99 0.23 ms | **0.00** (0/20) [^keyword] | no | — |\n| [honcho](https://github.com/NousResearch/hermes-agent/tree/main/plugins/memory/honcho) | self-hosted | couldn't verify — requires honcho-server URL or api key | — | — | — | — | — |\n| [mem0](https://github.com/NousResearch/hermes-agent/tree/main/plugins/memory/mem0) | cloud or self-host | couldn't verify — requires `mem0.api_key` | — | — | — | — | — |\n| [openviking](https://github.com/NousResearch/hermes-agent/tree/main/plugins/memory/openviking) | self-hosted | couldn't verify — requires `OPENVIKING_ENDPOINT` | — | — | — | — | — |\n| [retaindb](https://github.com/NousResearch/hermes-agent/tree/main/plugins/memory/retaindb) | cloud | couldn't verify — requires `RETAINDB_API_KEY` | — | — | — | — | — |\n| [supermemory](https://github.com/NousResearch/hermes-agent/tree/main/plugins/memory/supermemory) | cloud | couldn't verify — requires `SUPERMEMORY_API_KEY` | — | — | — | — | — |\n\n[^queuecap]: yantrikdb v0.4.2 plugin against yantrikdb engine 0.7.8 on Linux: the engine's ingest queue is bounded at 256 pending ops and didn't drain during the 1000-fact burst (probe hit `RuntimeError('ingest queue full ...; retry after 50ms')` from fact 257 onward, even with 60-attempt × 100 ms backoff). Recall on the 256 stored facts is solid (P@5 = 0.80). Surfaced upstream as a likely queue-drain regression in the manylinux build of 0.7.8 — the Hermes plugin itself doesn't loop the writes.\n\n[^localstub]: `HINDSIGHT_MODE=local_embedded` was set so `is_available()` returns true without an API key, but in this configuration writes return immediately (sub-millisecond) and recall returns no results — the local mode appears to be a no-op stub rather than a real local backend. Full retrieval almost certainly requires the cloud account.\n\n[^hrrcap]: At ~256 stored items, the engine emits `HRR storage near capacity: SNR=2.00 (dim=1024, n_items=...)` warnings on every subsequent write. The capacity warning is part of holographic's normal output; it's not an error and writes continue to succeed, but retrieval quality is expected to degrade past that point.\n\n[^keyword]: Holographic's recall is keyword-based (FTS5 + HRR cleanup); the probe's queries are full sentences (`\"What color scheme does the user prefer in VS Code?\"`). The 0/20 result is a query-format mismatch, not a retrieval failure — keyword-shaped queries probably hit. The honest takeaway is that holographic and yantrikdb target different query shapes, not that one is \"better\".\n\n**Where the verified data lives** — every cell in the table maps to a file:\n\n- `findings_scale.yaml` — structured cells (the table is generated from these by [`compare.py`](tests/comparison/compare.py))\n- `transcript.md` — human-readable session log with timing\n- `raw/recall-Q*.json` — captured raw recall responses for every query\n- `fixtures/corpus_1k.json`, `fixtures/queries_1k.json` — the deterministic corpus + queries used\n\n**How to re-run it** — clone the repo, `scp tests/comparison/` to a Hermes-installed machine, `python3 runner_scale.py --all`. The harness will skip-with-honest-reason for any provider whose `is_available()` returns False (e.g. missing API key); for the ones that initialise, it produces a fresh `findings_scale.yaml`. Pull requests welcomed when accounts unlock more rows.\n\nThree optional lifecycle hooks: `on_session_end` auto-consolidates, `on_pre_compress` preserves high-salience memories through context compression, `on_memory_write` mirrors built-in `MEMORY.md` / `USER.md` additions.\n\n## Skills (opt-in, v0.3.0+)\n\nSkills are **procedural memory**: reusable patterns the agent distills from observed success and pulls back next session. They live in YantrikDB's shared `skill_substrate` namespace alongside skills authored by other consumers (Lane B SDK, server handlers, WisePick). Hermes-authored skills are tagged `metadata.source=hermes` so any downstream consumer can filter them in or out cleanly.\n\n**Disabled by default.** Adding the plugin to an existing Hermes install doesn't change the tool schema the model sees. Enable explicitly when you want the agentic skill loop:\n\n```bash\necho \"YANTRIKDB_SKILLS_ENABLED=true\" \u003e\u003e ~/.hermes/.env\n```\n\nWhen enabled, three new tools join the schema:\n\n| Tool | Purpose |\n|---|---|\n| `yantrikdb_skill_search` | Semantic search over agent-authored skills, namespace-isolated from regular memory recall. |\n| `yantrikdb_skill_define` | Distill a procedural pattern into a reusable skill (`skill_id`, `body`, `skill_type`, `applies_to`). Client-side validation reproduces yantrikdb-server's wrapper checks. |\n| `yantrikdb_skill_outcome` | Record success/failure for a skill after it's used. Append-only event log; rollup is the agent's call, not the substrate's. |\n\nThe agentic loop closes: agent observes a successful sequence → distills it via `define` → next session pulls it via `search` → records outcome via `outcome` → over time, ranking reflects what actually works.\n\n**Lifecycle distinction worth understanding.** Hermes' own filesystem skills (`$HERMES_HOME/skills/*.md`) are *human-authored, durable, version-controlled*. YantrikDB skills are *agent-authored, runtime-evolving, semantic-search-queryable*. Different kinds of canonical, not competing authorities. The model picks by lifecycle.\n\n### Explainability is a side effect, not a bolt-on\n\nEvery `recall()` result already carries the structured ranking-reason list — that's the engine's standard response shape. The model can *read* it without prompt engineering. From the live Hermes session captured in `VERIFICATION.md`, DeepSeek's natural-language summary of the recall:\n\n\u003e *\"All 3 memories returned, ranked by relevance × recency × importance. The top result ranked highest (semantic match + keyword + high importance + recency), followed by [...] (keyword match), then [...] (high importance but no direct keyword overlap).\"*\n\nDeepSeek wasn't told the reason codes existed; it parsed them from the tool response and reflected them in its explanation. That's the architectural shape we wanted: the explainability surface is the recall response itself, transport-agnostic, model-agnostic, and visible to anyone who looks at the JSON. No separate \"explain\" tool. No second LLM call. The cost of explainability is zero because it was never separate.\n\n## Verification\n\n- **96 unit tests** covering request formation, error taxonomy, provider contract, hook semantics, circuit breaker, text truncation, mode-aware availability — all mocked, no network required.\n- **2 live integration tests** (`tests/integration/test_live.py`) that exercise the full flow against a real `yantrikdb-server`. Skipped by default; run with `YANTRIKDB_INTEGRATION_URL` + `YANTRIKDB_INTEGRATION_TOKEN` set.\n- **End-to-end Hermes demos** against an unmodified Hermes 0.9.0 install for both backends, captured in **[VERIFICATION.md](VERIFICATION.md)** — DeepSeek-driven sessions calling all 8 tools, with `why_retrieved` reason codes flowing through the model's reasoning verbatim.\n\n### Performance (steady-state, post-warmup)\n\n| Op | v0.1 HTTP (Apr 14) | v0.2 Embedded (May 9) |\n|---|---|---|\n| `record_text` p50 | 13.8 ms | **0.60 ms** |\n| `recall_text` p50 | 24.0 ms | **2.58 ms** |\n| `record_text` p99 | 55.3 ms | 10.66 ms |\n| `recall_text` p99 | 67.2 ms | 13.24 ms |\n| Cold start | n/a | 77 ms (one-time) |\n| Required infrastructure | yantrikdb-server + token | none |\n| `pip install` footprint | wheel + requests | wheel + 2 small libs (~10 MB total) |\n\nEven embedded p99 tail latency is faster than HTTP p50 — bad-case embedded beats typical-case HTTP. Long-running soak validation is in progress upstream ([yantrikos/yantrikdb saga task #2](https://github.com/yantrikos/yantrikdb)); these numbers are 100-iteration micro-benchmarks, not 24-hour production traces.\n\n### About the embedder quality claims\n\nTier 1 (`with_default()`, ~8 MB) uses [`potion-base-2M`](https://huggingface.co/minishlab/potion-base-2M) via [`model2vec-rs`](https://github.com/MinishLab/model2vec-rs) — a pure-Rust static embedding (lookup table + mean-pool + L2-normalize), no transformer forward pass. Tier 2 (`potion-base-8M`, 28 MB) and Tier 3 (`potion-base-32M`, 121 MB) trade larger model files for higher recall and live behind `set_embedder_named()` (downloaded on first use, cached under user data dir).\n\n**Quality numbers cited in this README are R@5 vs `sentence-transformers/all-MiniLM-L6-v2` (dim=384) on the upstream [evaluation corpus](https://github.com/yantrikos/yantrikdb/blob/main/scratch/eval_potion_2m.py).** The \"~89% / ~92% / ~95% of MiniLM\" approximations are from that specific eval; your mileage will vary on a different corpus or task. Semantic separation is also corpus-size dependent — at 3 records all vectors look similar (top score ~0.58); at 8+ with real diversity the score range opens up (top score ~0.84). If you're evaluating, run against your own data.\n\nCI runs ruff + mypy + pytest on Python 3.11 / 3.12 / 3.13 / 3.14 on every push.\n\n## Running the tests\n\n```bash\npython -m pytest tests/                          # unit tests\nYANTRIKDB_INTEGRATION_URL=http://localhost:7438 \\\nYANTRIKDB_INTEGRATION_TOKEN=ydb_... \\\n  python -m pytest tests/integration/ -v         # live integration\n```\n\n## Status\n\n**v0.4.2** (current) — first-class embedder loaders for the `model2vec` family and the HF `sentence-transformers` ecosystem; embedding dim auto-probed; default install stays slim via optional `[model2vec]` and `[sentence-transformers]` pip extras. 151 tests passing on Python 3.11/3.12/3.13. **Standalone-by-design** per Hermes maintainer guidance — Hermes is not accepting new memory providers upstream; standalone plugins installed via `pip` are the recommended pattern. PR [#9989](https://github.com/NousResearch/hermes-agent/pull/9989) closed 2026-05-13 with that resolution.\n\n### Release cadence\n\n| Version | Date | Highlight |\n|---|---|---|\n| v0.1.0 | 2026-04-14 | HTTP backend, 8 tools, 96 tests |\n| v0.2.0 | 2026-05-09 | Embedded backend default, ~10 MB install, sub-ms recall |\n| v0.3.0 | 2026-05-09 | Skill substrate bridge (opt-in) |\n| v0.3.1 | 2026-05-09 | PyPI distribution + `yantrikdb-hermes` CLI installer |\n| v0.4.1 | 2026-05-12 | Pluggable embedders (custom Python class via `YANTRIKDB_EMBEDDER_CLASS`) |\n| v0.4.2 | 2026-05-12 | First-class `model2vec` + `sentence-transformers` loaders, auto-probed dim |\n\n### Durability signals\n\nThe maintainer doesn't promise \"I won't quit\" — promises like that aren't testable. What's testable:\n\n- Every release ships with tests + CI (Python 3.11 / 3.12 / 3.13) + tagged CHANGELOG + a publish gate where 151 tests + ruff + mypy must pass before the wheel uploads to PyPI.\n- First user issue on this repo (multilingual embedding support) was filed and shipped to PyPI the same day — 25 minutes from raised to released.\n- Underlying yantrikdb engine: ~5.2k/mo PyPI downloads; flagship server repo has 141 GitHub stars; broader yantrikos namespace ~13.5k/mo combined PyPI+npm. Cross-stack ownership (engine + HTTP server + MCP server + this plugin) — 14+ months of parallel maintenance, not a one-week hobby.\n- Independent recognition: accepted into the [Cursor Directory](https://cursor.directory/plugins/yantrikdb) (300k+ developer reach) and (sibling project) the Anthropic MCP Directory.\n- Substrate design deposited as a peer-citable preprint: [10.5281/zenodo.20128887](https://doi.org/10.5281/zenodo.20128887).\n\nThat's what I can give you. The technical merits are above; the maintenance shape is here so you can audit before adopting.\n\nSee [yantrikdb/CHANGELOG.md](yantrikdb/CHANGELOG.md) for full release notes and [yantrikdb/ARCHITECTURE.md](yantrikdb/ARCHITECTURE.md) for the control flow, error taxonomy, and threading model (covering both backends).\n\n## License\n\nThis plugin is **MIT** (matching Hermes — the code is intended for upstream contribution). The [YantrikDB server](https://github.com/yantrikos/yantrikdb-server) itself is AGPL-3.0; the plugin only talks to it over HTTP and does not embed or redistribute any server code, so the boundary is the same as any MIT client talking to an AGPL service. See [yantrikdb/SECURITY.md](yantrikdb/SECURITY.md#license-boundary-agpl-vs-mit) for the full note.\n\n## Links\n\n- **Plugin docs**: [yantrikdb/README.md](yantrikdb/README.md)\n- **Architecture**: [yantrikdb/ARCHITECTURE.md](yantrikdb/ARCHITECTURE.md)\n- **Verification transcripts**: [VERIFICATION.md](VERIFICATION.md)\n- **Hermes Agent**: \u003chttps://github.com/NousResearch/hermes-agent\u003e\n- **YantrikDB server**: \u003chttps://github.com/yantrikos/yantrikdb-server\u003e\n- **YantrikDB docs**: \u003chttps://yantrikdb.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyantrikos%2Fyantrikdb-hermes-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyantrikos%2Fyantrikdb-hermes-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyantrikos%2Fyantrikdb-hermes-plugin/lists"}