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

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 dream learning 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, the silence_before watermark, 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 optional vault.include_paths allowlist. 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 empty include_paths is refused at parse time (it would be an off switch on indexing, not a boundary); an empty ignore_paths keeps 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) and hook_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-local mcp_tool_profile / install_hook_timeout_seconds keys, and an unreadable _brain.yaml refuses 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 in tests/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-config writes 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 -r or tar. 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 dream algorithm 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 dream run takes a .snapshots/<run_id>.tar.zst before any state change (streamed through a staging file, and published under its final name only once complete); per-file writes go through fs-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.