Hermes Dashboard on YantrikDB — Operator Console for Hermes Memory

yantrikdb-hermes-dashboard is a FastAPI operator console built by community member @wysie for a Hermes agent backed by YantrikDB. It’s not just a memory viewer — it’s the configuration surface for per-user memory, identity/scope routing, namespace coverage, contradiction review, lifecycle housekeeping, and the entity-graph visualiser. Read-only browsing by default; mutating operations are gated behind an opt-in Admin Mode plus an optional dashboard password.

Until v0.8.17 the dashboard only ran against an embedded SQLite file, which meant you could only point it at the single machine the agent ran on. YantrikDB Server v0.8.17 ships the three HTTP read endpoints the dashboard needs, so you can now run it against a clustered or remote YantrikDB deployment and inspect a multi-agent fleet’s shared memory from one place.

What the dashboard does

Per the dashboard’s README, the operator surface covers:

Overview — active / consolidated / forgotten memories, conflicts, entities, edges, DB size, embedder
Memory browser — search, status / domain / source filters, namespace chips, detail drawer
Recall debugger — top-k, domain / source, consolidated-memory and entity-expansion controls
Identity & Scope — Hermes owner / person scoping, actor mapping, shared spaces, conversation routing, namespace coverage (this is where you toggle the per-user memory the plugin’s v0.4.10 owner-scoping feature exposes)
Contradiction review and resolution helpers — Admin Mode required for resolution
Entity graph inspection + a Visualiser with Constellation and Neural Map modes backed by local YantrikDB data
Lifecycle and maintenance — stale / upcoming memories, triggers, patterns, safe housekeeping
JSONL export of active memories
Settings page — Admin Mode toggle, dashboard password, namespace defaults

Security considerations

The dashboard is a community project, not maintained by the YantrikDB org. We surface it here because it solves a real problem and integrates cleanly with the v0.8.17 endpoints — but you are running third-party code that can read and (in Admin Mode) mutate your agent’s memory. Read this section before pointing it at anything sensitive.

The dashboard ships its own safety model (per its README), and that’s the first line of defence:

Read-only browsing by default. Mutating operations require Admin Mode, which is opt-in via the Settings page (or YANTRIKDB_DASHBOARD_ADMIN_MODE=true at launch).
Optional dashboard password — configure from Settings before exposing the dashboard beyond 127.0.0.1.
Bind to 127.0.0.1 by default. The README recommends YANTRIKDB_DASHBOARD_HOST=127.0.0.1; bind to 0.0.0.0 only if you intentionally want LAN access — and set the dashboard password first.

Additional cautions that apply to any third-party tool holding a memory credential:

Audit the source. Read app.py and its dependencies before deploying. Pin a specific commit (git checkout <sha>) — don’t run main blindly.
Bearer token = full data-plane access in HTTP mode. YantrikDB Server v0.8.17 doesn’t yet ship scope-restricted tokens. A token you give the dashboard for cluster mode can remember, forget, recall, and relate on every memory in its namespace — not just read. Treat the dashboard’s token as a full credential, and rotate it after sessions where you don’t trust the local state. (Per-token Scope::Read-only is a Phase 2 follow-up; when it ships, mint the dashboard a Read-only token.)
Don’t expose Admin Mode externally without password protection. The README is explicit: “Do not expose an Admin Mode dashboard without password protection.” If you port-forward or front the dashboard with a permissive reverse proxy, set the password from Settings first, and prefer your own SSO / basic-auth layer in front of it.
XSS surface. The dashboard renders raw memory text in the browser. If the memories were written by an untrusted agent (e.g. one that ingested external content), HTML/script in the memory body can execute in your browser session. Running on 127.0.0.1 keeps the attack surface to your own machine.
Token-pinning best practice (HTTP mode). Mint a dashboard-specific token (yantrikdb token create --db <name> --label hermes-dashboard) rather than reusing the agent’s token — so you can revoke it via yantrikdb token revoke without affecting the agent’s writes.
Supply-chain hygiene. Watch the dashboard repo’s commit history if you re-deploy from main. The repo is a personal account (not org-protected); pinning to a known-good commit hash is the simplest defense.

These cautions apply to any third-party tool that holds a token to your memory. We’re naming them explicitly because the v0.8.17 endpoints make this category of tooling possible, and we want the security model to be visible upfront — both the dashboard’s own (Admin Mode + password + 127.0.0.1 default) and the operator’s responsibility for the broader supply chain.

What changed in v0.8.17

Issue #39 Phase 1 shipped three new /v1/* read endpoints plus the substrate that authorizes them:

Endpoint	What it returns
`GET /v1/identity-scope`	What this token can see: principal, effective scope, namespace inventory, identities/actors/spaces/conversations summary. The nested envelope the dashboard’s sidebar reads.
`GET /v1/memories`	Paged, filtered listing of active memories. Query params: `namespace`, `status`, `domain`, `memory_type`, `limit` (default 50, max 200), `offset`, `sort` (`created_at` / `importance` / `last_access`). Response: `{total, limit, offset, items[]}` with each row in the dashboard’s 25-field shape.
`GET /v1/memory/{rid}`	Point read for a single memory by RID, with `consolidation_sources`/`entities`/`claims` conditional arrays. Supports `?min_seq=N` for read-your-writes after a write.

Plus three cross-cutting upgrades the dashboard also benefits from:

Structured error envelope across the whole /v1/* surface: {"error":{"code":"stable_id","message":"human","hint":"optional"}} per docs/error-codes.md. The dashboard branches on code, not on the prose message.
Token-derived auth + namespace scoping. /v1/identity-scope is computed from the token’s authorized scope — a tenant-pinned token sees exactly one namespace, a cluster-admin token enumerates everything.
FTS5 fallback marker on /v1/recall. The dashboard’s search box gets an explicit fallback: "fts5_keyword" field when semantic returned nothing and the engine fell back to BM25 keyword matching — so the UI can flag the result as “we keyword-matched, not semantic-matched”.

Quickstart

1. Run a YantrikDB server

docker pull ghcr.io/yantrikos/yantrikdb:0.8.17
docker run --rm -p 7438:7438 \
  -v $PWD/data:/var/lib/yantrikdb \
  ghcr.io/yantrikos/yantrikdb:0.8.17

The Docker image ships the bundled potion-base-2M embedder by default — no network calls at first run, ~7 MB baked into the binary.

2. Create a database and mint a token

docker exec -it <container> yantrikdb db create --data-dir /var/lib/yantrikdb default
docker exec -it <container> yantrikdb token create --data-dir /var/lib/yantrikdb --db default --label hermes
# → ydb_xxxxxxxxxxxx... (save this — shown once)

3. Point your Hermes agent at the cluster

In ~/.hermes/.env:

YANTRIKDB_MODE=http
YANTRIKDB_URL=http://localhost:7438
YANTRIKDB_TOKEN=ydb_xxxxxxxxxxxx...
YANTRIKDB_NAMESPACE=default

See the Hermes plugin guide for the per-mode trade-offs (embedded vs HTTP).

4. Run the dashboard

git clone https://github.com/wysie/yantrikdb-hermes-dashboard
cd yantrikdb-hermes-dashboard
# Configure the dashboard to talk to the same server
export YANTRIKDB_URL=http://localhost:7438
export YANTRIKDB_TOKEN=ydb_xxxxxxxxxxxx...
uvicorn app:app --port 8080

Open http://localhost:8080. The sidebar enumerates the namespaces visible to the token via /v1/identity-scope. Click into a memory to see the per-row detail via /v1/memory/{rid}. The search box hits /v1/recall and surfaces the FTS5-fallback indicator when relevant.

Auth model (what the token sees)

The dashboard’s left-hand “Identity Scope” panel is rendered directly from the /v1/identity-scope response. Two patterns matter:

Tenant-pinned token (created via yantrikdb token create --db <name>) → the dashboard sees exactly that database’s namespace. Requesting ?namespace=other returns 403 namespace_not_found. This is the safe-by-default path for production deployments where each agent has its own scoped token.
Cluster-admin token (the cluster_secret from your config, when cluster mode is enabled) → the dashboard enumerates every database on the cluster. The operator inspecting a multi-agent fleet uses this token.

Either way, the token is never echoed in the response body — the principal’s id field surfaces a non-reversible hash prefix only, so refreshing the dashboard with browser devtools open doesn’t leak the secret to the JavaScript console.

Phase 1 limitations (Phase 2/3 follow-ups)

The dashboard ships against the shape, not yet the full depth. Honest call-outs:

identity_scope.{identities,actors,spaces,conversations} are empty arrays in Phase 1 — those are plugin-side concepts the engine doesn’t store on its own.
namespace_inventory[].count is null for cluster-admin tokens — populating per-namespace counts would mean opening every engine on a synchronous handler call, which is a cached path that lands in Phase 2.
Memory rows return null for updated_at, updated_at_iso, tombstone_reason, embedding_model, and embedding_bytes — engine v0.7.x doesn’t surface those on its public listing API yet. created_at_iso is populated.
/v1/memories rejects (specific 400 invalid_query_parameter) on q text search, source filter, and the sort ∈ {updated_at, access_count, certainty} variants. The dashboard either omits these or routes q through /v1/recall instead. Phase 2/3 backfills as engine APIs land.

The full list is in the v0.8.17 CHANGELOG.

Why this exists

YantrikDB stores a Hermes agent’s whole working memory — every fact, every conversation turn, every consolidation, every contradiction. The dashboard is the visual layer for that memory: namespaces on the left, raw rows in the middle, identity scope and recall traces on the right. Without it you’d be writing one-off curl /v1/memories?... invocations.

@wysie is a community member who maintains the dashboard — they’re also the contributor behind yantrikdb-hermes-plugin v0.4.10 (the owner-scoping feature). The issue → spec → ship loop for v0.8.17 took about a day of focused work after the design questions were locked.