/open-second-brain

name: open-second-brain
description: Use Open Second Brain to read, write, and maintain an agent-owned second brain in an Obsidian-compatible Markdown vault. The agent owns one top-level directory (`Brain/`). User-authored notes live wherever the operator names them and are read-only inputs when listed in `notes.read_paths`.

Open Second Brain

Use this skill when a user asks an agent to use, configure, inspect, or maintain Open Second Brain.

Layout

Open Second Brain owns one top-level directory in the vault: `Brain/`. Everything the agent generates on its own lives under it. The exception is the note-lifecycle family (`brain_note_lifecycle`, `brain_scaffold_stub`), which acts on a user-note path the caller names and can move a note to a second top-level directory, `Archive/`.

• **`Brain/`** - agent-writable observing memory. Taste signals, accreted preferences (unconfirmed → confirmed → retired), evidence log, snapshots. Operations go through MCP tools `brain_feedback`, `brain_apply_evidence`, `brain_dream`, `brain_brief`, `brain_query`, `brain_doctor` - see the `brain-memory` skill for the calling protocol. CLI counterparts: `o2b brain *`.
• **User-authored notes** - the operator's daily journal, weekly notes, project notes, etc. Folder names are operator-chosen. The agent reads these paths only when they appear under `notes.read_paths` in `Brain/_brain.yaml`; the agent never writes to them.

Core principles

• Treat the vault as user-owned durable knowledge.
• Write only into `Brain/`. Never write to user-authored note folders.
• Keep raw operational evidence separate from synthesized knowledge: per-event records go to `Brain/log/`, preferences live in `Brain/preferences/`.
• Never write secrets, tokens, passwords, private keys, or credential-bearing connection strings.
• Prefer deterministic CLI commands (`o2b brain ...`, `o2b doctor`, `o2b status`) over guessing file paths.

Default workflow

1. Check whether Open Second Brain is configured: `o2b status` or `second_brain_status` MCP tool. 2. Read the machine-local config if available (vault path, agent identity, timezone). 3. Read the vault-local operating manual `Brain/_BRAIN.md` - this is the per-vault contract for agents. 4. Record taste signals as they arrive in dialogue via `brain_feedback` (see the `brain-memory` skill). 5. After producing a durable artifact, check applicable preferences and record evidence via `brain_apply_evidence` (see the `brain-memory` skill). 6. For read access to vault pages by title, use `second_brain_query`.

Search surfaces

Name the surface a question is shaped for, and route to it explicitly:

• **Generic recall** - `brain_search` runs hybrid keyword + semantic search over raw chunks. Use it for open-ended, topical, or exploratory questions.
• **Summary surface** - for a question that targets a specific source or an artifact kind (a summary, digest, or other declared `schema.page_types` type), reach for the summary surface: search by source or filter by artifact kind rather than running a generic search over raw chunks. `brain_search` detects this structurally and returns `surface: "summary"` on the response as an advisory route hint; a source-targeted query uses a `source:<path>` token and an artifact-kind query uses a `kind:<type>`/`type:<type>` token whose value is a declared page type. The hint never changes ranking - it names the intended surface so the agent asks the right way.
• **Answerable signal** - when `brain_search` returns `decision_model.answerable`, pass its `probability` to `brain_recall_gate` or `brain_context_pack` as `decision_answerable` together with the scores and `match_quality`. `decision_answerable.disagrees: true` on the verdict means search again with other words, or say the vault may not cover the question; the level and action stay as they are.
• **Skill offers** - `skills_attach` offers skills for the current turn; when the operator configured the optional `skills` decision-model use it may be decision-model assisted (the result then carries a `decision_model` field). Cite its `offer_id` on `get_skill` either way.

Safety

If a write operation might affect anything outside the `Brain/` directory, ask for explicit confirmation. When in doubt, prefer `Brain/`.

Decision-model verdicts (`decision_model` on `brain_hygiene scan` dedup findings, doctor alias candidates and `brain_tension verify`) are advisory only: merges, dismissals and resolutions still need an explicit action.

To label a note, call `brain_labels suggest` before `assign`; `suggest` never assigns, and a null suggestion means no confident value.

See also

• `brain-memory` skill — when and how to call `brain_feedback` / `brain_apply_evidence`.
• `Brain/_BRAIN.md` (in each vault) — operating manual for that vault, generated by `o2b brain init`.
• `docs/plans/2026-05-15-brain-observing-memory.md` (in the repo) — full design.