open-second-brain

Open Second Brain

An Obsidian-native memory layer for your AI agent. Plain Markdown you own, in the same vault you already use.

Open Second Brain plugs into Hermes Agent and turns your Obsidian vault into a memory layer the agent reads and writes through deterministic CLI / MCP tools. Preferences, signals, evidence, and audit trails are real .md files under Brain/ in the vault you already open in Obsidian every day. You can grep them, version them with git, search them in Obsidian, edit them by hand. No daemon, no vector black box, no hidden state outside the vault.

What is new

Open Second Brain 1.38.0 adds baselining for semantic-health advisories. When a vault is bulk-seeded with many preferences at once, the concept-gap and batch-concept-inflation advisories fire permanently and pin the health verdict at watch, with no way to acknowledge the burst short of deleting real memory. Now an optional health.silence_before watermark in _brain.yaml (managed by o2b brain health-baseline set <date>|now, get, clear) declares the state accepted up to that date: findings whose underlying entries are entirely older than the watermark are filtered from the surfaced report, the verdict reflects only what is shown, and the report always says exactly how many findings the baseline hid. Detection and storage are untouched, an entry without a parseable timestamp is never suppressed, and with no watermark set every output is byte-identical to 1.37.0.

Previous release, 1.37.0, was a retrieval quality and context delivery wave: a typed-edge relational retrieval arm, composite owner/session/project scope keys, an overwrite-only o2b brain state lane with a retrieval-time staleness barrier, a deterministic summary-search router, o2b search rerank-fit, the read-only brain_retrieval_plan MCP tool, a cadence-controlled navigation tier, an opt-in strict orientation hook, and workspace-wide codegraph partnering. Details live in the CHANGELOG.

Why

• Lives in your Obsidian vault. Open Brain/preferences/pref-no-internal-abbrev.md in Obsidian and you literally see what your agent learned about you - title, status, evidence count, confidence band, body text. Wikilinks, backlinks, graph view all work.
• You own the data. Plain Markdown on your filesystem. No service to cancel, no cloud account, no schema migration when a vendor pivots. Syncthing to your other machines if you want.
• Memory that learns deterministically. A dream pass turns repeat signals into rules and retires the ones nothing applies any more. Counters and atomic file moves - no LLM inside the algorithm, no surprise hallucinations in your memory.
• One vault, every agent. Hermes Agent is the primary integration. Claude Code, OpenAI Codex, Cursor, Aider, OpenClaw, opencode, Grok Build, kiro, Copilot CLI, Gemini CLI, and Pi all plug into the same Brain through MCP.

One vault, many runtimes

flowchart LR
    Vault[("Your vault<br/>Brain/ - plain Markdown")]
    Hermes["**Hermes Agent**<br/>(primary)"]
    CC[Claude Code]
    Codex[OpenAI Codex]
    Others["Cursor · Aider · OpenClaw<br/>opencode · Grok Build · kiro · Copilot CLI<br/>Gemini CLI · Pi · any MCP host"]

    Hermes <==> Vault
    CC <--> Vault
    Codex <--> Vault
    Others <--> Vault

    style Hermes fill:#1e3a5f,stroke:#90caf9,color:#fff
    style Vault fill:#5d3a9b,stroke:#ce93d8,color:#fff

Hermes Agent owns the schedule (dream cron, daily digests, Telegram delivery). Other runtimes participate as readers and writers of the same Brain through MCP - no per-runtime fork of the memory.

Quick start with Hermes Agent

The simplest path - let your agent set it up. Paste this into Hermes (or whichever AI agent already has shell access on the target machine):

Install Open Second Brain for me by following the steps at https://github.com/itechmeat/open-second-brain/blob/main/install/hermes.md. My vault is at /path/to/your-vault.

The agent reads the install doc, runs every command, and verifies the result. That's it.

If you prefer running the steps yourself:

# 1. Install the plugin
hermes plugins install itechmeat/open-second-brain --enable
hermes gateway restart

# 2. Put `o2b` on PATH
~/.hermes/plugins/open-second-brain/scripts/o2b install-cli

# 3. Bootstrap the vault
o2b init       --vault /path/to/your-vault --name "My Second Brain"
o2b brain init --vault /path/to/your-vault --primary-agent <agent-name>

# 4. Verify
o2b doctor --vault /path/to/your-vault