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.
Cross-project setup
When the coding work happens in a project directory that is not the Open Second Brain vault, the agent needs a pointer to find the vault on session start. This page describes the canonical snippet to drop into a project, the conventions around the vault's primary dream-running agent, and what changes when several devices share the same vault.
1. Add the pointer snippet to your project
Append the block below to one of the agent-prompt files your runtime reads on startup. Common targets:
CLAUDE.mdβ Claude Code.AGENTS.mdβ Codex, Cursor, Aider, and other tools that follow theagents.mdconvention.
Pick one location per project. You can have Open Second Brain write
and maintain this block for you instead of pasting it by hand:
o2b install --target <host> --apply writes the managed block into the
agent-instruction file your host reads at the vault root (AGENTS.md for
codex, cursor, opencode and aider; GEMINI.md for gemini-cli), under an
explicit consent prompt, keeping every byte outside the block intact on
every re-run. The installed block merges the usage content below with
the memory write gate, and a later uninstall removes exactly the pair
the tool wrote. The manual snippet stays for hosts you provision by
hand. Install only writes the vault-root instruction file of the target
host; there, a pasted snippet or any hand edit inside the managed
fences makes the run refuse with user-modified-block unless --force
replaces it (a backup of the previous file is taken first).
Replace <absolute-vault-path> with the absolute path of your
Obsidian-compatible vault before pasting.
# >>> open-second-brain managed >>>
## Open Second Brain
This project shares an Obsidian-compatible vault with an active
observing-memory layer. At session start, read the current
preferences:
<absolute-vault-path>/Brain/active.md
Record taste signals via `brain_feedback` (MCP) or
`o2b brain feedback` (CLI). After producing a durable artifact, call
`brain_apply_evidence` with `result: applied | violated | outdated`
for any preference whose `scope` matches.
Do not run `o2b brain dream` from this runtime. The vault has a
primary dream-running agent declared in `<vault>/Brain/_brain.yaml`
(key `primary_agent`).
# <<< open-second-brain managed <<<
The snippet is intentionally short. The agent does not need
configuration here β every operational detail lives in the vault
itself (preferences, the active digest, the _brain.yaml config).
2. Primary agent and the dream cron
A shared vault has exactly one runtime responsible for running the
deterministic dream consolidation pass. Declare that runtime in
Brain/_brain.yaml:
o2b brain set-primary <agent-name> --vault <vault-path>
<agent-name> is the value of agent_name in
~/.config/open-second-brain/config.yaml on the host that runs the
dream cron. To verify, run:
grep agent_name ~/.config/open-second-brain/config.yaml
When dream runs from a different agent, the response carries a structured warning:
- The CLI prints
warning: non-primary-dream-run: dream run from agent '<caller>', ...tostderr. Exit code stays0. - The MCP
brain_dreamtool returns awarningsarray containing{ code: "non-primary-dream-run", message: "..." }alongside the usual summary. - The dream summary log event (
Brain/log/<date>.md) gains anon_primary_agent: <caller>payload row so the breach is greppable in the audit trail.
The pass still completes β the declaration is observability, not access control. Pinning, rejecting, and toggling pins remain unrestricted: any agent on any device can mutate the protected set.
To clear the primary declaration (the vault becomes single-host again, or you want to disable the check during local experimentation):
o2b brain set-primary --clear --vault <vault-path>
A vault initialised with o2b brain init --primary-agent <name>
writes the value into the fresh _brain.yaml on the first run; on
re-runs against an existing file --primary-agent is ignored β use
set-primary instead.
3. Multi-device through Syncthing
The vault is designed to be Syncthing-shared. Signals can be captured on any peer:
brain_feedbackfrom a coding session on the laptop.o2b brain feedbackfrom a terminal.@osbmarkers added by hand in Daily notes from the phone (captured later byo2b brain scan-inlineon any peer).
All of these land in Brain/inbox/. The primary host's dream cron
picks them up on the next pass, regardless of which peer wrote them.
Use the primary_agent declaration to keep dream serialised to one
host so signal processing does not race; the rest of the Brain
layer is conflict-free because writes are append-only or
locally-scoped (signals, daily logs, snapshots).