BrainDB

Local-first AI Memory & Multi-Agent Orchestrator

BrainDB is a persistent memory system for AI agents. It provides structured knowledge storage, hybrid search (FTS5 + embeddings), contradiction detection, multi-agent coordination, and a nightly self-learning pipeline -- all backed by a single SQLite database.

An open-source project.

---

Key Features

• 3-Layer Memory System -- Raw memories, indexed summaries, and entity graph
• Full-Text Search (FTS5) -- Sub-millisecond search with relevance scoring and type-aware ranking
• Contradiction Detection -- Automatic detection of conflicting facts across memories
• Multi-Agent Orchestration -- Signal protocol, heartbeats, claims, and round-based discussions
• Inception Knowledge -- Nightly self-learning: validates memories against web sources (SearXNG)
• Knowledge Graph -- Entity extraction, relation tracking, and graph queries
• MCP Server -- 51 tools for Claude, Cursor, and other MCP-compatible clients
• REST API -- 107 endpoints grouped by domain (core, search, agents, graph, coordination)
• Decision Memory -- Authoritative decisions that supersede conflicting older memories
• Anti-Hallucination -- Confidence scores, staleness warnings, and temporal fact tracking
• GPU Wake-on-LAN -- Automatically wake GPU machines for local LLM inference
• Auto-Backup -- Scheduled SQLite backups with rotation

Quick Start

Docker (recommended)

# Clone the repo
git clone https://github.com/your-org/braindb.git
cd braindb

# Configure
cp .env.example .env
# Edit .env with your settings (at minimum: MISTRAL_API_KEY for LLM features)

# Start
docker compose up -d

# Verify
curl http://localhost:3197/health

Bare Metal (Bun)

# Prerequisites: Bun >= 1.0 or Node.js >= 22
bun install
cp .env.example .env

# Start the API server
bun run start

# Or run the MCP server (stdio)
bun run mcp

Architecture

                    +------------------+
                    |   MCP Clients    |
                    | (Claude, Cursor) |
                    +--------+---------+
                             |  stdio
                    +--------v---------+
                    |  MCP Thin-Client |
                    |  (mcp-client.ts) |
                    +--------+---------+
                             |  HTTP
+----------+        +--------v---------+        +-----------+
|  Agents  | <----> |    BrainDB API   | <----> |  Ollama   |
| (Mistral,|  HTTP  |    (api.ts)      |  HTTP  | (Local    |
|  Cortex, |        |  107 endpoints   |        |  LLM)     |
|  Custom) |        +--------+---------+        +-----------+
+----------+                 |
                    +--------v---------+        +-----------+
                    |     SQLite       | <----> |  SearXNG  |
                    |  (FTS5 + WAL)    |  HTTP  | (Search)  |
                    +------------------+        +-----------+

Comparison

Feature	BrainDB	LangChain Memory	Mem0	MemPalace
Local-first (SQLite)	Yes	No (Redis/Postgres)	No (Cloud)	Yes
Full-text search	FTS5	Vector only	Vector only	Basic
Contradiction detection	Yes	No	No	No
Multi-agent orchestration	Yes	No	No	No
Self-learning (Inception)	Yes	No	No	No
Knowledge graph	Yes	No	Partial	No
MCP support	51 tools	No	No	No
Decision memory	Yes	No	No	No
Zero external deps	Yes	Many	Cloud	Yes

API Overview

Core Memory

Method	Endpoint	Description
POST	/remember	Store or update a memory
POST	/recall	Search memories (FTS5 + relevance)
POST	/forget	Soft/hard delete
POST	/context	Session context (project, feedback, issues)
POST	/smart-context	CWD/Git-aware context loading
GET	/stats	Memory statistics
GET	/memories	List (paginated)
GET	/health	Health check

Knowledge Graph

Method	Endpoint	Description
POST	/link	Create relation between memories
GET	/graph	Full relation graph
POST	/entities/extract	Extract entities from text
GET	/entities	List/search entities

Multi-Agent

Method	Endpoint	Description
POST	/agents/heartbeat	Agent heartbeat
GET	/agents/health	All agents status
POST	/claim	Claim a task
POST	/coordinate	Create coordination task
POST	/signal	Agent-to-agent messaging

Inception (Self-Learning)

Method	Endpoint	Description
POST	/inception/run	Start knowledge enrichment
GET	/inception/status	Last run status
GET	/inception/findings	Browse findings

Decisions

Method	Endpoint	Description
POST	/decide	Create authoritative decision
GET	/contradictions	List contradictions
POST	/contradictions/verify	LLM-verify a contradiction

MCP Tools

BrainDB exposes 51 MCP tools for AI assistants:

• braindb_remember / braindb_recall / braindb_forget -- Core CRUD
• braindb_context / braindb_smart_context -- Session context
• braindb_decide / braindb_contradictions -- Decision management
• braindb_link / braindb_graph -- Knowledge graph
• braindb_claim / braindb_coordinate -- Multi-agent coordination
• braindb_handover / braindb_handovers -- Agent handoffs
• braindb_inception -- Trigger knowledge enrichment
• braindb_ask -- RAG-powered Q&A
• braindb_stats / braindb_export / braindb_backup -- Operations

Configure in your MCP client:

{
  "braindb": {
    "command": "npx",
    "args": ["tsx", "src/mcp-client.ts"],
    "env": {
      "BRAINDB_URL": "http://localhost:3197"
    }
  }
}

Configuration

See .env.example for all available environment variables.

Security

BrainDB is designed for local/trusted network deployment. Before exposing it to untrusted networks:

Authentication (required for production)

# Set in .env — all endpoints except /health require Bearer token
BRAINDB_API_KEY=your-secret-key-here

Without BRAINDB_API_KEY, the API is completely open. The server logs a warning at startup.

Webhook Authentication

# Required for /webhook/:source endpoint
WEBHOOK_SECRET=your-webhook-secret

Webhooks are disabled unless WEBHOOK_SECRET is configured.

CORS

# Restrict to specific origins (comma-separated)
CORS_ORIGINS=http://localhost:3000,https://brain.example.com

Without CORS_ORIGINS, only same-origin requests are allowed.

Reporting Vulnerabilities

Please report security issues privately via GitHub Security Advisories — not in public issues. See CONTRIBUTING.md.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

AGPL-3.0