Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
8.9 KB
Raw Blame

Metrics layer - the dashboard data contract

Since v0.45.0 every run-level pass in Open Second Brain reports its numbers into one uniform, machine-readable layer under Brain/metrics/. This document is the stable on-disk contract for consumers - in particular the upcoming dashboard plugin - so they can read metrics without importing Open Second Brain internals.

Layout

One append-only JSONL file per surface PER DEVICE, named <surface>[.<device-id>].jsonl:

Brain/metrics/
β”œβ”€β”€ index.jsonl                  # the shard with the empty device id
β”œβ”€β”€ index.a1b2c3d4.jsonl         # one machine's shard
β”œβ”€β”€ index.e5f6a7b8.jsonl         # another machine's shard
β”œβ”€β”€ bridge_discovery.a1b2c3d4.jsonl
β”œβ”€β”€ communities.a1b2c3d4.jsonl
β”œβ”€β”€ recall_benchmark.a1b2c3d4.jsonl
β”œβ”€β”€ self_tuning.a1b2c3d4.jsonl
β”œβ”€β”€ self_heal_reindex.a1b2c3d4.jsonl
└── dream_stage.a1b2c3d4.jsonl

Surface names are lowercase snake_case ([a-z][a-z0-9_]*, max 64 chars); device ids are lowercase slugs ([a-z0-9-], max 32 chars). The vault is Syncthing-replicated, so a device only ever appends to the file its own id names - see "The per-device shard rule" in docs/observability.md. A file with no device suffix is the shard with the empty device id and is read exactly like any other.

A consumer must therefore group by surface, not by file name: strip an optional trailing .<device-id> segment before the .jsonl extension to get the surface, and read every file that maps to the surface it renders. Two names are never metric shards: a *.sync-conflict-* copy (Syncthing leftover; o2b brain doctor reports it) and any other unknown file in the directory, which must be ignored.

Record envelope

Every line is one JSON object:

{
  "schema": "o2b.metrics.v1",
  "surface": "recall_benchmark",
  "run_at": "2026-06-05T12:00:00Z",
  "payload": { "hit_at_k": 1, "mrr": 0.958 }
}
  • schema - envelope version. Evolution rule mirrors continuity records: additive optional payload fields do NOT bump the version; renames, removals, or semantic changes bump to o2b.metrics.v2.
  • surface - matches the file name with any .<device-id> shard suffix removed.
  • run_at - ISO-8601 UTC timestamp of the run the record describes.
  • payload - surface-specific object (fields below).

Records are RUN-LEVEL: one line per index run, discovery pass, benchmark, or tuning run. Per-query retrieval events stay in recall telemetry (docs/observability.md). Writes are O_APPEND single lines, so concurrent writers interleave instead of racing; readers must skip torn or non-object lines (the bundled listMetrics reader does). Keep payloads small (well under the platform pipe-buffer size, ~4 KiB) - O_APPEND atomicity is only guaranteed for short writes, and a metric record is a summary, not a report.

Surfaces and payload fields (v0.45.0)

Surface Writer Payload fields
index every non-empty index run added, updated, deleted, alias_resolved, relation_violations, tier_drift
bridge_discovery o2b brain bridges discover, MCP brain_bridges, maintenance lane proposals, scanned_candidates, vec_available, dismissed_total, min_similarity, max_proposals, lane (lane runs)
communities o2b brain clusters run, MCP brain_clusters, maintenance lane run record: communities, sizes, written, removed, min_size, lane (lane runs), batches / failed_batches (batched runs). Freshness record (--if-stale only, since v1.46.0): freshness, freshness_reason, newest_input_ms, oldest_output_ms, oldest_output_age_ms
recall_benchmark o2b brain benchmark run, MCP brain_benchmark total, k, expand, hit_at_k, mrr, misses
self_tuning o2b brain tune run, MCP brain_tune chosen, evaluated, best_mrr, dataset_hash
dream_stage o2b brain dream stage / apply, MCP brain_dream (since 1.0.0) action (stage/apply), run_id, proposals, sources, changed; apply adds new_unconfirmed, confirmed, retired counts
prompt_prefix decision-panel commit (opt-in promptPrefixMetric), context-pack consume (opt-in promptPrefix) kind (write_session/context_pack), prefix_hash (sha-256 of the stable preamble), prefix_chars, call_count, stable_count
vault_vitals o2b brain vitals preferences_scanned, domain_diversity, connectivity_index, orphan_count, gap_pressure
self_heal_upgrade o2b brain upgrade --self-heal (the detached worker ensureVaultCurrent starts) outcome (applied / failed), duration_ms, files (rewritten, or pending on failed), error (on failed). An attempt that finds nothing pending writes no row
self_heal_reindex ensureVaultCurrent (parent) and o2b search reindex --self-heal <run-id> (child) parent row: decision (spawned / skipped_writer_lock), run_id (on spawned). Child row: outcome (completed / failed), run_id, duration_ms, error (on failed)
index_freshen (since v1.76.0) o2b search index --freshen <token> (the background run freshen on read starts) outcome (completed / failed), duration_ms, changed (on completed), error and failures (on failed). A row is written only when the run changed documents or failed
maintenance_spend (since v1.64.0) o2b brain maintenance run, MCP brain_maintenance (run) task (reindex), model (null when the config names none), tokens, estimated_usd, forced (force-cost overrode a positive gate), lane (always true: both front doors are the lane)
storage_usage (since v1.85.0) o2b brain storage, MCP brain_storage (every report invocation), and a maintenance-lane run the capacity gate skips (sampled before the skip, from the gate's own census) run_id, total_bytes, bytes_by_tier (per recoverability tier: vault-content, derived), measured (true when every surface answered), unmeasured (the surfaces refused, each with its reason). The series is the forecast's input: o2b brain storage reports its linear trend, and the run id is the idempotency key, so one invocation never writes a second row

Payload fields marked "(lane runs)" appear only on maintenance-lane emissions. All fields are additive-optional from a consumer's point of view: render what is present, ignore what is unknown.

self_heal_reindex is the one surface written by two processes. The post-upgrade rebuild is spawned detached with every stream ignored, so the parent records what it decided to do and the child records how it ended; the two pair on the run_id the parent mints and passes to the child on its command line. Not a pid: a pid is machine-local, and these rows sync, so two devices' pid spaces (and one device's pid reuse) pair rows from unrelated runs.

A spawned row with no terminal row beside it means only that no terminal outcome was recorded. The child may have been killed or reaped with its session; it may still be running (a full reindex takes minutes); it may have died before the recording was armed; or its own fail-soft append may have failed on a read-only vault or a full disk. The rows describe a per-device index from inside a synced vault, so a row says a self-heal ran on some device, never that this device's index is stale.

Reading

  • Newest records sit at the end of each file; the bundled reader (listMetrics(vault, {surface?, since?, limit?}) in src/core/brain/metrics.ts) returns newest-first and merges surfaces when none is specified.
  • External consumers (dashboards, scripts in other languages) should read the files directly: split on newlines, JSON.parse each line, skip lines that fail to parse or lack a string surface/run_at.
  • Metric emission is fail-soft everywhere: a metrics-layer problem never fails the pass that produced the numbers, so gaps in a file mean the run failed or predates the layer - not data corruption.

prompt_prefix: stability, not provider cache-hit rate

The prompt_prefix surface measures STRUCTURAL prefix stability - how many generation handoffs in one pass led with byte-identical preamble bytes (stable_count of call_count). It deliberately does NOT claim to measure a provider's cache-hit rate: the kernel never calls an LLM, so it cannot observe whether a provider actually reused a cached prefix. What it can guarantee, and what this metric reports, is that the kernel handed the agent a stable, cache-eligible prefix across the pass - the precondition a provider prefix cache rewards. The raw prompt is never stored; only the sha-256 hash and the code-point length of the prefix.

The genuine multi-call pass is the decision panel (every persona step and the synthesis share the Decision topic: frame, so a fully stable pass reports stable_count == call_count == personas + 1). A context-pack consume is a single-call pass over its stable request preamble. Both surfaces are opt-in and default off; the pass output is byte-identical when the gate is unset.