@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

| Tool | Description | Mode | |------|-------------|------| | query_knowledge | Full-text search with category, author, tag, confidence, date filters | all | | archive_knowledge | Store a new knowledge entry | all | | update_knowledge | Partial update of an existing entry | all | | delete_knowledge | Remove an entry by ID | all | | get_memory_guidance | RAE: retrieve relevant past decisions before acting | all | | create_edge | Create a typed relationship between entries | all | | get_graph | Traverse the knowledge graph from any entry | all | | search_with_context | Graph-enriched search with trust scores (rrf/hybrid/hyde modes) | cloud only | | suggest_connections | Embedding-similarity edge suggestions for an entry | cloud only |

OpenMemory Compatibility (drop-in replacement)

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

| Tool | Description | Mode | |------|-------------|------| | add_memories | Store a memory with optional client_app tracking | all | | search_memory | Search memories, optionally filtered by client_app | all | | list_memories | List recent memories with pagination and client_app filter | all | | delete_all_memories | Delete all memories (requires confirm: true) | all | | get_memory_status | Stats + optional did:starknet identity binding | all |

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

| Tool | Description | Mode | |------|-------------|------| | prove | Anchor entry hash on Starknet L3 | cloud only | | verify | Verify on-chain proof for an entry | cloud only | | archive_giza_proof | Archive a Giza zkML proof as verified knowledge | all | | query_giza_proofs | Query archived proofs with model/verification filters | all | | link_proof_to_entry | Link a proof to a knowledge entry via typed edge | all |

Agent Intelligence (cloud mode)

| Tool | Description | |------|-------------| | get_agent_stats | Agent performance statistics | | log_agent_task | Record an agent task execution | | suggest_patterns | AI-powered code pattern suggestions | | detect_antipatterns | Detect anti-patterns in code | | architectural_advice | Get architectural guidance |

Usage & Billing (cloud mode)

| Tool | Description | |------|-------------| | get_usage | API usage statistics for your account (requests, latency, endpoints) |

Giza zkML Proofs (Trust Triangle)

| Tool | Description | |------|-------------| | archive_giza_proof | Archive a Giza zkML proof as verified knowledge | | query_giza_proofs | Query archived proofs with model/verification filters | | link_proof_to_entry | Link a proof to a knowledge entry via typed edge |

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

| Tool | Description | |------|-------------| | record_decision | Record a structured decision with context, options, rationale, and chain linking | | get_decision_chain | Traverse the decision graph from a starting decision | | get_memory_guidance | Get relevant past decisions and patterns before acting (RAE) |

Brain Sync (hybrid mode)

| Tool | Description | |------|-------------| | sync_status | Current sync state: pending uploads, conflicts, cumulative stats | | trigger_sync | Force an immediate sync cycle | | resolve_conflict | Resolve a sync conflict (keep_local, keep_cloud, keep_both) |

Consciousness & Health

| Tool | Description | |------|-------------| | consciousness_score | 5D consciousness metrics (knowledge, recall, growth, coherence, verification) | | get_consciousness_trend | Historical consciousness trend with anomaly detection |

Knowledge Curation (cloud mode)

| Tool | Description | |------|-------------| | bulk_archive | Archive multiple entries by filters (category, date, author, confidence) with dry_run preview | | get_archive_stats | Archive statistics: count by reason, category, and total |

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

| Variable | Default | Description | |----------|---------|-------------| | BRAIN_API_URL | (unset = local mode) | Cloud API URL. When set, uses HTTP instead of SQLite | | BRAIN_API_KEY | (unset) | API key for cloud authentication (sent as X-API-Key header) | | BRAIN_DB_PATH | XDG default | Custom path for the SQLite database file |

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