Open Second Brain

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

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):

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:

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:

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:

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.

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

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).