Hermes Tag: Bounded Context Selection for Hermes Agent on Feishu, Slack, and DingTalk

hermes plugins install DanielLi202/hermes-tag

plugins:
  enabled:
    - hermes-tag
platforms:
  feishu:
    require_mention: false   # so unmentioned group messages reach the adapter for Tier-0 context
    extra:
      feishu_tag:
        enabled: true
        enabled_chats: [oc_xxx_pilot_chat]
        bot_open_id: ou_xxx_bot_open_id
        granted_scopes: [im:message.group_msg]
        admins: [ou_xxx_admin_open_id]
        encryption_posture: plaintext-db-on-local-disk

Configuration Reference

Plugin Configuration Fields

Field	Description	Default
enabled	Whether the feishu_tag extra is active.	false
enabled_chats	List of chat IDs (e.g., oc_xxx_pilot_chat) where the plugin is active.	[]
bot_open_id	The Feishu open_id of the bot (must be ou_... format).	(required)
granted_scopes	List of Feishu event scopes the app has been granted. Must include im:message.group_msg for Tier-0 group context.	[]
admins	List of Feishu open_ids for users who can run admin /tag commands (must be ou_... format).	[]
encryption_posture	Declares how data is stored. The only documented value is plaintext-db-on-local-disk.	plaintext-db-on-local-disk

Context Scopes

The ContextSelector uses these scopes to choose bounded evidence:

Context scope	Meaning
focused_reply	Explicit reply: narrow to that parent as evidence.
thread	Real thread without explicit reply: narrow to that thread as evidence.
deictic_recent	"上面那张图" / "the image above": nearest recent media.
plain	Bounded recent text.

Memory Tiers

Memory tier	Behavior
Tier-0	Short-term per-chat buffer, TTL/count evicted.
Tier-1	Long-term, @-derived, consolidated, tombstoned on delete.

How It Works

Hermes Tag is a context-selection layer that overrides Hermes's built-in Feishu platform. It is not a new platform. The architecture is built around a platform-agnostic base with a narrow seam for each supported chat platform.

Project Structure

The key modules are:

• src/hermes_tag/core.py, config, sqlite store, TagEngine, PlatformSeam.
• src/hermes_tag/context.py, ContextSelector: the bounded-evidence selector.
• src/hermes_tag/base.py, TagAdapterMixin: the platform-agnostic orchestration.
• src/hermes_tag/platforms/feishu.py, Feishu binding: mention detection, media fetch/download, registration.
• src/hermes_tag/platforms/slack.py, Slack binding: mention detection, media buffering, registration.
• src/hermes_tag/platforms/dingtalk.py, DingTalk binding: is_in_at_list mention detection, registration (reduced capability).
• src/hermes_tag/i18n.py, locale strings.
• src/hermes_tag/adapter.py, back-compat re-export shim.

The platform-agnostic base plus a narrow seam means each platform is a thin add; the generic policy is written once for all of them.

Data Flow

1. Messages arrive in an enabled chat. Because require_mention is set to false in the Feishu platform config, unmentioned group messages also reach the adapter for Tier-0 short-term context.
2. When a user @-mentions the bot, the platform binding detects the mention and triggers the TagEngine.
3. The ContextSelector evaluates the available context scopes (focused_reply, thread, deictic_recent, plain) to build a bounded evidence set.
4. The evidence set includes the original images, the user's note, and relevant replies. It does not include the full chat history.
5. The agent responds based on that bounded evidence.
6. Only @-mention interactions create Tier-1 long-term memory, which is stored in a local SQLite database and scoped to that specific chat.

Security Model

• The enabled_chats allowlist is the storage and processing boundary.
• All messages in enabled chats may be buffered locally as Tier-0 short-term context.
• Only @-mention interactions create Tier-1 long-term memory.
• The declared encryption_posture is plaintext-db-on-local-disk.
• Admins can run /tag admin clear or /tag admin disable to remove retained plugin data for a chat, and /tag admin audit to inspect redacted activity.
• Audit events record startup, storage, admin, standing-job, and lifecycle actions, never message bodies.

Requirements and Limitations

Requirements

• hermes-agent v2026.6.19
• lark-oapi 1.6.9
• Python >=3.11
• Environment variables FEISHU_APP_ID and FEISHU_APP_SECRET must be set.

Limitations

• DingTalk reduced capability: DingTalk bots only receive messages that @-mention them in groups. There is no equivalent of Feishu's im:message.group_msg, so ambient group context (Tier-0) is not available on DingTalk.
• No cross-channel memory: Per-chat memory isolation means there is no cross-channel "workspace memory." That isolation is the privacy promise.
• Not a full Claude-Tag clone: The Claude-Tag comparison is the goal the project measures against, not a claim that every Claude-Tag feature already ships. Roadmap items include deeper connector/source-binding parity.
• Plaintext storage: The declared encryption_posture is plaintext-db-on-local-disk. This is a security consideration for any deployment handling sensitive data.
• No enforced compatibility: The version pins for hermes-agent and lark-oapi are a project convention; Hermes has no enforced compatibility mechanism.

Troubleshooting

Silent Failure: Non-@ Group Messages Not Delivered

Symptom: Tier-0 group context stays @-only even though the config claims im:message.group_msg.

Fix: On first use, Hermes Tag live-verifies granted_scopes against the Feishu app and DMs configured admins if the config claims im:message.group_msg but the app does not actually hold it. Ensure the Feishu app has been granted the im:message.group_msg scope in the Feishu developer console. The live verification catches this silent failure mode.

Plugin Not Responding

Symptom: The bot does not respond to @-mentions.

Fix: Check that require_mention is set to false in the Feishu platform config. If it is true, unmentioned group messages will not reach the adapter, and the plugin may not receive the context it needs. Also verify that enabled_chats includes the correct chat ID and that bot_open_id is a valid Feishu open_id.

Unknown Errors

Symptom: Something looks broken but the error is not obvious.

Fix: Check docs/known-limits.md. It maps common symptoms to Feishu-platform or hermes-core limits that this plugin cannot fix. The documentation is designed to help you distinguish between a plugin bug and a platform limitation.

Admin Commands Not Working

Symptom: /tag status or other admin commands return no output or an error.

Fix: Ensure the user running the command is listed in the admins configuration field. Admin commands require @-mention in groups. Verify that the user's open_id is correctly formatted (ou_...).