Open Second Brain

Open Second Brain is a memory layer for AI agents that lives in an Obsidian vault. Agents read and write it through MCP servers, lifecycle hooks and the o2b CLI. Everything the agent learns is a Markdown file under Brain/, so you can open, edit, grep and version it like any other note. A deterministic dream pass turns repeated signals into rules and retires the ones nothing uses; no model runs inside that algorithm.

How it fits

flowchart LR
    subgraph Clients["Agent clients"]
        Plug["Plugins: Claude Code, Codex,<br/>Hermes, opencode, Grok Build"]
        Mcp["MCP config: Cursor, kiro, Copilot CLI,<br/>Gemini CLI, ZCode, any MCP host"]
        Claw["OpenClaw<br/>in-process plugin"]
        Cliu["Aider, Pi<br/>CLI and context file"]
    end
    subgraph Product["Open Second Brain"]
        Srv["MCP servers<br/>open-second-brain, open-second-brain-writer"]
        Hooks["Lifecycle hooks<br/>o2b-hook"]
        Cli["CLI<br/>o2b"]
        Core["Core"]
    end
    subgraph Vault["Your vault"]
        Brain["Brain/<br/>Markdown the agent writes"]
        Notes["Your notes"]
        Index[(".open-second-brain/brain.sqlite<br/>rebuildable search index")]
    end
    Plug --> Srv
    Plug --> Hooks
    Mcp --> Srv
    Claw --> Core
    Cliu --> Cli
    Srv --> Core
    Hooks --> Core
    Cli --> Core
    Core --> Brain
    Core --> Index
    Core -. reads, writes a named note on request .-> Notes

Loading

Each client reaches the same core through a plugin, an MCP registration or the CLI. The core keeps its own records under Brain/ and a generated search index under .open-second-brain/ that it can rebuild from the files. Your notes are read; the note tools write one only at a path the caller names.

flowchart LR
    Agent["Agent"] -->|brain_feedback| Inbox["Brain/inbox/<br/>signal"]
    Inbox -->|dream pass| Pref["Brain/preferences/<br/>rule"]
    Pref -->|rendered into| Active["Brain/active.md"]
    Active -->|read at session start| Agent
    Agent -->|brain_apply_evidence| Log["Brain/log/"]
    Log -->|next dream pass| Pref

Loading

The learning loop: signals become rules, rules reach the next session through Brain/active.md, and applied or violated evidence confirms, quarantines or retires them. Details: docs/how-it-works.md.

Install

1. Install Bun 1.1 or later: install/prerequisites.md.

2. Install the plugin for your client (guides below), or get the o2b CLI: install/prerequisites.md.

3. Create the vault files:

   o2b init       --vault /path/to/vault --name "My Second Brain"
   o2b brain init --vault /path/to/vault

4. Connect the client (table below), then check the result:

   o2b doctor --vault /path/to/vault
   o2b install --check

The full router with readiness criteria is install.md; native Windows is covered in install/windows.md.

Supported clients

Client	Integration	Guide
Claude Code	Marketplace plugin: MCP servers and hooks	install/claudecode.md
OpenAI Codex	Marketplace plugin, then o2b install --target codex --apply	install/codex.md
Hermes Agent	Plugin and memory provider	install/hermes.md
OpenClaw	Native plugin, no MCP	install/openclaw.md
opencode	o2b install --target opencode --apply: MCP servers and a native plugin	install/opencode.md
Grok Build	o2b install --target grok --apply: MCP servers and hooks	install/grok.md
Cursor	o2b install --target cursor --apply	install/cursor.md
kiro	o2b install --target kiro --apply	install/kiro.md
GitHub Copilot CLI	o2b install --target copilot-cli --apply	install/copilot-cli.md
Gemini CLI	o2b install --target gemini-cli --apply	install/gemini-cli.md
ZCode	MCP servers added to its config by hand	install/zcode.md
Aider	o2b install --target aider --apply: context file, no MCP	install/aider.md
Pi	o2b install --target pi --apply: skill over the CLI	install/pi.md
Any other MCP host	o2b install --target generic --apply --out - prints the server entries	install/generic.md

o2b uninstall --target <name> --apply removes what o2b install wrote; the vault is never touched (install.md).

Capabilities

• Preferences that learn and expire. Signals, a deterministic dream pass, confidence and retirement: how it works.
• Reversible changes. Brain mutations take a snapshot first; o2b brain rollback restores it: snapshots.
• Attributed writes. o2b brain writes lists every note write by agent and device, writes revert plans a restore, o2b brain freeze stops all writers, and o2b brain log verify checks the hash-chained log: Brain CLI.
• Search. Keyword search with an optional semantic lane, result explanations, recall profiles and compact cards: search CLI, ranking.
• Session recall. Import agent transcripts already on disk and search them: session logs.
• Hygiene. o2b brain hygiene scan finds contested, duplicate, stale and unused memories; apply runs only the findings you pick: maintenance.
• Claim ledger. o2b brain truth ingest records an entity claim with an optional validity window (--valid-from/--valid-until; with the flags absent, a window on the source record's frontmatter is adopted and frozen at ingest), truth events recalls a windowed slice of the ledger, and truth state grounds an agent-stated claim with an anchoring verdict - committed, or reported back with reason codes: entity truth CLI.
• Corrections. o2b brain lifecycle correct <target> reports a correction's blast radius and retires the affected records - validity-closed by default, tombstoned with --flatly-wrong, dry run by default and --apply to write. A retired record that recall can still serve is served only beside its correction, never alone: belief lifecycle CLI.
• Sharing and backup. Knowledge packs export a chosen subset; o2b brain bank-export writes a one-file backup bundle: knowledge packs.
• Today view and note markers. o2b brain today, @osb loop and @osb set markers: Brain CLI.
• Self-inspection. o2b version, o2b install --friction and o2b state status report what is installed and where state lives: CLI reference.
• MCP surface. Tools, tool profiles for hosts with tool limits, and the always-loaded writer server: docs/mcp.md.

Optional features

• Semantic search: an embedding provider plus sqlite-vec; the embeddings-setup skill walks through it: skills/embeddings-setup/SKILL.md.
• Decision models: a typed judgment model that can rerank search and filter candidates, off by default per use: docs/decision-models.md.
• Deep relational recall: a fourth search arm over typed links, off by default. Its traversal runs under width budgets - 8 seeds, 4 edges per node, 16 nodes in total, and a hub above 12 walked edges is reached but not expanded - each overridable through an OPEN_SECOND_BRAIN_SEARCH_TRAVERSAL_* environment variable or a search_traversal_* config key; entity co-occurrence bridges join the walk by default and switch off separately (OPEN_SECOND_BRAIN_SEARCH_ENTITY_BRIDGES): retrieval quality.

What is new

1.77.0 makes the claim ledger time-aware and correctable. A claim can carry a validity window (o2b brain truth ingest --valid-from/--valid-until, frozen from the source record when the flags are absent), o2b brain truth events recalls the ledger over an assertion-time slice, o2b brain truth state grounds an agent's stated claims with a per-claim anchoring verdict, and o2b brain lifecycle correct retires what a correction touches - dry run by default, with a retired record that recall can still serve answered only beside its resolved, readable correction, never alone. The deep relational recall arm now runs under width budgets with hub skipping and entity co-occurrence bridges. Every release is described in the CHANGELOG.

Documentation

Topic	Page
Mental model, vault layout, dream pass, safety properties	docs/how-it-works.md
Every CLI verb and flag	docs/cli-reference.md
MCP protocol, tools, writer split	docs/mcp.md
Architecture and configuration model	docs/architecture.md
Updating (o2b update) and upgrade notes	docs/updating.md
Observability events	docs/observability.md
Metrics data contract	docs/metrics.md
Cross-project pointer	docs/cross-project-pointer.md
Scheduled Brain digest (Hermes cron)	docs/hermes-cron.md
Stability policy	docs/stability.md
Origin of the idea	docs/idea.md

Project

CHANGELOG · Security policy · Source on GitHub · MIT License