Skip to main content
Hermes state.db is Xerg’s sole monetary authority. Xerg opens it read-only, reconciles Hermes’s session/model/task usage, and never lets observer or trace records add tokens, requests, or spend.

​
Compatibility and measurement bounds

The 0.33.0 compatibility update supports state schemas 25–26. Bounded live acceptance passed for these exact Hermes pins: These results apply to the exercised workloads, not every concurrent workload or unverified runtime revision. They do not establish exact mechanical comparisons on partial-observation runtimes. Earlier v0.17–v0.20.1 certification remains historical evidence. Older formats and schema 27+ are best-effort, explicitly uncertified readers. The optional third-party OTLP integration passed its own bounded v0.21.0 acceptance on the separate exact plugin/runtime pair documented in Hermes trace collection; it does not broaden first-party observer acceptance. The observer update omits policy-bearing pre-tool registration on pinned Hermes v0.20.6 and v0.21.0, where overlapping invocations can block before Xerg’s callback runs. Pinned v0.20.1 retains its demonstrated safe older registration; unverified runtimes omit it conservatively. Requested-versus-executed argument comparison is unavailable on affected versions. Delivered post-tool evidence remains local; pre-dependent repeated-input, sequential terminal-burst, and state-write metrics and comparisons are omitted, not zero or an improvement. Other security plugins remain effective. No runtime safety setting is disabled. Lifecycle observation is complete-capable for pinned v0.20.1, partial for pinned v0.20.6/v0.21.0, and unknown for unverified versions. Complete-capable describes the supported capability, not a guarantee for every audit. Liveness and zero local writer drops do not prove delivery; the upstream suppression count is unknown, not zero. Xerg exposes this distinction in local coverage and health. Timing and request order require actual, uniquely correlated boundaries, not matching event counts or spawn timestamps. Missing queue-time measurements are omitted. Partially observed mechanical totals are lower bounds and cannot establish exact before/after improvements or resolved findings. Missing API starts retain authoritative aggregate economics rather than invented request order. On v0.20.1/v0.20.6, a child result can report completed while schema_valid is false. Execution completion and schema-valid output are different facts. A bounded, content-free local subagent-result record preserves native status and available boolean metadata.schemaValid separately. It retains no child output and does not declare a successful outcome, validated savings, or avoidable spend. The child’s recorded cost and activity remain included. Hermes v0.20 bounds terminal results before the observer receives them. Xerg prefers the structured output_total_chars value and treats the character count as a conservative UTF-8 byte floor; marker parsing is fallback only. Returned bytes remain exact. Generated and truncated quantities render as At least when only a floor is known, and remain unavailable when neither structured nor marker totals are usable. Xerg counts Unicode codepoints for the visible-output subtraction and clamps the truncated floor at zero. Xerg never reads, stats, resolves, persists, or otherwise dereferences a full_output_path found in a Hermes tool result. Recoverable spill output is a Hermes operator concern, not an input to Xerg. The observer ledger stays xerg.hermes.observer.v1; optional measurement fields preserve tolerant parsing in both directions. New Xerg releases suppress generated/truncated findings from old ledgers when exactness cannot be proven, while old Xerg releases ignore the new lower-bound fields. Xerg 0.24.0 was not certified for Hermes v0.20.x terminal mechanics and could report bounded generated/truncated byte values as understated exact quantities. State-only economics remained sound for rows Hermes successfully recorded. Version 0.24.1 fixed those terminal measurements; 0.24.2 added continuous observer liveness without changing the evidence ledger.

​
Profiles and local-only rollups

Single-profile selection uses an explicit database, explicit profile, HERMES_HOME, the sticky active profile, then the platform default. Database, legacy files, observer events, and health resolve from that same home. An invalid explicit or sticky selection fails instead of silently switching profiles. Named profiles exclude explicit database/log/session paths. All-profile mode excludes individual path overrides and trace captures. Collector profile selection is also supported. The all-profile result is local-only, even if it contains one database. Direct push, cached push, activation/connect, wire dry runs, and file import reject it before an audit upload. Local JSON preserves its localUploadScope marker. Upload each established single source separately when wanted; Xerg does not fan out. Source bindings are independent of profile names, selectors, or accounting-policy keys. Initial registration requires explicit confirmation and retained/destination evidence checks; automation needs an established binding. Missing, damaged, locked, or conflicting identity data never silently creates another hosted source. Divergent copies remain visible for separate non-additive inspection and block a complete rollup until resolved. Restore the original binding rather than deleting the registry. Ambiguous legacy caches require resolution or a fresh audit; existing prepared Push files retain their original single-source retry metadata. These safeguards cover supported Xerg workflows, not arbitrary manually constructed or marker-stripped aggregates submitted to an unchanged backend.

​
Recover an existing source binding

For a native-default upgrade, xerg audit --runtime hermes --push can recover the legacy binding after confirmation when retained evidence and the exact existing destination agree. Unresolved custom or opaque Hermes history without a consistent retained binding requires explicit binding; established bindings still work:
Use the original authoritative database and exact existing wire source ID/source key, not its hosted src_* identifier. Confirm only after verifying that this database supplied that source’s history. The command verifies authenticated destination metadata and retained evidence, records the local binding, and never creates a hosted source or uploads an audit. Then retry the single-source audit or cached xerg push; binding does not rewrite historical comparison keys. Destination verification rejects redirects and requires HTTPS, except for HTTP localhost development. If redirected, verify the configured workspace API URL before retrying; no binding is recorded from the redirect target. Fresh audit uploads also recheck an established binding’s exact source key for conflicting destination metadata, without prompting again or changing its captured identity. This does not prove that arbitrary unrelated databases with identical destination metadata are the same authority. Successful registration preserves a verified current .bak, including the first binding and subsequently added profiles. If backup persistence fails, the operation stops before upload; retry preserves an already committed identity. A crash between the separate file updates can still leave an older backup, which recovery must reject if it cannot account for newer history. If a registry is damaged and its validated original .bak exists, use the separate operation:
Restoration requires a validated backup consistent with retained and destination identities, and preserves damaged registry bytes. Both commands accept --db /path/to/snapshots.json to select recovery evidence; this does not change the default cache selected by xerg push. In automation, --yes replaces only the explicit confirmation, after the original authority/binding has been verified; it never waives evidence, ambiguity, lock, conflict or damage checks. If recovery is rejected, preserve the registry and source evidence rather than deleting them or creating a replacement identity. Existing prepared Push files remain unchanged and do not require registry reconstruction. Hidden/pinned Bot Chats remain included economically. Bot source categories are retained without exposing room, member, profile, or bot names as spend attribution.

​
Cost provenance and accounting changes

Positive recorded actual cost wins, followed by positive recorded estimated cost. Only supported explicit status with a corresponding valid zero amount establishes known-zero usage: actual and included are observed zero; estimated is estimated zero. NULL, unknown, or missing provenance and subscription billing mode alone do not prove free usage. Priced zero remains priced; an included subscription itself is not claimed to be free. Paid MoA advisor cost is retained even when the latest aggregator status says included. For schemas 25–26, session residuals subtract main-task usage only; auxiliary rows are added once. Earlier readers remain best-effort. Parent and child direct costs remain separate, and delegation/footer views never add another monetary source. Earlier Xerg versions could replace explicitly included zero with catalog spend or hide a main-session residual behind auxiliary usage; corrected measurements may therefore differ without an underlying workload change.

​
State-only audits

State-only audits provide aggregate economics exact for rows Hermes recorded, tool inventory when Hermes stored tool-message records, compression/branch/delegation lineage, workload economics, and explicit analysis coverage. For schema 22 and newer, Xerg checks the session_model_usage table primary key without mutating the database. If its key does not match Hermes’s expected six-column key, Hermes may have dropped distinct task rows: totals may be floors for affected periods. Totals remain exact for rows Hermes recorded. This source integrity warning is local-only, advisory, excluded from audit identity and Push Payload v7, and does not repair the source. Identical economics may therefore deduplicate against an older hosted row that was stored before the warning was available. They preserve total spend, request count, cumulative input/output/cache tokens, workflow and model rollups, tool counts, and delegated-workload totals. They do not populate first-request cost, initial context, request-level context growth, retry sequences, or identical-input loop findings because those require an ordered request stream. A state-only result therefore reads like:
$0 identified waste; request-sequence waste was not assessed.
Because a state aggregate may represent several API requests, Xerg excludes it from retry waste, tool-loop waste, cache churn, and sequence-dependent signals. The report says when each detector was not eligible; missing evidence is never presented as proof of zero inefficiency.

​
Full first-party request evidence

Install Xerg’s optional local observer:
Restart Hermes and verify liveness before starting new Xerg-directed activity:
Doctor separates current-process liveness from audit-window reconciliation. A bounded mode-0600 sidecar is atomically refreshed every 60 seconds and becomes stale after 150 seconds; no heartbeat is appended to the evidence ledger. The strict command exits 5 unless a process is running and its writer is not known unhealthy. This is a continuous production-coverage guard, not only a test check. The observer must be enabled before sequence-dependent activity occurs; historical aggregate sessions cannot be reconstructed. Existing aggregate audits may still run, but their warning appears before totals and conclusions. When XERG_HERMES_EVENTS_DIR configures the observer writer, doctor and audit use that same directory by default; an explicit --hermes-events-dir still overrides command input. Then run:
The observer records content-free request, tool, terminal, delegation, and lifecycle evidence. For each provider/model/task group Xerg requires request count and input/output/cache buckets to equal state.db exactly. Exact groups become ordered one-request calls; incomplete, dropped, ambiguous, or conflicting groups remain unchanged aggregates. Authoritative cost is allocated across exact requests and sums back to the state cost exactly. Logical-request detail in 0.33.0. Equivalent captured native starts under the same profile/writer/session/request identity may represent one detailed logical request when one completion matches and state request counts and token buckets reconcile exactly. Local metadata.observedAttemptCount has basis observedAttemptCountBasis: "observed-native-starts": it counts captured native starts, not every provider attempt or a proven retry cause. The latencyBasis: "logical-request-including-native-retries" value describes the whole logical interval; per-attempt timing, usage and cost remain unavailable. Missing required native metadata or ambiguous starts preserve aggregate fallback. Old captures without that metadata cannot be repaired retroactively. Bounded live acceptance demonstrated detailed request reconciliation and actual baseline selection on all three pins above. Historical observer records outside the selected state sessions do not make otherwise complete current-session pairs incomplete; those records remain retained. Missing or conflicting evidence for a current session still prevents exact reconciliation. Acceptance does not turn observed native starts into a complete provider-attempt ledger. state.db remains the only monetary authority. Controlled truncated-tool retry cases on pinned v0.20.1, v0.20.6 and v0.21.0 omit superseded-response usage from state. This is not a claim about every abandoned attempt or zero provider billing: Xerg does not reconstruct missing charges or treat a logical request as a complete provider-attempt ledger. On post-only runtimes, a uniquely delivered completion can associate an already counted state tool execution with its reconciled request. Xerg requires matching session, native tool ID, tool name, writer/profile scope and request completion evidence. Missing or conflicting matches remain unassociated. This does not create another execution, add spend, or reconstruct requested arguments, execution starts, duration or order from a completion callback. Hermes v0.20.1 also records auxiliary model work such as title_generation in task-scoped economic rows. That work does not pass through Hermes’s public per-request plugin hooks. Xerg therefore includes its authoritative requests, tokens, and cost as a separate aggregate, marks sequence-dependent analysis for that activity unavailable, and continues using exact observer evidence for the observable main and delegated requests. Xerg does not monkey-patch Hermes’s private auxiliary client or present the mixed result as full request coverage. The observer never persists prompts, messages, tool definitions, arguments, commands, paths, results, delegated goals, summaries, or file contents. Content may be inspected transiently only to compute counts, byte sizes, and process-scoped keyed fingerprints. Registration binds the observer to Hermes’s profile-aware home accessor; writers, correlation maps, and health remain isolated across profiles in one process. Unload/reload produces unique files and an orderly stopped-health record. The v1 ledger/health formats gain a path-free profile_scope_id; old unscoped ledgers remain usable only for an explicitly paired single-source audit. All-profile strict liveness requires every included profile to be healthy. Recognized request_messages take precedence over conversation history. Local hermesRequestInput counts tool results and their serialized bytes with basis hermes-request-hook; this is not an exact HTTP-payload claim. Raw post-tool bytes stay separate because transforms and spilling can change the next request. Unsupported or oversized inputs omit measurements and reduce coverage. Rejected system/tool definitions or post-tool arguments/results can drop the whole local callback event, including its boundary; the drop is reported and cannot establish complete request coverage. Authoritative state economics remain available. The observer never opens spill references. Executed-argument fingerprints use correlated post-hook evidence; blocked/cancelled attempts are not executions. Callbacks return no directives and do not wait for disk or network.

​
Local analysis blocks

Both Hermes and OpenClaw local summaries can include:
  • analysisCoverage: eligible/fallback request counts plus tool, lineage, and context coverage
  • toolActivity: execution names/counts, exact/heuristic/unassociated linkage, result bytes, and associated model spend
  • workloadEconomics: root/child/descendant calls and spend, depth, first-child economics, and lineage gaps
Hermes also retains mechanicalEfficiency for direct terminal/tool mechanics. Detailed tool mechanics remain local. Audit Push Payload v7 sends only bounded, content-free detector eligibility, assessed request/spend counts, and source stability so the dashboard, Compare, trends, Ask Xerg, hosted MCP, and Slack can state what was and was not assessed.

​
IDs and comparisons

economicAuditId identifies shared economics and remains stable when exact observer evidence replaces an aggregate without changing totals. auditId identifies the analysis and includes findings, detector coverage, and source stability, so an observer-enriched analysis is stored separately. Old v1-v4 push retries keep their original deduplication behavior. Identified-waste rate always divides identified waste by total spend. Every surface also shows assessed spend. Waste rates compare only when detector modes match and partial audits have compatible eligible-spend ratios; total-spend comparisons remain available when source and time-window semantics match. Hermes’s hermes-accounting-v2 comparison policy separates corrected measurements from pre-correction baselines, including custom comparison overrides. It does not change the hosted source, reset metering/highwater, or rewrite historical snapshots. Repeated --since 7d selections remain comparable as their actual measurement dates advance. Period-ledger deltas may reflect accounting-method changes; they are not qualified savings. Compatible corrected measurements remain eligible under the ordinary evidence and validation requirements. Mechanical generated/truncated bytes compare only when both audits carry exact measurements. Floors are not differenced, even against another floor, and legacy unknown values are not compared. A comparison spanning different Hermes versions or state schema versions carries a caveat because runtime changes may account for part of the observed savings.