# mindroom

[![PyPI](https://img.shields.io/pypi/v/mindroom)](https://pypi.org/project/mindroom/)
[![Python](https://img.shields.io/pypi/pyversions/mindroom)](https://pypi.org/project/mindroom/)
[![Tests](https://img.shields.io/github/actions/workflow/status/mindroom-ai/mindroom/pytest.yml?label=tests)](https://github.com/mindroom-ai/mindroom/actions/workflows/pytest.yml)
[![Build](https://img.shields.io/github/actions/workflow/status/mindroom-ai/mindroom/build-mindroom.yml?label=build)](https://github.com/mindroom-ai/mindroom/actions/workflows/build-mindroom.yml)
[![Docs](https://img.shields.io/badge/docs-mindroom.chat-blue)](https://docs.mindroom.chat)
[![License](https://img.shields.io/github/license/mindroom-ai/mindroom)](https://github.com/mindroom-ai/mindroom/blob/main/LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/mindroom)](https://pypi.org/project/mindroom/)
[![GitHub](https://img.shields.io/badge/github-mindroom--ai%2Fmindroom-blue?logo=github)](https://github.com/mindroom-ai/mindroom)

<img src="frontend/public/logo.png" alt="MindRoom Logo" align="right" width="150" />

**Your AI is trapped in apps. We set it free.**

AI agents that learn who you are shouldn't forget everything when you switch apps. MindRoom agents follow you everywhere—Slack, Telegram, Discord, WhatsApp—with persistent memory intact.

Deploy once on Matrix. Your agents now work in any chat platform via bridges. They can even visit your client's workspace or join your friend's group chat.

Self-host for complete control or use our encrypted service. Either way, your agents remember you and can collaborate across organizations.

https://github.com/user-attachments/assets/1f121c89-5418-4f42-bdfe-fb9de0fecd03

## The Problem

Every AI app is a prison:
- ChatGPT knows your coding style... but can't join your team's Slack
- Claude understands your writing... but can't access your email
- GitHub Copilot helps with code... but can't see your project specs
- You teach each AI from scratch, over and over

Meanwhile, your human team collaborates across Slack, Discord, Telegram, and email daily. Why can't your AI?

## The Solution

MindRoom agents:
- **Live in Matrix** - A federated protocol like email
- **Work everywhere** - Via bridges to Slack, Telegram, Discord, WhatsApp, IRC, email
- **Remember everything** - Persistent memory across all platforms
- **Collaborate naturally** - Multiple agents working together in threads
- **Respect boundaries** - You control which agent sees what data

## Built on Proven Infrastructure

MindRoom leverages the Matrix protocol, a decade-old open standard with significant real-world adoption:

**Foundation**
- **10+ years** of development by the Matrix.org Foundation
- **€10M+** invested in protocol development
- **100+ developers** contributing to the core ecosystem
- **35+ million users** globally

**Enterprise Validation**
- **German Healthcare**: 150,000+ organizations using Ti-Messenger
- **French Government**: 5.5 million civil servants on Tchap
- **Military Adoption**: NATO, U.S. Space Force, and other defense organizations
- **GDPR Compliant**: Built for European privacy standards

**What This Means For You**

By building on Matrix, MindRoom inherits:
- Production-tested federation across organizations
- Military-grade E2E encryption (Olm/Megolm)
- Professional clients (Element, FluffyChat, Cinny)
- 50+ maintained bridges to other platforms
- Proven scale and reliability

This foundation allows MindRoom to focus entirely on agent orchestration and intelligence, rather than reimplementing communication infrastructure.

## See It In Action

```
Monday, in your Matrix room:
You: @assistant Remember our project uses Python 3.11 and FastAPI

Tuesday, in your team's Slack (via bridge):
Colleague: What Python version are we using?
You: @assistant can you help?
Assistant: [Joins from Matrix] We're using Python 3.11 with FastAPI

Wednesday, in client's Telegram (via bridge):
Client: Can your AI review our API spec?
You: @assistant please analyze this
Assistant: [Travels from your server] I'll review this against our FastAPI patterns...
```

One agent. Every platform. Continuous memory.

## The Magic Moment - Cross-Organization Collaboration

```
Thursday, your client asks in their Discord:
Client: Can our architect AI review this with your team?
You: Sure! @assistant please collaborate with them

Your Assistant: [Joins from your Matrix server]
Client's Architect AI: [Joins from their server]
Together: [They review architecture, sharing context from both organizations]
```

**Two AI agents from different companies collaborating.**
This is impossible with ChatGPT, Claude, or any other platform.

## But It Gets Better - Your Agents Work as a Team

```
Friday, planning next sprint:
You: @research @analyst @writer Create a competitive analysis report
Research: I'll gather data on our top 5 competitors...
Analyst: I'll identify strategic patterns and opportunities...
Writer: I'll compile everything into an executive summary...
[They work together, transparently, delivering a comprehensive report]
```

## Key Features

### 🧠 Dual Memory System
- **Agent Memory**: Each agent remembers conversations, preferences, and patterns across all platforms
- **Room Memory**: Contextual knowledge that stays within specific rooms (work projects, personal notes)

### 🤝 Multi-Agent Collaboration
```
You: @research @analyst @email Create weekly competitor analysis reports
Research: I'll gather competitor updates
Analyst: I'll identify strategic patterns
Email: I'll compile and send every Friday
[They work together, automatically, every week]
```

### 💬 Direct Messages (DMs)
- Agents respond naturally in 1:1 DMs without needing mentions
- Add more agents to existing DM rooms for collaborative private work
- Complete privacy separate from configured public rooms

### 🔐 Intelligent Trust Boundaries
- Route sensitive data to local Ollama models on your hardware
- Use GPT-5.2 for complex reasoning
- Send general queries to cost-effective cloud models
- You decide which AI sees what

### 🔌 100+ Integrations
Gmail, GitHub, Spotify, Home Assistant, Google Drive, Reddit, weather services, news APIs, financial data, and many more. Your agents can interact with all your tools.
Native Matrix tools include `matrix_message`, `matrix_room`, `thread_tags`, and `matrix_api` for room, thread, event, state, and room-search operations.

### 📅 Automation & Scheduling
- Daily check-ins from your mindfulness agent
- Scheduled reports and summaries
- Event-driven workflows (conditional requests converted to polling schedules)
- Background tasks with human escalation

## Who This Is For

- **Teams using Matrix/Element** - Add AI to your existing secure infrastructure without migration
- **Open Source Projects** - Agents that remember all decisions and can visit contributor chats
- **Consultants & Agencies** - Your AI can securely join client workspaces
- **Privacy-Focused Organizations** - Self-host everything, own your data completely
- **Developers** - Build on our platform, contribute agents, extend functionality

## Quick Start

### Prerequisites
- Python 3.12+
- [uv](https://github.com/astral-sh/uv) for Python package management
- Node.js 20+ and [bun](https://bun.sh/) (optional, for web UI)

### Fastest Path: Hosted Matrix + Local MindRoom (`uvx` only)

Use this path if you want to run MindRoom locally while using hosted chat + Matrix on `mindroom.chat`.

```bash
# Create ~/.mindroom/config.yaml and ~/.mindroom/.env with hosted defaults
uvx mindroom config init --profile public

# Add model auth, or use `--profile public-codex` and run `codex login`
$EDITOR ~/.mindroom/.env

# Generate pair code in https://chat.mindroom.chat:
# Settings -> Local MindRoom -> Generate Pair Code
uvx mindroom connect --pair-code ABCD-EFGH

# Start MindRoom
uvx mindroom run
```

See [Hosted Matrix deployment guide](docs/deployment/hosted-matrix.md) for full details.

### Installation and starting

```bash
# Clone and install
git clone https://github.com/mindroom-ai/mindroom
cd mindroom
uv sync
```

MindRoom auto-installs the fully local sentence-transformers embedder runtime on first use when `memory.embedder.provider: sentence_transformers` is configured.
Matrix E2EE support is installed by default.

```bash
# Start MindRoom (agents + API + web dashboard)
uv run mindroom run
```

The web interface will be available at http://localhost:8765
When running from a source checkout, MindRoom will build the dashboard assets on first start if Bun is available.

### First Steps

In any Matrix client (Element, FluffyChat, etc):
```
You: @mindroom_assistant What can you do?
Assistant: I can coordinate our team of specialized agents...

You: @mindroom_research @mindroom_analyst What are the latest AI breakthroughs?
[Agents collaborate to research and analyze]
```

## How Agents Work

### Agent Response Rules
Agents respond using Matrix thread relations to keep conversations organized.
If your client or bridge only sends plain replies, MindRoom keeps them in an existing thread when the reply chain eventually reaches a threaded ancestor or proven thread root.
Plain replies that never reach threaded context still stay plain replies.

1. **Mentioned agents always respond** - Tag them to get their attention
2. **Single agent continues** - One agent in thread? It keeps responding
3. **Multiple agents collaborate** - They work together, not compete
4. **Smart routing** - System picks the best agent for new threads

### Available Commands

<!-- CODE:START -->
<!-- import sys -->
<!-- sys.path.insert(0, 'src') -->
<!-- from mindroom.commands.parsing import _get_command_entries -->
<!-- for entry in _get_command_entries(format_code=True): -->
<!--     print(entry) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
- `!help [topic]` - Get help
- `!reload-plugins` - Reload configured plugins (admin only)
- `!schedule <task>` - Schedule a task
- `!list_schedules` - List scheduled tasks
- `!cancel_schedule <id>` - Cancel a scheduled task
- `!edit_schedule <id> <task>` - Edit an existing scheduled task
- `!config <operation>` - Manage configuration
- `!hi` - Show welcome message

<!-- OUTPUT:END -->

## Note for Self-Hosters

This repository contains everything you need to self-host MindRoom. The `saas-platform/` directory contains infrastructure and code specific to running MindRoom as a hosted service and can be safely ignored by self-hosters.

## Configuration

### Basic Setup

1. Create `config.yaml` (for example):
```yaml
agents:
  assistant:
    display_name: Assistant
    role: A helpful AI assistant
    model: default
    rooms: [lobby]
    accept_invites: true  # Optional: accept authorized ad-hoc room invites

models:
  default:
    provider: anthropic
    id: claude-sonnet-4-6

mindroom_user:
  username: mindroom_user  # Set this before first run; username is immutable after bootstrap
  display_name: MindRoomUser

defaults:
  markdown: true
  compress_tool_results: false       # Safer default; enabling can invalidate Anthropic/Vertex Claude prompt caches
  # Required compaction is enabled by default when the runtime model has context_window.
  # Soft thresholds do not compact by themselves while history still fits.
  # compaction:
  #   enabled: true
  #   threshold_percent: 0.8
  #   reserve_tokens: 16384
  max_tool_calls_from_history: null  # Limit tool call messages replayed from history (null = no limit)
  num_history_runs: null             # Number of prior runs to include (null = all)
  thread_summary_first_threshold: 1  # First automatic summary after 1 thread message
  thread_summary_subsequent_interval: 10  # Re-summarize after each additional 10 messages
```

Add the `thread_summary` tool to an agent when you want it to write or refresh the one-line summary shown for a Matrix thread.
`set_thread_summary` uses the current resolved thread context by default.
Outside a resolved thread context, pass `thread_id` explicitly.

`compress_tool_results` now defaults to `false`.
On Anthropic and Vertex Claude models, enabling it can mutate replayed tool messages and invalidate prompt-cache prefixes.
Only re-enable it when the context savings matter more than prompt-cache reuse.

```yaml
agents:
  assistant:
    tools:
      - matrix_message
      - thread_summary
```

Required compaction is destructive inside the active session.
It uses one Matrix lifecycle notice that is edited in place.
It runs before a reply when raw history exceeds the hard replay budget.
It also runs before the next reply after a manual `compact_context` request.
Otherwise MindRoom leaves the stored session unchanged and relies on replay fitting for that reply.
It rewrites the stored session summary and removes the compacted raw runs from the live session so Agno replays only the merged summary plus the remaining recent runs.

2. Configure your Matrix homeserver and API keys (optional, defaults shown):
```bash
export MATRIX_HOMESERVER=https://your-matrix.server
export ANTHROPIC_API_KEY=your-key-here
# Optional: protect dashboard API endpoints (recommended for non-localhost)
# export MINDROOM_API_KEY=your-secret-key
# Optional: use a non-default config location
# export MINDROOM_CONFIG_PATH=/path/to/config.yaml
```

### Optional Advanced Configuration

```yaml
knowledge_bases:
  engineering_docs:
    description: Internal engineering docs, ADRs, deployment runbooks, and coding conventions.
    path: ./knowledge_docs
    watch: false  # Direct external edits require reindex; API/dashboard mutations still schedule refresh.

agents:
  assistant:
    display_name: Assistant
    role: A helpful AI assistant
    model: default
    rooms: [lobby]
    accept_invites: true
    knowledge_bases: [engineering_docs]
    # Per-agent overrides for history/context (override defaults above):
    # compress_tool_results: true  # Re-enable only if you accept Anthropic/Vertex Claude prompt-cache invalidation
    # max_tool_calls_from_history: 5
    # num_history_runs: 10
    # compaction:
    #   enabled: true
    #   threshold_tokens: 60000  # Soft replay budget; hard-budget compaction still requires context_window

voice:
  enabled: true
  stt:
    provider: openai
    model: whisper-1

memory:
  backend: mem0
  embedder:
    provider: sentence_transformers
    config:
      model: sentence-transformers/all-MiniLM-L6-v2

mindroom_user:
  username: mindroom_user  # Set this before first run; username is immutable after bootstrap
  display_name: MindRoomUser

authorization:
  global_users: ["@alice:example.com"]
  room_permissions:
    "!exampleRoomId:example.com": ["@bob:example.com"]
  default_room_access: false
```

`mindroom_user.username` can only be set before the internal user account is created. After first startup, change `mindroom_user.display_name` if you only want a different visible name.

## Deployment Options

### 🏠 Self-Hosted
Complete control on your infrastructure:
```bash
# Using your existing Matrix server
MATRIX_HOMESERVER=https://your-matrix.server uv run mindroom run

# Or bootstrap local Synapse + Cinny (Linux/macOS; Docker required)
mindroom local-stack-setup --synapse-dir /path/to/mindroom-stack/local/matrix
uv run mindroom run
```

### ☁️ Our Hosted Service (Coming Soon)
Zero setup, enterprise security:
- End-to-end encrypted (we can't read your data)
- Automatic updates and scaling
- 99.9% uptime SLA
- Start free, scale as needed

### 🔀 Hybrid
Mix and match:
- Sensitive rooms on your server
- General rooms on our cloud
- Agents collaborate seamlessly across both

## Architecture

### Technical Stack
- **Matrix**: Any homeserver (Synapse, Conduit, Dendrite, etc.)
- **Agents**: Python with matrix-nio
- **AI Models**: OpenAI, Anthropic, Ollama, or any provider
- **Memory**: Mem0 + ChromaDB vector storage (persistent on disk)
- **UI**: Web dashboard + any Matrix client

## Philosophy

We believe AI should be:

1. **Persistent**: Your AI should remember and learn from every interaction
2. **Ubiquitous**: Available wherever you communicate
3. **Collaborative**: Multiple specialists working together
4. **Private**: You control where your data lives
5. **Natural**: Just chat—no complex interfaces

## Status

- ✅ **Production ready** with 1000+ commits
- ✅ **100+ integrations** working today
- ✅ **Multi-agent collaboration** with persistent memory
- ✅ **Federation** across organizations and platforms
- ✅ **Self-hosted & cloud** options available
- ✅ **Voice transcription** for Matrix voice messages
- ✅ **Text-to-speech tools** via OpenAI, Groq, ElevenLabs, and Cartesia
- 🚧 Mobile apps in development
- 🚧 Agent marketplace planned


## Contributing

We welcome contributions! See [CLAUDE.md](CLAUDE.md) for the current development workflow and quality checks.

From the developer of 10+ successful open source projects with thousands of users. MindRoom represents 1000+ commits of production-ready code, not a weekend experiment.

## License

- **Repository (except `saas-platform/`)**: [Apache License 2.0](LICENSE)
- **SaaS Platform** (`saas-platform/`): [Business Source License 1.1](saas-platform/LICENSE) (converts to Apache 2.0 on 2030-02-06)

## Acknowledgments

Built with:
- [Matrix](https://matrix.org/) - The federated communication protocol
- [Agno](https://agno.dev/) - AI agent framework
- [mindroom-nio](https://github.com/mindroom-ai/mindroom-nio) - Python Matrix client

---

**mindroom** - AI that follows you everywhere, remembers everything, and stays under your control.
