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
4.7 KB
Raw Blame

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 the agents.md convention.

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>', ... to stderr. Exit code stays 0.
  • The MCP brain_dream tool returns a warnings array containing { code: "non-primary-dream-run", message: "..." } alongside the usual summary.
  • The dream summary log event (Brain/log/<date>.md) gains a non_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_feedback from a coding session on the laptop.
  • o2b brain feedback from a terminal.
  • @osb markers added by hand in Daily notes from the phone (captured later by o2b brain scan-inline on 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).