Matrix integration

.env.example

@@ -84,6 +84,29 @@ TELEGRAM_BOT_TOKEN=your_telegram_bot_token
 # Enable/disable Note to Self messages (default: true)
 # SIGNAL_SELF_CHAT_MODE=true
 
+# ============================================
+# Matrix (optional)
+# ============================================
+# Get access token from Element: Settings → Help & About → Access Token
+# Or run: npm run matrix-login
+# MATRIX_HOMESERVER_URL=https://matrix.org
+# MATRIX_ACCESS_TOKEN=your_access_token
+
+# Enable E2EE encryption (default: true)
+# MATRIX_ENCRYPTION_ENABLED=true
+
+# Auto-join rooms when invited (default: true)
+# MATRIX_AUTO_JOIN_ROOMS=true
+
+# DM access policy: pairing (default), allowlist, open
+# - pairing: Unknown senders get a code, must be approved via CLI
+# - allowlist: Only users in MATRIX_ALLOWED_USERS can message
+# - open: Anyone can message
+# MATRIX_DM_POLICY=pairing
+
+# Restrict to specific Matrix user IDs (comma-separated)
+# MATRIX_ALLOWED_USERS=@user1:matrix.org,@user2:example.com
+
 # ============================================
 # Polling (system-level background checks)
 # ============================================

README.md

@@ -1,6 +1,6 @@
 # LettaBot
 
-Your personal AI assistant that remembers everything across **Telegram, Slack, Discord, WhatsApp, and Signal**. Powered by the [Letta Code SDK](https://github.com/letta-ai/letta-code-sdk).
+Your personal AI assistant that remembers everything across **Telegram, Slack, Discord, WhatsApp, Signal, and Matrix**. Powered by the [Letta Code SDK](https://github.com/letta-ai/letta-code-sdk).
 
 <img width="750" alt="lettabot-preview" src="https://github.com/user-attachments/assets/9f01b845-d5b0-447b-927d-ae15f9ec7511" />
 
@@ -15,7 +15,7 @@ Your personal AI assistant that remembers everything across **Telegram, Slack, D
 
 ## Features
 
-- **Multi-Channel** - Chat seamlessly across Telegram, Slack, Discord, WhatsApp, and Signal
+- **Multi-Channel** - Chat seamlessly across Telegram, Slack, Discord, WhatsApp, Signal, and Matrix
 - **Unified Memory** - Single agent remembers everything from all channels
 - **Persistent Memory** - Agent remembers conversations across sessions (days/weeks/months)
 - **Local Tool Execution** - Agent can read files, search code, run commands on your machine
@@ -111,7 +111,7 @@ That's it! Message your bot on Telegram.
 
 LettaBot can transcribe voice messages using either OpenAI Whisper or Mistral Voxtral. Voice messages are automatically converted to text and sent to the agent with a `[Voice message]:` prefix.
 
-**Supported channels:** Telegram, WhatsApp, Signal, Slack, Discord
+**Supported channels:** Telegram, WhatsApp, Signal, Slack, Discord, Matrix
 
 ### Configuration
 
@@ -218,12 +218,13 @@ Telegram ──┐
 Slack ─────┤
 Discord ───┼──→ ONE AGENT ──→ ONE CONVERSATION
 WhatsApp ──┤    (memory)      (chat history)
-Signal ────┘
+Signal ────┤
+Matrix ────┘
 ```
 
 - Start a conversation on Telegram
 - Continue it on Slack
-- Pick it up on WhatsApp
+- Pick it up on WhatsApp or Matrix
 - The agent remembers everything!
 
 You can also enable **per-channel conversations** (one conversation per channel adapter, not per chat/user):
@@ -233,6 +234,7 @@ Telegram ──→ CONVERSATION (telegram)
 Slack ─────→ CONVERSATION (slack)
 Discord ───→ CONVERSATION (discord)
 WhatsApp ──→ CONVERSATION (whatsapp)
+Matrix ────→ CONVERSATION (matrix)
 Signal ────→ CONVERSATION (signal)
         (shared agent memory across channels)
 ```
@@ -262,6 +264,7 @@ agents:
 | Discord | [Setup Guide](docs/discord-setup.md) | Discord bot + Message Content Intent |
 | WhatsApp | [Setup Guide](docs/whatsapp-setup.md) | Phone with WhatsApp |
 | Signal | [Setup Guide](docs/signal-setup.md) | signal-cli + phone number |
+| Matrix | [Setup Guide](docs/matrix-setup.md) | Matrix account + access token |
 
 At least one channel is required. Telegram is the easiest to start with.
 
@@ -364,6 +367,7 @@ Supports sync and streaming responses. See the [full documentation](docs/openai-
 | Discord | Gateway (outbound WebSocket) | None |
 | WhatsApp | Outbound WebSocket via Baileys | None |
 | Signal | Local daemon on 127.0.0.1 | None |
+| Matrix | Client API (outbound HTTP) | None |
 
 ### Tool Execution
 
@@ -466,6 +470,7 @@ Check the [ADE](https://app.letta.com) to see if your agent is attempting to use
 - [Discord Setup](docs/discord-setup.md)
 - [WhatsApp Setup](docs/whatsapp-setup.md)
 - [Signal Setup](docs/signal-setup.md)
+- [Matrix Setup](docs/matrix-setup.md)
 
 ## Acknowledgement
 Some skills were adapted from [Moltbot](https://github.com/moltbot/moltbot). 

docs/MATRIX_INTEGRATION_COMPLETE.md

@@ -0,0 +1,127 @@
+# Matrix Integration - Complete Implementation
+
+> Successfully integrated Matrix channel support into lettabot main branch
+
+## Summary
+
+This PR adds full Matrix channel support to lettabot, including:
+- E2EE encryption support
+- Interactive onboard/setup wizard
+- Matrix login helper script
+- Full config normalization
+
+## Files Changed
+
+### New Files
+| File | Description |
+|------|-------------|
+| `src/channels/matrix.ts` | Matrix channel adapter with E2EE support |
+| `src/scripts/matrix-login.ts` | Interactive Matrix token generator |
+
+### Modified Files
+| File | Changes |
+|------|---------|
+| `src/channels/index.ts` | Added Matrix export |
+| `src/channels/setup.ts` | Added Matrix to CHANNELS array, setupMatrix function, GROUP_ID_HINTS |
+| `src/core/types.ts` | Added 'matrix' to ChannelId type |
+| `src/config/types.ts` | Added MatrixConfig interface, normalizeChannels support, env var support |
+| `src/main.ts` | Added MatrixAdapter import and registration |
+| `src/onboard.ts` | Added Matrix to OnboardConfig, stepChannels, config summary, and save logic |
+| `package.json` | Added matrix-bot-sdk dependency and matrix-login script |
+
+## Features
+
+### E2EE Encryption
+- Uses `RustSdkCryptoStorageProvider` for encryption
+- Automatically decrypts encrypted messages
+- Crypto storage persisted to `./data/matrix/crypto`
+
+### Interactive Setup
+- Matrix appears in channel selection during `lettabot onboard`
+- Prompts for homeserver URL, access token, encryption settings
+- Supports dmPolicy: 'pairing', 'allowlist', or 'open'
+
+### Matrix Login Helper
+```bash
+npm run matrix-login
+# or
+node dist/cli.js matrix-login
+```
+Interactive script to generate Matrix access tokens.
+
+## Configuration
+
+### YAML Format
+```yaml
+agents:
+  - name: MyBot
+    channels:
+      matrix:
+        enabled: true
+        homeserverUrl: https://matrix.org
+        accessToken: your_access_token
+        encryptionEnabled: true
+        autoJoinRooms: true
+        dmPolicy: pairing
+        allowedUsers:
+          - "@user:matrix.org"
+```
+
+### Environment Variables
+```bash
+MATRIX_HOMESERVER_URL=https://matrix.org
+MATRIX_ACCESS_TOKEN=your_token
+MATRIX_ENCRYPTION_ENABLED=true
+MATRIX_AUTO_JOIN_ROOMS=true
+MATRIX_DM_POLICY=pairing
+MATRIX_ALLOWED_USERS=@user1:matrix.org,@user2:matrix.org
+```
+
+## Technical Details
+
+### Session Management
+The Matrix adapter uses lettabot's sophisticated session management from main branch:
+- Sessions cached per conversation key
+- Creation locks prevent duplicate sessions
+- Generation tracking for reset/invalidation
+
+### Message Flow
+1. Matrix adapter receives message via `room.message` event
+2. Decrypts if encrypted (E2EE)
+3. Checks access control (dmPolicy)
+4. Passes to bot core with metadata envelope
+5. Bot processes and returns response
+6. Adapter sends response as HTML-formatted message
+
+### M_NOT_FOUND Errors
+During E2EE operation, `M_NOT_FOUND` errors may appear in logs. These are expected during:
+- Initial key sync
+- Fetching encryption keys
+- Room state synchronization
+
+These errors don't affect functionality.
+
+## Testing Checklist
+
+- [x] npm install succeeds
+- [x] npm run build compiles
+- [x] Matrix appears in onboard channel selection
+- [x] Matrix setup prompts work
+- [x] Config saves correctly to lettabot.yaml
+- [x] Bot connects to Matrix server
+- [x] E2EE encryption works
+- [x] Messages are received and sent
+- [x] Session persistence works
+- [x] Conversation context maintained
+- [x] Typing indicators work
+
+## Credits
+
+- Original Matrix PR: #42 (matrix-support branch)
+- Integration to main branch: February 2026
+- Session management: Uses main branch's sophisticated system
+
+## Related
+
+- [matrix-bot-sdk documentation](https://github.com/turt2live/matrix-bot-sdk)
+- [Matrix protocol](https://matrix.org/docs/guides)