AllBrain MCP
AllBrain MCP is a shared, event-sourced memory and orchestration server for multi-agent projects.
Record shared events: append agent actions, decisions, and state changes with metadata (
save_event).Inspect history: query and filter events by type, session, or limit (
list_events).Resume project state: reconstruct tasks, sessions, and memory from snapshots or raw events (
resume_project).Checkpoint state: create point-in-time snapshots for fast restore or backup (
create_snapshot).Manage tasks: create event-sourced tasks and inspect task dependency graphs (
create_task,get_task_graph).Get an orchestration view: combine tasks, agents, metrics, sessions, and optional Git context (
orchestrate_project).Retrieve semantic memory: search past workflows and failure patterns using natural-language queries (
retrieve_memory).Inspect Git context: view branch, remote, commits, working tree status, and recent changes (
git_info).Run decision pipelines: perform counterfactual, scenario, foresight, uncertainty, and meta-reasoning analyses with ranked recommendations (
run_decision_pipeline).Support multi-agent collaboration: shared memory, agent attribution, conflict detection, and deterministic replay (README).
Provides tools to access Git commit history, diffs, and repository context for project awareness.
Integrates with Google's Gemini AI model for executing agent tasks.
Allows execution of subtasks using OpenAI models via the Agent Runtime adapter.
Used as an alternative distributed task queue backend for asynchronous execution of agent tasks.
Used as a distributed task queue backend for asynchronous execution of agent tasks.
Serves as the global database for storing agent events, snapshots, and project context.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AllBrain MCP orchestrate a multi-agent DAG workflow to implement OAuth login"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AllBrain Agent Runtime
One brain. Many agents. One shared memory.
Without AllBrain vs with AllBrain
Scenario | Without AllBrain | With AllBrain |
Agent A saves a plan | Written to local chat history, immediately lost when session ends | Appended to shared event store via |
Agent B starts the same project | Fresh context — no knowledge of Agent A's work |
|
Two agents write conflicting changes | Silent overwrite, no one knows |
|
Handoff between agents | Manual copy-paste of context |
|
Debugging state drift | "It worked in my session" | Deterministic replay from raw events, exactly reproducible |
Related MCP server: Enhanced Sequential Thinking MCP Server
The problem
Your AI coding agents don't talk to each other. Agent A saves a plan, Agent B starts fresh, Agent C has no idea what happened. Each agent works in isolation, repeating mistakes and missing context.
AllBrain gives every agent a shared workbench. Each tool call is recorded in an append-only event store. When the next agent arrives, it sees everything that happened before — events, sessions, conflicts, decisions — and picks up cleanly.
What AllBrain gives you
Shared memory —
save_event,list_events,resume_projectacross any MCP clientAgent attribution — every event is tagged with the agent that wrote it
Conflict detection — automatic surface of conflicting state updates
Decision pipelines — counterfactual reasoning, scenario planning, foresight
Deterministic replay — rebuild project state from raw events
53 tools in full profile across 18 domain modules (start with 3, enable more as needed)
30-second demo
# Agent A: save a plan
uv run allbrain start --project . --agent agent-a
# In Agent A's client, call:
# save_event(type="task_planned", payload={"task": "implement auth"})# Agent B: see what Agent A did
uv run allbrain start --project . --agent agent-b
# In Agent B's client, call:
# list_events()
# resume_project()See examples/two_agent_sqlite_pilot.py for a full two-agent workflow with conflict detection and replay verification.
Install for one client
The PyPI distribution is allbrain-agent-runtime. The canonical CLI command is
allbrain; allbrain-mcp and allbrain-agent-runtime remain compatibility
aliases for existing installations and scripts.
uvx allbrain-agent-runtime install --codexThis configures Codex to start AllBrain automatically. Replace --codex with the client name:
Client | Flag |
Codex |
|
Claude Code |
|
OpenCode |
|
Cursor |
|
VS Code |
|
Zed |
|
Gemini CLI |
|
Kiro |
|
Windsurf |
|
Antigravity |
|
Claude Desktop |
|
Use --all to configure every supported client at once.
Verify it works
uvx allbrain-agent-runtime install --codex --verifyThe --verify flag starts the server, saves a test event, reads it back, and confirms shared memory is working.
Tool profiles
Start with --tool-profile minimal (3 tools) and expand when needed:
Profile | Tools | Use when |
| save_event, list_events, resume_project | Getting started |
| minimal + retrieve_memory | Need recall |
| memory + task/conflict/resolution tools | Multi-agent handoff |
| memory + decision pipeline tools | Planning and analysis |
| save_event, list_events, retrieve_memory, git_info, create_task, get_task_graph, orchestrate_project, run_decision_pipeline, create_snapshot, resume_project, get_context_pack | Essential workflow + context pack |
| 53 tools | Complete surface across all 18 tool modules |
uv run allbrain start --project . --agent my-agent --tool-profile memoryGlama MCP Portal
Glama MCP evaluates this server with the balanced core tool profile
(--tool-profile core in glama.json). Its 11 public tools cover shared
memory, task orchestration, snapshots, Git context, and decision workflows
without exposing the entire development surface.
For local development or to access all capabilities, use the full profile:
uv run allbrain start --project . --agent claude-code --tool-profile fullAlternatively, standard client configurations like .mcp.json (which default to full) can be used.
From source
git clone https://github.com/Mustafa-Ali-Ertugrul/allbrain-mcp.git
cd allbrain-mcp
uv sync
./scripts/install-mcp.sh --all --isolate --verifyOr run the guided onboarding wizard:
uv run allbrain onboardIt walks you through client selection, install, verification, and your first event step by step.
See the full setup guide for manual config, troubleshooting, and shared-vs-isolated databases.
First memory save
Once AllBrain is installed and the client is restarted, call:
save_event(type="task_started", payload={"task": "implement auth", "agent": "codex"})Then verify it was recorded:
list_events()Switch to another client, call list_events() again — the same event appears.
Tool count and supported clients
Note: Glama evaluates the balanced 11-tool
coreprofile. The full profile remains available for local development.
53 tools in the full MCP profile across 18 server tool implementation modules (
src/allbrain/server/tools/)Default profile (
full) registers all toolsminimalprofile: 3 tools (save_event,list_events,resume_project)coreprofile: 11 tools (essential workflow + reasoning + context pack)
What's New in v1.1.0
Security hardening (threat-model remediation)
Fail-closed sanitization (§B1): Depth-limit bypass closed; configurable max depth and payload size cap.
gitbrain RCE sandbox (§D): No-shell argv, hard env isolation, and dangerous git config overrides.
SQLite permissions (§E1): Restrictive file/dir modes and umask hardening (Windows best-effort documented).
Memory poisoning defense (§1): Event-sourced quarantine, default exclusion from context, untrusted event boundaries,
promote_event/review_quarantined.Safe install (§C1):
.mcp.jsonbackup + merge + confirm/--force+ integrity hash.Windows path hardening (§C2): Case-insensitive
normcase+realpathcontainment checks.Event hash-chain (§A2): Lightweight tamper-evidence via chained payload hashes.
Runtime changes
Full tool surface: 53 tools (
promote_event,review_quarantinedadded)list_eventsdefault limit raised to 1000CI matrix: Python 3.12 & 3.13, coverage gate 85%
What's New in v1.0.0
1. 6 Bounded Contexts & 73 Domain Modules Migration
Modular Namespace: All 73 domain packages have been reorganized into the canonical
allbrain.domains.*namespace across 6 bounded contexts:reasoning,analysis,learning,governance,memory, andcollaboration.Backward Compatibility Shims: Root imports (
allbrain.<module>) remain functional withDeprecationWarningand are slated for removal inv2.0.0.
2. High-Performance Benchmarks & FastMCP Engine
Cold Startup: $\le 0.11$s server initialization.
Throughput: 277–371+ eps across varying payload sizes on local SQLite WAL.
Snapshot Generation: 0.091s for 10,000 events.
Memory Footprint: ~150 MB RSS peak under concurrent load.
3. Production Security & Verification
Secret Redaction: Multi-layer masking for 13+ secret formats and Pydantic validation error sanitization.
Input Validation: Strict Pydantic models with null-byte rejection and prompt injection filtering across MCP tools.
Filesystem Sandbox:
ALLBRAIN_ALLOWED_PROJECT_ROOTSpath traversal isolation.Dual-Window Rate Limiting: Process-local thread-safe rate limiter (1,000 RPS burst, 100,000 RPM rolling).
Community
Issues — bug reports and feature requests via issue templates
Changelog — every release documented in CHANGELOG.md
Releases — tagged, tested builds on GitHub Releases and PyPI
Contributing — see CONTRIBUTING.md; PRs welcome,
make ci-localbefore opening one
Data lifecycle and security
AllBrain stores events, sessions, and audit logs in local SQLite. Data never leaves your machine. Credential-like values are redacted before storage.
Data lifecycle — what is stored, retention, cleanup, restore
Uninstall guide — remove AllBrain from clients and delete data
Advanced docs
Full setup guide — all clients, shared vs isolated databases, troubleshooting
Custom agent integration — use AllBrain from any MCP client
Python SDK — typed async client (experimental)
Architecture — event sourcing, reducers, stream ordering, pipeline, bounded contexts
Storage backends — SQLite vs PostgreSQL vs queue adapters
Package maturity — production core vs opt-in vs experimental packages
Multi-agent pilot — two-agent workflow walkthrough
Upgrade guide — migrations, rollback, breaking changes
Community examples — real user setups, terminal output, workflows
Status
3,110 passed tests, 5 skipped tests (100% green)
53 tools in full profile
stdio FastMCP handshake verified
Python 3.12 & 3.13 (CI matrix)
Coverage: 86.54% (enforced threshold 85%)
Released under MIT · all releases are reproducible from the tagged source
Available Tools
5 toolscreate_taskA
Create a new task in the event-sourced task graph for multi-agent orchestration.
Use this to add work items before assigning them to agents. For updating an existing
task's priority, use change_task_priority instead. This appends a TASK_CREATED event
to the append-only SQLite event log with stable UUIDv7 ordering.
Side effects: Creates a TASK_CREATED event in the project's event log. Triggers an automatic snapshot when the event threshold is reached. Does NOT assign the task.
Inputs: goal (required), kind, task_id, priority, +1 more. Returns: object
git_infoA
Retrieve git repository context, working tree status, or recent changes.
Consolidated tool replacing the previous get_git_context, get_git_status,
and get_recent_changes tools. Use info_type to select what subset to return.
"all" returns branch, remote, recent commits, working tree status, and staged/ modified/untracked file lists in a single response. Use this when you need the full picture before making changes.
Side effects: Read-only operation; queries git repository.
Inputs: limit, since, until, info_type. Returns: object
list_eventsA
Query and filter recorded events from the append-only event log.
Use this to inspect the history of agent actions and system state changes. Events are ordered by stable UUIDv7 timestamps for consistent replay.
Side effects: Read-only operation; no data is modified.
Inputs: type, limit, session_id. Returns: object
retrieve_memoryA
Semantic search over stored memories to find similar workflows and patterns.
Use this to discover relevant past work when facing a new task. Returns both similar workflows and common failure patterns that match the query.
Side effects: Reads from the semantic memory store built by build_memory.
Use build_memory first to ensure the index is up-to-date.
Inputs: query (required), limit, top_k. Returns: object
save_eventA
Append an event to the shared event log with optional metadata.
Use this to record agent actions, decisions, and state changes. All events are append-only with stable UUIDv7 ordering, enabling deterministic replay.
Side effects: Creates a new event in the SQLite event log. Triggers an automatic snapshot when the event threshold is reached. This is the primary write operation for the event-sourced architecture.
Inputs: type (required), payload (required), branch, source, +6 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct function: event logging (save/list), git context, semantic memory retrieval, and task creation. There is no overlap or ambiguity in their purposes.
Most tools follow a verb_noun pattern (save_event, list_events, retrieve_memory, create_task), but git_info breaks this pattern as a noun phrase, introducing inconsistency.
With 5 tools covering event log, git, memory, and tasks, the count is within the typical 3-15 range but feels slightly thin given the broad scope, making it reasonable but not well-scoped.
The event log is complete with save and list, but git lacks write operations, memory lacks a creation tool (build_memory is referenced but not present), and tasks lack update, delete, or list operations, leaving notable gaps.
Maintenance
Related MCP Connectors
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Hosted runtime for persistent agent teams, durable workflows, memory, schedules, and goals.
Multi-agent governance: task orchestration, compliance, decision validation, and ML predictions.
Related MCP Servers
- FlicenseAqualityBmaintenanceA basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.9340,089 npm92,139-
- AlicenseNot gradedqualityNot gradedmaintenanceEnables structured problem-solving through sequential thinking stages with persistent storage and analysis. Helps break down complex problems into manageable cognitive steps while tracking progress and generating summaries of the entire thought process.MIT
- AlicenseAqualityDmaintenanceEnables efficient code navigation and retrieval through natural language search, BM25 ranking, and fuzzy matching across multiple programming languages. It drastically reduces token usage by allowing Claude to query specific code symbols and logic instead of reading entire files.1313MIT
- FlicenseAqualityDmaintenanceA durable multi-agent orchestrator for software development with explicit run graphs, checkpoint/resume capabilities, and project memory exposed through MCP resources and tools. It enables coordinated agent workflows for coding, review, repair, CI, and approval with SQLite-backed memory retrieval and pluggable research backends.10-