agentbrain-mcp 0.2.0

Agent Brain MCP Server — stdio + Streamable-HTTP transport surfaces for cross-source personal memory (Claude Code, Claude Desktop, Cursor, Windsurf)

agentbrain-mcp

MCP server that gives any MCP-capable AI client (Claude Code, Claude Desktop, Cursor, Windsurf) access to your personal Agent Brain — cross-source memory that persists across tools, conversations, and devices.

Status: status.agentbrain.ch · Changelog: CHANGELOG.md · License: MIT

What it does

Native MCP tools registered for cross-source personal memory:

Core recall + store:

• brain_recall(query, limit) — search your Brain for relevant memories (semantic + recency + authority)
• brain_recall_index(query, limit) — slim L0-preview (id+score+weight+preview+tags+created_at)
• brain_get(ids) — full-content retrieval by memory-ID
• brain_store(content, type, source_trust, layers) — persist a memory with structured tags
• brain_memory_content(id) — fetch full content of a single memory
• brain_timeline(limit) — chronological WAL recent entries
• brain_status() — agent + workspace health

Identity + self-model:

• brain_identity_backbone() — read agent identity-backbone (mission, principles, forbidden_drifts, voice)
• brain_self_model() — composite self-model (mood + arousal + calibration)
• brain_list_modes() — capability-modes + active selection (with Sprint-1 #2 safe-navigation)

Mythos-Layer (introduced v0.2.0):

• brain_belief(belief_id) — fetch belief-memory with reasoning chain
• brain_predict_record(prediction_text, horizon_hours) — register a prediction for later resolution
• brain_correct(claim_id, correction) — supersede a prior belief with corrected statement
• brain_quality_metrics() — agent calibration + Brier-decomposition + decision-audit

Plus presence/observability tools: brain_presence_hydrate, brain_presence_thoughts, brain_active_skills, brain_dream_recent, brain_pulse_recent, brain_calibration_history, brain_observe, brain_session_save, brain_session_resume, brain_open_loops, brain_pin_thought, brain_why, brain_tom_summary, brain_create_mode, brain_edit_mode, brain_set_mode, brain_learning_event, brain_flag_wrong, brain_backbone_update, mcp_observe_output.

The server is per-agent: each install is bound to one workspace via env vars. If you have multiple brains (work/personal/customer), run multiple instances.

Transport surfaces

Two transport modes (stdio + Streamable-HTTP):

• stdio — default. Spawned by MCP-clients (Claude Code, Desktop, Cursor, Windsurf). Auth via env-var BRAIN_API_KEY.
• Streamable-HTTP — agentbrain-mcp --http. HTTP server on configurable port. Auth via X-API-Key header. Stateless session management (per F-P3.1-05).

Install

pip install agentbrain-mcp

Or from source:

git clone https://github.com/AgentBrainHQ/agentbrain-mcp
cd agentbrain-mcp
pip install -e .

Quick start — Claude Code

claude mcp add agentbrain-max -- agentbrain-mcp

With explicit env:

BRAIN_AGENT=max BRAIN_API_KEY=<your-key> claude mcp add agentbrain-max -- agentbrain-mcp

Quick start — Claude Desktop / Cursor / Windsurf

Add to your MCP config (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "agentbrain-max": {
      "command": "agentbrain-mcp",
      "env": {
        "BRAIN_AGENT": "max",
        "BRAIN_API_KEY": "your-key-here"
      }
    }
  }
}

Configuration

Env Var	Required	Description
BRAIN_BASE_URL	yes (defaults to https://mcp.agentbrain.ch)	MCP-server URL
BRAIN_API_KEY	yes	per-agent API key
BRAIN_AGENT	yes (default max)	agent-identity
MCP_PHASE6_UNLOCK_ACK	conditional	HTTP-transport unlock acknowledgment (per F-P6-00)

See .env.example for full configuration reference.

Architecture

See ARCHITECTURE.md for canonical cross-surface routing reference (Phase-D).

Development

pip install -e ".[dev]"
pytest tests/

Test infrastructure includes:

• Phase-B CI-Guard (AST-based structural bug-class regression-prevention, 12/12 + 109/109 GREEN)
• Phase-C cross-surface smoke-script (9-call matrix baseline, see scripts/cross_surface_smoke.py)
• Sprint-1 #2 safe-navigation regression tests (13 tests, see tests/test_mcp_wrappers_safe_navigation.py)
• Sprint-2 #4 Mythos wrapper tests (22 tests, see tests/test_mcp_mythos_tools.py)

License

MIT — see LICENSE.

Copyright (c) 2026 Theshoth Sritharan / AgentBrain.