The Problem

AI agents need a deterministic, version‑controlled place to store context and preferences. Current vector‑store approaches hide data in opaque binaries, making audit, diffing, and manual correction difficult. Teams using Obsidian already keep knowledge in plain Markdown – they lack a thin, local‑first layer that lets an agent read/write that vault safely and reproducibly.

What This Does

open-second-brain ships a set of CLI and MCP (Memory‑Control‑Protocol) tools that treat an Obsidian vault as the single source of truth. The core logic lives under src/cli/brain/ (e.g., src/cli/brain/verbs/index.ts defines the verb dispatcher) and under src/core/brain/ where policies, time handling, and the atomic file helper src/core/fs-atomic.ts reside.

Adapters for Claude, Codex and OpenClaw are in plugins/ – each provides a cli.py that registers the provider with the Hermes Agent (plugins/hermes/provider.py). The memory layer persists everything as .md files under Brain/ in the vault, so normal Git workflows, search, and manual edits remain possible.

How It Is Wired

Execution starts at the concrete entry points:

  • plugins/hermes/cli.py – run is invoked by the Hermes Agent. It calls _status → resolve_vault → _config_value → _config_text, which reads the vault configuration file (_config_text uses path.read_text).
  • src/cli/main.ts – the top‑level Node CLI parses arguments (src/cli/argparse.ts) and dispatches to the verb map in src/cli/brain/verbs/index.ts. That module imports 120 other verb implementations, making it the most outward‑facing hub (instability = 1).

The internal call graph shows that the most widely used functions are:

  • FakeBrainBridge – called from 35 places.
  • _init – called from 17 places.
  • OpenSecondBrainMemoryProvider – called from 14 places.

These functions sit in plugins/hermes/provider.py and src/core/brain/, and any change propagates to many callers.

Filesystem interaction occurs in 12 functions (e.g., _config_text, src/core/fs-atomic.ts), external commands in 2 functions (plugins/hermes/bridge.py runs the agent binary), and network calls in 3 functions (e.g., call_tool in plugins/hermes/bridge.py).

A circular import exists between plugins/hermes/cli.py and plugins/hermes/__init__.py; breaking it would reduce the risk of import‑time side effects. The duplicated 720 six‑line blocks across hooks/ and plugins/ indicate that shared helpers should be extracted to a common module.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/open-second-brain
cd open-second-brain

# Install TypeScript dependencies
npm install   # reads package.json (no lockfile)

# Install Python dependencies
pip install -e .   # reads pyproject.toml

# Configure the vault location (example)
export O2B_VAULT_PATH=/path/to/obsidian/vault

# Register the provider with Hermes Agent
python -m plugins.hermes.cli run

The plugins/hermes/cli.py script registers the memory provider; the Node CLI (npm run start → src/cli/main.ts) can be used for ad‑hoc commands such as o2b brain snapshot. No Dockerfile or pre‑built binary is supplied, so the above local install is the only supported path.

Real‑World Use

A development team stores design notes in Obsidian. By adding the Hermes plugin (plugins/hermes/cli.py) to their CI pipeline, each test run invokes o2b brain snapshot to capture the current context. The agent can later retrieve that snapshot via call_tool to answer questions about prior decisions, with the entire audit trail available as Git‑tracked Markdown.

Code Health & Issues

  • Measured findings (static analysis)
  • HIGH – Hub module: src/core/fs-atomic.ts imported by 148 modules – keep it stable, move volatile logic out.
  • HIGH – Duplicated code: 720 repeated 6‑line blocks across 179 files – extract shared helpers.
  • MEDIUM – High branching density: src/cli/argparse.ts, src/core/path-safety.ts, src/mcp/coerce.ts have >20 branches in <80 lines – consider strategy tables.
  • MEDIUM – Deep nesting: src/mcp/instructions.ts depth 7 – flatten with guard clauses.
  • HIGH – Import cycle: plugins/hermes/cli.py ↔ plugins/hermes/__init__.py – break by moving shared types.
  • MEDIUM – Broad exception handling: plugins/hermes/__init__.py uses bare except – catch specific errors.
  • Repository hygiene
  • No lockfile for npm (package.json only) – builds are non‑reproducible.
  • CI exists (.github/workflows/ci.yml) but lacks pinned actions, dependency scanning, and job timeouts.
  • Code‑health audit (high‑confidence)
  • HIGH – Pin GitHub Actions to commit SHA (e.g., oven-sh/setup-bun@v2).
  • MEDIUM – Enable Dependabot (.github/dependabot.yml).
  • MEDIUM – Add dependency‑vulnerability scan to CI.
  • LOW – Set timeout-minutes on workflow jobs.
  • LOW – Add .editorconfig, .gitattributes, and formatter config.

The Bottom Line

open-second-brain provides a transparent, Markdown‑based memory layer that plugs directly into Hermes Agent, making context auditability trivial. The codebase is functional but concentrates risk in a few hub modules, contains duplicated logic, and lacks reproducible builds and robust CI safeguards. It is suitable for teams comfortable editing the core TypeScript/Python code and willing to address the identified hygiene gaps before production use.