Skip to content

Event schema

Hermes Usage Insights stores normalized usage events as newline-delimited JSON objects on ingest and as rows in SQLite after import.

This page documents both:

  • the generic JSONL event contract
  • the collector-generated event shapes produced by Hermes artifact import

Required fields

  • timestamp — ISO8601 timestamp, ideally UTC with Z
  • session_id — Hermes session identifier or equivalent upstream session key

Optional fields

  • event_id — caller-supplied id; if omitted, the package creates a deterministic id from the payload
  • conversation_id
  • provider
  • model
  • role
  • tool_name
  • skill_name
  • source
  • prompt_tokens
  • completion_tokens
  • total_tokens
  • cost_usd
  • notes
  • metadata — arbitrary JSON object

Generic semantics

  • total_tokens defaults to prompt_tokens + completion_tokens
  • metadata is stored as JSON and included in free-text search
  • search is intentionally simple substring matching over normalized event text
  • duplicate event ids are ignored on insert

For upstream JSONL emitters, these are good default source values:

  • assistant_message
  • tool_call
  • skill_load
  • session_rollup

Example JSONL event

{
  "timestamp": "2026-04-08T16:30:00Z",
  "session_id": "session-1",
  "conversation_id": "conv-1",
  "provider": "openai",
  "model": "gpt-5.4",
  "role": "assistant",
  "tool_name": "search_files",
  "skill_name": "writing-plans",
  "source": "tool_call",
  "prompt_tokens": 94,
  "completion_tokens": 26,
  "total_tokens": 120,
  "cost_usd": 0.011,
  "notes": "planning step",
  "metadata": {
    "path": "/workspace/hermes-usage-insights",
    "category": "planning"
  }
}

Collector-generated Hermes events

When you run import-hermes or watch-hermes, the package synthesizes events from Hermes persisted artifacts.

Those imported rows use event shapes that are worth documenting explicitly.

1. Session delta events

These represent changes in cumulative Hermes session totals.

Typical characteristics:

  • source is hermes_session_delta
  • session_id identifies the imported Hermes session
  • total_tokens reflects the imported delta for that polling/import step
  • metadata includes collector-specific provenance and current totals

Representative example:

{
  "timestamp": "2026-04-10T18:12:00Z",
  "session_id": "session-abc",
  "provider": "openai",
  "model": "gpt-5.4",
  "source": "hermes_session_delta",
  "prompt_tokens": 640,
  "completion_tokens": 210,
  "total_tokens": 850,
  "cost_usd": 0.0912,
  "notes": "Imported Hermes session totals delta",
  "metadata": {
    "import_kind": "session_delta",
    "session_key": "telegram:589084909",
    "cache_read_tokens": 120,
    "cache_write_tokens": 0,
    "current_totals": {
      "input_tokens": 1440,
      "output_tokens": 510,
      "cache_read_tokens": 120,
      "cache_write_tokens": 0,
      "total_cost": 0.1538
    }
  }
}

Semantics:

  • this is the event family that drives accurate session-level totals in collector mode
  • cache read/write totals may appear in metadata even though the main generic event model only exposes prompt/completion/total/cost at top level
  • these events are incremental deltas, not full session snapshots repeated verbatim

2. Tool-call events

These represent transcript-derived tool calls.

Typical characteristics:

  • source is hermes_tool_call
  • tool_name is populated from transcript metadata
  • total_tokens is usually 0 in collector mode because exact tool-level usage is not available from persisted transcripts alone
  • metadata includes transcript provenance such as call id or message index

Representative example:

{
  "timestamp": "2026-04-10T18:12:01Z",
  "session_id": "session-abc",
  "model": "gpt-5.4",
  "tool_name": "browser_navigate",
  "source": "hermes_tool_call",
  "total_tokens": 0,
  "notes": "Imported Hermes transcript tool call",
  "metadata": {
    "import_kind": "tool_call",
    "session_key": "telegram:589084909",
    "message_index": 42,
    "tool_index": 0,
    "call_id": "call_123"
  }
}

Semantics:

  • these rows are reliable for tool frequency and search
  • they should not be interpreted as exact tool-level token accounting unless richer usage telemetry is emitted upstream

Search semantics

The package stores normalized event text for quick substring search.

Searchable material may include:

  • notes
  • tool names
  • skill names
  • model names
  • serialized metadata content

It is intentionally simple and deterministic rather than a heavyweight full-text engine.

Storage notes

Once ingested, events are stored in SQLite.

The package treats:

  • deterministic event ids as the main deduplication mechanism
  • incremental collector progress as part of the local database state
  • metadata as structured JSON carried through to export and search