Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
5.5 KB
Raw Blame

Open Second Brain β€” Installation

Open Second Brain ships one CLI (o2b), one always-loaded MCP writer server, one full MCP server, and a runtime-specific install adapter per supported runtime. This file is a router β€” pick the runtime you use and read the corresponding install/<runtime>.md.

Always install the latest released version. The runtime CLIs resolve latest from a bare owner/repo identifier by default. Do not append @v... β€” that freezes the install at a specific tag, including back to an older release if you happen to know an outdated number.

Prerequisites

Read install/prerequisites.md first β€” Bun runtime, vault discovery, identity (agent name + timezone), and the verification pattern that every install path ends with. On native Windows, read install/windows.md as well.

Quick install

For these runtimes one o2b install command writes the integration (every apply is consent-gated: an interactive run asks once, and a headless run needs the shown --yes β€” see install/prerequisites.md):

Runtime Command Notes
Cursor o2b install --target cursor --apply --yes install/cursor.md β€” JSON-merge; restart Cursor after apply
Aider o2b install --target aider --apply --yes install/aider.md β€” managed block + sidecar context; no native MCP
opencode o2b install --target opencode --apply --yes install/opencode.md β€” MCP servers + native plugin
Grok Build o2b install --target grok --apply --yes install/grok.md β€” MCP in ~/.grok/config.toml + native hooks (absolute command)
kiro o2b install --target kiro --apply --yes install/kiro.md β€” JSON-merge
GitHub Copilot CLI o2b install --target copilot-cli --apply --yes install/copilot-cli.md β€” copilot mcp add with JSON fallback
Google Gemini CLI o2b install --target gemini-cli --apply --yes install/gemini-cli.md β€” JSON-merge in ~/.gemini/settings.json
Pi (pi.dev) o2b install --target pi --apply --yes install/pi.md β€” skill symlink, not MCP
Generic / other o2b install --target generic --apply --yes --out - install/generic.md β€” prints payload; never edits external config

ZCode has no install target yet: add the printed servers to its config by hand, see install/zcode.md.

For runtimes that ship their own plugin/MCP install pipeline, OSB hooks into that pipeline instead of o2b install --target:

Runtime Doc
Hermes Agent install/hermes.md
OpenClaw install/openclaw.md
Codex install/codex.md
Claude Code install/claudecode.md

Interactive setup

For a guided first-time setup that composes o2b init, optional o2b brain init, and per-target o2b install:

o2b init --interactive

The wizard reads from stdin, prints the full action plan, and requires an explicit yes before any side effects.

Verify

After any install:

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

o2b install --check is the runtime-install health check (per-target managed-block / MCP verification). Exit code is 0 when every target is ok or not installed, 3 if any target reports drift, and 5 if a target is configured but proved unreachable. The 5 is new in v1.46.0: that case used to exit 0, so a script gating on the exit status treated a runtime it had proved unreachable as healthy. docs/cli-reference.md lists every code.

Uninstall

For MCP-aware runtimes:

o2b uninstall --target <name> --apply

Removes exactly what o2b install --target <name> wrote (recorded in <vault>/.open-second-brain/install.lock.json). For runtimes that ship their own plugin uninstall command, see the corresponding install/<runtime>.md for the full sequence.

The vault and its Markdown files are never deleted by the uninstall process.

Installation readiness criteria

The installation is complete only when all of the following hold:

Universal:

  • plugin (or per-target managed block / symlink / printout) installed;
  • runtime restarted to pick up the change;
  • vault initialized (o2b init succeeded);
  • o2b doctor reports OK;
  • o2b install --check reports ok (or installed for generic) for the target;
  • AI Wiki/identity/agents.md contains the chosen agent name;
  • a test event written without an explicit agent argument stamps @<chosen-agent-name> in Daily/, not @agent.

MCP-driven runtimes only (Cursor, opencode, Grok Build, kiro, Copilot CLI, Gemini CLI, Claude Code, Codex, Hermes, ZCode; not aider, pi, or generic):

  • all OSB tools advertised by the runtime's MCP listing.

If any single item is missing, the install is incomplete β€” report that to the user and do not mark the workflow as successful.