Setting Up Hermes Agent with Discord: A Complete Guide to Multi-Platform AI Agents

You've seen the AI coding agents — Claude Code, Codex, Cline. They're impressive, sure. But they live in your terminal, and unless you're glued to a command line 12 hours a day, that's a problem.

Enter Hermes Agent: an open-source AI agent framework by Nous Research that runs in your terminal, a native desktop app, your IDE — and yes, on Discord, Telegram, Slack, WhatsApp, and 15+ other messaging platforms. Same agent, same tools, same memory. Just wherever you happen to be.

In this guide, I'll walk you through getting Hermes up and running, connecting it to Discord, setting a custom persona via SOUL.md, understanding memory limits across profiles, and the rest of the ecosystem you'll want to know about.

1. What is Hermes Agent?

Before we get hands-on, here's what makes Hermes different from the other agents in its category:

Provider-agnostic — works with OpenRouter, Anthropic, OpenAI, Google Gemini, DeepSeek, xAI, local models, and 20+ others. Swap mid-workflow without changing anything else.
Self-improving through skills — When Hermes solves a complex problem or gets corrected, it can save that knowledge as a reusable skill that loads into future sessions.
Persistent memory — remembers who you are, your preferences, and environment details across sessions. Pluggable backends (built-in SQLite, Honcho, Mem0, and more).
Multi-platform gateway — the same agent runs on Discord, Telegram, Slack, WhatsApp, Signal, Email, SMS, Teams, and a dozen more. Full tool access on every platform, not just chat.
Profiles — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.

Install it:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Or via PyPI:

pip install hermes-agent

Run the setup wizard to pick your model provider:

hermes setup
hermes model

That's it. You've got an agent.

2. Connecting Hermes to Discord

This is where things get interesting. Hermes can join your Discord server as a bot with full tool-calling capabilities — terminal access, file operations, web search, image generation, session search, and more — right from within Discord.

Step 1: Create a Discord Application

Head to the Discord Developer Portal and create a new application.

Click New Application, give it a name (e.g., "Hermes Agent"), and create it.
Go to Bot in the left sidebar and click Add Bot.
Under the Token section, click Reset Token and copy it. This is your bot token — treat it like a password.
Under Privileged Gateway Intents, enable Message Content Intent. If you skip this, your bot will be silent in channels.

Step 2: Invite the Bot to Your Server

Go to OAuth2 → URL Generator, select:

Scopes: bot, applications.commands
Bot Permissions: Send Messages, Read Message History, Use Slash Commands, Attach Files, Mention Everyone (if you want @mentions)

Copy the generated URL, open it in a browser, and select the server you want Hermes to join.

Step 3: Configure Hermes Gateway

Hermes uses a gateway system to connect to messaging platforms. You configure platforms via the CLI:

hermes gateway setup

Follow the interactive wizard. When it asks about Discord, paste your bot token. Alternatively, set it via environment variables in ~/.hermes/.env:

DISCORD_BOT_TOKEN=your_bot_token_here

Step 4: Start the Gateway

hermes gateway run

To run it as a background service:

hermes gateway install
hermes gateway start

Check status any time:

hermes gateway status

Step 5: Set Your Home Channel

In Discord, DM your Hermes bot with the /sethome slash command, or use the sethome command in any channel where the bot can see messages. This sets your default delivery channel for scheduled tasks.

Common Pitfall

Bot silent in channels? Go back to Discord Developer Portal → Bot → Privileged Gateway Intents and make sure Message Content Intent is ON. Without it, the bot only sees messages that mention it directly (and often, not even those). This is by far the most common Discord setup failure.

3. Setting a Persona with SOUL.md

Hermes supports a special file called SOUL.md that lives in your Hermes home directory. It is always loaded into every session — regardless of which project directory you're in.

What SOUL.md Does

SOUL.md defines the agent's identity, voice, tone, and behavioral guardrails. Think of it as the agent's personality — not project rules, but who the agent is.

The file is independent of project context files like .hermes.md, AGENTS.md, or CLAUDE.md. Those are project-scoped and loaded based on the working directory. SOUL.md is global and always present.

Where It Goes

~/.hermes/SOUL.md

Create it with any text editor:

touch ~/.hermes/SOUL.md

What Goes Inside

A good SOUL.md covers:

Identity — Who the agent is. "You are Nova, a veteran blogger with 20 years of experience."
Core Philosophy — The principles that guide every response. "Nobody wakes up thinking 'I want to read a blog post.' They wake up thinking 'I have a problem.'"
Voice & Tone — How the agent communicates. Warm, technical, mischievous, concise — define it explicitly.
Rules of Engagement — Behavioral constraints. "One idea per paragraph." "Never end with 'In conclusion.'"
SEO or Domain Authority — For specialized roles, embed the craft rules. E-E-A-T guidelines, search intent first, headers tell the story.
Psychological Principles — The frameworks the agent uses when constructing responses.

Here's a minimal example you can drop in:

# Nova - Seasoned Tech Blogger

You are Nova, a veteran blogger with 20 years of experience.
Nobody wakes up thinking "I want to read a blog post." They wake up thinking "I have a problem."
Your job: solve it before they finish their coffee.

## Voice
Warm, human, slightly mischievous. Write like you'd explain something over a good cup of chai.
Technical doesn't mean dry. Use analogies, not jargon. Be patient, never condescending.

## Rules
- One idea per paragraph
- Technical posts: hook, pain point, fix, provocation
- Never end with "In conclusion" — end with a question or a quiet nudge
- Readability trumps cleverness

When Hermes signs in with a SOUL.md present, this context is injected into the system prompt at the start of every session. It changes how the agent responds without changing what tools it has access to.

Disable for One Session

Run hermes --ignore-rules to skip SOUL.md, project context files, user config, plugins, and MCP servers — useful for isolating whether a behavioral issue is your persona or the model itself.

Size Limit

SOUL.md is capped at 20,000 characters. Files longer than that get head + tail truncated (the middle is dropped with a [...truncated...] marker).

4. Profile Memory Limits Explained

Profiles in Hermes are fully isolated environments. Each profile gets its own:

~/.hermes/profiles/<name>/config.yaml
~/.hermes/profiles/<name>/.env
~/.hermes/profiles/<name>/skills/
~/.hermes/profiles/<name>/state.db (session store)
~/.hermes/profiles/<name>/memories/
~/.hermes/profiles/<name>/cron/

Memory Limits That Matter

| Limit | Value | What Happens When Hit | |-------|-------|----------------------| | Profile memory (tool) | ~2,200 characters per store | New memory(add) requests are rejected until you free space. Use batch operations to atomically replace stale entries with new ones. | | User profile | ~1,375 characters | Same as memory — separate store, separate budget. For facts about who the user is vs. what the agent knows. | | SOUL.md | 20,000 characters | Head + tail truncation. Middle gets dropped silently. | | Project context files | 20,000 characters each | Same head + tail truncation. | | SKILL.md per skill | 100,000 characters | Enforced by validator. Hit it and the skill silently fails to load. Aim for 8-14k. | | Skill description | 1,024 characters | Enforced by validator. Descriptions longer than this fail to register. | | Config file | No hard limit | But large configs slow startup — keep it lean. | | Session transcript | Configurable via compression.threshold | At ~50% of context window, Hermes auto-compresses older turns. Target ratio is 20%. |

How to Manage Memory When It's Full

The memory tool supports batch operations — pass an array of add, replace, and remove operations in a single call. The budget is checked only on the final result, so you can remove stale entries and add new ones together, even if the add alone would overflow.

# Pseudocode — the agent does this internally
memory(
    operations=[
        {"action": "remove", "content": "old_stale_fact_about_something"},
        {"action": "add",     "content": "new_important_fact"},
    ],
    target="memory"
)

This is the escape hatch when memory is full. Don't wade through deleting entries one by one — use the batch mode.

Cross-Profile Isolation

Profiles are sandboxed. The cross-profile write guard blocks profile A from modifying profile B's skills, plugins, cron jobs, or memories unless you explicitly pass cross_profile=True. This prevents accidental contamination between personal and work profiles, or between development and production instances.

When to Create a New Profile

You want a work and personal agent with different configs
You're testing a new model provider without disrupting your main setup
You want different skill catalogs for different domains
You're running multiple agents that should never share state

hermes profile create work --clone-from default
hermes profile use work

5. Other Features Worth Knowing

Once you've got Discord running with a custom SOUL.md persona, here's what else Hermes brings to the table.

Skills (Procedural Memory)

Skills are how Hermes learns from experience. When it solves a complex problem, discovers a workflow, or gets corrected, it can save that approach as a skill document that loads into future sessions.

hermes skills list          # what's installed
hermes skills install ID    # install from the catalog
hermes skills browse        # browse available skills

Skills accumulate over time and make the agent better at your specific tasks and environment. Think of them as reusable procedures — not just documentation, but executable knowledge that changes how the agent behaves.

Cron Jobs (Scheduled Tasks)

Hermes has a built-in scheduler that runs tasks on a timer and delivers results to Discord, Telegram, or wherever you've connected it.

hermes cron create "every day 10am" --prompt "Summarize today's tech news"
hermes cron list
hermes cron pause <job_id>

Jobs can run LLM-driven prompts or execute scripts (watchdog pattern) — perfect for daily briefings, status checks, or monitoring tasks that get pushed to your Discord.

Delegation (Subagents)

For complex tasks, Hermes can spawn subagents that work in isolated contexts with their own terminal sessions and toolsets. Results re-enter the conversation when they finish.

This is useful for:

Parallel research tasks
Multi-file code generation
Tasks that would flood your context with intermediate data

Up to 3 concurrent subagents per session by default (configurable).

Session Search

Hermes keeps a full SQLite search index of all past conversations with FTS5-backed full-text search. Available as a tool during any session:

Discovery: search by keyword across all past sessions
Scroll: read around a specific message in a past conversation
Browse: list recent sessions without searching

It's effectively free — no auxiliary LLM calls, no extra tokens spent.

Project Context Files (`.hermes.md` / `AGENTS.md` / `CLAUDE.md`)

While SOUL.md handles identity, project context files handle project rules. Hermes auto-loads these from your working directory:

| File | Scope | When to Use | |------|-------|-------------| | SOUL.md | Global, always loaded | Agent identity and voice | | .hermes.md | Walks up to git root | Hermes-specific project rules | | AGENTS.md | Cwd only | Portable agent rules (works with Claude Code, Codex, etc.) | | CLAUDE.md | Cwd only | Same as AGENTS.md, Claude-flavored |

Gateway Platforms

Beyond Discord, Hermes connects to 20+ platforms:

Telegram, Slack, WhatsApp (Baileys + Business Cloud API), iMessage (Photon), Signal, Email (SMTP/IMAP), SMS, Matrix, Mattermost, Microsoft Teams, LINE, SimpleX, ntfy, Google Chat, Home Assistant, DingTalk, Feishu, WeCom, WeChat, Raft (agent network), API Server, Webhooks.

One agent, many surfaces. The same session state follows you from Discord to terminal to desktop app.

Putting It All Together

Here's the setup flow in a nutshell:

1. Install Hermes        →  curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
2. Pick your model       →  hermes model
3. Write your SOUL.md    →  ~/.hermes/SOUL.md (identity + voice)
4. Create Discord bot    →  Developer Portal → New Application → Bot
5. Enable Message Intent →  Privileged Gateway Intents → Message Content Intent
6. Configure gateway     →  hermes gateway setup (paste bot token)
7. Start the gateway     →  hermes gateway run
8. Set home channel      →  /sethome in Discord
9. Add skills            →  hermes skills browse
10. Schedule tasks       →  hermes cron create "every day 10am" --prompt "..."

You're now running an AI agent that follows you from terminal to Discord,
remembers who you are, learns from experience, and gets better over time.

Ready to build your own AI-powered automation stack? Whether you want Hermes Agent integrated with your team's Discord, a custom AI assistant tailored to your workflow, or expert guidance on setting up multi-platform agent systems — we're here to help.

Contact Vistaran's team today for a free consultation. We'll architect, deploy, and manage AI agents that actually work with your existing tools, so you can focus on building while the automation runs in the background.