PR #13063: feat(discord): history backfill for multi-user Discord

• Repository: NousResearch/hermes-agent
• Author: simpolism
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/13063

Description (problem / solution / changelog)

What does this PR do?

Feature Outline

The main feature in this PR is providing history backfill in Discord, specifically intended for cases where require_mention = true. In this case, Hermes Agent will only reply when mentioned, and several intermediate messages may have occurred between mentions.

The current behavior on mention is to only provide Hermes Agent with the mentioning message. This fails in multi-user chats, in particular multi-agent chats where e.g. Hermes Agent is being asked to review another agent's output.

Implementation Details

This PR introduces two config variables: history_backfill, and history_backfill_limit. Without require_mention, these do nothing. With require_mention enabled, history_backfill = true will construct a user message that includes prior messages in the chat, tagged with names, up to the limit specified in history_backfill_limit (typically set to something like 50 for cold starts -- in practice when participating in active multi-user conversation, it should include all messages).

The message format provided in the user block looks like: [Recent channel messages] <backfill> \n\n [New message] <mentioning message>, which gives Hermes Agent a distinction between the history used as context and the specific tagging message that instructs Hermes Agent on what to do.

Design Decisions

Two main opinionated choices:

Interleaved Message Handling

Core question: what happens if users message each other while Hermes Agent is processing? Should that context be included on the next message, or omitted? We chose in this PR to omit interleaved context entirely. This simplifies the history backfill, as it spans precisely from the most recent Hermes Agent output forward to the tagging message, without having to deal with "in between" messages.

The reasoning is that the alternative approaches have problems.

1. If we include interleaved messages, we would also want to reproduce the assistant messages, so that specific context (e.g. someone responding to an interleaved thinking trace) is preserved. The issue with this approach is that we're then duplicating assistant output tokens, which could be confusing for the agent + is wasteful.
2. If we include interleaved messages without reproducing assistant messages, the Agent could get potentially more backfill context, but it could also risk providing incorrect cues, if users are discussing their mid-output messages and the Agent isn't aware of it.

The guiding principle here is a kind of skeuomorphic idea, where once you tag Hermes Agent, they 'turn away' from the live chat to process / do the work, and then 'return' afterward, so the messages they missed in the middle get dropped. They need to be filled in on what happened while they were working. This idea is open to revision, but suits my personal use case fine, so long as I as a user am aware that Hermes Agent wont see intermediate messages. I can simply avoid triggering them. This decision may need to be revised based on other use cases, such as more social rather than multi-agent single-human work Discords (how I am using this PR).

Structured message format.

The choice to use [Recent channel messages] <backfill> \n\n [New message] <mentioning message> is not neutral -- an alternative could be a flat message list that includes the @ tag for the Agent in the final message. This structured format uses a few more tokens, but helps the Agent attend specifically to the tagged request, by separating it structurally from the backfill context. Again, this is ideal for my specific use case, but could be reconsidered according to other related use cases.

Related Issue

Fixes #13054 Fixes #13050 (necessary bug fix to support named multi-user in channels and not just threads)

Type of Change

<!-- Check the one that applies. -->

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

<!-- List the specific changes. Include file paths for code changes. -->

• Gateway config: added 2 new flags.
• Gateway base: adds temporary channel history tracking variable
• Discord platform logic: the bulk of the change set, includes history tracking + message construction based on flags
• gateway run/session logic: includes fix for user name inclusion

How to Test

<!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. -->

Run the Hermes Agent + Gateway attached to Discord with require_mention = false; auto_thread = false; history_backfill: true.

Send multiple messages (such as a secret string) then tag Hermes Agent (e.g. to ask what the secret string was) and confirm that it was able to review prior messages.

Extensive test cases also included as part of PR for both the small bug fix and the feature logic.

Qualitatively, I have been running my fork of Hermes Agent that includes this code for several days as a main coding agent within a multi-agent Discord (so I can e.g. tag Codex for a code review against Hermes Agent and facilitate and back and forth) and I haven't noticed any serious issues. See attached image for an example of the feature in action.

Checklist

<!-- Complete these before requesting review. -->

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu 24.04

Documentation & Housekeeping

<!-- Check all that apply. It's OK to check "N/A" if a category doesn't apply to your change. -->

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• N/A I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• N/A I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• N/A I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

<img width="966" height="718" alt="screenshot-20260420-102245" src="https://github.com/user-attachments/assets/8bb072b9-688c-4f4c-b83a-a78e5386286d" />

Changed files

• cli-config.yaml.example (modified, +10/-0)
• gateway/config.py (modified, +8/-0)
• gateway/platforms/base.py (modified, +6/-0)
• gateway/platforms/discord.py (modified, +169/-2)
• gateway/run.py (modified, +15/-4)
• gateway/session.py (modified, +26/-11)
• scripts/release.py (modified, +1/-0)
• tests/gateway/test_config.py (modified, +20/-0)
• tests/gateway/test_discord_free_response.py (modified, +204/-0)
• tests/gateway/test_session.py (modified, +97/-4)
• website/docs/user-guide/messaging/discord.md (modified, +27/-0)