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.
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 too2b.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?})insrc/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.parseeach line, skip lines that fail to parse or lack a stringsurface/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.