Skip to content

MindRoom

AI agents that live in Matrix and work everywhere via bridges.

What is MindRoom?

MindRoom is an AI agent orchestration system with Matrix integration. It provides:

  • Multi-agent collaboration - Configure multiple specialized agents that can work together
  • Matrix-native - Agents live in Matrix rooms and respond to messages
  • Persistent memory - Agent and team-scoped memory that persists across conversations
  • 100+ tool integrations - Connect to external services like GitHub, Slack, Gmail, and more
  • Hot-reload configuration - Update config.yaml and agents restart automatically
  • Scheduled tasks - Schedule agents to run at specific times with cron expressions or natural language
  • Voice messages - Speech-to-text transcription with intelligent command recognition
  • Image analysis - Pass images to vision-capable AI models for analysis
  • Authorization - Fine-grained access control for users and rooms

Tip

Matrix is the backbone - MindRoom agents communicate through the Matrix protocol, which means they can be bridged to Discord, Slack, Telegram, and other platforms.

Quick Start

Prereqs: Docker + Docker Compose.

git clone https://github.com/mindroom-ai/mindroom-stack
cd mindroom-stack
cp .env.example .env
$EDITOR .env  # add at least one AI provider key

docker compose up -d

Open:

  • MindRoom UI: http://localhost:8765
  • MindRoom client: http://localhost:8080
  • Matrix homeserver: http://localhost:8008

The stack uses published mindroom, mindroom-cinny, and mindroom-tuwunel images by default.

If you access the stack from another device, set CLIENT_HOMESERVER_URL=http://<host-ip>:8008 in .env before starting it.

Manual Install (advanced)

Use this if you already have a Matrix homeserver and want to run MindRoom directly.

# Using uv
uv tool install mindroom

# Or using pip
pip install mindroom

Basic Usage (manual)

  1. Create a config.yaml:
agents:
  assistant:
    display_name: Assistant
    role: A helpful AI assistant
    model: default
    rooms: [lobby]

models:
  default:
    provider: openai
    id: gpt-5.4

defaults:
  tools: [scheduler]
  markdown: true
  1. Set up your environment in .env:
# Matrix homeserver (must allow open registration)
MATRIX_HOMESERVER=https://matrix.example.com

# AI provider API keys
OPENAI_API_KEY=your_api_key
  1. Run MindRoom:
mindroom run

For local development with a host-installed backend plus Dockerized Synapse + Cinny (Linux/macOS), you can bootstrap the local stack with:

mindroom local-stack-setup --synapse-dir /path/to/mindroom-stack/local/matrix
mindroom run

Features

Feature Description
Agents Single-specialty actors with specific tools and instructions
Teams Collaborative bundles of agents (coordinate or collaborate modes)
Router Built-in traffic director that routes messages to the right agent
Memory Mem0-inspired memory system with agent and team scopes
Knowledge Bases File-backed RAG indexing with per-agent base assignment
Tools 100+ integrations for external services
Skills OpenClaw-compatible skills system for extended agent capabilities
Scheduling Schedule tasks with cron expressions or natural language
Voice Speech-to-text transcription for voice messages
Images Pass user-sent images to vision-capable AI models
File & Video Attachments Context-scoped file and video handling with attachment IDs
Cultures Shared evolving principles across groups of agents
Interactive Q&A Clickable multiple-choice questions via Matrix reactions
Authorization Fine-grained user and room access control
OpenAI-Compatible API Use agents from LibreChat, Open WebUI, or any OpenAI client
Streaming Progressive message edits with presence-based gating and tool-call markers
Chat Commands Built-in !help, !schedule, !config, !skill commands handled by the router
Hot Reload Config changes are detected and agents restart automatically

Architecture

┌─────────────────────────────────────────────────────┐
│                 Matrix Homeserver                    │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│              MultiAgentOrchestrator                  │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │ Router  │ │ Agent 1 │ │ Agent 2 │ │  Team   │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
└─────────────────────────────────────────────────────┘

Documentation

License

  • Repository (except saas-platform/): Apache License 2.0
  • SaaS Platform (saas-platform/): Business Source License 1.1 (converts to Apache 2.0 on 2030-02-06)