Package Exports

@brain-protocol/mcp
@brain-protocol/mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@brain-protocol/mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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

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
`prove`	Anchor entry on Starknet (cloud mode)
`verify`	Verify on-chain proof (cloud mode)
`get_agent_stats`	Agent performance statistics (cloud mode)
`log_agent_task`	Record an agent task execution (cloud mode)
`suggest_patterns`	AI-powered code pattern suggestions (cloud mode)
`detect_antipatterns`	Detect anti-patterns in code (cloud mode)
`architectural_advice`	Get architectural guidance (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.3.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

Architecture

┌─────────────────────────────────────────────┐
│              MCP Protocol (stdio)            │
├─────────────────────────────────────────────┤
│              16 Tool Handlers               │
│  query | archive | update | delete | edge   │
│  graph | stats | export | import | prove    │
│  verify | agent_stats | log_task            │
│  suggest_patterns | detect_antipatterns     │
│  architectural_advice                       │
├─────────────────────────────────────────────┤
│            StoreAdapter Interface            │
├──────────────────┬──────────────────────────┤
│   SQLiteStore    │      CloudStore          │
│   FTS5 + WAL     │      @brain-protocol/sdk │
│   Graph CTE      │      HTTP + API Key      │
│   Schema v2      │      On-chain proof      │
└──────────────────┴──────────────────────────┘

Programmatic Use

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

const store = new SQLiteStore("/path/to/brain.db");
await store.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