Metadata-Version: 2.4
Name: agentbrain-mcp
Version: 0.2.0
Summary: Agent Brain MCP Server — stdio + Streamable-HTTP transport surfaces for cross-source personal memory (Claude Code, Claude Desktop, Cursor, Windsurf)
Author-email: Theshoth Sritharan <hello@agentbrain.ch>
License-Expression: MIT
Project-URL: Homepage, https://agentbrain.ch
Project-URL: Documentation, https://agentbrain.ch/docs/mcp
Project-URL: Repository, https://github.com/AgentBrainHQ/agentbrain-mcp
Project-URL: Issues, https://github.com/AgentBrainHQ/agentbrain-mcp/issues
Keywords: mcp,model-context-protocol,memory,agent,brain,ai,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp==1.27.0
Requires-Dist: starlette<2,>=0.37
Requires-Dist: uvicorn<1,>=0.30
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: pytest-asyncio<2,>=0.23; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Dynamic: license-file

# 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](https://status.agentbrain.ch) · **Changelog:** [CHANGELOG.md](./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

```bash
pip install agentbrain-mcp
```

Or from source:

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

## Quick start — Claude Code

```bash
claude mcp add agentbrain-max -- agentbrain-mcp
```

With explicit env:

```bash
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):

```json
{
  "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`](./ARCHITECTURE.md) for canonical cross-surface routing reference (Phase-D).

## Development

```bash
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](./LICENSE).

Copyright (c) 2026 Theshoth Sritharan / AgentBrain.
