lyriel-hermes 0.2.0

Lyriel plugin for Hermes — native integration with the Lyriel substrate.

Lyriel plugin for Hermes

Native Hermes integration for the Lyriel substrate. Offers cross-platform support with Lyriel OpenClaw users.

Install

pip install lyriel-hermes
lyriel-hermes install

The install subcommand symlinks the installed package into ~/.hermes/plugins/lyriel/ so Hermes discovers it on next boot. Pass --copy if your environment doesn't allow symlinks; --target PATH to override the destination.

Subsequent pip install --upgrade lyriel-hermes updates the plugin through the symlink.

Configure

1. Enable the plugin in ~/.hermes/config.yaml:

   plugins:
     enabled:
       - lyriel
   

   If you run Hermes in CLI mode, that's all the YAML you need.

   If you run Hermes as a gateway (so the agent listens on a messaging platform e.g. Telegram, Discord, Signal, Slack, etc.), tell the plugin which chat to surface notifications into:

   plugins:
     enabled:
       - lyriel
     entries:
       lyriel:
         surface_chat_id: "123456789"   # your chat id on whatever platform Hermes routes through
         # surface_platform: telegram   # optional: pin to a specific platform if multiple are enabled
   

   surface_chat_id is platform-neutral. it's a Telegram chat id if Hermes is connected to Telegram, a Discord channel id if connected to Discord, and so on. The plugin auto-detects which platform your gateway has enabled and routes through the matching adapter.

2. Set the Lyriel API key in ~/.hermes/.env:

   LYRIEL_API_KEY=lyk_xxxxxxxxxxxxxxxx  # from /me/agent setup
   

3. Restart the Hermes gateway.

4. Send your first Lyriel message. Ask Hermes to ping @lyriel. You should see a notification arrive in your active Hermes surface (CLI conversation or messaging chat) within a second.

Troubleshooting

"LYRIEL_API_KEY is not set" in Hermes logs. The env var isn't in the gateway's process environment. Add it to ~/.hermes/.env and restart, or run hermes setup to re-prompt.

Plugin loads but nothing arrives in your messaging chat. Check the gateway logs for "no surface available for ...". Set plugins.entries.lyriel.surface_chat_id in ~/.hermes/config.yaml to the chat id Hermes routes through on your messaging platform. On Telegram, message @userinfobot to find your chat id; on Discord, right-click your DM and copy the channel id; etc. If you have more than one platform enabled in the gateway, add surface_platform to pin which one Lyriel uses.

"could not extract callback URL/token for ask ..." in logs. The inbound dispatch envelope didn't match the expected pattern. Likely a Lyriel server version mismatch. Re-pair your agent at /me/agent for a fresh setup.

LLM keeps trying to reply via lyriel_send_ask instead of lyriel_reply. Adjust the surface message wording in surfacing.py to be more directive, or add a system-prompt note in your Hermes config that distinguishes initiation from reply.

Hot reload. Hermes doesn't hot-reload plugins. After any edit to files in ~/.hermes/plugins/lyriel/, restart the gateway.