Skip to main content

​
Basic usage

Xerg compares the current audit against the newest compatible prior snapshot stored in the local JSON snapshot store. For Hermes, local snapshots also compare mechanical metric values and report newly observed or resolved mechanical finding kinds. These deltas remain separate from monetary comparison, recommendations, and failure thresholds, and never cross the push wire. Mechanical comparisons require compatible, available evidence on both sides. Missing measurements are not zero, and lower bounds cannot establish an exact improvement or a resolved finding. Partial or unknown Hermes lifecycle observation omits unsupported timing, queue and sequence comparisons; a spawn timestamp does not substitute for an observed execution start. These limits do not change authoritative state costs.

​
What makes a snapshot compatible?

For local audits, Xerg matches on:
  • the same effective authoritative source roots
  • the same normalized --since window
For OpenClaw, a mixed gateway/transcript audit that finds calls in both kinds uses transcript source identity, so it can compare with a transcript-only audit over the same session root and window. It does not match an older combined-source baseline. For SSH and Railway audits, Xerg uses a stable comparison key derived from the target, the effective remote log and session paths, and the normalized --since window. When mixed OpenClaw source authority is engaged, the key also carries the source-authority version. Equivalent values such as 024h and 24h share a key. Omitting the flag uses all. That means these usually compare cleanly:
  • rerunning the same local audit
  • rerunning the same SSH target with the same remote paths
  • rerunning the same Railway service with the same remote paths
These usually do not compare cleanly:
  • changing from default paths to different explicit paths
  • changing the --since window from 24h to 7d
  • switching to a different SSH host or Railway service
CLI versions before 0.22.0 did not include the remote window in this identity. Xerg intentionally does not compare or deduplicate across that boundary. The first upgraded remote push therefore has new economic and analysis fingerprints and may consume one Free snapshot; a Free workspace already at its monthly limit receives the existing 429 quota response. Version 0.28.0 adds a second intentional remote boundary when mixed OpenClaw source authority is engaged. The first corrected mixed --compare run reports that no compatible baseline was found instead of presenting excluded gateway economics as a spend reduction. The next mixed run with the same target, paths, and window compares normally. Single-kind remote keys are unchanged. Existing local and hosted measurements remain immutable; re-audit the original evidence to create a corrected measurement.

​
Hermes accounting-policy boundary

hermes-accounting-v2 separates corrected Hermes measurements from older accounting, including custom comparison overrides. Source identity and captured host/environment remain unchanged; this does not create a new hosted source, reset metering highwater, or rewrite old snapshots. Old-to-corrected methodology changes are not eligible savings or Optimization validation evidence. Compatible corrected measurements use the same normalized window selection. Two --since 7d audits can compare as their actual dates advance; absolute start, end, and generation times are not comparison-key components. Period-ledger measurement deltas can include methodology changes and are not qualified savings.

​
First run behavior

If you use --compare before a compatible baseline exists, Xerg still completes the audit. It adds this note to the summary:
Versions before 0.5.3 stored local snapshots in a native SQLite database. The current CLI uses a JSON snapshot store, so older xerg.db baselines do not participate in new comparisons. Run one current audit to create the new baseline.

​
Database requirements

--compare needs local snapshot history. This works:
This does not:
That combination fails because there is no local snapshot store to compare against.
  1. Run an initial audit.
  2. Make one workflow or model change.
  3. Re-run the same audit with the same effective inputs and --compare.
  4. Use the delta section to confirm whether runtime spend, structural waste, and high-confidence waste improved.
In the hosted dashboard, Measurement A is the baseline and Measurement B is current. Compare starts with the most recently active source, selects its newest measurement as B, and recommends the nearest earlier compatible activity period as A. Measurement choices show the activity period rather than repeating source, framework, host, IDs, or economics. Existing explicit a and b links remain authoritative, and Compare different sources retains the advanced cross-source workflow. Compatibility requires the same source key, environment, and comparison key. Compare still allows incompatible or reverse-chronology explicit pairs, but it limits incompatible evidence to membership-only groups and warns when B predates A. Every delta remains B − A. When pushed measurements include outcomes, Compare also shows success rate and cost per successful run for A and B. A missing outcome rollup is labeled unavailable rather than treated as zero. Source and Measurement decision summaries use the comparison already attached to the current measurement. They show baseline → current plus the signed Runtime spend change, Identified waste change, and Waste-rate change only when the stored comparison explicitly establishes pricing on both measurements. A missing availability flag is treated as unavailable, so an entirely unpriced baseline’s placeholder zero is never presented as an exact change. Spend direction remains workload-dependent. Waste direction additionally requires compatible detector coverage. Waste-rate deltas use percentage points (pp), not relative percentages: 20% → 15% is a decrease of 5 percentage points and a relative decrease of 25%.