hermes-vault/Brain/_BRAIN.md

kind, vault_name, schema_version

kind	vault_name	schema_version
brain-manual	Hermes	1

Brain — operating manual

Brain is the observing-memory layer of Open Second Brain. It records what the user likes and dislikes by watching what they accept and reject, then distils that into rules the next agent session can read and apply.

Read this file at the start of every session that may write to the vault. Cross-reference: Projects/OpenSecondBrain/Plan if the vault carries the design notes.

Layout

Brain/
  _brain.yaml          # configuration; hand-editable
  _BRAIN.md            # this file
  inbox/               # raw signals captured during work
    processed/        # signals already folded into a preference
  preferences/         # active rules (unconfirmed or confirmed)
  retired/             # superseded / expired / rebutted / rejected rules
  log/                 # daily ledger of every state change
  bases/               # Obsidian Bases views (projects/people/tasks/daily)
  .snapshots/          # pre-`dream` archives for rollback

bases/*.base are native Obsidian structured views over the Brain collections (entities, obligations, log) — no Dataview plugin required. They are inert scaffolding: never hand-edit them as a data source.

The directory a note sits in encodes its lifecycle state. The frontmatter status field duplicates it for convenience. o2b brain doctor reports mismatches.

Lifecycle of one preference

inbox/sig-*           dream              unconfirmed
  (taste signal) ───► (cluster) ───► preferences/pref-*
                                          │
            apply-evidence (applied) ─────┤
                                          ▼
                                       confirmed
                                          │
       no evidence within window  ───────►│
       rebuttal signals reach threshold  ─┤
       stale_evidence_days passed  ──────►│
       o2b brain reject  ────────────────►▼
                                       retired/ret-*

Promotion happens automatically when N positive same-topic signals accumulate (_brain.yaml: dream.candidate_threshold, default 3). First real-work application flips a preference from unconfirmed to confirmed. No human approval step exists in the default loop.

When to call brain_feedback

After a taste signal — the user accepted or rejected a stylistic choice, a structural decision, a tone, a naming convention.

• Sign: positive (user liked it) or negative (user pushed back).
• topic is the dedup anchor: same topic accumulates toward promotion. Pick a stable, hyphenated slug (no-internal-abbrev, not abbreviations).
• principle is one short imperative sentence — what rule should emerge.
• Skip pure preferences with no action attached, idle banter, and repeated agreement on a topic that already has an active preference (the next dream run notes the redundancy automatically).

When to call brain_apply_evidence

After producing a durable artifact whose form was governed by an active preference. Two outcomes:

• applied — the artifact followed the rule.
• violated — the artifact contradicted it (rare, but record it; the log keeps both columns).

The preference argument is the wikilink target (pref-no-internal-abbrev), the artifact argument is the wikilink to the produced note / file / PR / message. Confirmation, confidence, and retire eligibility are recomputed by the next dream run from log evidence — there is no separate "promote" call.

Apply-evidence is only meaningful for confirmed preferences and for unconfirmed ones that the artifact actually exercised. Stay quiet otherwise — noise drowns the signal.

dream — the batch pass

dream is the one mutating operation. It is deterministic given inputs and --now. It:

• groups signals by topic, promotes those that cross the threshold;
• recomputes applied_count / violated_count / last_evidence_at from log/;
• flips first-applied unconfirmed prefs to confirmed;
• retires expired, stale, rebutted, or user-rejected prefs;
• moves consumed signals into inbox/processed/;
• archives Brain into .snapshots/<run_id>.tar.zst before mutating;
• appends one summary entry to log/<today>.md if anything changed.

Rerunning dream without new inputs is a no-op (including in the log). Schedule it on a cron with confidence — duplicate runs do not pollute.

What NOT to do

• Do not hand-edit files under log/ — they are append-only ledgers. dream, apply-evidence, feedback, and the CLI escape hatches are the only writers.
• Do not rename preference or signal files. The id field is duplicated in frontmatter to survive mv, but slugs are stable for a reason; changing them breaks every wikilink and every log reference.
• Do not write into .snapshots/. dream produces archives there; o2b brain rollback consumes them; nothing else touches the directory.
• Do not edit files in retired/ to undo a retirement. The reason is preserved on purpose; a rule that should return becomes a new preference with supersedes: [[ret-...]].
• Brain operations stay scoped to Brain/. User-authored notes (daily journals, etc.) are read-only inputs whose folders are listed in _brain.yaml:notes.read_paths; the agent never writes there.
• Do not invent topics. Reuse an existing topic slug if the rule space is the same; dream collapses near-duplicates only by exact match.

Escape hatches

These are CLI-only, intended for rare manual intervention. Do not call them as part of normal agent work.

• o2b brain reject <pref-id> — explicit user-driven retirement. Moves the preference to retired/ with reason user-rejected. A pinned preference requires --yes and prints a warning.
• o2b brain rollback <run_id> — restore Brain from a snapshot. Interactive by default; --list enumerates available snapshots. From v0.10.6 a snapshot ships with a sha256 sidecar manifest so rollback aborts when the live tree drifted from the snapshot moment; pass --force-rollback to override.
• o2b brain pin <pref-id> / unpin <pref-id> — protect a preference from automatic retirement (still subject to explicit reject).
• o2b brain upgrade — migrate the release-owned files (_brain.yaml, _BRAIN.md) forward when a new open-second-brain version ships. --dry-run (default) prints a per-file plan; --apply rewrites the files after taking a snapshot named upgrade-<ts>.
• o2b brain export --format json|llms-txt — read-only dump of active preferences (confirmed | unconfirmed | quarantine) for backup, prompt injection, or sharing.

The full CLI surface is documented in docs/plans/2026-05-15-brain-observing-memory.md section 9; the MCP tool surface mirrors it for the most common verbs (brain_feedback, brain_apply_evidence, brain_dream, brain_brief, brain_query, brain_doctor).

Reading order for a new agent

1. This file (Brain/_BRAIN.md).
2. Brain/_brain.yaml for threshold values currently in effect.
3. Brain/preferences/ for active rules; confirmed first, then unconfirmed (in trial).
4. Brain/retired/ only when checking why a rule no longer applies.

Brain is filesystem-first. A cp -r Brain/ is a complete backup; a git diff shows the exact state delta. Trust the files.