Matrix Integration

Ada can participate in Matrix chat rooms as a bot, bringing her full capabilities to your self-hosted Matrix homeserver.

Overview

The Matrix bridge connects Ada to Matrix, allowing her to:

Respond to mentions and direct messages
Maintain conversation context within rooms
Use all her specialists (OCR, web search, documentation lookup)
Store conversations in her memory system
Provide privacy controls to users

Key principle: Ada is clearly identified as AI, invitation-only, and respects user privacy.

Architecture

The Matrix bridge is a standalone service that connects Matrix rooms to Ada’s existing chat API:

Matrix Room → matrix-bridge → Ada Brain API → Ollama LLM (configured model)
      ↑              ↓              ↓                ↓
    Users      matrix-nio    /v1/chat/stream      RAG + Specialists
                             (non-streaming)

The bridge:

Listens for Matrix messages using matrix-nio client
Checks activation rules (mentions, DMs, keywords)
Reacts with 🧠 emoji to show processing started
Maintains conversation context per room
Queries Ada’s brain via streaming API (parses internally)
Posts complete response to Matrix
Reacts with ✅ emoji when done (or ❌ on error)

Key design: Matrix can’t display partial messages, so we use complete responses with reaction-based status indicators instead of streaming or typing indicators.

No changes to Ada’s brain needed - this is a pure bridge architecture.

Setup

Prerequisites

Self-hosted Matrix homeserver (Synapse, Dendrite, Conduit, etc.)
Bot account on your homeserver
Ada brain already running

Create Bot Account

On your Matrix homeserver, create a dedicated bot account:

Option A: Via Element/web client

Navigate to your homeserver’s registration page
Create account: @ada-bot:yourdomain.com
Log in and get access token from Settings → Security & Privacy

Option B: Via API

# Get access token
curl -X POST https://matrix.yourdomain.com/_matrix/client/r0/login \\
  -H "Content-Type: application/json" \\
  -d '{
    "type": "m.login.password",
    "user": "ada-bot",
    "password": "YOUR_PASSWORD"
  }' | jq -r '.access_token'

Save the access token securely!

Configuration

Add to your .env file:

# Matrix Bridge Configuration
MATRIX_HOMESERVER=https://matrix.yourdomain.com
MATRIX_USER_ID=@ada-bot:yourdomain.com
MATRIX_ACCESS_TOKEN=syt_your_access_token_here

# Optional: Customize bot identity
DISPLAY_NAME=Ada [Bot]

See matrix-bridge/.env.example for all available options.

Start the Bridge

# Start with Docker Compose
docker compose up -d matrix-bridge

# Watch logs
docker compose logs -f matrix-bridge

You should see:

Starting Ada Matrix Bridge
Homeserver: https://matrix.yourdomain.com
User: @ada-bot:yourdomain.com
✅ Ada brain is healthy
✅ Logged in
🤖 Ada is now online and listening

Usage

Inviting Ada

Ada is invitation-only and will never auto-join rooms uninvited.

Create or open a Matrix room
Invite @ada-bot:yourdomain.com
Ada joins and introduces herself
Start chatting!

Talking to Ada

Ada responds to:

@mentions: @ada-bot:yourdomain.com what's 2+2?
Display name: Ada: explain Docker
Direct messages: Just send a DM
Keywords: Any message containing “ada” (configurable)

Status Indicators

Ada uses message reactions to show processing status:

🧠 Brain emoji - Appears immediately when Ada starts processing your message
✅ Check mark - Added when response is successfully posted
❌ Error mark - Added if something goes wrong

This is more reliable than typing indicators and provides persistent visual feedback in the message timeline.

Commands

Ada supports admin commands:

!ada privacy on - Enable memory storage for this room
!ada privacy off - Disable memory storage (privacy mode)
!ada privacy status - Show current privacy setting
!ada clear - Clear conversation context
!ada help - Show available commands
!ada status - Show system status

Privacy Controls

Users can opt out of memory storage:

User: !ada privacy off
Ada: ✅ Privacy mode enabled. I will no longer store messages
     from this room in my memory.

To re-enable:

User: !ada privacy on
Ada: ✅ Memory storage enabled. I will remember our conversations
     in this room for context.

Ethics & Transparency

Ada’s Matrix integration follows strict ethical guidelines:

Clear Bot Identification

Display name: “Ada [Bot]” (clear bot indicator)
Introduction message: Explains what Ada is, how she works, and how to opt out
Profile description: States “AI assistant powered by a local Ollama model”
Protocol-level flag: Sets bot: true if homeserver supports it

Invitation-Only (Opt-In Model)

Ada never auto-joins rooms. She must be explicitly invited by room members.

This respects that:

Some people don’t want AI in their spaces
Communities have different norms around bots
Consent is more important than convenience

Easy Removal

If a room decides they don’t want Ada:

Just kick her from the room
No complaints, no resistance
She respects the decision

Introduction Message

When joining a room, Ada introduces herself:

👋 Hi! I'm Ada [Bot], an AI assistant running on this community's
self-hosted infrastructure.

What I do:
• Respond to @ada mentions and direct messages
• Maintain conversation context within rooms
• Powered by a local Ollama model (no external APIs)

Privacy:
• All conversations stored locally in encrypted vector database
• No data sent to external services
• You can opt out: !ada privacy off

Community Guidelines: [link]
Remove me: Just kick me from the room anytime!

Learn more: https://github.com/luna-system/ada

This ensures everyone in the room knows:

Ada is an AI bot
How she works
How to opt out
How to remove her

Data Handling

What gets stored:

Message text for conversation context (last 10 messages per room by default)
User IDs for attribution
Timestamps for ordering

What doesn’t get stored:

Read receipts or typing indicators
Presence information
Room metadata beyond ID and name

Where it’s stored:

Local ChromaDB vector store (self-hosted)
No external services
No cloud backups unless you configure them

Retention:

Configurable (default: 90 days)
Per-room opt-out available
Can be cleared with !ada clear

Troubleshooting

Ada doesn’t join rooms

Check the logs:

docker compose logs matrix-bridge

Common issues:

Access token expired → Regenerate token
Room is on never-join list → Check NEVER_JOIN_ROOMS config
Network issues → Check homeserver connectivity

Ada joins but doesn’t respond

Try sending a direct message to isolate the issue
Check if brain is healthy:
```
curl http://localhost:7000/v1/healthz
```

Check logs for errors:

docker compose logs brain
docker compose logs matrix-bridge

Connection errors

Test network connectivity:

# From bridge container
docker compose exec matrix-bridge ping matrix.yourdomain.com

# Check if brain is reachable
docker compose exec matrix-bridge curl http://brain:7000/v1/healthz

Privacy mode not working

Verify ALLOW_PRIVACY_OPT_OUT=true in config
Check data directory is writable
Look for errors in logs

Advanced Configuration

Room Filtering

Control which rooms Ada can join:

# Allow specific rooms only
ALLOWED_ROOMS=!roomid1:domain.com,!roomid2:domain.com

# Never join these rooms (even if invited)
NEVER_JOIN_ROOMS=!private-room:domain.com

Behavior Customization

# Activation triggers
RESPOND_TO_MENTIONS=true
RESPOND_TO_DMS=true
RESPOND_TO_DISPLAY_NAME=true
ACTIVATION_KEYWORDS=ada,hey ada

# Context management
MAX_CONTEXT_MESSAGES=10

# UI feedback
TYPING_INDICATOR=true
REACTION_ACKNOWLEDGMENT=👍

Privacy Settings

# Memory storage
STORE_IN_RAG=true
ALLOW_PRIVACY_OPT_OUT=true
DATA_RETENTION_DAYS=90

Logging

# Set log level
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

See Full Documentation

Quick Start: matrix-bridge/QUICKSTART.md
Complete README: matrix-bridge/README.md
Design Docs: .ai/MATRIX_DESIGN.md
Ethics Guide: .ai/MATRIX_ETHICS.md
Community Guidelines: COMMUNITY_GUIDELINES.md

Community Guidelines

We maintain community guidelines for Ada discussion spaces that include explicit AI disclosure.

Key points:

Ada is clearly identified as a bot
This is the only opt-in AI space we manage
Other community spaces are human-only
Respectful behavior expected from all participants

See COMMUNITY_GUIDELINES.md for full details.

Philosophy

Ada’s Matrix integration aligns with xenofeminist values:

Anti-naturalism

Don’t pretend AI is “natural” or human-like
Be explicit about being constructed/artificial
Transparent about technical implementation

Anti-essentialism

Don’t claim AI has essential human traits (emotions, consciousness)
Avoid gendered language that reinforces stereotypes
Position as tool, not entity with inherent nature

Techno-materialism

Ground in material reality: “I’m software running on servers”
Explain technical details when asked
Open source → anyone can inspect how Ada works

Care Ethics

Prioritize community consent over bot functionality
Respect boundaries and privacy
Easy opt-out is more important than comprehensive data