letta-matrix-channel

A dynamic Letta Code channel plugin that connects a Letta agent to Matrix, mirroring the first-class Telegram channel.

Status: v4 (production) — 186/186 tests passing across five suites, including a real Rust conduwuit Matrix homeserver.

Suite	Assertions	Environment
Unit	72	Mocked SDK
Integration	50	Real matrix-bot-sdk + fake homeserver over HTTP
Stress	20	Real SDK + fake HS: unicode, burst, 100KB, concurrency
Fault injection	16	Real SDK + fault-injecting HTTP proxy (429/500/413/drop/hang)
Real conduwuit	28	Real matrix-bot-sdk against real Rust Matrix homeserver

See docs/CHANGELOG.md for the v1 → v2 → v3 → v4 debug passes.

letta-matrix-channel/
├── channel/
│   ├── channel.json                 # Runtime manifest
│   ├── plugin.mjs                   # Adapter + MessageChannel actions
│   ├── accounts.example.json        # Account envelope
│   └── test/
│       └── plugin.test.mjs          # 72 unit tests (mocked SDK)
├── real-test/
│   ├── fake-synapse.mjs             # HTTP homeserver speaking Matrix CS v3
│   ├── integration.test.mjs         # 50 real-HTTP tests
│   ├── stress.test.mjs              # 20 stress tests
│   ├── fault-injection.test.mjs     # 16 fault injection tests
│   └── real-conduwuit.test.mjs      # 28 real Matrix HS tests
└── docs/
    ├── letta-matrix-channel-analysis.md
    └── CHANGELOG.md

Running the tests

# 72 unit tests — no deps to install (mocks matrix-bot-sdk + markdown-it)
node channel/test/plugin.test.mjs

# Real integration + stress + fault injection — requires real matrix-bot-sdk
cd real-test && npm install
node integration.test.mjs
node stress.test.mjs
node fault-injection.test.mjs

# Real conduwuit — requires a running conduwuit homeserver at $HS.
# See real-test/real-conduwuit.test.mjs for the /tmp/*.token file layout.
node real-conduwuit.test.mjs

Quick start

mkdir -p ~/.letta/channels/matrix
cp channel/{channel.json,plugin.mjs,accounts.example.json} ~/.letta/channels/matrix/
op inject -i ~/.letta/channels/matrix/accounts.example.json \
          -o ~/.letta/channels/matrix/accounts.json
letta channels install matrix
letta server --channels telegram,slack,matrix

Then DM the bot from Element/Beeper, take the pairing code, and:

letta channels pair --channel matrix \
  --code <code> --agent <agent_id> --conversation default

Full context in docs/letta-matrix-channel-analysis.md.