@brain-protocol/mcp

@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