Skip to content

Choose a collection path

Hermes Usage Insights supports more than one ingestion model because different deployments have different constraints.

The right path depends on whether you can modify Hermes, whether you need continuous collection, and how much attribution fidelity you need.

Quick comparison

demo-data

  • Best when: you want to test reports and plots locally
  • Requires Hermes source changes: no
  • Continuous: no
  • Session totals: demo only
  • Per-tool token attribution: demo only

import-hermes

  • Best when: you want a one-shot no-source-change backfill
  • Requires Hermes source changes: no
  • Continuous: no
  • Session totals: yes
  • Per-tool token attribution: no

watch-hermes

  • Best when: you want a continuous no-source-change collector
  • Requires Hermes source changes: no
  • Continuous: yes
  • Session totals: yes
  • Per-tool token attribution: no

ingest-jsonl

  • Best when: you already emit structured events or need richer attribution
  • Requires Hermes source changes: usually yes upstream
  • Continuous: depends on the caller
  • Session totals: yes if emitted
  • Per-tool token attribution: yes if emitted

Use demo-data when you want a local proof first

uv run hui --db usage.db demo-data
uv run hui --db usage.db report summary

This is the best first step when you want to verify the package before wiring real data.

Use import-hermes for a one-shot backfill

uv run hui \
  --db artifacts/hermes-usage.db \
  import-hermes \
  --hermes-home /path/to/hermes-home

Use this when:

  • Hermes is already running or has historical artifacts on disk
  • you want to import current totals without changing Hermes source
  • you do not need an always-on collector loop yet

Use watch-hermes for steady collector mode

uv run hui \
  --db artifacts/hermes-usage.db \
  watch-hermes \
  --hermes-home /path/to/hermes-home \
  --interval-seconds 60

Use this when:

  • you want continuous no-source-change collection
  • Hermes keeps writing state.db and sessions/
  • a polling loop is operationally acceptable

What collector mode tells you reliably

Collector mode is built from Hermes' persisted artifacts.

It gives you:

  • accurate session-level token deltas when state.db is present
  • tool-call events and tool-call counts from session transcripts
  • incremental imports into the local SQLite database

It does not give you:

  • exact per-tool token attribution from transcript-only tool-call events
  • exact per-message usage attribution when Hermes does not persist those usage blocks

Practical consequence:

  • report breakdown --by tool is useful for frequency analysis in collector mode
  • it should not be interpreted as exact token spend by tool unless those tokens were emitted explicitly upstream

Use ingest-jsonl when you need richer attribution

uv run hui --db usage.db ingest-jsonl path/to/events.jsonl

Use this when:

  • you can emit structured events from Hermes or another upstream producer
  • you want exact event-level fields such as tool_name, skill_name, and token counts on the same event
  • you want the most forward-compatible ingestion path

Rule of thumb

  • Start with demo-data to verify the package.
  • Use import-hermes or watch-hermes when you need the no-source-change Hermes path.
  • Use ingest-jsonl when you care about precise attribution more than zero-touch integration.