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
111 KB
Raw Blame

Observability contract

Open Second Brain records what it did - learning events, recall decisions, served context, session activity - across a small set of file-based surfaces inside the vault. This document is the contract for anyone consuming those surfaces: which events exist, when they fire, what correlates them, what safety guarantees their payloads carry, and how the record shapes evolve. Everything here is verified against the source files named in each section.

Surfaces at a glance

Surface Location Writer Format
Brain log Brain/log/<date>[.<device-id>].md + JSONL sidecar appendLogEvent() in src/core/brain/log.ts Markdown line + JSONL row per event
Continuity store Brain/log/continuity/<month>[.<device-id>].jsonl appendContinuityRecord() in src/core/brain/continuity/store.ts one JSON record per line
Idempotency ledger Brain/logs/idempotency/<month>[.<device-id>].jsonl rememberKey() in src/core/brain/idempotency-ledger.ts one key -> content hash record per line
Decision ledger Brain/logs/decisions/<month>[.<device-id>].jsonl appendDecisionLedger() in src/core/brain/permissions/ledger.ts; read back by o2b brain permissions ledger one JSON decision row per line (see "The decision ledger" below)
Preference mutation audit Brain/log/pref-audit/<pref-id>/device[.<device-id>].jsonl (legacy flat Brain/log/pref-audit/<pref-id>[.<device-id>].jsonl still read) appendPrefAudit() in src/core/brain/pref-audit.ts one JSON record per line
Session lineage ledger Brain/.state/session-lineage[.<device-id>].jsonl (+ session-lineage-gaps[.<device-id>].jsonl) recordLineageObservation() in src/core/brain/lineage/ledger.ts one JSON record per line, sequence-numbered and hash-chained per file
Session lifecycle audit Brain/log/session-lifecycle/<ISO-week>[.<device-id>].jsonl captureSessionLifecycleEvent() in src/core/brain/session-lifecycle.ts JSONL audit rows
Other audit weeks <ISO-week>[.<device-id>].jsonl under Brain/log/hygiene/, Brain/log/secret-custody/, Brain/log/schema-mutations/, Brain/log/watchdog/ (fallback .open-second-brain/watchdog-audit/) and .open-second-brain/hook-audit/ appendAuditRecord() in src/core/reliability/audit.ts, the one writer every audit site calls JSONL audit rows
Fixed-name ledgers Brain/log/query-demand, Brain/log/recurrence-support, Brain/log/capture-decisions, Brain/skill-proposals/verifier-rejections, Brain/preferences/pref-<slug>.history, Brain/projects/git/<repo>/commits and .open-second-brain/maintenance-runs, each <stem>[.<device-id>].jsonl the owning module's path helper through shardedFileName() in src/core/brain/ledger-shards.ts one JSON record per line
Bench runs <runs-dir>/<run-id>/ (default .open-second-brain/bench-runs/; excluded from git by the guard block o2b brain init seeds into the vault .gitignore) runMemoryBench() in src/core/bench/phases.ts checkpoint.json, per-question results, report.json
Failed automatic upgrade .open-second-brain/self-heal-upgrade.json (per device, not synced with Brain/) recordSelfHealUpgradeFailure() in src/core/maintenance/self-heal-upgrade-state.ts one JSON object: failed_at, error, consecutive_failures, pending, retry_after; read by o2b doctor (self_heal_upgrade), o2b brain status and o2b brain upgrade --dry-run
Metrics Brain/metrics/<surface>[.<device-id>].jsonl appendMetric() in src/core/brain/metrics.ts one run-level JSON record per line (see docs/metrics.md)
Signal archive Brain/inbox/archived/sig-*.md the dream pass (archiveStaleSignals() in src/core/brain/dream-apply.ts, policy in src/core/brain/signal-archive.ts) the inbox signal file, moved byte for byte; the moving run's dream log event lists every id under archived_signals
Dedup index cache $OPEN_SECOND_BRAIN_DEDUP_CACHE_DIR, else the user cache dir open-second-brain/dedup-index/<vault-digest>.json (outside the vault; OPEN_SECOND_BRAIN_DEDUP_CACHE=0 disables) writeDedupIndexCache() in src/core/brain/dedup-index-cache.ts one JSON file per vault: per directory its listing digest, count and mtime, per signal file its size, mtime, id and dedup_hash; derived, safe to delete

The per-device shard rule

Every append-only ledger above is one file per period (or per key, or per surface) PER DEVICE. The vault is replicated with Syncthing, and two machines appending to one file inside a single sync window produce a .sync-conflict-* copy that no reader merges β€” so the rows split silently across two files. The shard suffix removes the contention instead of resolving it after the fact: a device only ever appends to the file its own id names.

The grammar is <base>[.<device-id>].<ext>, and it lives in exactly one place, src/core/brain/ledger-shards.ts. The device id is the lowercase slug resolveDeviceId() produces (src/core/config.ts), which is device-local config and never synced. A file with no device suffix is the shard with the EMPTY id: legacy history stays readable, no migration renames anything, and a vault whose device id resolves empty (O2B_DEVICE_ID="", or a config that cannot be read) keeps writing exactly the bytes it always did.

Every reader merges every shard it finds, in the one order all devices agree on: the ledger's own sort key, then the shard id, then position within the shard. The shard id is the tie-break rather than the arrival order because arrival order is precisely what differs between two Syncthing peers β€” so two machines reading the same set of shards return the same sequence. The continuity store adds its content-hash record id as a last resort after the shard id, which is what keeps a single-shard vault reading back in exactly the order it did before sharding existed.

Two names are never shards. A *.sync-conflict-* copy is excluded from every listing even when its middle segment fits the shard-id shape (the sync-conflict prefix is reserved in the device-id validator for the same reason), and o2b brain doctor reports any leftover copy under any ledger directory as sync-conflict-log, naming the directory so the union+dedup merge has an address. A name whose base does not match the ledger's own layout is not that ledger's file at all β€” bases go into the grammar as patterns, or as escaped literals where the base is a value (a preference id may legitimately contain a dot).

The audit weeks and the fixed-name ledgers adopted the grammar in 1.63.0. Their readers merge every shard: the maintenance journal, the git commit store and the recurrence-support ledger interleave shards by each row's own time without ever reordering the rows of one shard (so a single-shard vault reads exactly as before, and the order-sensitive recurrence fold never replays one device's purge before another device's earlier event), the git store keeps one copy of each commit and tag, the query-demand read keeps its timestamp order, the preference edit history reads shards in shard-id order, and the schema-pack digest picks the newest record across every week shard. The capture-decision and verifier-rejection ledgers have no reader; only their writers changed. A rewrite touches only the shard this device writes: query-demand compaction caps that shard, and the maintenance-journal cap sweep rewrites only the local shard, so the journal cap applies per device. o2b state status reports a sharded fixed-name ledger present when its legacy file or any shard exists, and the doctor's sync-conflict-log sweep covers the directories of these two rows except the maintenance journal's .open-second-brain/ root. Where a swept directory also holds whole files (Brain/skill-proposals/, Brain/preferences/, a git repository's state.json), a conflict copy without the .jsonl extension is not a split shard: it keeps the sync-conflict-log code with a hand-resolve remedy instead of the merge instruction. A source-layout test fails when a new append-mode writer uses neither the shard helpers nor a named allow-list entry.

The session lineage ledger is the one with an extra invariant: its sequence numbers and hash chain are per FILE, so a per-device shard is a per-device chain, compaction is per shard, and verifyLineageLedger verifies each shard separately and reports each finding under that shard's own path. A break in one machine's ledger says nothing about another's.

The prompt_prefix metric surface measures STRUCTURAL prompt-prefix stability (whether the kernel handed the agent a byte-stable, cache-eligible preamble across a generation pass), never a provider's cache-hit rate the kernel cannot observe. It stores only the SHA-256 hash and length of the prefix, never the raw prompt - the same payload-safety rule as generation_report. See docs/metrics.md.

Brain log events

appendLogEvent() writes one human-readable line to the daily Markdown log plus a structured JSONL sidecar row. These events are always-on: each one is the audit trail of the operation that produced it, never optional telemetry. Kinds (from BRAIN_LOG_EVENT_KIND in src/core/brain/types.ts):

Kind Fires when
dream, promote, retire, noted-redundant, signal-suppressed, skip-corrupted-frontmatter, reconcile the deterministic learning pass runs. The dream event lists signals moved to inbox/processed/ under moved_to_processed and signals moved to inbox/archived/ (older than dream.contradiction_window_days, never consumed) under archived_signals
feedback, apply-evidence, force-confirmed, reject a taste signal or evidence event is recorded
pin, unpin, rollback, merge, upgrade operator-facing vault maintenance
freeze, unfreeze an operator stopped or reopened the content lane for every device that syncs the vault (o2b brain freeze / o2b brain unfreeze). One event per real transition only - a second freeze, or an unfreeze on an open vault, writes nothing. freeze carries the reason and the device_id it was set from; unfreeze carries the frozen_at, by and reason read off the marker before it was removed, which is the only place they survive the file
write-refused a write was refused because the vault is frozen. Appended at the MCP tool boundary - the guard that refuses sits below the log module and cannot append without closing an import cycle - one per refused call, carrying the tool, the agent and the marker's reason. The Brain log itself keeps writing while frozen (the audit write lane, WRITE_LANE.audit in src/core/brain/freeze-marker.ts), because a freeze that silenced the log would erase the record of itself
scan-inline, import-session, import-claude-memory capture and import operations
note a narrative milestone is recorded (brain_note); since v1.81.0 also the answer-quote-check Stop hook's enforce trail - exactly one event per turn that found unverified quoted spans, carrying hook: answer-quote-check, the phases that ran, the checked and unverified counts, and the findings as capped one-line previews
note-write a vault note is created, updated, appended to, or reverted
session-lifecycle a captured lifecycle event also produced Brain writes
decision-open a question was parked with enumerated options at Brain/decisions/open-<slug>.md, ahead of the decision it may become. Payload carries the open wikilink, the title, the option count and the agent. Distinct from decision-record because nothing has been decided yet
decision-resolved an open decision was closed by choosing one of its options, minting a real type: decision page. Payload carries the open wikilink, the minted decision wikilink, the choice and the agent. The minted page itself carries the usual decision-record event; this event records the transition
decision-discarded an open decision was closed WITHOUT a decision. Payload carries the open wikilink, the reason and the agent. Separated from decision-resolved so "never decided" is machine-filterable against "decided as X"
ambient-withheld an ambient extraction capture was suppressed by operator consent (guardrails.ambient_writeback: false). One event per suppressed capture, carrying the count of signals the capture would have written - never their content. Keys absent log nothing, because the lane ran as today
lessons-approved, lessons-denied, lessons-promoted (agent-presence, t_1e952e43) the operator records a lesson-promotion decision or a managed block receives lesson content. Operator CLI only - o2b brain lessons approve / deny / refresh-blocks; no agent-facing surface can mint these events, so the audit trail of what entered an agent rules file is operator-authored by construction. lessons-approved carries the pref wikilink, the targets, the pinned approved_content_hash and the consent verdict; lessons-denied carries the pref and the verdict; lessons-promoted carries the targets that changed and the prefs delivered, one event per write that landed (a no-op refresh emits nothing). The doctor grades managed blocks in the four-state vocabulary absent | current | drifted | stale-lessons (registered in the verdict-vocabulary census), where stale-lessons is an approval whose pinned hash no longer matches the live text; the counts ride the brain status snapshot (lessons.approved/denied/stale) without a new surface

Note writes

Every note mutation funnels through two seams - createNote and the write-batch kernel - and each one appends exactly ONE note-write event. The payload is all strings, because the log payload contract admits string | string[] and nothing else:

Field What it holds
write_id nw_<14 timestamp digits>_<16 hex>, derived from the event body, so two devices that record the same write agree on its id
op create, update, append, or revert (NOTE_WRITE_OP)
target vault-relative POSIX path of the note
hash_before sha-256 of the bytes replaced, or the literal absent when the target did not exist - deliberately not the sha-256 of zero bytes, which an empty FILE would also produce
hash_after sha-256 of the bytes now on disk, or the same literal absent when the write left no file - which only a revert that removes a note the selected writes created produces, paired with bytes_after: 0
bytes_before / bytes_after byte sizes, rendered as decimal strings
agent resolveAgentName() against the config the writing surface runs under; caller-asserted by construction, as src/core/write-binding/index.ts states

The device is NOT a payload field: it rides on the log shard name exactly as it does for every other event, and origin_channel is stamped by the appender. listNoteWrites (src/core/brain/notes/write-log.ts) reads the record back and reports the shard as the device, the empty string being the legacy un-sharded log rather than an unknown machine. o2b brain writes and the brain_writes MCP tool are the two surfaces over it, and brain_agent_query --kind note answers "which notes did this agent touch" off the same events.

Order, and the gap the receipt names. The bytes are written FIRST and the event appended second, so a log failure never fails a write that has already landed - the snapshot-event precedent, with the silence removed. recordNoteWrite never throws: it returns write_id: null with an audit_reason, and every note-write result and MCP receipt carries both. A write that authored no bytes - a skipped create (if_exists: "skip") or a byte-identical rewrite - records nothing and carries no write_id at all; the receipt reports the skip through the op's own flag (updated: false / appended: false).

Before-image store. The bytes an update or append replaced are kept at Brain/.state/write-images/<sha256>, stored BEFORE the atomic write so a crash or a failed store never leaves the prior bytes replaced without their copy - a byte-identical rewrite is decided first and stores no image, because the prior bytes stay on disk and an image would claim a replace that never happened - and skipped when an image of that content already exists - so a note toggled between two states costs two files, not two per write. The store is a STATE_SURFACES row inside the snapshot region; o2b brain writes prune-images [--older-than-days N] [--dry-run] bounds it by file age, default 30 days (WRITE_IMAGE_RETENTION_DAYS). An image is a copy of note content the snapshot region already archives, so removing one loses no content - it only narrows how far back a revert can reach, which a revert plan reports by name.

Revert. o2b brain writes revert (--agent A | --device D | --path P) [--since --until] reads the same events back and plans what undoing them would do; brain_writes action plan_revert returns the same plan and never applies it. A selector naming none of agent, device or path is refused by name (unbounded_selector): a time window alone selects every write by every agent on every machine, which is a vault rollback and has its own verb. Per target, over the selected writes S (oldest..newest) and every recorded write A on that target:

Verdict When
refuse / unrecorded the current bytes cannot be read at all, so no drift verdict is possible
refuse / drift sha-256 of the bytes on disk is not the hash_after of the newest write in S - including the target being gone when it should be there
refuse / interleaved a write in A \ S sits between the oldest and newest write in S in the merged total order - (timestamp, shard id, line), the order readLogDay already yields. Timestamps are second-precision, so "between" is a position and not a clock comparison: line order inside one shard IS append order, and three writes in one second on one device are perfectly ordered. The one tie that is not evidence is a same-second tie ACROSS shards, where the merge falls back to the shard id - a name, not a clock - and two devices could have written in either order. So a non-selected write sharing a second with a selected write is trusted only when it shares that write's shard; a cross-shard tie is interleaved on doubt
refuse / already-reverted the target already holds exactly what the revert would produce
refuse / image-missing a restore's before-image is not in the store, or no longer hashes to its own name
delete the oldest write in S has hash_before: absent AND no write in A precedes it - the selection brought the note into existence
restore otherwise: put back the before-image of the oldest write in S

A refused target is reported, never skipped, and the plan's digest - sha256(canonical JSON of { selector, entries }), deliberately NOT covering planned_at - covers refusals too, so an operator who applies a digest applies the plan they read. --apply <digest> re-plans from scratch and refuses digest_mismatch before any byte moves when the vault changed in between; a plan with no actionable entry is refused nothing_to_apply; a frozen vault refuses the whole apply by name before anything is read. Everything that does run goes inside ONE withDestructiveSnapshot under the note-revert reason, so a revert that half-succeeds still has one recovery point covering the state before all of it. Each restored or deleted target keeps a before-image of the bytes it replaced and is recorded through recordNoteWrite with op: revert - a delete as hash_after: absent, bytes_after: 0 - which is what makes a revert attributable and itself revertible: reverting the reverting agent puts the bytes back.

The log chain

Once the log is the attribution record for every write, a line someone deleted or edited has to be detectable. Every JSONL row appended from v1.55.0 on carries two extra keys after payload:

  • h β€” sha256(canonical JSON of { prev, ts, kind, payload }), this row's chain hash;
  • prev β€” the h of the previous chained line in the same shard, or null at that shard's genesis.

prev is inside the hash rather than beside it, which is what makes the structure a chain: editing any earlier line changes every later hash, so a tampered history cannot be re-linked without rewriting the whole shard from the edit forward. The appender computes the link from the shard text it already holds under the directory lock, which is also what makes the link correct β€” two appenders reading the same head would otherwise write two lines claiming the same predecessor.

One chain per shard. Two machines append to two files that Syncthing delivers in whatever order it likes, so there is no total order to chain across; the chain's unit is one file and a break in one device's shard says nothing about another's. The markdown twin is a derived rendering and is NOT chained β€” a human-editable view is the wrong thing to hold to a hash, and the JSONL sidecar is the machine-primary surface every reader already prefers.

Report-only. readLogDay reads ts, kind and payload and nothing else, so a broken shard still yields every event it holds. A log that refused to be read because someone edited it would be a worse outcome than the edit. What the chain buys is that the edit has a name, a file and a line number.

o2b brain log verify [--json] walks every shard and reports the first break in each, by path and line: hash-mismatch (the line was edited after it was written), prev-mismatch (a line between it and its predecessor was removed or reordered), malformed (the line carries no usable chain link where the chain had already started). It exits 1 when any shard does not link up. o2b brain doctor emits one log-chain-broken warning per broken shard with the same next command. Neither repairs anything: the only way to make a broken chain verify is to rewrite the history it records, which is the act the chain exists to detect.

Rows written before the chain shipped carry no h. They are counted as legacy and are clean while they precede the chain β€” the first chained line after them anchors the shard with prev: null. The same shape after a chained line is not history but a line whose links were stripped, and it is reported. The head of a shard is not exempt either: the Brain log never compacts, so a first chained line naming a predecessor means the head of the file was cut off. Sync-conflict copies are excluded from verification β€” they are the doctor's separate sync-conflict-log finding, and their chain never held by construction.

The decision ledger

The Brain log, the pref-audit, the idempotency ledger and the continuity store each record what happened; none of them answers "which rule allowed, asked or denied this write". The decision ledger (Brain/logs/decisions/, write-side-trust wave) is the queryable record of that answer: one JSONL row per gate disposition that was not a plain publish, written by the gate that produced the verdict. appendDecisionLedger() (src/core/brain/permissions/ledger.ts) appends to the month/device shards on the shared shard grammar - the per-device rule and the merged (timestamp, shard id, line) read order are exactly the ones "The per-device shard rule" above states.

The row shape is closed: ts, actor (the resolved principal), via (token, config or operator - where the identity came from), action (write, ingest or owner_write), target, verdict (the disposition - allow, ask, deny, a gate mode such as warn, or a refusal token), source (the deciding rule: an entry id, an agent or role name, default, or a gate key such as integrity.owner_scope_writes), reason (the named token), and the optional tool and correlation_id that join a row to the other trails the way event-trace.ts joins log events.

When rows land is deliberately quiet:

Trigger Rows
No permissions document, every gate key off none - default-silent like every ledger
A permissions document resolves ask or deny for a staged-lane write one row naming the entry, role or default that decided
A permissions document resolves allow one row ONLY when the document sets ledger.record_allows: true
integrity.owner_scope_writes: warn allows a caller-named foreign owner on the preference lane one row carrying the gate key as source

The append contract is absolute: a failed append NEVER throws and never blocks the verdict it records. The ledger rides behind gates that must refuse or stage a write even when accountability cannot be written, so every failure - an unwritable directory, a lock another writer holds - comes back as { logged: false, audit_reason } that the caller surfaces; the receipt carries the reason rather than claiming a record that does not exist.

o2b brain permissions ledger --actor <name> --action <a> --verdict <v> --since <iso> --until <iso> --limit <n> reads the merged rows back (--json for the raw rows); every filter is optional and applied after the deterministic sort, so two devices listing the same shards agree on the order. The ledger is append-only and has no prune verb: retention follows the same open question as every sharded ledger in the vault.

Continuity record kinds

Every continuity record shares one envelope, and exactly these eight fields in this order: schema, id, kind, createdAt, sourceRefs, payload, private, redacted. The table marks how each kind is gated - this is the always-on vs opt-in matrix, verified against the call sites named in the right column.

Kind Gate Emitted by
recall_telemetry opt-in per call (telemetry option/param); the prompt-time hook emitter is gated by recall_inject_enabled instead packContext (mode: context_pack), buildPreCompressPack (mode: pre_compress), brain_search MCP handler (mode: search), brain_query MCP handler (mode: query, since v0.40.0 - payload carries the query kind only, never the supplied preference id / topic / timestamp), and since v1.46.0 the UserPromptSubmit recall-inject hook (mode: search, channel: hook, mapping its inject / abstain / error decision onto ok / empty / error; with the optional recall_inject decision-model use in shadow or enforce, metadata gains a decision_model object - mode, outcome (ok, not_sent or degraded), latency_ms, notes_dropped, abstained - and the abstain reason decision_model_abstain, never prompt or note text; see docs/decision-models/recall-inject.md)
context_receipt opt-in per call (receipt option/param) packContext, buildPreCompressPack
gate_telemetry config key recall_gate_telemetry (default off) brain_recall_gate MCP handler; a call carrying decision_answerable while that decision-model use is on adds adequacy_level and decision_answerable (probability, disagrees); since v1.69.0 a call carrying turn_id records it under turn_id, which the read-model lifts like every other turn id; since v1.82.0 a call that carried a measured quality also records the graded surfacing key - key (null exactly where nothing was measurable), tier and the channel the decision arrived over - and the summary counts the measured records by tier (by_tier)
negative_recall config key recall_gate_telemetry (default off - the SAME gate as gate_telemetry above, so one config decision governs both observations the recall gate makes) brain_recall_gate MCP handler on the zero-usable-result path only (emitNegativeRecallTelemetry in src/core/brain/gate-telemetry.ts) - one record per gate call whose caller reported no usable result, carrying the typed corpus verdict (state, complete, the named unknown_reason when the verdict is unknown, reason) plus the reduced coverage receipt when one could be built (coverage_digest, documents, chunks, schema_version, embedding_signature, last_indexed_at, scope, unindexed_roots). Two receipt fields are not copied into the payload: index_path is deliberately dropped - a host filesystem path is not vault content and these records sync between devices, and the digest already binds it; the embeddings census the receipt carries is likewise absent from the payload and likewise bound by coverage_digest, so a reader comparing two records still sees a keyword-only index differ from a fully embedded one. Same prompt invariant as gate_telemetry: a SHA-256 prefix (prompt_hash) and the length (prompt_chars), never the prompt. A call with usable results writes NO record, so a corpus statement is never invented for an attempt that had one
generation_report opt-in per call (enable) or config key generation_trace_enabled (default off) inbound agent report after a generation handoff (brain_generation_reports action record, o2b brain generation-reports record)
mcp_route_latency config key mcp_route_metrics_enabled (default off) the MCP server's tool-call seam (MCPServer.invokeToolHandler in src/mcp/server.ts) - one record per tools/call and per CLI-bridge callTool; payload carries the tool name, scope, status, duration, and argument KEY NAMES only, never argument values, plus the optional decision_ms and allowlisted stages timings
decision_model_call the optional decision model is active (decision_model_enabled: "true" AND the named key variable set, which a self-hosted laya or openjev server on loopback does not need, and no vault opt-out); an install without the feature writes none runDecision in src/core/decision-model/run.ts - one record per attempted decision request: use, mode, provider, model (the answering version), calibrated, question_count, candidate_count, input_tokens, output_tokens, cost_usd, cost_source (reported, estimated or unknown), latency_ms, outcome (ok or a degrade reason), state_hash (sha-256 of the redacted state), origin (eval or ping) when not an ordinary use call, plus per-use identifiers (a rerank adds head_size, withheld_count, budget_dropped_count, frontmatter_only_count when a frontmatter-only chunk was not sent, injection_suspected in enforce, answerable_probability, and in shadow heuristic_order and decision_order as paths, in enforce decision_permutation as head positions; every other use adds its own identifiers and counts, described on its page under docs/decision-models/). Never the state, a passage, a prompt or a question text. Fail-open: a failed write never fails the search. The daily cost gate and o2b decision-model report read these records
decision_model_extract_commit the optional decision model is active and the extract_prefilter use is not off commit phase of brain_extract_signals / o2b brain extract-signals (src/core/brain/extract-signals-prefilter.ts) - one record per commit that wrote items: session_id, mode, written_count, source_turns (the cited turn ids that name a real turn of the session) and without_source_turn_count; turn ids and counts only, never text. Read by o2b decision-model report --use extract_prefilter for its regret metric
token_impact config key token_impact_ledger_enabled (default off) brain_token_impact action record (emitTokenImpact in src/core/brain/token-impact.ts) - one sample per context pack; payload carries the tokenizer-exact prompt-token counts (baseline_tokens, packed_tokens, signed delta_tokens), the method label (exact/fallback), an optional opaque pack_id, an optional source attribution (decision_model:<use> for savings of a decision-model use), and the optional modeled inference-avoidance estimate - never raw prompts or recalled text
token_impact_outcome config key token_impact_ledger_enabled (default off) brain_token_impact action outcome (recordTokenImpactOutcome) - one first-pass/repair/retry post used only to calibrate the modeled ledger
context_pack_outcome config key context_pack_outcome_enabled (default off) brain_context_pack_outcome action post (postContextPackOutcome in src/core/brain/context-pack-outcome.ts) - one compact per-sample outcome row for a carried context-pack quality-sample id: first-pass/repair/retry counters plus three STRICTLY SEPARATE token signals (exact_prompt_token_savings, modeled_inference_avoidance, observed_provider_tokens), never merged; payload carries counters + an opaque sample_id only, never raw prompts or recalled text, and a caller-omitted field is not invented. One post writes THREE records, all joined on the same sample_id: this row, a token_impact_outcome calibration post, and a context_pack_evidence row (both listed separately below and in this table). The thin wrapper emitContextPackOutcome returns only this row; the two composed records are written either way
context_pack_evidence config key context_pack_outcome_enabled (default off - the same gate as the outcome row it accompanies) composed by every brain_context_pack_outcome action post (recordContextPackEvidence in src/core/brain/context-pack-evidence.ts) - one row per outcome row, joined on the same sample_id, carrying the evidence the kernel reads back off disk (the context_receipt that id names: final_text_hash, item_count, final_text_chars) and a closed verdict over the acting agent's optional claim: match, mismatch, unclaimed (evidence obtained, nothing asserted), or unresolved. A mismatch lists the drifted fields and is RECORDED, never resolved - the outcome row is neither rejected nor silently corrected by it. An unresolved verdict names why through a separate token, sample_absent (the log was read and holds no such receipt) or evidence_unreadable (the log could not be read at all), so absence is never reported as inability. Payload carries those tokens + the opaque sample_id only, never raw prompts or recalled text. NOT an independent attestation: the agent id on the row is self-asserted and this same process wrote the receipt it now reads. The post response echoes the payload under evidence, so a contradicted claim is visible to the poster and not only to a later reader
ingest_dedup always-on, fail-open; written ONLY by a run that actually dropped something the three ingest runs that drop an item on an exact sha-256 dedup_hash collision: captureSessionLifecycleEvent, scanInline, importSession (emitIngestDedupReport in src/core/brain/dedup-telemetry.ts) - one record per run, payload carries the surface, the run's exact_deduped total, and a by_source map keyed by the session id or vault-relative note path being re-ingested. A run that deduped nothing writes NO record, so a real zero stays distinguishable from an absent measurement. Every count is an EXACT-hash drop; the semantic detectors nominate merge candidates and never drop, so no semantic figure appears here
session_turn, session_summary_node always-on within its operation session-recall import (src/core/brain/session-recall.ts) - the write IS the operation
pre_compact_extract always-on within its operation explicit pre-compact extraction (src/core/brain/pre-compact-extract.ts)
source_invalidation always-on within its operation source drift detection (appendContinuitySourceInvalidation)
skill_rewrite_eval_grade always-on, one record per COMPLETED benchmark-gated skill rewrite gate run (agent-presence, t_635e3e72); a run that ends before the gates complete - a promote still awaiting its single held-out check - writes nothing recordSkillRewriteGrade in src/core/brain/skill-proposals.ts, called from o2b brain skill-proposals rewrite-score: payload carries the skill name, the spec hash and tasks hash the run verified against, the metric (tasks_passed_rate), the seed and split rule, the final verdict (promote / hold / not_enough_evidence, where a hold is also what a missed held-out check downgrades a promote to), the baseline and candidate rates, and per-task rows (task_id, passed, failed_checks) for the dev and held-out arms. Identifiers, numbers, booleans and check ids only - never task text and never transcript text; the payload is rebuilt field by field at the boundary so nothing else in the caller's object survives. Kept never-folded so an operator can audit why a rewrite landed or held; the MCP status surface reads the same rows read-only

Session lifecycle capture (captureSessionLifecycleEvent) writes audit rows and Brain log events, and no continuity record at all unless the event actually dropped a repeat - in which case it writes exactly one ingest_dedup record. Both halves of that boundary are pinned by regression tests (tests/core/brain/continuity-emit.test.ts for the silent path, tests/core/brain/dedup-telemetry.test.ts for the dedup path).

Schema version and evolution rule

Since v0.39.0 every new continuity record is stamped schema: "o2b.continuity.v1" (CONTINUITY_SCHEMA_VERSION in src/core/brain/continuity/types.ts).

  • Records written before the stamp existed carry no schema field; every reader treats undefined as v1. Existing JSONL files are never migrated.
  • Additive optional fields do NOT bump the version. Renames, removals, or semantic changes bump to o2b.continuity.v2.
  • The record id (recordId(), sha-256 over kind + createdAt + sourceRefs + payload) deliberately EXCLUDES the schema field, so identical records keep identical dedup ids across the stamp transition. Locked by a known-answer test.
  • Consumers should go through the read-model (src/core/brain/continuity/read-model.ts), which absorbs the version dispatch, lifts session_id/turn_id into first-class fields, and applies the masking policy below.

Correlation IDs

Field Where Stable join?
id (ctn_<stamp>_<sha16>) every continuity record yes - content-hash dedup id
createdAt every continuity record ordering key (store sorts by createdAt, then id)
sourceRefs[].id / .path continuity records joins records to vault artifacts
session_id, turn_id payloads of session-scoped kinds; lifted by the read-model yes - the cross-surface session join
handoffKind, handoffRef generation_report payload handoff; lifted by the read-model yes - joins a generation report to the write-session / context-receipt / dream run it traced
timestamp + agent Brain log events per-event attribution
agentId, isSidechain SessionTurn, from a transcript that records delegation yes - the only thing separating a delegated sub-agent's turns from its parent's, because a sub-agent transcript reuses the PARENT's session id

Multi-agent vaults attribute writers via per-agent identity (brain_agent_query). Delegated sub-agents are correlated as of v1.49.0, and by the additive route this sentence used to promise: SessionTurn carries an optional agentId and an optional isSidechain: true, both emitted only where the transcript records them, so a flat transcript keeps its pre-delegation shape byte for byte. A sub-agent transcript reuses its PARENT's session id, so those two fields are the only thing separating the two agents' turns. The SubagentStop hook records the close under <delegator>-sub-<agent-id>; the agent_transcript_path the event also carries is deliberately not persisted, being a machine-local host path.

Absence is its own identity. Since v1.81.0 a payload with no string session_id is a no-session record, never a member of a blank bucket: the readers no longer coerce the missing key to "", so scoped recall excludes such records (the lineage ledger already omitted blank declarations, so the scope set never held them), grouping sites skip them instead of lumping every unattributed record from every unrelated lane together, and the brain_session_summary digest omits its session_id key rather than answering "". o2b brain doctor counts the rows older writers left under the legacy coercion with the count-only, fail-soft blank-session-identity check - one issue per affected record kind, no fix field: the continuity store is append-only, and rewriting it is a backup-gated design, not a doctor step.

Payload safety

Every continuity payload passes safeContinuityPayload() (src/core/brain/continuity/redaction.ts) before it reaches disk:

  • <private>...</private> regions are stripped and replaced; the record is flagged private: true.
  • Secret-shaped tokens are redacted to ***REDACTED***; the record is flagged redacted: true.
  • The sanitized payload is deep-frozen; nothing mutates it after the flags are computed.
  • gate_telemetry never stores the raw prompt by construction - only a SHA-256 prefix (prompt_hash) and the length (prompt_chars). The test suite asserts this against the persisted files, not just returned values. negative_recall shares that construction (same module, same hash helper) and adds one rule of its own: the coverage receipt it carries drops index_path, so no host filesystem path replicates with the vault.
  • generation_report follows the same rule: the handoff prompt is hashed and counted but never persisted - only prompt_hash (full SHA-256 hex) and prompt_chars land on disk, plus token counts. The kernel never calls an LLM; the report is the agent's INBOUND record after it performed a generation for a brain handoff, so the local token estimate (local_estimate.input_tokens) is always present while the agent-reported usage block is present only when supplied - absent is reported as absent, never fabricated. A grep-guarded regression test pins that no fetch/provider HTTP call exists under src/core for this feature, and a persisted-file assertion confirms no raw prompt survives.
  • mcp_route_latency carries an optional decision_ms (wall time spent in decision-model requests during that call) only when the call made at least one; records from an install without the feature are unchanged.
  • mcp_route_latency carries an optional stages array of { name, ms } entries (v1.74.0): the wall time the call spent in each write stage, summed per name in first-seen order and rounded to 0.1 ms. Names come from the closed ROUTE_STAGE allowlist in src/core/route-scope.ts - validate, idempotency_lookup, near_duplicate_lookup, document_write, idempotency_remember, log_append, preference_write, write_receipt, lint - and emitMcpRouteLatency drops any other name, any negative value and any non-finite value before the record is written, so no path, topic or other free text can land on disk. The key is omitted when no stage ran, so a record from a route without stages is byte-identical to before. Stage timings never appear in the response of the call being measured; they live only in its continuity record, which brain_route_metrics reads back. Stages can nest, so they are not a partition of duration_ms: lint wraps the receipt lint, and the near-duplicate scoring inside that lint is also counted under near_duplicate_lookup. The same milliseconds then appear under both names, lint includes that scoring, and the stages of one record can add up to more than its duration.
  • Routes that emit stages, by the write helpers they reach: every route that writes a signal through writeSignal gets validate and document_write, plus idempotency_lookup and, when the signal is written, idempotency_remember only when the signal carries an idempotency key, which only brain_feedback accepts (its idempotency_key argument). That covers brain_feedback and brain_extract_signals; the latter writes one signal per accepted item, so its stage values are summed across items. brain_feedback adds near_duplicate_lookup (the write-conflict advisory), log_append (the feedback log line, and the second log line under force_confirmed; the advisory's own log line is not timed) and preference_write with force_confirmed; a retry that the idempotency key dedupes stops after idempotency_lookup. Every note write that ends in a write receipt - brain_create_note, brain_update_note, brain_append_note and brain_write_batch - gets write_receipt for each note it writes or rewrites, document_write for each note it creates, and, when at least one page was written, lint and near_duplicate_lookup from the receipt lint (the latter also covers the keyword-index widening when that is on). One route scope per tool call carries both decision_ms and stages; with mcp_route_metrics_enabled off no scope is opened and every stage helper reduces to a plain call.
  • Hook capture is not an MCP route: lifecycle hooks call captureSessionLifecycleEvent directly and hand the dedup walk to a detached worker, so they never pass through invokeToolHandler and carry no stage timings.
  • mcp_route_latency records the route (tool name), MCP scope, status, duration, and the sorted set of argument KEY NAMES only - the tool's own JSON-Schema property names, never operator-supplied argument values - so no prompt, note body, or preference id can land on disk. A persisted-file test asserts key names survive while values never do.
  • The masking policy lives in the read-model (src/core/brain/continuity/read-model.ts) and governs only the readers that go through it: records flagged private are dropped by default and kept only on explicit request; masked text is never un-masked. That is FOUR modules - the o2b brain continuity verbs (trajectory export and listing), the bench harness, brain_event_trace, and skill-usage aggregation. Twenty-two other modules call listContinuityRecords on the store directly and see raw records: no private drop and no schema-version dispatch. The policy is read-model-wide, NOT store-wide. Both lists are asserted by name in tests/core/brain/continuity/reader-census.test.ts, which fails when a module joins or leaves either set, and both COUNTS are pinned there as equalities rather than floors - the direct floor used to sit at twenty against a reality of twenty-one, which is how the number in this sentence came to be wrong. Auditing the direct readers is tracked separately.
  • A hook's tool_response is READ and never written. Lifecycle capture consults it to decide whether the call it is reacting to actually succeeded - a failed brain_feedback must not be replayed, because replaying it mints the record the tool declined to create - and the decline is counted rather than swallowed. The response body itself is arbitrary tool output and never reaches a payload, so declaring it in the hook contract costs nothing on disk.
  • private is the ONLY visibility signal a record carries, and it is inferred from a <private> region in the payload rather than declared. A caller-declared scope field was built for this envelope and removed before release: nothing in the codebase could supply one - no tool argument, no command-line flag, no config key and no library entry point - and its single vocabulary member would have narrowed a record's visibility rather than widened it, since a declared scope is dropped by every reader that does not name it. Adding a declaration to the envelope is a schema change; tests/core/brain/continuity/record-envelope.test.ts pins the eight fields and their order so the next attempt has to be argued for.

Fail-open rules

Telemetry must never block or fail the primary operation. The guarantee is structural, not conventional: gated surfaces route through emitGatedTelemetry(gate, build) (src/core/brain/continuity/emit.ts):

  • gate off (undefined/false/null): the build thunk is NEVER invoked - no payload object, no hash, no write on the no-consumer path;
  • a throwing thunk or store write is swallowed and reported as null; the context pack, pre-compress pack, search response, and recall-gate decision all complete normally with the telemetry field simply absent.

No-consumer regression tests cover each gated surface, so a future call site cannot silently regress to eager payload construction. Writers whose continuity append IS the primary operation (session-recall import, pre-compact extract) stay fail-fast on purpose - failing silently there would lose user data, not telemetry.

Reading the surfaces

  • brain_recall_telemetry (MCP) and o2b brain recall-telemetry list|summary|gate-list|gate-summary aggregate recall and gate records. Since v1.46.0 every recall_telemetry payload carries a channel naming the seam the recall came through - mcp, cli, or hook, a closed set. It is a property of the emit site rather than a caller argument: the MCP handlers stamp mcp, o2b brain context-pack --telemetry stamps cli, and the recall-inject hook stamps hook. Every emit site must name one, enforced at build time, so no new record lacks it. channel is clip-protected alongside session_id and agent_id, so an output-budget clip may not drop it. Filter on it with the channel argument (MCP) or --channel (CLI) on list and summary, and read the by_channel rollup on summary; a channel with no record is absent from that rollup rather than reported as 0. Records written before v1.46.0 carry no channel at all and are never migrated, so they count in total / by_mode / by_status but fall into no by_channel bucket, and any channel filter excludes them. o2b brain doctor crosses the rollup against per-channel install state and reports recall-channel-silent (installed, expected to deliver, silent for 30 days) or recall-channel-unmeasured (one half of that cross could not be read - the latter rides the uncertain stream and does not affect the exit code).
  • The recall-inject hook's optional decision-model filter (decision_model_uses: "recall_inject:shadow|enforce", see docs/decision-models/recall-inject.md) adds to the hook's recall_telemetry metadata and to its local hook-audit line a decision_model object: mode, outcome (ok, not_sent or degraded), latency_ms (the time the filter added to the prompt), notes_dropped and abstained (in shadow, what enforce would have done). Only the local audit line adds degrade_reason on a failure. In enforce a withheld brief is an abstain with reason decision_model_abstain (status empty). Its decision_model_call records carry note_paths (a note that may not leave the machine as (withheld)), helps, inject_any, abstained, notes_dropped, withheld_count, budget_dropped_count and budget_ms; an enforced brief that got shorter writes one token_impact sample with source: decision_model:recall_inject when token_impact_ledger_enabled is on. None of these carries prompt or note text. o2b decision-model report --use recall_inject reads them with p50/p95 added latency, timeout rate, abstain rate and notes dropped next to the hook's recall telemetry.
  • The recall-inject hook's local hook-audit line (action: recall_inject_decision) carries what only the hook knows, each field present only when it applies: config_invalid (the settings among recall_inject_max_notes, recall_inject_max_chars, recall_inject_time_budget_ms and recall_inject_confidence_floor whose value was rejected, so the built-in default ran; a value taken from the environment is named by its OPEN_SECOND_BRAIN_RECALL_INJECT_* variable), dedupe_sets (already_injected and digest_paths, the sizes of the session's recall set and SessionStart digest set the decision consulted, not counts of suppressed notes; absent without a session id or with recall_inject_dedupe off), ledger_recorded: false (an injected brief whose post-stdout ledger write failed, so its notes can repeat; absent when the write succeeded or no ledger applies), slices (one {name, outcome, notes} per declared slice, outcome being inject or that slice's abstain reason) slices_config: "invalid" (the vault's _brain.yaml failed to load; the search reads the same file, so that decision is an error with fault retriever_failed) and, since v1.73.0, retrieval_degraded (the retrieval trail codes of the searches behind the decision, each once in first-seen order, for example semantic-cost-unpriced when the hook's query embed was refused by the cost gate). The gap-promote hook's audit line carries the same retrieval_degraded field for its recall checks. Slice names are vault policy vocabulary and ride the local audit line only, never the synced recall_telemetry record. The abstain reasons all_already_injected and all_slices_abstained reach both surfaces through the existing reason field. See docs/decision-models/recall-inject.md.
  • brain_recall_telemetry operation: "cost" (MCP) and o2b brain recall-telemetry cost fold WRITE volume against the read telemetry above: memory-write ops (Brain-log feedback/apply-evidence/note verbs plus host_memory_write continuity records) are counted per period and reported alongside reads as a write-vs-read ratio, a write_heavy flag, and a rough weighted cost signal. Weights (--write-cost/--read-cost, default 1 each) model "some tools charge on write, some on read"; --write-heavy-ratio (default 1) sets the write-heavy threshold. Read-only; period-scoped by --since/--until. brain_create_note file creation emits no telemetry event today and is not counted.
  • brain_recall_telemetry operation: "dead_weight" (MCP) and o2b brain recall-telemetry dead-weight (since v1.80.0) read the other side of the same records: pages currently in scope that no recorded recall within the telemetry window ever surfaced. The denominator is the vault walk's included paths (current on-disk truth), not the index's document table, so a deleted-but-indexed page is never reported as dead weight; the retrieved set is the union of recorded top_artifacts and observed-use source references, windowed by --since/--until (the report states the earliest matching record). The payload carries pages_total, pages_retrieved, dead_count and a capped dead list behind the usual vault_path envelope, plus a gate_caveat: telemetry is opt-in and records only surfaced top rows, so the report claims "no recorded retrieval surface within telemetry history", never absolute never. Read-only; at remote reach hidden rows are dropped before total.
  • brain_context_receipts and o2b brain context-receipts inspect served-context receipts.
  • The score-aware tail trim (opt-in tail_trim_context_pack config key, default off) adds to a context_pack recall_telemetry record's metadata four counters, present only when the trim actually ran: tail_trim_dropped (tail items dropped whole), tail_trim_kept_by_query_terms (tail items kept because their query-term overlap nearly matched the top delivered score), tail_trim_rescued (former over-budget candidates re-admitted under the freed budget) and tail_trim_tokens_saved (tokens freed, net of the budget the rescue re-spent; never negative, because the rescue may spend only the budget the trim freed). The same counters ride the context_receipt budget block, and each dropped item's tail-trim skip reason surfaces as the telemetry gap tail_trim. An untrimmed pack carries none of these keys, so its records stay byte-identical.
  • The answer-quote-check Stop hook (since v1.81.0) is the answer-boundary counterpart of the receipts above: it verifies the quoted spans in the assistant's own answer against the evidence the turn actually had - the note a span's context names, else the injection ledger's delivered notes - and annotates the unverified ones. Verdicts: verified, not-in-note, source-truncated, note-unavailable, not-text; degradation never upgrades a verdict, so a truncated source arms source-truncated on a miss and an unreadable note arms note-unavailable, never an all-clear. The annotation rides the Stop additionalContext channel Claude Code renders; the other registered runtimes stay silent. Gated per phase by quote_check.recall|active|subagent in _brain.yaml, each off|shadow|enforce, default shadow; in enforce the turn also lands one Brain-log note event (the enforce trail in the table above), so findings survive the session. The check reads only the transcript's bounded tail window and writes nothing else; it never blocks and never edits a transcript.
  • The SessionStart hook writes one context_receipt per injection (host: "hook", trigger: "session_inject") with one item per source it injected. On a measured run its budget block carries inject_budget_chars (the configured value), budgeted_source_count and, since v1.70.0, scoped_rules_chars: the length of the rendered scoped operator rules block, 0 when none rendered. The scoped block is a budgeted source named scoped-rules, but it is subtracted from the budget rather than charged against the full ceiling: the active body was budgeted to inject_budget_chars minus scoped_rules_chars (never below zero). The budget block is present whenever the scoped block rendered, also when there is no active.md. A run that fell back to the last good cache records no budget block, as before, but keeps the standing-rules and scoped-rules items, which are produced outside the fail-open boundary. See "Scoped operator rules" in how-it-works.md.
  • With reground_parts_enabled on, the same receipt's extra.injection gains the chunked re-grounding fields: utf16_chars (the joined payload length in UTF-16 code units), part_ceiling_chars (the per-part ceiling it was cut to, null on a runtime without the reground-deliver carrier or without a session id), parts_total, parts_dropped (parts past the 8-part maximum that were never queued; when it is above zero the last delivered part ends with (context truncated: N further part(s) not delivered)) and over_budget (true when parts were dropped, when a part is still longer than the ceiling, or when the queue could not be written and the whole payload went out as one part). That last case also sets reground_fallback: "ledger_write_failed", which no other path writes, so a failed queue write is told apart from a plain over-budget payload. A part-ceiling key (reground_part_chars, reground_part_chars_claudecode, reground_part_chars_codex) whose value is out of range or not an integer falls through to the next level and is named in config_invalid (by its environment variable, such as OPEN_SECOND_BRAIN_REGROUND_PART_CHARS, when the rejected value came from the environment), present only then. With the flag off none of these fields appears and the receipt keeps its shape. Each part the reground-deliver hook hands out writes one hook-audit line (actor: reground-deliver, action: reground_part_delivered, target the host event PostToolUse or UserPromptSubmit) with part (the 1-based part number), total, epoch (the SessionStart that queued it, as <source>:<epoch-ms> with the source one of startup, resume, clear or compact, any other value recorded as unknown), bytes (UTF-8), utf16_chars, part_ceiling_chars and over_budget (the part alone is longer than the ceiling). A take that fails for a reason other than lock contention (an unreadable state directory, a full disk) writes action: reground_take_failed with ok: false, no part and epoch (the queue's SessionStart, null when unreadable), once per epoch on each machine: a state write that keeps failing leaves the queue undrained, and the repeats on later tool calls write no further line. A tool call inside a delegated sub-agent (the payload carries agent_id) takes no part and writes no line. A process-ceiling exit writes action: hook_ceiling_exceeded, target: reground.
  • brain_route_metrics (MCP, operation: "list"|"summary") reads route-level MCP tool latency. list returns raw mcp_route_latency records (filter by tool/status/since/until/limit); summary rolls each tool up into count, error count, and min/avg/max plus p50/p95/p99 latency, ordered slowest-first so an operator can identify which endpoint blocks an agent turn by route rather than by aggregate benchmark. A route whose records carry stages also gets a stages roll-up - per stage name, in ROUTE_STAGE order, the count, the average and the nearest-rank p95 in ms - and a route without stages has no stages key. Records are emitted only when mcp_route_metrics_enabled is on (default off); read-only.
  • brain_token_impact (MCP, operation: "record"|"outcome"|"list"|"summary") is the durable value-of-memory ledger. record posts one context pack's prompt-token delta (baseline_tokens βˆ’ packed_tokens, labelled method: tokenizer|heuristic β€” how the CALLER produced the counts, never how accurate they are; the ledger counts nothing itself and verifies neither. Samples written under the retired exact/fallback labels are still read and classified) plus an optional modeled inference-avoidance estimate (modeled_avoided_inferences Γ— modeled_tokens_per_inference); outcome posts a first_pass/repair/retry result. summary keeps the two ledgers STRICTLY SEPARATE: prompt_token_delta reports the net/saved/added tokens with a per-method split (so a tokenizer-produced count is never averaged in with a heuristic estimate), while modeled_inference_avoidance reports the raw modeled figure and a calibrated_savings_tokens dampened by the observed first-pass rate from posted outcomes (null until an outcome exists β€” uncalibrated, not zero). list returns raw samples (filter by pack_id/method/host/since/until/limit); summary accepts max_samples to bound aggregation. Writes are emitted only when token_impact_ledger_enabled is on (default off) and are payload-safe (counts + opaque pack_id only, never prompts or recalled text); list/summary read regardless of the gate. Aggregates are recomputed from the continuity store on every read, so they survive restarts.
  • brain_event_trace (MCP) and o2b brain event-trace join the Brain log to the continuity store: given a logged event (by day, --at stamp, kind, or --session-id), they resolve the continuity records attached to it via the stable correlation ids above (session_id, turn_id, and artifact sourceRefs), so an operator can answer "which context was supplied to this action?" from one surface. Each attached record reports joinedBy (session / turn / artifact); open the full record through the per-kind readers (context-receipts show, recall-telemetry, generation-reports show). Read-only; private records are dropped unless explicitly kept.
  • brain_generation_reports (MCP, actions record/list/summary) and o2b brain generation-reports record|list|summary|show post and read inbound LLM generation traces. summary rolls up call counts, the always-present local token estimate, agent-reported usage where present, and a per-path linkage map so a memory path resolves back to the generation reports that produced or consumed it.
  • o2b brain continuity export --format atof|atif renders the store as standard trajectory formats (ATOF JSONL event stream; ATIF v1.7 one document per session) for replay and eval tooling. Read-only; private records never reach an export file. Mapping decisions: docs/brainstorm/memory-observability-suite/atof-atif-mapping.md.
  • o2b brain bench memory measures memory quality over disposable fixture vaults and reports quality, latency, context cost, and failure modes as separate families (o2b.bench.v2 report schema). Beyond the retrieval categories it scores three failure modes the retrieval questions cannot see: proactive_recall drives decideRecallInject over the fixture and reports know_to_ask_failure_rate and false_fire_rate (both denominated in decisions, so a strategy that always injects scores worse than one that abstains correctly); write_fidelity grades the provenance that survives the shipped extraction, insertion and dedup path with no model call; source_isolation asserts on delivered context-pack contents under a requested owner scope and gates at zero. context_cost.avg_injected_tokens is estimateTokens over the strings the bench actually injected β€” the suite's one token estimator. Two things the numbers do NOT say: recall_inject_enabled is off by default, so the proactive metric describes a capability rather than delivered behaviour, and integrity.owner_scope_delivery is off by default, so an isolation fixture must set it to fail or the gate is vacuous. The committed baseline is tests/fixtures/bench/failure-modes.baseline.json, compared by tests/core/bench/failure-modes-baseline.test.ts inside the ordinary bun test gate. Since v1.82.0 the verb's suite registry maps a --suite name to its loader plus a declared capability set ({embeddings: boolean}; omitting --suite stays the byte-identical locomo default), the run identity folds the pinned search knobs and the proactive-recall admission floor into the checkpoint hash beside the fixture hash - a resumed run that would mix configurations fails the identity guard by name - and two suites join locomo: --suite longmemeval scores the LongMemEval dataset shape with the strict longmemeval: {recall_all_at_5, abstention_excluded} family (the committed sample fixture certifies CI, the full dataset is operator-supplied, and the judge rides bench_judge_cmd with question/answer/gold added to the stdin payload only for suites that provide them; the embeddings capability is apply-gated and its arming is API-only this wave, with a shared provider+model+text-hash vector cache under the runs dir), and --suite surfacing-replay replays a recorded prompt corpus through the shipped decision core and scores the graded surfacing gate's know_to_ask / false_fire rates, which closes the caveat that the structural gate alone was not scoreable: the graded admission key is a measured bound, and the replay suite is the instrument that re-measures it. Since v1.83.0 the capability set also declares sampling, and --sample-seed <value> plus --sample-cap <n> (a pair - either alone is refused by name; a non-positive or non-integer cap is refused naming the value; a suite without the capability is refused naming the suite, and longmemeval is the only one that has it) run a seeded, question-type-proportional subset of the dataset instead of the whole fixture: abstention questions are excluded first and their count still lands in abstention_excluded, the survivors are stratified by the dataset's own question_type values, each stratum contributes its population-proportional share of the cap by largest-remainder apportionment (remainders compared as integers, ties by stratum name), and the draw is a seeded shuffle over entries sorted by question id - no wall clock, no Math.random - so dataset file order cannot change the subset and the same seed and cap always select the same questions. Sampling happens before conversion, so a sampled run materializes notes and continuity records only for the questions it scores. A sampled run's --json report carries the sampling receipt in its longmemeval family: sample_population, sample_selected and the per-stratum sample_strata sit beside abstention_excluded, each present only on a sampled run and absent from a whole-dataset report, and the human longmemeval report line gains sample_selected N only on a sampled run; the seed and cap fold into the run identity with the same spread-omission the floor uses: run ids of runs without sampling are byte-stable, and a resumed run whose sampling options changed fails the identity guard by name (the guard's message names the sampling options beside the pinned knobs and the floor).

Consumers should treat unknown record kinds and unknown payload fields as fine - skip what you do not recognize (the store and read-model already behave this way).