open-second-brain

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 writes lives under it.

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

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.