BrainBrainBrains (BBB) — MCP Server

How to use

You install BBB MCP Server and run it as an MCP endpoint that your AI coding tools can connect to. Once connected, you can store memories (decisions, conventions, constraints), artifacts (ADR, API contracts, PRDs), tasks, and codebase context. BBB automatically assembles relevant context for your current task, searches memories with full-text relevance, and lets you snapshot or rehydrate sessions across different tools. Use it to keep your project’s knowledge base synchronized across your entire development workflow.

How to install

Prerequisites: ensure you have Node.js and npm installed on your machine. You can verify by running node -v and npm -v in your terminal.

Option 1: run BBB MCP Server directly with npx (recommended) by starting a project. This runs the server without any local setup beyond having Node and npm.

Option 2: configure a client to start BBB from your MCP settings. See the Quick Start steps for common editors.

npx bbb-mcp-server --project my-project

Configuration and quick start details

BBB runs locally and stores all data in a SQLite database under your home directory, keeping data private to your machine.

To use BBB from a compatible MCP client, add an MCP server configuration that points to the BBB executable. The simplest form uses npx to launch the server for your project.

{
  "mcpServers": {
    "bbb": {
      "command": "npx",
      "args": ["bbb-mcp-server", "--project", "my-project"]
    }
  }
}

Usage with MCP clients

Attach BBB to your MCP client following your editor’s standard MCP configuration flow. You can start BBB in a dedicated project folder and then connect your editor or IDE to that local endpoint. There are no API keys or cloud accounts required; everything runs locally on your device.

Tools available through BBB

BBB exposes a suite of tools to manage memories, artifacts, tasks, and context.

Examples of creating and querying data

# Start a project (server side action)
# This step is shown for illustration; actual start is via the MCP client connection
# The server stores data in ~/.bbb/data/my-project.db

# Create a memory entry
memory_store {
  category: "decision",
  title: "Use PostgreSQL for primary database",
  content: "Chose PostgreSQL over MySQL for JSONB support and full-text search.",
  tags: ["database", "infrastructure"]
}

# Create an artifact entry
artifact_store {
  type: "adr",
  title: "ADR-001: Event-driven architecture",
  content: "## Context\nWe need async processing...",
  tags: ["architecture"]
}

Notes and troubleshooting

If you encounter issues connecting with a client, ensure the BBB MCP Server process is running and the client is configured to point to the correct local endpoint. There are no external services or accounts required. If you change the project name, the underlying SQLite database location will be ~/.bbb/data/<project>.db.

Architecture

BBB consists of a common core and a dedicated MCP server that exposes 17 tools for memories, artifacts, tasks, and context management. It stores data locally using SQLite with full-text search for rapid context assembly.

memory_store

Store a new memory such as a decision, convention, constraint, or other project knowledge.

memory_query

Search memories by full-text query with optional filters to surface relevant context.

memory_list

List memories with pagination and filtering to browse past decisions and notes.

memory_update

Update an existing memory and create a new version that supersedes the previous one.

memory_delete

Delete a memory by its ID from the local store.

artifact_store

Store a structured artifact such as ADRs, PRDs, API contracts, or design docs.

artifact_get

Retrieve an artifact by ID or search by type/title.

artifact_list

List artifacts with optional filters to understand project decisions and specifications.

task_create

Create a task with dependencies and acceptance criteria for structured progress tracking.

task_update

Update a task's status or fields to reflect current progress.

task_get_dag

Get all tasks as a dependency graph to visualize work relationships.

context_assemble

Assemble relevant context for a development task by combining memories, artifacts, and codebase context.

project_init

Initialize BBB for a new project and prepare local storage.

ingest_codebase

Auto-ingest context from a repository directory by indexing READMEs, docs, and source files.

session_snapshot

Capture the full session state for later rehydration in another tool.

session_rehydrate

Restore a previously captured session snapshot into a target tool.

search_memories

Perform full-text search across all memories to locate relevant decisions and notes.