Hermes Brain

Hermes Agent 的多代理编排工具

生成并行 Hermes 代理。赋予它们一个共享大脑。一条命令即可交付。由 SQLite 提供支持，Python 协调，协调过程零 Token 消耗。

License: MIT Python Node.js Hermes MCP

安装

选项 1 — 从源码引导（推荐用于 Hermes）

curl -fsSL https://raw.githubusercontent.com/DevvGwardo/brain-mcp/main/install.sh | bash

安装程序：

构建 Node.js MCP 服务器 (brain-mcp)
安装 Python 编排包 (hermes-brain)
在 Hermes 中将大脑注册为 MCP 服务器

选项 2 — 手动安装

git clone https://github.com/DevvGwardo/brain-mcp.git
cd brain-mcp
npm install
npm run build
pip install -e .
hermes mcp add brain --command node --args "$PWD/dist/index.js"

注意： npm 包尚未发布，因此目前支持通过仓库路径安装。

验证：

hermes mcp list | grep brain
hermes mcp test brain
hermes-brain --help

先决条件： Python 3.10+，Node.js 18+，Hermes Agent

与朋友共享？ 每个人的大脑都是其独立的 SQLite 数据库 — 无需网络配置。同样的单行命令在任何地方都适用。

Docker 用户： 使用 layout: "headless" 生成代理，因为 tmux 面板无法在无头容器中渲染：

brain_wake({ task: "...", layout: "headless" })

快速入门

一条命令编排一组 Hermes 代理：

hermes-brain "Build a REST API with auth, users, and posts" \
  --agents api-routes auth-layer db-models tests

执行过程：

Python 指挥官生成 4 个后台 Hermes 代理 (hermes -q)
每个代理认领其文件、发布契约、编写代码、发送心跳
指挥官运行集成门 (integration gate) — 编译项目，并通过私信 (DM) 将错误路由回负责的代理
代理进行自我修正。集成门重试直到通过。
打印摘要：代理、契约、记忆、指标，完成。

更多运行方式：

# Auto-named agents
hermes-brain "Add error handling to the whole codebase"

# Mix models per task
hermes-brain "Build a game" --agents engine ui store --model claude-sonnet-4-5

# Cheap model for boilerplate
hermes-brain "Generate 10 test files" --model claude-haiku-4-5

# JSON pipeline with multiple phases
hermes-brain --config pipeline.json

或者在 Hermes 内部运行（交互式）：

hermes> Use register, then wake to spawn 3 agents
        that each refactor a different module.

工作原理

graph TB
    subgraph "Python Conductor"
        CLI["hermes-brain CLI"]
        ORCH["Orchestrator<br/><small>spawn · wait · gate · retry</small>"]
    end

    subgraph "Hermes Agents"
        direction LR
        H1["Agent 1<br/><small>hermes -q</small>"]
        H2["Agent 2<br/><small>hermes -q</small>"]
        H3["Agent 3<br/><small>hermes -q</small>"]
    end

    CLI --> ORCH
    ORCH -->|spawn| H1
    ORCH -->|spawn| H2
    ORCH -->|spawn| H3

    subgraph "Brain (shared SQLite)"
        DB[("brain.db")]
        PULSE["Heartbeats"]
        MX["Mutex Locks"]
        KV["Shared State"]
        CON["Contracts"]
        MEM["Memory"]
        PLAN["Task DAG"]
    end

    ORCH <--> DB
    H1 <--> DB
    H2 <--> DB
    H3 <--> DB

    subgraph "Integration Gate"
        GATE["tsc · mypy · cargo · go vet"]
        ROUTE["DM errors → agents"]
    end

    ORCH --> GATE
    GATE --> ROUTE
    ROUTE -.->|DM| H1
    ROUTE -.->|DM| H2

    style CLI fill:#9333EA,stroke:#7C3AED,color:#fff
    style ORCH fill:#9333EA,stroke:#7C3AED,color:#fff
    style H1 fill:#3B82F6,stroke:#2563EB,color:#fff
    style H2 fill:#10B981,stroke:#059669,color:#fff
    style H3 fill:#F59E0B,stroke:#D97706,color:#000
    style DB fill:#1E293B,stroke:#334155,color:#fff
    style GATE fill:#EF4444,stroke:#DC2626,color:#fff

架构

此图展示了 brain-mcp 的内部架构及其组件如何交互：

graph TB
    subgraph "External Clients"
        HERMES["Hermes CLI"]
        CLAUDE["Claude Code"]
        ANY["Any MCP Client"]
    end

    subgraph "brain-mcp (Node.js)"
        SERVER["src/index.ts<br/>MCP Request Router"]
        CONDUCTOR["brain-conductor<br/>Zero-token Orchestration CLI"]
        GATE["src/gate.ts<br/>Integration Gate"]
    end

    subgraph "pi-agent-core Runtime"
        PI_CORE["src/pi-core-agent.ts<br/>In-process Agent Runner"]
        PI_CORE_TOOLS["src/pi-core-tools.ts<br/>14 Brain Tools as AgentTools"]
        PI_AGENT["pi-agent-core Agent<br/>model + tools + events"]
    end

    subgraph "BrainDB (SQLite)"
        DB[("brain.db<br/>sessions, state, messages,<br/>claims, contracts, memory")]
    end

    HERMES & CLAUDE & ANY --> SERVER
    SERVER <--> DB
    SERVER --> CONDUCTOR
    CONDUCTOR --> PI_CORE
    PI_CORE --> PI_CORE_TOOLS
    PI_CORE --> PI_AGENT
    PI_CORE_TOOLS --> DB
    PI_AGENT -->|beforeToolCall<br/>pulse| DB
    CONDUCTOR --> GATE
    GATE -->|DM errors| CONDUCTOR

    style HERMES fill:#FF6B6B,stroke:#DC2626,color:#fff
    style CLAUDE fill:#3B82F6,stroke:#2563EB,color:#fff
    style ANY fill:#7C3AED,stroke:#6D28D9,color:#fff
    style SERVER fill:#1E293B,stroke:#334155,color:#fff
    style CONDUCTOR fill:#9333EA,stroke:#7C3AED,color:#fff
    style GATE fill:#EF4444,stroke:#DC2626,color:#fff
    style PI_CORE fill:#10B981,stroke:#059669,color:#fff
    style PI_CORE_TOOLS fill:#059669,stroke:#047857,color:#fff
    style PI_AGENT fill:#06B6D4,stroke:#0891B2,color:#fff
    style DB fill:#1E293B,stroke:#334155,color:#fff

pi-agent-core 是 LLM 代理运行时 — 处理模型交互循环、工具执行和事件订阅。brain-mcp 提供协调层（状态、消息传递、心跳、锁、契约），作为 pi 代理调用的工具。指挥官 (conductor) 通过阶段、门和 tmux 布局将这一切串联起来。

零 Token 协调。 指挥官是纯 Python 编写的 — LLM Token 仅消耗在实际工作上。心跳、认领、契约、门、重试均在本地运行。

无需管理服务器。 每个代理打开其自己的 stdio 连接到大脑。SQLite WAL 模式安全地处理并发访问。

相同的大脑，任意 CLI。 Hermes、Claude Code、MiniMax — 所有客户端都访问同一个 SQLite 数据库。Hermes + Claude 代理的混合舰队可以在同一个任务上进行协调。

`hermes-brain` CLI

hermes-brain <task> [options]

标志	默认值	作用
`--agents <names...>`	`agent-1 agent-2`	并行生成的代理名称
`--model <id>`	`claude-sonnet-4-5`	传递给每个代理的模型
`--no-gate`	关闭	跳过集成门
`--retries <n>`	`3`	集成门最大重试次数
`--timeout <seconds>`	`600`	每个代理的超时时间
`--config <file.json>`		加载多阶段流水线
`--db-path <path>`	`~/.claude/brain/brain.db`	自定义大脑数据库路径

流水线配置文件

{
  "task": "Build a todo app",
  "model": "claude-sonnet-4-5",
  "gate": true,
  "max_gate_retries": 3,
  "phases": [
    {
      "name": "foundation",
      "parallel": true,
      "agents": [
        { "name": "types",  "files": ["src/types/"], "task": "Define all TS types" },
        { "name": "db",     "files": ["src/db/"],    "task": "Set up Prisma schema" }
      ]
    },
    {
      "name": "feature",
      "parallel": true,
      "agents": [
        { "name": "api",    "files": ["src/api/"],   "task": "REST endpoints" },
        { "name": "ui",     "files": ["src/ui/"],    "task": "React components" }
      ]
    },
    {
      "name": "quality",
      "parallel": true,
      "agents": [
        { "name": "tests",  "task": "Write unit + integration tests" }
      ]
    }
  ]
}

阶段按顺序运行。同一阶段内的代理并行运行。集成门在阶段之间运行。

大脑工具

涵盖 12 个类别的 35+ 种工具。 Hermes、Claude Code 以及任何兼容 MCP 的代理均可使用。

身份与健康

工具	作用
`brain_register`	命名此会话
`brain_sessions`	列出活动会话
`brain_status`	显示会话信息 + 房间
`brain_pulse`	带有状态 + 进度的脉冲（返回待处理的私信）
`brain_agents`	所有代理的实时健康状况（状态、心跳时长、认领情况）

消息传递

工具	作用
`brain_post`	发布到频道
`brain_read`	从频道读取
`brain_dm`	直接向另一个代理发送消息
`brain_inbox`	读取你的私信

共享状态与记忆

工具	作用
`brain_set` / `brain_get`	临时键值存储
`brain_keys` / `brain_delete`	列出/删除键
`brain_remember`	存储持久知识（在 `brain_clear` 后依然存在）
`brain_recall`	搜索之前会话的记忆
`brain_forget`	删除过时的记忆

文件锁定

工具	作用
`brain_claim`	锁定文件/资源（基于 TTL 的互斥锁）
`brain_release`	解锁
`brain_claims`	列出活动锁

契约（防止集成错误）

工具	作用
`brain_contract_set`	发布你的模块提供/期望的内容
`brain_contract_get`	在编码前读取其他代理的契约
`brain_contract_check`	验证所有契约 — 捕获参数不匹配、缺失函数

集成门

工具	作用
`brain_gate`	运行编译 + 契约检查，将错误私信给负责的代理
`brain_auto_gate`	循环运行门，等待修复，重试直到通过

任务规划 (DAG)

工具	作用
`brain_plan`	创建带有依赖关系的任务 DAG
`brain_plan_next`	获取依赖关系已满足的任务
`brain_plan_update`	标记任务完成/失败（自动推进后续任务）
`brain_plan_status`	整体进度
`brain_workflow_compile`	将自然语言目标转化为阶段、代理、文件范围和指挥官配置
`brain_workflow_apply`	将编译后的工作流持久化到大脑状态 + 任务 DAG，可选写入指挥官 JSON

编排

工具	作用
`brain_wake`	生成新代理（hermes、claude 或无头模式）
`brain_swarm`	一次调用生成多个代理
`brain_respawn`	用恢复上下文替换失败的代理
`brain_metrics`	每个代理的成功率、持续时间、错误计数

上下文账本（防止丢失追踪）

工具	作用
`brain_context_push`	记录操作/发现/决策/错误
`brain_context_get`	读取账本
`brain_context_summary`	用于上下文恢复的精简视图
`brain_checkpoint`	保存完整工作状态
`brain_checkpoint_restore`	在上下文压缩后恢复

心跳与契约协议

每个生成的代理都遵循编排器强制执行的两项协议：

心跳 — 代理每 2-3 次工具调用就调用一次 brain_pulse，报告其状态和简短的进度说明。指挥官利用此功能：

在终端显示实时状态 (● working — editing src/api/routes.ts)
检测停滞的代理（60 秒内无脉冲 → stale）
将待处理的私信作为脉冲返回值发送（无需额外的往返）

契约 — 在代理编写代码之前，它们调用 brain_contract_get 查看其他代理导出了什么。编写完成后，它们使用 brain_contract_set 发布自己的契约。在标记完成之前，brain_contract_check 会验证整个舰队 — 捕获：

函数签名不匹配（期望 2 个参数，实际得到 3 个）
缺失导出（代理 A 导入了 getUser 但代理 B 从未导出它）
类型漂移（期望 User，实际得到 {name, email}）

这是将单代理集成质量与并行舰队匹配的关键。

集成门

sequenceDiagram
    participant O as Orchestrator
    participant C as Compiler
    participant DB as Brain DB
    participant A as Agent

    O->>C: Run tsc / mypy / cargo / go vet
    C-->>O: Errors with file:line:message

    O->>DB: Query: who claimed this file?
    DB-->>O: Agent X owned src/api/routes.ts

    O->>A: DM: "Fix these errors in your files"
    Note over A: Agent reads DM on next pulse
    Note over A: Fixes code, pulses done

    O->>C: Re-run compiler
    C-->>O: Clean
    O->>DB: Record metrics

集成门会自动检测项目语言并运行相应的检查器：

语言	检查器
TypeScript	`npx tsc --noEmit`
Python	`mypy`
Rust	`cargo check`
Go	`go vet`

错误会被解析，匹配到认领了失败文件的代理，并以私信形式路由。代理在下一次脉冲时获取错误并自我修正。循环最多重试 --retries 次，之后放弃。

混合舰队

大脑数据库在所有 MCP 客户端之间共享。单个项目可以拥有：

graph LR
    subgraph "Fleet"
        direction TB
        HA["Hermes Agent<br/><small>fast local inference</small>"]
        CC["Claude Code<br/><small>deep reasoning</small>"]
        MM["MiniMax<br/><small>cheap boilerplate</small>"]
    end

    subgraph "Brain"
        DB[("brain.db")]
    end

    HA <--> DB
    CC <--> DB
    MM <--> DB

    style HA fill:#F59E0B,stroke:#D97706,color:#000
    style CC fill:#9333EA,stroke:#7C3AED,color:#fff
    style MM fill:#3B82F6,stroke:#2563EB,color:#fff
    style DB fill:#1E293B,stroke:#334155,color:#fff

按任务类型路由。使用 Hermes 进行日常工作，Claude 进行架构决策，更便宜的模型处理样板代码 — 所有这些都通过同一个大脑进行协调，共享契约、门和记忆。

从 Claude Code：

brain_wake({ task: "...", cli: "hermes", layout: "headless" })
brain_wake({ task: "...", cli: "claude", layout: "horizontal" })

高级

以下内容涵盖了全部技术深度。

性能

自行运行基准测试：

node benchmark.mjs        # SQLite direct layer (1000 iterations)
node benchmark-mcp.mjs    # MCP tool layer (30 iterations per tool)

SQLite 直接层 (2026-04-06, M4 Pro, WAL 模式)

操作	平均值	p50	p95	p99	吞吐量
session_register	0.021ms	0.011ms	0.027ms	0.039ms	~47K/s
message_post (1 msg)	0.014ms	0.011ms	0.019ms	0.031ms	~70K/s
message_read (50 msgs)	0.042ms	0.042ms	0.045ms	0.066ms	~24K/s
state_get	0.002ms	0.002ms	0.002ms	0.003ms	~570K/s
claim_query (all)	0.001ms	0.001ms	0.002ms	0.002ms	~670K/s
heartbeat_pulse (update)	0.002ms	0.002ms	0.002ms	0.003ms	~464K/s
session_query (by id)	0.002ms	0.002ms	0.002ms	0.003ms	~455K/s

直接 SQLite：每个核心协调操作都在亚毫秒级。KV 存储 (state_get) 可维持约 570K 次读取/秒。高频协调（心跳、认领、状态）保持在 1ms 以下。

MCP 工具层 (2026-04-06, stdio JSON-RPC, 每次 30 次调用)

工具	平均值	p50	p95	最小值	最大值
brain_status	12.2ms	12.0ms	15.6ms	8.8ms	21.2ms
brain_sessions	1.9ms	1.7ms	3.6ms	0.9ms	4.7ms
brain_keys	1.6ms	1.6ms	2.6ms	0.8ms	4.5ms
brain_claims	2.0ms	1.8ms	3.4ms	1.2ms	4.9ms
brain_metrics	2.0ms	1.9ms	4.0ms	1.1ms	4.4ms

MCP 工具调用包括 JSON-RPC 帧、stdio IPC、TypeScript 工具分发和 SQLite 查询。一旦服务器预热，大多数工具在 1-2ms 内响应。brain_status 较慢 (12ms)，因为它聚合了所有房间的会话数据 — 基准测试期间存在 3000 多个会话。

这在实践中意味着什么

高频协调（每 2-3 次代理轮次的心跳、认领/释放、状态获取/设置）：始终直接通过 Python hermes.db.BrainDB — 而不是 MCP 层。亚毫秒级，无 stdio 开销。
代理级操作（生成、门、契约检查、集群）：使用 MCP 工具。每次调用 1-5ms 是可以接受的 — 这些操作每个代理只发生一次，而不是每轮一次。
零 Token 协调开销：整个协调层（消息传递、锁定、状态、心跳）不增加 LLM Token 成本。Token 仅消耗在实际工作上。

架构深度解析

graph TB
    subgraph "MCP Clients"
        HA["hermes sessions"]
        CC["claude sessions"]
        PY["Python orchestrator"]
    end

    subgraph "MCP Layer"
        M1["brain-mcp<br/><small>stdio server</small>"]
    end

    subgraph "Python API"
        PYDB["hermes.db.BrainDB<br/><small>direct SQLite access</small>"]
    end

    subgraph "Storage"
        DB[("~/.claude/brain/brain.db<br/><small>SQLite WAL</small>")]
    end

    HA --> M1
    CC --> M1
    PY --> PYDB
    M1 --> DB
    PYDB --> DB

    subgraph "Tables"
        T1["sessions · messages · dms"]
        T2["state · claims · contracts"]
        T3["memory · plans · metrics"]
        T4["context_ledger · checkpoints"]
    end

    DB --- T1
    DB --- T2
    DB --- T3
    DB --- T4

    style HA fill:#F59E0B,stroke:#D97706,color:#000
    style CC fill:#9333EA,stroke:#7C3AED,color:#fff
    style PY fill:#3776AB,stroke:#2C5F8D,color:#fff
    style DB fill:#10B981,stroke:#059669,color:#fff

设计决策：

双重访问路径 — 代理通过 brain-mcp 使用 MCP (stdio)。Python 编排器使用 hermes.db.BrainDB 直接、快速地访问同一个 SQLite

Brain MCP