Integrate Matrix chat server into Exponential

[positonic]

Matrix Chat Integration

Integration Approaches

1. Workspace-Scoped Chat Rooms (Most Natural Fit)

Our workspace model already maps cleanly to Matrix rooms:

• Each workspace → Matrix Space (container)
• Each project → Matrix Room within the Space
• WorkspaceUser roles (owner/admin/member/viewer) → Matrix power levels
• Custom assistants (Aria, Max, etc.) → Matrix bot users that join rooms

This would give us real-time collaboration that's currently missing — right now everything is REST-based polling with React Query.

2. AI Agent Bridge (Leverage Existing Mastra Architecture)

Our Mastra agent system already supports multi-platform routing (Slack, WhatsApp, ManyChat). Matrix becomes another platform:

User message in Matrix room
  → Matrix Application Service webhook
  → /api/webhooks/matrix/route.ts
  → Semantic agent selection (existing)
  → Agent response
  → Bridge posts back to Matrix room

This follows the exact same pattern as the Slack integration, with AiInteractionHistory logging with platform: "matrix".

3. Federation for Team Workspaces

Matrix's federation protocol means team/organization workspaces could communicate across instances — useful if Exponential ever becomes multi-tenant with separate deployments.

---

Architecture Options

Approach	Complexity	What You Get
Matrix JS SDK in frontend	Medium	Embed Matrix chat directly in the app, rooms per project/workspace
Application Service (bridge)	Medium	AI agents respond in Matrix rooms, users use any Matrix client
Self-hosted Synapse/Conduit	High	Full control, federation, E2E encryption, bridges to Slack/Discord
Element embedded widget	Low	Drop-in Element Web as an iframe in workspace pages

---

Recommended Path (Incremental)

Phase 1 — Application Service Bridge (webhook-based)

• Create /api/webhooks/matrix/route.ts following the Slack pattern
• Add IntegrationCredential entries for Matrix homeserver tokens
• Map Matrix user IDs → system users via IntegrationUserMapping
• AI agents respond in Matrix rooms (extends ManyChat to another channel)
• No frontend changes needed — users interact via any Matrix client

Phase 2 — Embedded Chat UI

• Replace or augment ManyChat modal with Matrix-backed rooms using matrix-js-sdk
• Each workspace gets a Matrix Space, each project a room
• Messages persist in Matrix (replacing localStorage conversation state)
• Adds user-to-user messaging (currently doesn't exist)

Phase 3 — Full Integration

• Self-hosted Conduit (lightweight Rust homeserver) or Synapse
• E2E encryption for sensitive workspace data
• Bridges to Discord/Slack (users already auth with both)
• Matrix-backed notifications replacing any polling patterns
• Action items / tasks created directly from Matrix messages via bot commands

---

Key Considerations

What Matrix solves that we don't have today:

• Real-time messaging (no WebSocket infrastructure exists currently)
• User-to-user communication (only AI chat exists)
• Message persistence beyond localStorage
• Federation and interoperability
• E2E encryption

What already maps well:

• Workspace → Space/Room hierarchy
• IntegrationCredential for encrypted token storage
• IntegrationUserMapping for external ID mapping
• AiInteractionHistory for cross-platform analytics
• JWT auth for agent callbacks
• Custom assistant personalities as bot personas

Trade-offs to consider:

• Synapse is resource-heavy (Python) — Conduit (Rust) is much lighter for self-hosting
• Matrix JS SDK adds ~200KB+ to the frontend bundle — consider dynamic imports (already done with ManyChat)
• E2E encryption complicates AI agent access to messages (agents need to decrypt)
• Running a homeserver adds operational complexity vs. using matrix.org as a hosted provider

[linear]

EXP-55