| 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
- Check whether Open Second Brain is configured:
o2b status or second_brain_status MCP tool.
- Read the machine-local config if available (vault path, agent identity, timezone).
- Read the vault-local operating manual
Brain/_BRAIN.md - this is the per-vault contract for agents.
- Record taste signals as they arrive in dialogue via
brain_feedback (see the brain-memory skill).
- After producing a durable artifact, check applicable preferences and record evidence via
brain_apply_evidence (see the brain-memory skill).
- 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.
Safety
If a write operation might affect anything outside the Brain/ directory, ask for explicit confirmation. When in doubt, prefer Brain/.
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.
