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.
Architecture
Open Second Brain is organized around a stable core and multiple runtime adapters.
Layers
Agent runtime
-> runtime adapter/plugin
-> skills and commands
-> CLI/core library
-> vault files and local config
Core responsibilities
The core (src/core/) provides deterministic operations for:
- locating and validating configuration;
- initializing a vault profile (
o2b brain init); - recording taste signals, applied-evidence, and narrative milestones into
Brain/log/<YYYY-MM-DD>.md(plus a JSONL sidecar); - running the nightly
dreamlearning pass (deterministic, no LLM calls); - exporting redacted config snapshots;
- checking vault health (
o2b brain doctor); - querying preferences, signals, and link-graph relationships through the MCP and CLI surface.
The core does not depend on Hermes, Claude Code, Codex, OpenClaw, or Obsidian internals.
Runtime adapters
Hermes adapter
The Hermes adapter can be a real runtime plugin:
plugins/hermes/
plugin.yaml
__init__.py
Possible responsibilities:
- register available hooks;
- check configuration at gateway startup;
- expose readiness diagnostics;
- connect Hermes session metadata to Open Second Brain profiles;
- optionally add event capture hooks when safe and explicit.
The Hermes adapter must not silently change model routing, write secrets, or mutate unrelated vault areas.
Claude Code adapter
Claude Code support should be packaged through plugin metadata and bundled skills/commands.
The adapter should focus on:
- installing skills;
- exposing slash-command style workflows where supported;
- optionally configuring hooks;
- optionally declaring MCP configuration in later versions.
Codex adapter
Codex support has two halves. The distribution half is a plugin:
.codex-plugin/plugin.json # declares "skills": "./skills" and "hooks": "./hooks/hooks.json"
skills/
hooks/hooks.json
The MCP half is a runtime install adapter
(src/core/install/adapters/codex.ts), reached the same way every other
adapter-backed runtime is: o2b install --target codex --apply. It has two
paths into the same file. With the codex binary on PATH it drives
codex mcp add, which persists the servers into $CODEX_HOME/config.toml;
without it, it merges the two [mcp_servers.*] tables into that file
directly, leaving every unrelated table byte-for-byte intact.
verify therefore asks two different questions of one file. In fallback
mode this build serialised the tables, so any edit is drift. In subprocess
mode the Codex CLI serialised them in a layout this build has no published
grammar for, so verify checks only that the two tables are still DECLARED
and lets codex mcp list answer whether the host is actually serving them.
Both the file half and the probe half resolve CODEX_HOME from the
adapter's own injected environment, so a relocated Codex home cannot verify
against the operator's real ~/.codex. Operator steps:
install/codex.md.
OpenClaw adapter
OpenClaw discovers Open Second Brain as a Native plugin via the
openclaw.extensions entry in package.json. The entry
(src/openclaw/index.ts) reads and writes the vault directory
directly with node:fs / node:path; no subprocess is spawned, so
the OpenClaw security scanner (which blocks child_process imports)
accepts the plugin.
Installation (always installs the latest from main; do not append @v...):
openclaw plugins install git:github.com/itechmeat/open-second-brain
The OpenClaw adapter must remain compatible with the Hermes, Claude
Code, and Codex adapters. The o2b mcp MCP server is the canonical
way for any runtime to reach the writer / reader tools.
Configuration model
Open Second Brain separates immutable package code from mutable user configuration and data.
Machine-local config
Machine-local config points a runtime to a vault and environment profile.
Suggested path:
$OPEN_SECOND_BRAIN_CONFIG
~/.config/open-second-brain/config.yaml
Example:
version: 1
instance_name: My Second Brain
runtime: hermes
environment_name: <hostname>
vault:
path: <absolute-path-to-Obsidian-vault>
identity:
agent_name: <chosen-agent-name>
user_language: <BCP-47 tag, e.g. en or ru>
policy:
write_mode: agent-owned-dir
Machine-local config may contain absolute paths. It must not contain secrets.
Vault-portable config
Vault-portable config lives at <vault>/Brain/_brain.yaml and travels
with backup/sync. It describes:
- schema version + dream / retire / confidence / snapshot thresholds;
- optional
notes.read_paths(user-authored folders the agent may read); - optional
temporal:,link_graph:,guardrails:,discipline_report:tuning blocks; - an optional
health:block tuning the semantic lints, the remediation step cap, thesilence_beforewatermark, and the derived-page freshness ceiling (materialize_max_age_days, default 30 days). Its day and count keys must each be a positive integer; a zero or a fraction is an explicit config error at load, never a clamped default; - optional
integrity:gates (owner_scope_delivery,embedding_abi,pack_validity_seconds) that decide where a mismatch is reported and where it is refused; vault.ignore_paths(exclusion policy for every vault walker) and the optionalvault.include_pathsallowlist. A path is in scope when it is not excluded AND, if an allowlist is declared, under one of its roots; absent, the allowlist changes nothing. The two compose in that order β an allowlist narrows, it never re-includes an exclusion. An emptyinclude_pathsis refused at parse time (it would be an off switch on indexing, not a boundary); an emptyignore_pathskeeps its meaning of "exclude nothing". Both keys share one grammar: no slash is a bare name matched at any depth, a slash is a vault-relative path matched exactly;- an optional
install:block with the two settings that parameterise GENERATED install output:tool_profile(the MCP tool surface a generated registration selects) andhook_timeout_seconds(1β600, the cap on a generated lifecycle hook entry). They live here rather than in the machine-local config because install verification works by RE-CONSTRUCTION rather than a stored hash: a knob only one machine could see would make the other report drift it cannot explain and re-apply a file that was already correct. This block therefore OUTRANKS the machine-localmcp_tool_profile/install_hook_timeout_secondskeys, and an unreadable_brain.yamlrefuses the resolution rather than falling back to a default the operator never chose; - optional
write_binding.path_prefixes(where a CALLER-NAMED write may land:brain_create_note,brain_update_note,brain_append_note,brain_write_batch). This is a write boundary over caller-named paths, not a security boundary and not per-agent β its authority is this file, which no tool call can rewrite, and it reads no caller identity. Writes whose destination is derived rather than named are outside it; the boundary is recorded intests/core/architecture/write-site-census.test.ts.
It must not contain secrets.
Backup model
Open Second Brain should assume the vault is the primary portable backup unit.
Recommended behavior:
- vault-portable config is backed up with the vault;
- machine-local config can be regenerated with
o2b init --adopt-vault; o2b export-configwrites a redacted machine snapshot into the vault;- secrets are excluded and represented as
***REDACTED***only when needed.
What "the vault" contains is enumerated rather than assumed.
src/core/state/surfaces.ts declares every durable location this build
keeps INSIDE a vault β 44 of them β each with the layer that can move it
and what its loss costs, split into derived (rebuildable, so deleting it
costs time) and vault-content (the memory itself, permanent without a
backup). o2b state status measures that catalogue against one vault and
the vault_health MCP tool carries the same value; o2b state migrate
is the one operation that changes where a surface lives, and it binds every
byte it moves with a digest manifest so the move is reversible. The sibling
population β what this build can leave OUTSIDE a vault β is
src/core/install/ownership.ts, reported by the ownership statement
o2b install --target <t> --apply prints.
Vault layout
The agent owns one directory in the vault for its own artefacts:
Brain/. User-authored notes (daily journals, weekly notes) live
wherever the operator names them; the agent reads those paths only when
they are listed in notes.read_paths.
Two operations reach user space, both of them operator-invoked and named
here rather than implied. brain_note_lifecycle moves, renames, archives
and deletes a note at a path the caller supplies, and rewrites inbound
[[wikilink]] references to it across the vault. Its archive action
moves the note to Archive/<original path> β a second top-level
directory, because the note is user content and Brain/ is refused for
every note path, source and destination alike. An operator whose backup
rule covers only Brain/ should extend it to Archive/. The rewrite
pass never writes outside the vault, never writes a path vault.ignore_paths
or vault.include_paths excludes, and never rewrites Brain/log/, which
is an append-only record of what was said at a time.
An export refuses in two cases rather than writing something misleading. A payload the redactor could only partially scan refuses, because a file that was scanned in part cannot claim to be clean. And a secret-shaped identifier β a filename, an id, a mapping key β refuses rather than being redacted, because redacting an identifier does not hide it, it renames it: two notes whose names both redact to the same placeholder collapse onto one path and one of the bodies is lost. A placeholder in a payload is a redaction; a placeholder in an identifier is a lost identity.
Brain/
_brain.yaml # schema + thresholds + notes.read_paths (validated by o2b brain doctor)
_BRAIN.md # operating manual for agents (rendered by o2b brain init)
active.md # derived digest, auto-regenerated
inbox/ # raw taste signals, sig-<date>-<slug>.md
processed/ # signals already folded into a preference
archived/ # unconsumed signals older than dream.contradiction_window_days
preferences/ # active rules: pref-<slug>.md, status unconfirmed | confirmed
retired/ # ret-<slug>.md with retired_reason
log/ # YYYY-MM-DD.md, append-only event log (dream / apply-evidence / etc.)
.snapshots/ # <run_id>.tar.zst, pre-run snapshots for o2b brain rollback
# plus hygiene-<date>/ archives (pages moved, never deleted)
.state/ # machine state, excluded from indexing (since v1.3.0):
# session-lineage.jsonl (compression-chain ledger)
# anticipatory/<root>.json (hook-warmed context cache)
This layout is intentionally agent-owned: every artefact Open Second
Brain generates lives under Brain/. User-authored content elsewhere in
the vault stays under operator control and is read-only to the agent's
own passes; the note-lifecycle verbs above are the one surface that
writes it, and they act only on a path the caller named.
Brain layer
Three architectural invariants:
- Filesystem-first. No database, no daemon. Every artifact is plain Markdown with YAML frontmatter; backup is
cp -rortar. Background work is started only by agent activity and exits when done: the search index is refreshed by a short detached run a stale read starts (freshen on read) - an applied note-lifecycle write claims one the same way - never by a resident process. - Deterministic core. The
dreamalgorithm is a pure function of inputs (signals, preferences, log, configuration, current time). No LLM calls inside the core. Semantic merging, if needed, is delegated to external agents via the same CLI / MCP surface. External judgment (the bench judge, the hygiene conflict resolver) goes through one sanctioned fail-open boundary: the operator-configured command bridge (src/core/reliability/command-bridge.ts). - Pre-run snapshot + atomic per-file writes. Each
dreamrun takes a.snapshots/<run_id>.tar.zstbefore any state change (streamed through a staging file, and published under its final name only once complete); per-file writes go throughfs-atomic(temp + rename). Combined with retention of the most-recent N snapshots, this gives reversible, audit-friendly mutation.
The layered diagram from the top of this document still holds β Brain/ sits at the same level as the vault files in the bottom layer:
Agent runtime
-> runtime adapter/plugin
-> skills and commands (brain-memory skill, open-second-brain skill)
-> CLI/core library (src/core/brain/*)
-> vault files: Brain/ (observing memory)
Full design: docs/plans/2026-05-15-brain-observing-memory.md.
As of v0.10.10 the always-loaded open-second-brain-writer MCP
server hosts one read tool (brain_context) alongside the three
writers (brain_feedback, brain_apply_evidence, brain_note).
The reader exists for runtimes without a SessionStart hook
(Cursor, Aider, raw Claude API) β they call it once at session
start to pull the same Brain/active.md content the hook-aware
runtimes get auto-injected. The MCP server name is preserved for
backward compatibility with existing client .mcp.json entries;
renaming is deferred until a second reader joins the always-load
scope.
Event log
The Brain event log is append-only. It records operational events, not polished knowledge.
Storage: <vault>/Brain/log/<YYYY-MM-DD>.md (Markdown for human
reading) plus a JSONL sidecar at <vault>/Brain/log/<YYYY-MM-DD>.jsonl
(machine-friendly for downstream tooling). Each event kind is one
line per row, written through atomic temp+rename. The shared
redactor strips secret-shaped tokens before write.
Security rules
Open Second Brain must not store:
- API keys;
- tokens;
- passwords;
- private SSH keys;
- credentials;
- connection strings containing secrets.
If secret-like content appears in input, tools should redact it as ***REDACTED*** before writing.
Every path that writes vault content to a destination OUTSIDE the vault - the
export verbs and o2b export-config - goes through src/core/egress/guard.ts
and is declared in src/core/egress/registry.ts, with
tests/core/architecture/egress-census.test.ts deriving the population from
source so a new export path cannot ship undeclared. A payload the redactor
could only partially scan refuses the write rather than producing a file that
claims to be clean.
The census derives that population under TWO rules, because a registry whose
membership check is narrower than what it claims to enforce is a label with
nothing behind it. The first rule finds FILE destinations - a destination
parameter plus a raw file write - and it is how o2b brain explorer --export
went undeclared: its destination flag was not in the list the rule keys on, so
the site wrote an unredacted vault export past a registry built to prevent
exactly that. The second rule finds NETWORK destinations - a module POSTing
vault-derived bytes to an operator-configured URL - which the first rule
cannot express at all. Under it the embedding endpoint
(src/core/search/embeddings/openai-compat.ts) is declared with a reason
stating plainly that chunk bodies leave unscanned. Both rules are proved by
synthetic modules, so each fails the build until the site it finds is
declared.
Five paths send vault-derived bytes to a network destination without passing
the shared redactor - the two embedding providers, the cross-encoder reranker
(which POSTs the query PLUS the candidate documents), the Telegram capture
reply, and the research transport. Each is declared in
src/core/egress/registry.ts as unscanned_network_payload with the reason
redaction would corrupt rather than protect the result, and
docs/cli-reference.md carries the operator-facing table; the census fails if
a sixth appears undeclared or an existing one falls out of that table. A
default install reaches none of them.
The optional decision model (src/core/decision-model/, next to the
embedding and rerank providers) is a third outbound model seam and the one
network path that IS scanned: its adapter (systemone.ts, registry id
decision-model-systemone) passes the whole request body through
redactForEgress, and the state builder drops any candidate whose page is
private or whose visibility cannot be resolved before anything is built. It
fits the rule that Open Second Brain never calls an LLM the same way the
embedding and rerank calls do: a decision model returns probabilities over
candidates this code produced and never text, the deterministic result stays
canonical and is returned on every failure, and no decision writes to the
vault. It is active only when the operator enables it in machine config AND
the named key variable is set (a self-hosted laya or openjev server on
loopback needs no key); otherwise every code path is the one without
it. Every use goes through runDecision (run.ts), which owns the modes
(off, shadow, enforce), the daily cost gate and the
decision_model_call accounting record. The uses are the rerank kind
decision-model (src/core/search/rerank/decision-model.ts, which also
carries the advisory answerable question), skills
(src/core/surface/skill-attach-decision.ts), extract_prefilter
(src/core/brain/extract-signals-prefilter.ts), dedup and tension
(pair-verdict.ts), labels (src/core/brain/label-suggest.ts) and recall_inject
(src/core/brain/recall-inject-decision.ts); each use's evaluation report
lives in reports/ and is registered in reports/index.ts. See
docs/decision-models.md.
Decision adapters, all behind makeDecisionProvider (provider.ts, null
unless active, loaded lazily) and the shared transport rules in
transport.ts: systemone.ts (TypeSafe, OpenRouter, Vercel compatible
route, OpenCode Zen, any compatible server, and the self-hosted laya and
openjev presets on loopback), vercel-evaluate.ts (the Vercel AI Gateway
/v1/evaluate variant, a field mapping over systemone.ts), and
llm-emulation.ts (an OpenAI-compatible chat model asked for probabilities
only, registry id decision-model-llm-emulation: the one uncalibrated,
generative route, used only when named explicitly and refused in enforce
without decision_model_allow_uncalibrated). Threshold profiles per model
family live in questions.ts; see
docs/decision-models/providers.md.
Ownership is a boundary only where something writes it. With
integrity.owner_scope_delivery on, every production preference writer stamps
the server-resolved agent identity onto a NEW record; a rewrite never re-owns,
so a page created before the gate stays shared rather than being retro-owned
by whoever rewrote it first. With the gate off nothing is stamped and a vault
that never opted in is byte-identical. On the read side a caller-supplied
agent_scope naming another owner is REFUSED by name under the gate, never
silently narrowed to the caller's own - a narrowing would leave the caller
believing it had read what it asked for.
The surfaces that take no agent_scope argument honour the same gate through
the server-resolved identity. They aggregated their own rows and asked nothing,
so under fail they returned another owner's artifact ids, paths, titles and
body prose. Each now filters through ownerScopeView, an adapter over the one
ownership rule rather than a second one, and the set spans the tool surface,
the MCP resources surface and one CLI verb. A withheld row is dropped and
nothing counts it: brain_hygiene's per-detector counts, brain_claims'
count and the timeline's total are recomputed over the visible rows, so a
filtered report is indistinguishable from a report over a vault that never held
them. Two surfaces also bound a WRITE rather than only a payload -
brain_hygiene mode=apply and brain_doctor repair planned against the
unfiltered report, so a caller whose scan correctly returned nothing could
still act on a row it had never been shown. With the gate off every one of
these is byte-identical, because the view short-circuits before it reads a
file.
warn is inert on this set, deliberately and now stated where it is
implemented: reporting how many rows fail would withhold is itself the
disclosure, so warn's observability here is the owner: stamp appearing on
new files, not a count in any response.
A retirement does not always hide a record. A validity-closed predecessor
stays serveable inside its window and a superseded non-tip stays readable;
only a tombstoned record drops out of recall everywhere. Every surface that
serves memory - the search pool after ranking, recall by topic, context
packs, the Brain/active.md digest and the dream scan - applies one rule to
a serveable retired row: it is served only beside its chain-tip correction,
resolved and readable at the caller's reach, and dropped otherwise. The drop
is fail-closed, so a row whose correction is missing or out of reach is
indistinguishable from an absent one, and a correction pulled in beside its
predecessor passes the full filter set - status, visibility scope, agent
scope, reach - because a successor the caller could not read on its own must
not enter through the correction door. The predicate in
src/core/search/correction-coupling.ts is the rule's only spelling; the
surfaces differ in what they serve, never in what the rule says.
The enforcement lives in tests/mcp/agent-scope-matrix.test.ts, and its shape
is the point rather than its size. One hundred and ten classified tools carry
253 call recipes - one per mode, view or operation, because one executed view
is not an executed classification. Every recipe runs TWICE against the same
two-owner fixture, once with the gate closed and once with it open, and the
classification decides what the open run must show: the 32 recipes classified
as reaching owner-taggable content must surface the marker with the gate off,
which is what stops the closed run from passing vacuously. The other 221 carry
a claim of unreachability, and that claim is executed directly - the marker
must be absent even where nothing is hidden. The first version of this probe
asserted only the closed half, and 81 of its entries were driven against
arguments that named artifacts the fixture never created; they could not have
failed. Those three numbers are pinned as equalities in the same file.