Bug Description

Matrix integration works after setup, but there are multiple runtime issues that make it incomplete in practice.

1. Missing platform registration causes a KeyError when handling Matrix messages
2. Non-image file uploads are not accessible to the agent (MXC URLs require auth)
3. Text file uploads may cache locally but are not injected into context due to MIME mismatch

This is separate from #1973 (setup/env issue). These problems occur after Matrix is installed and connected.

I have included minimal working fixes below so this can be picked up and PR’d directly.

Steps to Reproduce

1. Set up Hermes Agent with Matrix integration (Synapse homeserver, matrix-nio installed)
2. Connect bot and send a message from Matrix

For issue #1:

• Send any message
• Agent crashes with KeyError: 'matrix'

For issue #2:

• Upload a non-image file (e.g., .txt or .pdf)
• Agent receives an MXC URL but cannot access the file

For issue #3:

• Upload a .txt file
• File is cached locally but agent does not read or reference its contents

Expected Behavior

• Matrix should be recognized as a valid platform and not cause runtime errors
• All uploaded files should be downloaded using authenticated Matrix client access
• Text-readable files should have their contents injected into the agent context regardless of MIME inconsistencies

Actual Behavior

• Sending a Matrix message can trigger KeyError: 'matrix'
• Non-image uploads (txt, pdf, etc.) are passed as MXC URLs and are not accessible to the agent
• Text files may be cached locally but their contents are not injected into context

Affected Component

Gateway (Telegram/Discord/Slack/WhatsApp)

Messaging Platform (if gateway-related)

No response

Operating System

Ubuntu 24.04

Python Version

3.11.9

Hermes Version

0.4.0

Relevant Logs / Traceback

KeyError: 'matrix'

Root Cause Analysis (optional)

Root Cause + Fixes

1) Missing PLATFORMS entry

File: hermes_cli/tools_config.py

"matrix": {"label": "💬 Matrix", "default_toolset": "hermes-telegram"},

2) Matrix media handling only downloads images

File: gateway/platforms/matrix.py

if url:
data = await self._client.download(url)

if msg_type == MessageType.PHOTO:
    cache_image_from_bytes(data, ...)
else:
    filename = sanitize_filename(name or "matrix_file")
    path = os.path.expanduser(f"~/.hermes/document_cache/{filename}")

    with open(path, "wb") as f:
        f.write(data)

3) Text enrichment fails due to MIME mismatch

File: gateway/run.py

_text_extensions = {
".txt",".md",".json",".yaml",".yml",".py",".js",".ts",".sh",
".csv",".xml",".html",".css",".toml",".ini",".cfg",".conf",".log",".rst"
}

_is_text = mtype.startswith("text/") or os.path.splitext(path)[1].lower() in _text_extensions

Notes

Tested on live deployment. These fixes resolve the issues locally.

Proposed Fix (optional)

See Root Cause Analysis section for working patches.

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR