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.
Hermes
Hermes installs Open Second Brain through its native plugin and
memory-provider machinery, not through o2b install --target hermes.
The flow below assumes a working Hermes Agent with hermes on PATH.
Open Second Brain registers as a native Hermes memory provider:
one mechanism that injects Brain/active.md into the system prompt,
recalls context before each turn, captures turns for the deterministic
dream pass, mirrors Hermes built-in memory writes into Brain/, and
exposes the brain_* tools - all over a single internal o2b mcp
bridge. There is no separate mcp_servers entry to maintain.
1. Install the plugin
hermes plugins install itechmeat/open-second-brain --enable
hermes gateway restart
Or paste https://github.com/itechmeat/open-second-brain into the
Hermes Dashboard -> Plugins -> Install from GitHub URL. Do not pin
a tag - the CLI resolves to the latest released version on its own.
On native Windows (Hermes desktop app or install.ps1), Hermes keeps its
home in %LOCALAPPDATA%\hermes; the plugin, the provider and the steps
below are the same, with the Windows paths from
windows.md.
2. Publish the o2b CLI on PATH
~/.hermes/plugins/open-second-brain/scripts/o2b install-cli
Creates symlinks for o2b, vault-log, and o2b-hook in
~/.local/bin. Survives hermes plugins update.
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 \
--primary-agent "<chosen-agent-name>"
--primary-agent declares this Hermes install as the vault's
dream-running host. Multi-device setups (Syncthing) benefit from
a single dream-runner.
4. Enable the memory provider
Run the setup wizard and choose open-second-brain:
hermes memory setup
Or set it directly in ~/.hermes/config.yaml:
memory:
provider: open-second-brain
Then restart the gateway:
hermes gateway restart
Only one external memory provider can be active at a time; selecting
open-second-brain makes it the active provider. The provider reads
the vault, agent name, and timezone from the Open Second Brain config
written in step 3 (~/.config/open-second-brain/config.yaml), so no
vault path is duplicated in the Hermes config.
The dashboard's Memory Provider panel reads those same three values
back from the provider, so a vault configured in step 3 shows there as
already set and the panel reports the provider as ready. Saving from
the panel writes the Open Second Brain config, not the Hermes one.
Clearing a field is the one edit the panel cannot make - the host
resubmits the current value in place of an empty one - so unset a key
with hermes memory setup or by editing the config file.
Activation lifecycle
Hermes activates memory providers through the memory.provider config
key, not at install time — hermes plugins install only makes the
provider available. This is by design (exactly one provider is active
at a time), so activation is one explicit command:
| Action | What happens | What you run |
|---|---|---|
| First install | Not auto — install only makes it available | hermes memory setup open-second-brain |
| Plugin update | Automatic — memory.provider persists in config.yaml |
nothing |
| Deactivate / uninstall | Not auto | hermes memory off (reverts to built-in) |
Multiple Hermes profiles
A Hermes gateway with gateway.multiplex_profiles: true serves several
profiles from one process, and that process's environment belongs to
the profile that launched it. Since v1.70.0 the plugin then reads its
profile-scoped settings from each turn's own profile scope - the
profile's .env, as Hermes composes it - and never from the gateway
process environment:
| Variable | Setting |
|---|---|
VAULT_DIR |
vault |
VAULT_AGENT_NAME |
agent name |
VAULT_TIMEZONE |
timezone |
OPEN_SECOND_BRAIN_CONFIG |
config file path |
OPEN_SECOND_BRAIN_MCP_TIMEOUT |
MCP request timeout |
Set these in each profile's .env. A variable the profile does not set
falls through to the Open Second Brain config chain (the project
pointer, the active profile, the config file, the default), not to the
gateway environment. Each profile gets its own o2b mcp child, started
with its own vault, agent name, timezone and config path, so two
profiles that share a vault but not an agent name write under their own
names. Without multiplexing nothing changes: the plugin reads the
process environment as before.
When one of these variables is also set in the gateway process environment, the gateway log names it once per process with a WARNING from the plugin's config module, never its value:
open-second-brain: ignoring VAULT_AGENT_NAME from the gateway process environment on a multiplexed gateway; set it in the profile's .env instead
If the gateway bound no profile scope for a call, the plugin refuses to
guess: the provider reports a ProfileScopeError naming the variable
and the remedy (hermes gateway restart), and a turn in that state
runs without the vault reminder instead of failing.
What stays process-wide on a multiplexed gateway:
HOME,PATHandPATHEXTdescribe the machine, not the profile, and are read from the process environment in both modes.XDG_CONFIG_HOMEandLOCALAPPDATA, which locate the config file, are read from the profile's.envfirst; a profile that does not set one uses the gateway process environment's value, so a value set in the launch profile's.envis seen by every profile that sets none.- Other variables the
o2b mcpchild reads - the search settings,OPEN_SECOND_BRAIN_MCP_API_KEY, embedding provider keys and theTELEGRAM_*settings - are still inherited from the gateway process environment. - A gateway that serves a routed profile home without multiplexing reads the process environment, as Hermes's own memory providers do.
One install pitfall: Hermes looks for a memory provider in its own
bundled plugins/memory/open-second-brain/ before
$HERMES_HOME/plugins/open-second-brain/. A copy left in the bundled
location shadows the plugin hermes plugins install and
hermes plugins update manage, so an update appears to change nothing.
Remove such a copy and restart the gateway.
Current Hermes limitation: The per-profile configuration above describes
what this provider supports. With separate copies of this buildable plugin in
two profile homes on the same machine, Hermes's plugin manager can fail to
resolve its workspace on hermes update because both copies declare the same
Python package name. The update may disable the plugin in the second profile.
Until the host issue is resolved, avoid installing separate copies in multiple
profile homes. See Hermes issue #138702
for the host-side status. A shared clone was reported as a workaround in
issue #308, but
has not been validated on every Hermes version or platform. Updating a shared
clone affects every profile that uses it.
How Hermes discovers the provider
The primary route needs no packaging metadata at all: hermes plugins install git-clones the repo into ~/.hermes/plugins/open-second-brain/,
and Hermes discovers the provider by scanning that plugin directory -
the plugins/hermes package ships plugin.yaml declaring
memory_provider: true, and the loader imports plugins.hermes and
finds the register callable there. A git clone registers no Python
entry-point metadata, so this path never consults the entry point.
The declared hermes_agent.memory_providers entry point group - the
open-second-brain entry names the same plugins.hermes module - is an
extra discovery route for pip or wheel installs only: entry-point
metadata exists when the package has been installed into the
environment, not when a checkout is cloned. That route presumes a clean
environment - the target rides the top-level plugins package name,
which only an operator-controlled install environment guarantees - so it
is a convenience layered on top of the directory scan, never a
requirement for the plugin install in step 1.
Registering the provider is automatic; running it is not entirely. The
provider serves memory by driving the Open Second Brain CLI over an
internal o2b mcp bridge, and Bun is required in every context: the
o2b wrapper on PATH (step 2 creates the links) is itself a bash script
that checks command -v bun first and refuses to run without it, and
the checkout fallback launches the repo's TypeScript entry point through
bun run directly. With Bun installed, either context - o2b on PATH
or a checkout - needs nothing beyond the install above. When Bun is
missing, or neither an o2b binary nor a checkout is present,
registration still succeeds and the failure surfaces later as a bridge
start error in the gateway log, so keep step 2 in place and Bun
installed.
5. Verify
o2b doctor --vault /path/to/vault --repo .
hermes memory status
hermes memory status shows Provider: open-second-brain with
available ✓ once active. Run the daily-identity check described in
install/prerequisites.md.
On a fresh gateway start the log shows
Memory provider 'open-second-brain' registered (10 tools) - the
provider advertises its curated brain_* tool set at registration
time, before the internal o2b mcp bridge starts. A (0 tools)
registration line indicates a version older than 1.0.1.
A provider-specific
hermes open-second-brainsubcommand is not surfaced on current Hermes. Usehermes memory statusfor provider state ando2b doctorfor the full readiness suite - together they cover the same ground.
6. Recall what Hermes wrote
Hermes built-in memory writes are mirrored into the Open Second Brain
continuity ledger, and o2b brain continuity promote is what makes
those mirrored facts recallable: each becomes an ordinary preference
page under Brain/preferences/, so page search finds it and the
context pack and its confirm flow treat it like any imported host
memory. Promote does not restore Hermes built-in memory - the ledger
stays the durable copy, and o2b brain continuity export remains the
full-fidelity audit path.
Promote is dry-run by default and writes nothing. Run it, read the per-record plan, then apply with the approval digest it prints:
o2b brain continuity promote --vault /path/to/vault
o2b brain continuity promote --vault /path/to/vault --apply \
--approval-digest <digest-from-the-dry-run>
--apply lands exactly the plan the digest seals or nothing at all; a
non-interactive apply must carry the digest. Promoted pages land
unconfirmed and stay under the trial window
(dream.unconfirmed_window_days) until the confirm flow accepts them,
like any other preference.
Update
hermes plugins update open-second-brain
hermes gateway restart
o2b doctor --vault /path/to/vault --repo .
memory.provider persists across updates, so the provider stays active
with no re-activation step.
Keep the o2b on PATH at the plugin's version. The links step 2
creates point into the plugin and follow it; an o2b installed some
other way must be updated too. Since v1.70.0 the plugin launches its
bridge with o2b mcp --harness hermes, and an older o2b refuses
--harness as an unknown flag, so the bridge does not start; the
gateway log shows the flag in the bridge's stderr.
Uninstall
Deactivate first (reverts to built-in memory), then remove:
hermes memory off
hermes plugins remove open-second-brain
o2b uninstall --apply-local --remove-cli
hermes gateway restart
hermes memory off is the native way to switch back to built-in memory
(or use hermes memory setup to pick a different provider). The vault
and its Markdown files are never deleted.