@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:

{
  "brain": {
    "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"]
    }
  }
}

Cloud Mode Configuration

For any IDE, add environment variables to connect to a Brain Protocol API server:

{
  "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)

Knowledge Management

| Tool | Description | |------|-------------| | query_knowledge | Full-text search with category, author, tag, brain_id filters | | archive_knowledge | Store a new knowledge entry | | update_knowledge | Partial update of an existing entry | | delete_knowledge | Remove an entry by ID | | create_edge | Create a typed relationship between entries | | get_graph | Traverse the knowledge graph from any entry | | get_stats | Knowledge base statistics | | export | Export all entries and edges as JSON | | import | Import entries and edges from a JSON export |

Verification & Proof

| Tool | Description | |------|-------------| | prove | Anchor entry hash on Starknet L3 (cloud mode) | | verify | Verify on-chain proof for an entry (cloud mode) |

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) |

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.4.1
# 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)            │
├─────────────────────────────────────────────┤
│              25 Tool Handlers               │
│  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