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.
Prerequisites
The o2b CLI runs on Bun. Every install path
expects bun >= 1.1.0 on PATH.
command -v bun >/dev/null 2>&1 || curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
bun --version
If you cannot install Bun (locked-down environment, unsupported architecture), the plugin will not function on that host. No Python fallback exists.
Get the o2b CLI
Plugin hosts (Claude Code, Codex, Hermes, OpenClaw) ship the launcher with the plugin; their install page shows how to publish it. For every other client, clone the repository and publish the launcher from the clone:
git clone https://github.com/itechmeat/open-second-brain ~/open-second-brain
~/open-second-brain/scripts/o2b install-cli
export PATH="$HOME/.local/bin:$PATH"
o2b version
install-cli links o2b, vault-log and o2b-hook into ~/.local/bin.
Add that directory to PATH in your shell profile. A client that starts
MCP servers with a bare o2b command needs it on the PATH it runs with;
if it does not have it, use the absolute path ~/.local/bin/o2b (expanded)
as the command.
On native Windows, follow windows.md instead.
Supported platforms
Linux, macOS and the other POSIX hosts Bun runs on, plus native Windows 10/11 (x64). WSL is a Linux host and follows the Linux instructions.
| Platform | Default config path |
|---|---|
| Linux, macOS, BSD | $HOME/.config/open-second-brain/config.yaml |
| Windows | %LOCALAPPDATA%\open-second-brain\config.yaml |
OPEN_SECOND_BRAIN_CONFIG (an explicit file) and XDG_CONFIG_HOME
(a configuration root) override the default on every platform.
On Windows, install Bun with
powershell -c "irm bun.sh/install.ps1 | iex" and follow
windows.md: the CLI is published as .cmd launchers,
MCP hosts start it through cmd /d /c, and Claude Code's hooks need
Git for Windows.
Identity (agent name + timezone)
o2b init persists two values into ~/.config/open-second-brain/config.yaml:
agent_nameβ prefix attached to everyBrain/log/event the MCP server records against this vault. Pick a deliberate value (<runtime>-<host>is a good default).timezoneβ IANA name (Europe/Belgrade,America/New_York,UTC). Used to stamp event timestamps regardless of the host's local clock.
If the vault was initialized previously, check the registry first:
- the config file above (
agent_name, authoritative) <vault>/Brain/_brain.yamlprimary_agent(when set)<vault>/Brain/log/*.{md,jsonl}(recurringagentfield)
A repeat o2b init --agent-name X is safe β it updates the
machine-local config in place.
Vault path discovery
Vault locations vary per user. Discover candidates in this order:
- Directories containing a
.obsidian/subdirectory under~/,~/Documents/,~/Sync/,~/Dropbox/, or a Syncthing-sharedvault/folder. - The user's choice when multiple candidates exist.
- A new directory at
~/vault/if none are found and the user agrees.
Consent before apply
The apply lanes that rewrite client configuration β
o2b install --target <runtime> --apply and
o2b brain protect --target <runtime> --apply β ask once before
writing. On an interactive terminal they print the plan with a unified
diff of the target file and prompt (Proceed? [y/N]); answering
anything but y/yes writes nothing. In a non-interactive run
(--json, CI, no TTY) there is no one to ask, so the command refuses
fail-closed and writes nothing; pass --yes to authorise the write
explicitly. A consent refusal exits with code 6 (o2b install) and
names the missing flag on stderr. --check, --plan and dry runs
never prompt and never gate.
Verification
After any install path completes, run:
o2b doctor --vault /path/to/vault --repo .
o2b install --check
o2b install --check is the runtime-install health check
(per-target managed-block / MCP-ping verification). o2b doctor
covers vault invariants β they are complementary, not substitutes.
Then call brain_note once (via MCP or o2b brain note "..." on the
CLI) and confirm that the new line in Brain/log/<today>.md carries
the chosen agent value, not the literal agent placeholder.
Plays well with codegraph
If your vault sits next to code repositories, OSB cooperates with
codegraph as a partner
tool: codegraph owns the symbol graph and call relationships in a
codebase, OSB owns the prose / Brain / preferences in the vault. When
o2b doctor runs from inside or beside a code project, it adds a
code_graph line that summarises whether codegraph is installed and
indexed there. Installation is performed by codegraph's own installer,
not by OSB. See skills/codegraph-partner/SKILL.md for the agent-side
playbook.