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.
Codex
Codex installs OSB through its marketplace + MCP subsystems. The MCP
registration is driven by the codex install adapter, so the steps below
are the same two commands every other adapter-backed runtime uses.
1. Install the plugin
codex plugin marketplace add itechmeat/open-second-brain
Then enable it by adding to ~/.codex/config.toml:
[plugins."open-second-brain@open-second-brain"]
enabled = true
2. Publish the o2b CLI on PATH
codex plugin marketplace add clones the whole repository into
$CODEX_HOME/.tmp/marketplaces/open-second-brain/, and that clone holds
the launcher. The installed plugin in $CODEX_HOME/plugins/cache/ holds
only the plugins/codex subtree (manifest, hooks/hooks.json, skills),
not scripts/. The hooks run o2b-hook from PATH, so this step is also
what turns them on. Locate the script in the clone (under CODEX_HOME
when it is set):
O2B_SCRIPT="$(find "${CODEX_HOME:-$HOME/.codex}/.tmp/marketplaces" -path '*open-second-brain*/scripts/o2b' -type f 2>/dev/null | head -1)"
[ -n "$O2B_SCRIPT" ] || { echo "o2b launcher not found in the Codex marketplace clone" >&2; exit 1; }
"$O2B_SCRIPT" install-cli
The clone arrives without node_modules, and the launcher heals that
itself: the first time it runs, it notices the missing dependency tree and
executes bun install --frozen-lockfile inside the clone once, announced
by a one-line notice on stderr. Every later run finds the tree present and
boots straight into the CLI. If that install cannot run - no network, or a
clone the launcher cannot write - the launcher exits nonzero and names the
manual command instead of dying with a module-not-found trace. Running
bun install --frozen-lockfile inside the clone yourself repairs the same
state.
3. Initialize the vault
o2b init --vault /path/to/vault --name "My Second Brain" \
--agent-name "<chosen-agent-name>" --timezone "<chosen-tz>"
o2b brain init --vault /path/to/vault
4. Register the MCP servers
o2b install --target codex --vault /path/to/vault
o2b install --target codex --vault /path/to/vault --apply --yes
The first command plans and writes nothing; the second applies. With the
codex binary on PATH the adapter registers both servers through
codex mcp add, which persists them into $CODEX_HOME/config.toml.
Without it, the adapter merges the same two [mcp_servers.*] tables into
that file directly, leaving every other table - including the
[plugins."..."] and [marketplaces....] blocks above - byte-for-byte
intact.
$CODEX_HOME is written that way throughout this page rather than as
~/.codex, because the variable is what the adapter resolves and
~/.codex is only its default. Setting CODEX_HOME relocates the whole
Codex configuration directory, and the adapter follows it on every path:
the file it merges, the CODEX_HOME it exports to the codex mcp add
subprocess, the codex mcp list it runs to verify, and the session roots
o2b sweeps for transcripts.
The adapter sets VAULT_AGENT_NAME for you, to Codex's own
host-qualified identity: it keeps the host segment of your configured
agent_name and substitutes codex as the vendor token, so an
agent_name of claude-vps-agent registers as codex-vps-agent. That
makes Codex's Brain writes distinguishable per runtime, and in a shared
multi-device vault also per device - the same derivation the grok and
opencode adapters apply.
ChatGPT desktop
ChatGPT desktop has no MCP registration of its own: it reads the shared
Codex configuration at $CODEX_HOME/config.toml (default
~/.codex/config.toml), the same file the codex target writes. One
registration serves both, so the install command is the codex one from
step 4 (add --vault, --apply and --yes as there):
o2b install --target codex --apply
Steps 1 and 2 need the codex binary - they drive the marketplace
clone it creates. A desktop-only machine without the Codex CLI skips
both and installs the o2b CLI by hand instead, exactly as
install/prerequisites.md describes (scripts/o2b install-cli links
o2b into ~/.local/bin); with o2b on PATH, the install command
above is all that remains of this page.
Install writes the two [mcp_servers.*] tables into that shared file -
through codex mcp add when the codex binary is on PATH, otherwise
through the direct TOML merge. In the merge case the detect output of
o2b install names ChatGPT desktop as a reader of the file. ChatGPT
desktop picks the servers up on its next session start, and $CODEX_HOME
relocates the file for both hosts exactly as documented above.
o2b uninstall --target codex --apply removes the shared registration,
which undoes it for ChatGPT desktop at the same time. Uninstall resolves
the vault through the same chain install does, so aim it at the vault
the install wrote: pass the same --vault (or set VAULT_DIR the same
way), because the install manifest it reads lives there. Only the two
Open Second Brain tables are removed; every other table in the file
stays.
5. Verify
o2b install --check --target codex --vault /path/to/vault
o2b doctor --vault /path/to/vault --repo .
A successful check prints:
o2b install --check
--------------------
codex ok `codex mcp list` reports both OSB servers registered
That line is the host's own answer: the check runs codex mcp list and
reports what Codex says it has registered. When the binary is not on
PATH, or exits non-zero, or does not answer within the probe's timeout,
the check names that obstacle instead and falls back to what
$CODEX_HOME/config.toml declares - and it declares a table only where
the header stands on its own line, so a commented-out
# [mcp_servers.open-second-brain] reads as absent, which is what an
operator who commented it out meant. This block is asserted
against the adapter's real verify() output by
tests/docs/install-verify-conformance.test.ts, so it cannot drift from
the code.
Run the daily-identity check from install/prerequisites.md.
Lifecycle hooks (auto-enabled)
The bundled hooks/hooks.json registers a PostToolUse hook
(matcher Write|Edit|MultiEdit|apply_patch) that invokes
o2b-hook from PATH after every file-mutating tool succeeds. Step
2 above wires it.
Machine-enforce write protection (optional)
o2b brain protect --target codex --vault /path/to/vault --apply --yes
o2b brain unprotect --target codex --vault /path/to/vault
The sidecar manifest at
<vault>/.open-second-brain/protect.lock.json records exactly
what was added; unprotect removes the same.
Update
codex plugin marketplace upgrade open-second-brain
An upgrade replaces the clone, so its node_modules is gone afterwards.
No extra step is needed: the next launcher run notices the missing
dependency tree and reinstalls it, exactly as in step 2 (the same one-line
notice on stderr, and the same manual bun install --frozen-lockfile
fallback if the automatic install cannot run).
Uninstall
o2b uninstall --target codex --vault /path/to/vault --apply
codex plugin marketplace remove open-second-brain
o2b uninstall --apply-local --remove-cli
o2b uninstall --target codex removes only the two OSB server
registrations - through codex mcp remove when the binary is present,
and by stripping the two tables from ~/.codex/config.toml when it is
not. Every other table in that file is left alone.