Open Second Brain

What is Open Second Brain about?

Open Second Brain adds a local‑first memory store to an Obsidian vault. Every interaction with an AI agent (Hermes, Claude Code, Codex, etc.) is recorded as regular .md files under a Brain/ folder. The system aggregates repeated signals through a nightly dream pass, turning them into stable preferences with confidence scores, all without hidden vector stores or external services.

How to use Open Second Brain?

1. Install the plugin via the Hermes CLI: hermes plugins install itechmeat/open-second-brain --enable and restart the gateway.
2. Add the CLI to PATH: ~/.hermes/plugins/open-second-brain/scripts/o2b install-cli.
3. Bootstrap a vault: o2b init --vault /path/to/vault --name "My Second Brain" then o2b brain init --vault /path/to/vault --primary-agent <agent-name>.
4. Verify with o2b doctor --vault /path/to/vault.
5. Use the o2b command suite (status, brain dream, search, brain rollback, etc.) to interact with the memory.

Key features of Open Second Brain

• Plain‑Markdown storage – files are fully visible and editable in Obsidian.
• Deterministic learning – the dream pass aggregates repeat signals into rules, using counters and atomic moves only.
• Multi‑runtime support – Hermes Agent, Claude Code, Codex, Cursor, Aider, OpenClaw, Copilot CLI, Gemini CLI, Pi and any MCP host share the same Brain.
• One‑line rule teaching – drop @osb feedback … markers in notes; o2b brain scan-inline converts them to signals.
• Explainable hybrid search – SQLite + FTS5 backed, optional semantic layer, with MMR diversity and why_retrieved explanations.
• Pay Memory audit – every monetary action is logged under Brain/payments/ with policy checks and daily reports.
• Full rollback & integrity – each mutation snapshots with SHA‑256; o2b brain rollback restores prior state safely.
• Graph explorer – visual HTML force‑directed graph of all rules and links.

Use cases of Open Second Brain

• Personal AI assistant that remembers user preferences (naming conventions, style guides) across multiple tools.
• Team knowledge base where developers can teach coding standards once and have every AI‑powered IDE enforce them.
• Compliance & audit for AI actions that involve spending, providing a tamper‑evident ledger.
• Explainable retrieval for research notes, where the system shows why a result matched the query.
• Iterative prompt engineering – experiment with feedback markers, let the dream pass consolidate stable prompts.

FAQ from the Open Second Brain

Q: Do I need a daemon running in the background? A: No. All operations are performed by the CLI or a short‑lived stdio MCP subprocess.

Q: Can I store secret keys in the vault? A: Secrets should not be stored in the vault. The system includes a redactor that attempts to strip common secret patterns from logs.

Q: What happens if a rule becomes obsolete? A: Rules without recent evidence are automatically retired during the dream pass; you can also manually retire or pin them.

Q: How does the system integrate with non‑Hermes runtimes? A: Install the corresponding adapter (e.g., Claude Code Marketplace plugin) which writes side‑car manifests under .<vault>/.open-second-brain/. The runtimes then read/write via MCP.

Q: Is the memory portable? A: Yes. Because it is plain Markdown, you can sync the vault with Git, Syncthing, or any file‑sharing method.

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.

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, kiro, Copilot CLI, Gemini CLI, and Pi all plug into the same Brain through MCP.

One vault, many runtimes

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

Register the MCP server in ~/.hermes/config.yaml and restart the gateway one more time - the agent now reads Brain/active.md on every session start and writes signals through brain_feedback. Full step-by-step including MCP wiring: install/hermes.md.

Other runtimes

Each non-Hermes target writes a sidecar manifest under <vault>/.open-second-brain/install.lock.json so o2b uninstall --target <name> --apply removes exactly what it added.

How rules accrete

Three repeat signals on the same topic graduate to a confirmed rule. Evidence shifts confidence up or down. Rules with zero recent evidence retire automatically. You can pin, merge, retire, or roll back with o2b brain {pin,merge,reject,rollback} - see docs/cli-reference.md.

Top features

The capabilities you actually feel day to day:

These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron, cross-project pointers for shared vaults, source-agent query and comparison (brain_agent_query, brain_agent_diff, o2b brain agent-query, o2b brain agent-diff), the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, an operator dashboard, the v0.12.0 Brain Integrity Suite (content-hash drift detection, durable workrun checkpoints, destructive-from-confirmed retire gate, and the brain_review_candidates MCP tool that previews what the next dream pass would do without writing anything), the v0.13.0 Hybrid Search and Recall Quality suite (explainable recall, MMR diversity, link-graph traversal, entity-boosted retrieval, header-anchored chunking), and the v0.14.0 Semantic Brain Health and Self-Maintenance suite (cross-preference contradiction detection, concept-gap and stale-claim surfacing, per-preference edit-history, a clean/watch/investigate reconciliation verdict via brain_health, and dependency-ordered doctor --remediate). Browse docs/cli-reference.md for every verb and docs/how-it-works.md for the mental model.

CLI

o2b status                    # Show config / vault status
o2b init                      # Bootstrap the vault profile
o2b doctor                    # Run vault + adapter checks
o2b brain dream               # Deterministic consolidation pass (idempotent)
o2b brain digest              # Recent transitions, markdown or JSON
o2b brain agent-query --agent claude --json   # Source-agent provenance query
o2b brain agent-diff --mode diff --agent claude --agent codex
o2b search "<query>"          # FTS5 over the vault
o2b update                    # Update across detected runtimes

Full list (~50 verbs across o2b, o2b brain, o2b vault, o2b discipline, Pay Memory) in docs/cli-reference.md.

Safety

• Plain Markdown on your filesystem. No daemon, no background writes.
• The MCP server is a stdio subprocess that exits with the parent runtime.
• Secrets are not supposed to live in the vault. Daily logs and config exports go through a best-effort redactor for common secret-name patterns.
• Brain mutations (dream, merge, upgrade) take a pre-run snapshot with a SHA-256 sidecar; o2b brain rollback aborts on drift unless --force-rollback.
• Hooks (Claude Code, Codex) only inject text into the agent's context; they never write to the vault directly.

Updating

o2b update                    # detect runtimes, skip unchanged, apply, verify
o2b doctor                    # confirm the new manifest validates

Per-runtime upgrade paths and the canonical version source live in install.md.

Documentation

Uninstalling

o2b uninstall                       # print plan (read-only)
o2b uninstall --apply-local --remove-cli   # remove local state and symlinks

Your vault is never touched by the uninstall flow. Delete it yourself with normal filesystem tools if you want to.

License

MIT. Source: https://github.com/itechmeat/open-second-brain.