BrainBrainBrains (BBB) — MCP Server

Persistent memory + context layer for AI-assisted dev teams, exposed via MCP.

17 free tools. Local-first. Zero config. MIT licensed.

What It Does

BBB gives your AI coding tools persistent project memory. Store decisions, conventions, architecture patterns, and business rules once — access them from any IDE, any AI tool, any time.

• Persistent Memory — Decisions, conventions, and constraints survive across sessions
• Intelligent Context Assembly — BM25 full-text search surfaces only relevant context
• Session Portability — Move between Claude Desktop, Claude Code, Cursor, Codex, Windsurf, and VS Code without losing context
• Local-First — All data stays on your machine. SQLite + FTS5. No cloud. No account.
• Codebase Ingestion — Index your READMEs, architecture docs, and API contracts directly into memory

Quick Start

Option 1: npx (recommended)

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

Option 2: Add to your MCP client config

Claude Desktop / Claude Code:

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

Cursor: Add to your MCP settings in Cursor preferences.

VS Code (Copilot): Add to .mcp.json in your project root.

Windsurf: Configure via mcp_config.json or the built-in MCP Marketplace.

That's it. No API keys. No cloud account. No configuration.

Tools (17)

| Tool | Description | |------|-------------| | memory_store | Store a new memory (decision, convention, constraint, etc.) | | memory_query | Search memories by full-text search with optional filters | | memory_list | List memories with pagination and filtering | | memory_update | Update an existing memory (creates new version) | | memory_delete | Delete a memory by ID | | artifact_store | Store a structured artifact (ADR, PRD, API contract, etc.) | | artifact_get | Retrieve an artifact by ID or search by type/title | | artifact_list | List artifacts with optional filters | | task_create | Create a task with dependencies and acceptance criteria | | task_update | Update a task's status or fields | | task_get_dag | Get all tasks as a dependency graph | | context_assemble | Assemble relevant context for a development task | | project_init | Initialize BBB for a new project | | ingest_codebase | Auto-ingest context from a repository directory | | session_snapshot | Capture session state for later rehydration | | session_rehydrate | Restore a session snapshot | | search_memories | Full-text search across all memories |

Usage Guide

1. Initialize Your Project

> project_init({ name: "my-saas-app", description: "B2B SaaS platform" })
← { id: "abc-123", slug: "my-saas-app", status: "created" }

This creates a SQLite database at ~/.bbb/data/my-saas-app.db. All memories, artifacts, and tasks are stored locally.

2. Store Decisions and Conventions

As you make decisions during development, store them so they persist across sessions:

> memory_store({
    category: "decision",
    title: "Use PostgreSQL for primary database",
    content: "Chose PostgreSQL over MySQL for JSONB support and full-text search. Evaluated both during sprint 3.",
    tags: ["database", "infrastructure"]
  })
← { id: "mem-1", version: 1 }

> memory_store({
    category: "convention",
    title: "API response format",
    content: "All API responses use { data, error, meta } envelope. Errors include code and message fields.",
    tags: ["api", "backend"]
  })

> memory_store({
    category: "constraint",
    title: "No external auth providers",
    content: "Client requires all auth to be self-hosted. No OAuth with Google/GitHub. JWT + refresh tokens only.",
    tags: ["auth", "security", "client-requirement"]
  })

Categories: decision, convention, constraint, architecture, lessons-learned, history

3. Store Artifacts

Store structured documents like ADRs, API contracts, and PRDs:

> artifact_store({
    type: "adr",
    title: "ADR-001: Event-driven architecture",
    content: "## Context\nWe need async processing for...\n## Decision\nWe will use an event bus...",
    tags: ["architecture", "events"]
  })
← { id: "art-1", version: 1, hash: "a1b2c3...", action: "created" }

> artifact_store({
    type: "api_contract",
    title: "Users API v2",
    content: "## Endpoints\n### POST /api/v2/users\n...",
    tags: ["api", "users"]
  })

Types: prd, adr, api_contract, design_doc, runbook, test_plan, user_story, component_spec, release_notes, other

4. Index Your Codebase

Pull context from your existing repository files:

> ingest_codebase({
    path: "./src",
    file_types: [".ts", ".tsx", ".md"],
    exclude: ["node_modules", "dist", "*.test.ts"]
  })
← { files_scanned: 142, files_indexed: 87, chunks_created: 340, total_tokens: 52000 }

This indexes READMEs, architecture docs, and source files into searchable chunks. Files over 1MB and binary files are automatically skipped.

5. Assemble Context for a Task

This is where BBB shines. When you start working on something, assemble all the relevant context:

> context_assemble({ task: "Implement the user authentication middleware" })
← {
    context: "## Relevant Decisions\n- JWT + refresh tokens only (no OAuth)...\n## Conventions\n- API response format: { data, error, meta }...\n## Architecture\n- Event-driven architecture (ADR-001)...",
    stats: {
      memories_included: 8,
      artifacts_included: 3,
      total_tokens: 4200,
      budget_used_percent: 5.25
    }
  }

BBB automatically:

• Extracts keywords from your task description
• Searches memories and indexed codebase via BM25
• Always includes conventions and constraints
• Scores results by relevance, recency, and tag overlap
• Stays within token budget (default 80k, configurable)

> context_assemble({ task: "Add rate limiting to the API", max_tokens: 40000, categories: ["decision", "constraint"] })

6. Search and Query

Find specific memories when you need them:

> memory_query({ query: "database", tags: ["infrastructure"] })
← [{ id: "mem-1", title: "Use PostgreSQL...", rank: 1.23 }, ...]

> search_memories({ query: "authentication", category: "decision", limit: 5 })
← [{ id: "mem-3", title: "No external auth providers", score: 2.1 }, ...]

> artifact_get({ type: "api_contract", title_search: "Users" })
← [{ id: "art-2", title: "Users API v2", ... }]

7. Track Tasks

Create tasks with dependencies for structured development:

> task_create({
    title: "Design auth middleware",
    description: "Create JWT validation middleware with refresh token rotation",
    status: "in-progress",
    owner_role: "backend",
    acceptance_criteria: ["Validates JWT signatures", "Handles expired tokens", "Rotates refresh tokens"],
    linked_artifacts: ["art-1"]
  })
← { id: "task-1", status: "in-progress" }

> task_create({
    title: "Add rate limiting",
    dependencies: ["task-1"],
    owner_role: "backend"
  })
← { id: "task-2", status: "pending" }

> task_get_dag()
← [{ id: "task-1", title: "Design auth middleware", status: "in-progress", dependencies: [] },
    { id: "task-2", title: "Add rate limiting", status: "pending", dependencies: ["task-1"] }]

8. Update Memories Over Time

When decisions evolve, update creates a new version and supersedes the old one:

> memory_update({
    memory_id: "mem-1",
    content: "Migrated from PostgreSQL to CockroachDB for multi-region support. Original decision was PostgreSQL (sprint 3), changed in sprint 12.",
    tags: ["database", "infrastructure", "migration"]
  })
← { id: "mem-1-v2", version: 2, supersedes: "mem-1" }

Old versions are preserved for history. Queries and context assembly automatically use the latest version.

9. Snapshot and Move Between Tools

Save your full session state and restore it in a different IDE:

> session_snapshot({ label: "end-of-sprint-5" })
← { id: "snap-abc", label: "end-of-sprint-5", memories_count: 34, artifacts_count: 12, size_mb: "2.1" }

# Later, in a different tool:
> session_rehydrate({ snapshot_id: "snap-abc", target_tool: "cursor" })
← { memories_restored: 34, artifacts_restored: 12, config_content: "{ ... }" }

Supported targets: claude-desktop, claude-code, cursor, vscode, generic

Typical Workflow

# Day 1: Set up your project
project_init → ingest_codebase → store initial decisions and conventions

# Every session: Get context automatically
context_assemble({ task: "whatever you're working on" })

# As you go: Capture new decisions
memory_store → artifact_store → task_create

# When switching tools: Snapshot and rehydrate
session_snapshot → session_rehydrate

Architecture

packages/
├── bbb-common/    @bbb/common  — Shared types, DB layer, utilities (0 tools)
└── bbb-core/      bbb-mcp-server — 17 MCP tools + CLI entry point

• Database: SQLite + FTS5, stored at ~/.bbb/data/<project>.db
• Transport: MCP stdio
• Search: BM25 ranking, zero external dependencies
• Token budgeting: Context assembly respects configurable token limits (default 80k)

Client Compatibility

Works with every major AI coding tool that supports MCP:

• Claude Desktop
• Claude Code
• Cursor
• Windsurf
• VS Code (GitHub Copilot)
• Codex CLI / Codex App
• Qoder
• Opencode
• Replit

Framework agnostic — works with any codebase language.

Development

npm install          # Install all workspace dependencies
npm run build        # Compile TypeScript (all packages)
npm test             # Run all tests

Project Structure

├── packages/
│   ├── bbb-common/src/       # Shared infrastructure
│   │   ├── db/               # SQLite connection + migrations (v1-v4)
│   │   ├── utils/            # Audit, hash, JSON, tokens, templates, schemas
│   │   ├── hooks/            # ContextScoringHook interface
│   │   └── types/            # Enums (MemoryCategory, ArtifactType, TaskStatus)
│   └── bbb-core/src/         # MCP server
│       ├── handlers/         # Memory, artifact, task, context, project, session
│       ├── tools/            # Optional extension integration points
│       ├── server.ts         # createServer() factory
│       ├── config.ts         # Configuration
│       └── index.ts          # CLI entry point
├── package.json              # Workspace root
└── tsconfig.base.json        # Shared TypeScript config

Extensions

This repository contains the open-source core toolset. Optional extensions are distributed separately.

License

MIT — see LICENSE