Open Second Brain: Obsidian-native memory for Hermes Agent

What Open Second Brain actually stores, and for whom

The project describes itself as an Obsidian-native memory layer for an AI agent. The concrete claim is that preferences, signals, evidence, and audit trails are real .md files under a Brain/ directory inside the vault you already open in Obsidian. That is the whole pitch: you can grep those files, version them with git, search them in Obsidian, or edit them by hand, and there is no daemon and no vector store sitting outside the vault.

The audience is narrow and the README is honest about it. Open Second Brain plugs into Hermes Agent and exposes deterministic CLI and MCP tools. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else, but the memory model is built around Hermes. If you do not run Hermes Agent, you are using the adapters against a system whose centre of gravity is elsewhere.

The useful part is the file format. Agent memory that lives as Markdown in a vault you own is inspectable in a way that a database-backed memory service is not. The cost is that the agent now writes into the same directory tree you keep your notes in, and the project has spent several releases building guards around exactly that.

The dream pass and the confidence model

The description states that nightly dream passes turn repeat corrections into confirmed preferences with measurable confidence. That is the mechanism that separates this from a plain note-taking integration: corrections are recorded as signals, a scheduled pass reads them, and repeated corrections graduate into confirmed preferences rather than being applied once and forgotten.

The README's release notes describe the surrounding machinery in more detail than the pitch does. Every note write is an attributable and revertible event: a write record, a before-image store, a planned revert sealed by a digest, and a per-shard hash chain under every append-only ledger. A note update refuses to destroy what it could not read, raising target_unreadable instead of parsing an unreadable file as empty, and a blank body over a non-empty note needs an explicit allow_empty. Every structured Brain record carries a server-derived origin_channel that no caller can supply.

That is a lot of bookkeeping for a memory layer, and it is the right kind. The failure mode of agent memory is silent corruption: a preference overwritten by a bad parse, a correction applied twice, a merge that loops. The 1.53.1 notes mention closing a dedup pass that proposed the same merge forever and could write a merge cycle. Those are the bugs you get when an agent has write access to your notes, and the release history reads like the maintainers found them the hard way.

Installing Open Second Brain and running a first check

The package is published as open-second-brain with three binaries declared in package.json: o2b, o2b-mcp, and vault-log. The canonical version lives in package.json, and pyproject.toml exists only so the Hermes Python shim at plugins/hermes/__init__.py and the root __init__.py are addressable as a Python package. That file states it has no runtime dependencies and no CLI entry points, because those moved to package.json bin. So the CLI is TypeScript on Bun, and the Python side is a shim Hermes loads in-process.

After installing, the first useful command answers a question about the install itself:

o2b version --json

The README states this renders {"version":"…"} for a caller that parses. Note that o2b version latest is a usage error rather than a print of the local number, because nothing in this build learns what any other version is.

The second command is the one that tells you whether your adapters are wired correctly. The README describes it as the same verify() call that the MCP tool second_brain_wiring exposes as view=hosts:

o2b install --check

That returns the per-target verdict over the same registry and install environment. If you are wiring an MCP client instead, the same information comes back through second_brain_wiring with view=hosts, and view=projects returns one entry per registered project link with the four-value pointer state and whether the vault it names still exists. Both views render paths through the expose_host_paths contract, which is opaque by default and raw only when the operator sets the flag.

Where the install path is narrower than the description

The description lists adapters for Claude Code, Codex, and OpenClaw plus an MCP server for anything else. The repository layout supports that: there are .claude-plugin/, .codex-plugin/, and openclaw/ directories, an .mcp.json, and a skills/ directory. What the README reproduced here does not give is a documented install command for any of them. It covers release behaviour, not setup steps, and the install.md and after-install.md files at the top level are named but their contents are not shown.

That matters for evaluation. You can confirm the shape of the system from package.json and pyproject.toml, and you can confirm the runtime is Bun, but you cannot confirm from the README what a fresh install actually looks like on a machine that has none of it. Treat the homepage and install.md as the source for that.

The other constraint is the Hermes dependency. The pyproject.toml comment is explicit that the Python package exists so Hermes can load the plugin in-process as part of its lifecycle. If you are not running Hermes Agent, the shim has nothing to attach to, and you are left with the CLI and MCP surfaces as a standalone memory store. That may work, but it is not the configuration the project is built and tested around.

No update check, and why that is a deliberate choice

The 1.56.0 notes record a card that was refused rather than built. Release awareness asked for a surface reporting whether a newer version is available by reading only cached update state. The maintainers declined: there is no producer for that cache, nothing in the tree ever learns what the latest release is, and filling it requires a network check. The tool renders to the operator, verbatim, that it has no update check.

This is the most interesting decision in the release. Both honest alternatives would have amended an operator-facing promise about network behaviour, which the notes classify as an operator policy decision rather than an engineering one, and it is recorded in the CHANGELOG for the operator to take rather than taken on their behalf. A local-first tool that quietly phones home to check for updates would undercut the local-first claim, so refusing the feature is consistent. It also means o2b version tells you what you have and never what exists, and you are responsible for noticing that a release happened.

The same release tightened the version surface in a smaller way. o2b version and --version route to one renderer rather than two spellings that could answer differently, and both the CLI and the MCP serverInfo.version read one constant the tree imports exactly once, held there by a census with a positive control.

How this differs from a hosted memory service

The obvious alternative is a hosted agent-memory product that stores facts in its own database and returns them over an API. The difference is not performance, it is where the data lives and who can read it. A hosted service gives you retrieval without you owning the store; Open Second Brain gives you a directory of Markdown files you can open, diff, and revert with git.

The trade-off runs the other way too. A hosted service can update its retrieval model without you doing anything, and it can tell you when a new version exists. Open Second Brain cannot, by design. It also puts the burden of correctness on the local tooling: the before-image store, the hash chain, and the revert digest exist because there is no server-side safety net. If your vault is not under version control, you are relying entirely on the project's own guards.

There is a second alternative worth naming: doing nothing and letting the agent keep its context in the session. That works until the session ends. The nightly dream pass and the confirmed-preference model are aimed at the case where a correction you made last week should still apply today without you repeating it.

Licence, maintenance, and what an upgrade costs

The licence is MIT, declared in both package.json and pyproject.toml. That permits commercial use and modification with attribution and no warranty, but this is a description of the licence text, not legal advice; read LICENSE before you ship anything built on it.

The repository is not archived, and the last push was on 2026-09-12, which is recent. Three releases landed in the weeks before that: v1.54.0 on 2026-08-28, v1.55.0 on 2026-09-10, and v1.56.0 on 2026-09-12. The release cadence is fast, and the notes are unusually detailed about what changed and what was refused.

Upgrade cost is where the cadence shows. Version 1.56.0 changed the instruction block every agent reads at connect time so that guidance whose tool the host disabled is removed rather than contradicted, with each removal named. With nothing withheld, the rendered text is byte-identical to the three frozen strings it replaces, pinned by fixtures captured from them. That fixture pinning is what makes the upgrade safe: the claim is that a default install sees no change. Versions 1.54.0 and 1.55.0 turned visibility: into a boundary enforced at the three roots every read surface reaches page content through, which is the kind of change that can alter what an agent sees even when nothing in your vault moved. Read the CHANGELOG before upgrading across those.

Editorial conclusion

Adopt Open Second Brain if you already run Hermes Agent and keep an Obsidian vault you are willing to let an agent write into, and if you accept that the CLI is TypeScript on Bun while the Hermes shim is a Python package with no runtime dependencies. Do not adopt it if you want a memory layer that works without Hermes Agent, or if you need the tool to tell you when a newer release exists: the README states there is no producer for cached update state and that filling it would require a network check. Verify two things first. Run o2b install --check to see the per-target verdict for your adapters, and run o2b version --json to confirm the installed version is the one you think it is, since o2b version latest is a usage error rather than a lookup.

Frequently asked questions

Official sources

1. itechmeat/open-second-brain on GitHub
2. License: MIT
3. Project website
4. README
5. Releases