Architecture

braynee is not a monolith and not clever. It's a thin orchestration layer with exactly two jobs. Hold those two jobs in your head and the whole system is legible.

The two pillars

                ┌─────────────────────────────┐
                │         Claude Code         │
                └───────┬─────────────┬───────┘
                        │             │
          lifecycle     │             │   settings
            events       │             │   read/write
                        │             │
        ┌───────────────▼─────────────▼───────────────┐
        │                  braynee                     │
        │                                              │
        │   PILLAR 1 — The Engine                      │
        │   hooks fire ambiently · settings managed    │
        │                                              │
        │   PILLAR 2 — Your Second Brain               │
        │   right slice of PARA memory → the session   │
        └───┬─────────────────┬─────────────────┬──────┘
            │                 │                 │
    ┌───────▼───┐     ┌───────▼───┐     ┌───────▼──────┐
    │  Obsidian │     │    QMD    │     │ beads / Dolt │
    │ PARA vault│     │  search   │     │ + vault view │
    └───────────┘     └───────────┘     └──────────────┘

Pillar 1 — The Engine

Claude Code emits lifecycle events: a session starts, you submit a prompt, a tool runs, the session ends. braynee registers hooks on those events. They run ambiently — you never invoke them. The same engine reads and edits your Claude Code settings so you don't hand-edit JSON.

That's the entire mechanism that makes the second brain feel automatic: events come in, scripts fire, context is injected and settings are managed. Mechanically it is simple.

Settings braynee manages

The hooks themselves register automatically via the plugin's hooks.json — nothing to configure. Separately, /braynee:setup writes exactly two keys into your Claude Code settings (~/.claude/settings.json), because they can't be expressed as hooks:

That is the complete list — braynee does not silently rewrite anything else.

Pillar 2 — Your Second Brain

The Engine has nowhere to put memory and nowhere to read it from on its own. That's the substrate's job. braynee wires three systems that already do their jobs well — it does not reimplement any of them:

Obsidian — the vault (long-term memory)

The vault is the memory itself, organized with PARA: Projects, Areas, Resources, Archives. Sessions, project context, decisions, clients, goals, and distilled knowledge all live here as Markdown — readable by you and searchable by Claude.

QMD — search (finding the right slice)

QMD indexes the vault for semantic and BM25 search. "Feed the right slice of context" is literally a QMD query: when Claude needs a past decision or a related note, it searches instead of guessing. recall and the knowledge agents are built on this.

beads + the vault task view — tasks (memory that carries work)

beads (bd) is a Dolt-backed issue tracker built for agent work — it's how an agent stays on task across compaction and how you track what it actually did. It is deliberately not Markdown and not the vault: agent task state needs dependencies, status, and survivability.

braynee keeps a three-way mirror, and the three roles are distinct on purpose:

• beads — the source of truth (agent task state).
• Claude Code's todo list — the live, in-terminal view while you work.
• The vault task view — the same tasks surfaced inside Obsidian via the Tasks + Dataview plugins, for a human reading next to their notes. braynee syncs it from beads; you read it, you don't hand-edit it.

The Engine's hooks keep all three in sync. (See the tools page for why these are separate, and where TaskNotes fits as an optional alternative.)

Why this shape

This is also why the reference pages on this site are generated from the live plugin: the architecture treats the plugin as the single source of truth, and everything downstream — including these docs — derives from it.