bbb-mcp-server

BrainBrainBrains — persistent memory + context layer for AI-assisted dev teams, exposed via the Model Context Protocol (MCP). Open source, local-first, zero config. Includes multi-model council deliberation with adaptive temperature tuning.

Your AI tools forget everything between sessions. BBB remembers. Store decisions, conventions, constraints, and architecture notes. Query them with full-text search. Assemble smart context for any task. Snapshot and rehydrate sessions across tools. For critical decisions, convene a multi-model council — structured peer review across AI models with automatic diversity optimization.

Quick Start

npx bbb-mcp-server --project my-project

Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bbb": {
      "command": "npx",
      "args": ["-y", "bbb-mcp-server", "--project", "my-project"]
    }
  }
}

Claude Code

claude mcp add bbb -- npx -y bbb-mcp-server --project my-project

Codex

Add to ~/.codex/config.toml:

[mcp_servers.bbb]
command = "npx"
args = ["-y", "bbb-mcp-server", "--project", "my-project"]

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "bbb": {
      "command": "npx",
      "args": ["-y", "bbb-mcp-server", "--project", "my-project"]
    }
  }
}

What Can You Do With It?

Give your AI persistent memory:

"Remember that we use the service locator pattern for dependency injection."

BBB stores this as a decision memory. Next session, any AI tool connected to BBB will know this automatically via context_assemble.

Convene a council for critical decisions:

"I need to decide between REST and GraphQL for the payments API. Set up a council with Claude, GPT, and Gemini to deliberate."

BBB runs a 3-stage deliberation: collects independent answers from each model, has them anonymously peer-review each other, then synthesizes a final recommendation from the council's collective wisdom. The result is auto-stored in project memory.

Tools (75)

Phase 1 — Core (17)

Memory (5)

| Tool | Description | |------|-------------| | memory_store | Store a memory (decision, convention, constraint, etc.) | | memory_query | Full-text search with BM25 ranking | | memory_list | Paginated listing with filters | | memory_update | Version-aware update (supersedes old) | | memory_delete | Delete by ID |

Artifacts (3)

| Tool | Description | |------|-------------| | artifact_store | Store/update ADRs, PRDs, API contracts, etc. | | artifact_get | Fetch by ID or search by type/title | | artifact_list | Paginated listing with filters |

Tasks (3)

| Tool | Description | |------|-------------| | task_create | Create task with dependencies | | task_update | Update status, linked artifacts | | task_get_dag | Dependency graph view |

Context (2)

| Tool | Description | |------|-------------| | context_assemble | Smart context assembly with token budgeting | | search_memories | Direct FTS5 search |

Project (2)

| Tool | Description | |------|-------------| | project_init | Initialize a new project | | ingest_codebase | Auto-index repository files |

Session (2)

| Tool | Description | |------|-------------| | session_snapshot | Capture full session state | | session_rehydrate | Restore snapshot + generate tool config |

Phase 2 — Agent Workflows (20)

Swarm Sessions (4)

| Tool | Description | |------|-------------| | swarm_session_start | Start a new swarm session in the hydrate phase | | swarm_session_transition | Transition session to the next lifecycle phase | | swarm_session_status | Get current status and allowed transitions | | swarm_session_complete | Mark a swarm session as complete |

Permissions & Approvals (5)

| Tool | Description | |------|-------------| | permission_set | Set allow/deny/approval_required rules per tool and role | | permission_list | List permission rules with filters | | approval_request | Request approval to execute a tool | | approval_respond | Approve or reject a pending request | | approval_list | List pending/resolved execution requests |

Audit (3)

| Tool | Description | |------|-------------| | audit_query | Query audit events with filters | | audit_verify | Verify audit trail integrity (SHA-256 chain) | | audit_export | Export audit trail as JSON |

Task Runner (4)

| Tool | Description | |------|-------------| | task_decompose | Create a task DAG from a structured plan | | task_execute | Mark a task as executed with results | | task_batch | Batch create or update multiple tasks | | task_rollback | Roll back a failed task to pending |

Sandbox (4)

| Tool | Description | |------|-------------| | sandbox_create | Create an E2B sandbox | | sandbox_exec | Execute a command in a sandbox | | sandbox_status | Get sandbox status | | sandbox_destroy | Destroy a sandbox |

Phase 3 — Multi-Model Orchestration (23)

OpenRouter Support: Register models from any provider with a single API key using OpenRouter. Set provider to "openrouter" in model_register and configure the OPENROUTER_API_KEY environment variable. Mix and match with direct provider keys (Anthropic, OpenAI, Google).

Roles (4)

| Tool | Description | |------|-------------| | role_register | Register an agent role with mission, model, and budget | | role_list | List all registered roles | | role_get | Get full role details by ID or name | | role_update | Update a role's configuration |

Models (2)

| Tool | Description | |------|-------------| | model_register | Register an AI model with provider, capabilities, and pricing | | model_list | List registered models with filters |

Dispatch (1)

| Tool | Description | |------|-------------| | task_dispatch | Route a task to the best model based on capabilities and strategy |

Agent Comms (2)

| Tool | Description | |------|-------------| | agent_message_send | Send a message between agent roles | | agent_message_inbox | Get pending messages for a role |

Conflicts (2)

| Tool | Description | |------|-------------| | conflict_list | List detected conflicts between agent outputs | | conflict_resolve | Resolve a conflict using a resolution strategy |

Observability (2)

| Tool | Description | |------|-------------| | cost_report | Get aggregated cost report by period, role, or model | | metrics_dashboard | Get metrics dashboard with cost, latency, throughput, and error rates |

Council Deliberation (10)

| Tool | Description | |------|-------------| | council_create | Create a council with member models and chairman | | council_get | Get council configuration by ID | | council_list | List all councils for the project | | council_update | Update council configuration | | council_deliberate | Run full 3-stage deliberation (collect → review → synthesize) | | council_stage1 | Run Stage 1 only (parallel model queries) | | council_stage2_review | Run Stage 2 only (anonymous peer review on any responses) | | council_synthesize | Run Stage 3 only (chairman synthesis) | | council_history | View past deliberation records | | council_leaderboard | Model performance rankings across deliberations |

Phase 4 — Platform & Adaptive Intelligence (15)

Adaptive Context (2)

| Tool | Description | |------|-------------| | context_feedback | Submit outcome signal for a context assembly | | context_debug | Show why memories were included/excluded |

Memory Quality (3)

| Tool | Description | |------|-------------| | memory_health | Get quality report (stale, duplicate, low-quality counts) | | memory_archive | Archive stale or low-quality memories | | memory_merge | Merge duplicate memories |

Sessions (2)

| Tool | Description | |------|-------------| | session_info | Get current session capabilities | | session_configure | Override auto-detected session settings |

Context Rules (2)

| Tool | Description | |------|-------------| | context_rules_set | Define capability-aware context filtering rules | | context_rules_list | List active context rules |

Teams (2)

| Tool | Description | |------|-------------| | team_members | List and manage team members and roles | | team_activity | Recent team activity feed |

Compliance (2)

| Tool | Description | |------|-------------| | audit_export | Export audit trail (JSON/CSV) | | compliance_status | Get compliance posture and retention status |

Marketplace (2)

| Tool | Description | |------|-------------| | marketplace_search | Search plugins and templates | | marketplace_install | Install a plugin or template into your project |

How It Works

• SQLite + FTS5 — One .db file per project at ~/.bbb/data/. Full-text search with BM25 ranking. WAL mode for performance.
• Context Assembly — Extracts keywords from your task, searches memories + codebase, scores by relevance (BM25 + recency + tag overlap + quality score + feedback boost), and assembles a token-budgeted context block.
• Adaptive Context — Submit feedback on context assembly results. Memories that consistently help get boosted; unhelpful ones get demoted. Quality scores decay over time for stale memories.
• Session Portability — Snapshot your entire project state and rehydrate it in any tool (Claude Code, Cursor, Claude Desktop, VS Code, Codex).
• Agent Workflows — Swarm session lifecycle, tool permissions with approval gates, SHA-256 audit chain, task decomposition/execution/rollback, and E2B sandbox integration.
• Council Deliberation — Send a question to multiple models simultaneously (Stage 1), have them anonymously peer-review each other's responses (Stage 2), then synthesize a final answer from a designated chairman model (Stage 3). Inspired by Karpathy's llm-council. All 3 stages can be run independently for custom workflows.
• Goldilocks Temperature — Adaptive temperature control for council deliberations. After Stage 1, BBB measures pairwise response diversity (Jaccard similarity). Too similar? Raises temperature and retries. Too different? Lowers it. Finds the sweet spot where models agree on fundamentals but offer genuinely different perspectives. Opt-in per council.
• Model Leaderboard — Tracks which models win peer review across deliberations. Over time, builds a real-world performance profile for each model on your actual workload — better than synthetic benchmarks.
• Multi-Model Orchestration — Role-based routing across Claude, GPT, Gemini, and OpenRouter with cost-optimized/quality-optimized/balanced strategies, inter-agent messaging, conflict detection, and cost tracking.
• Multi-User Teams — User identities, team membership, RBAC (owner/admin/member/viewer), and activity attribution.
• Marketplace — Plugin and template registry with install/share workflows.

BBB Platform

The BBB Platform extends this with cloud-hosted team memory, semantic vector search, advanced council governance (scheduled deliberations, quorum rules, approval workflows for high-cost deliberations), team-wide model leaderboard with department analytics, and enterprise features. It's coming soon.

License

MIT