@brain-protocol/mcp

Verifiable Memory for AI Agents — MCP server with local SQLite or cloud mode.

Give any AI agent persistent, searchable, graph-connected memory that works offline and optionally syncs to a cloud backend with on-chain verification.

Quick Start

npx @brain-protocol/mcp

That's it. The server starts in local mode with a SQLite database at your OS's standard data directory.

IDE Setup

Generate the config for your IDE automatically:

npx @brain-protocol/mcp --setup claude-desktop
npx @brain-protocol/mcp --setup cursor
npx @brain-protocol/mcp --setup claude-code
npx @brain-protocol/mcp --setup snak
npx @brain-protocol/mcp --setup windsurf

Claude Desktop

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

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["@brain-protocol/mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["@brain-protocol/mcp"]
    }
  }
}

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["@brain-protocol/mcp"]
    }
  }
}

Snak (Starknet AI Agent Framework)

Add to mcp.config.json in your Snak project:

{
  "servers": {
    "brain": {
      "transport": "stdio",
      "command": "npx",
      "args": ["@brain-protocol/mcp"]
    }
  }
}

See examples/snak/ for full integration examples including agent config and demo scripts.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["@brain-protocol/mcp"]
    }
  }
}

Authentication

Authenticate with the Brain Protocol cloud API in one command:

npx @brain-protocol/mcp --login --cloud https://brain.api.vauban.tech

This opens your browser, you sign in with GitHub or Google, and the CLI receives an API key automatically. Credentials are stored in ~/.config/brain-protocol/credentials.json.

After login, cloud mode works without explicit --api-key:

npx @brain-protocol/mcp --cloud https://brain.api.vauban.tech
npx @brain-protocol/mcp --check  # uses stored credentials

To clear stored credentials:

npx @brain-protocol/mcp --logout

Cloud Mode — OAuth 2.1 (zero config, no API key)

Connect to brain.api.vauban.tech with mcp-remote — OAuth handles auth automatically via GitHub:

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["mcp-remote", "https://brain.api.vauban.tech/mcp"]
    }
  }
}

First connection opens GitHub OAuth in your browser. Token is stored locally — subsequent connections are automatic. No API key needed.

Cloud Mode — API Key

For CI/CD pipelines or headless environments, use an API key:

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["@brain-protocol/mcp"],
      "env": {
        "BRAIN_API_URL": "https://brain.api.vauban.tech",
        "BRAIN_API_KEY": "your-api-key"
      }
    }
  }
}

Tools (25 active)

Tools marked cloud only require --cloud / BRAIN_API_URL to be set. In local mode they return a clear error.

Knowledge Management

OpenMemory Compatibility (drop-in replacement)

Brain Protocol is compatible with any OpenMemory MCP client (Claude Desktop, Cursor, Windsurf, Copilot) without config changes.

Entries are tagged openmemory:client:{app} for multi-client scoping. Use client_app: "cursor" in add_memories to silo memories per IDE.

did:starknet Identity

get_memory_status accepts an optional wallet_address + chain_id to bind a W3C DID to your memory:

{ "wallet_address": "0x237d3c...", "chain_id": "SN_MAIN" }

Returns a standard DID Document (did:starknet:SN_MAIN:0x237d3c...) usable for verifiable credential issuance.

Verification & Proof

Agent Intelligence (cloud mode)

Usage & Billing (cloud mode)

Giza zkML Proofs (Trust Triangle)

The Giza tools enable the Trust Triangle: Snak (execution) + Brain (memory) + Giza (verification). Proofs are stored with giza-proof tags and giza_* metadata for structured querying. Verified proofs get confidence 0.95, unverified get 0.6.

Decision Intelligence

Brain Sync (hybrid mode)

Consciousness & Health

Knowledge Curation (cloud mode)

CLI Options

--help       Show help message
--version    Show version number
--db-path    Override SQLite database path
--cloud      Cloud API URL (alternative to BRAIN_API_URL env)
--api-key    API key for cloud mode (alternative to BRAIN_API_KEY env)
--setup      Print IDE config (claude-desktop, cursor, claude-code, snak, windsurf)
--check      Health check: show mode, entry count, and exit

Health Check

Verify your installation without starting the server:

npx @brain-protocol/mcp --check
# brain-protocol MCP v0.6.3
# Mode: local (~/.local/share/brain-protocol/brain.db)
# Entries: 42 | Edges: 15
# Status: ready

Environment Variables

Local vs Cloud Mode

Local Mode (default)

Data stored in SQLite with FTS5 full-text search, WAL mode, and recursive CTE graph traversal. Works completely offline. Schema auto-migrates between versions.

Database location follows OS conventions:

• macOS: ~/Library/Application Support/brain-protocol/brain.db
• Linux: ~/.local/share/brain-protocol/brain.db
• Windows: %APPDATA%/brain-protocol/brain.db

Override with --db-path, BRAIN_DB_PATH, or XDG_DATA_HOME.

Cloud Mode

Connect to a Brain Protocol API server for multi-device sync, team collaboration, and on-chain verification via Starknet.

npx @brain-protocol/mcp --cloud https://brain.api.vauban.tech --api-key YOUR_KEY

Cloud mode includes built-in resilience:

• Retry with exponential backoff — automatic retry on 5xx errors and network failures (4 attempts, fail-fast on 4xx)
• Circuit breaker — after 5 consecutive failures, short-circuits all calls for 30s cooldown to avoid hammering a down server. Auto-recovers when the backend comes back.

Architecture

┌─────────────────────────────────────────────┐
│              MCP Protocol (stdio)            │
├─────────────────────────────────────────────┤
│           38 Tool Handlers (7 groups)       │
│  query | archive | update | delete | edge   │
│  graph | stats | export | import | prove    │
│  verify | agent_stats | log_task            │
│  suggest_patterns | detect_antipatterns     │
│  architectural_advice | get_usage           │
│  archive_giza_proof | query_giza_proofs     │
│  link_proof_to_entry | record_decision      │
│  get_decision_chain | get_memory_guidance   │
│  bulk_archive | get_archive_stats           │
├─────────────────────────────────────────────┤
│            StoreAdapter Interface            │
├──────────────────┬──────────────────────────┤
│   SQLiteStore    │      CloudStore          │
│   FTS5 + WAL     │      @brain-protocol/sdk │
│   Graph CTE      │      Retry + Circuit Brk │
│   Schema v2      │      On-chain proof      │
└──────────────────┴──────────────────────────┘

Programmatic Use

import { SQLiteStore, CloudStore, createMCPServer } from "@brain-protocol/mcp";

// Local mode
const store = new SQLiteStore("/path/to/brain.db");
await store.initialize();

// Cloud mode with resilience config
const cloud = new CloudStore("https://brain.api.vauban.tech", "api-key", {
  retry: { maxAttempts: 4, baseDelayMs: 500 },
  circuitBreaker: { failureThreshold: 5, cooldownMs: 30_000 },
});
await cloud.initialize();

// Use directly
const entry = await store.create({ content: "Hello brain" });
const results = await store.query({ q: "hello" });

// Or as MCP server
const server = createMCPServer(store);

License

MIT