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.

Hermes runs natively on Linux, macOS, and Windows -- no VMs, no Docker, no compromises. Pick your platform below.

Linux, macOS, or WSL2 -- open a terminal and run:

Windows (native) -- open PowerShell and run:

The Windows installer handles everything: Python, Node.js, a portable Git Bash, and every other dependency. No admin rights needed. Everything lands in a single folder (%LOCALAPPDATA%\hermes) and won't interfere with any Python or Git you already have.

If PowerShell feels unfamiliar: right-click the Start button, pick "Windows PowerShell" or "Terminal," paste that one-liner, and press Enter. The installer walks you through the rest.

After installation (all platforms):

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.

1. Click New Application, give it a name (e.g., "Hermes Agent"), and create it.
2. Go to Bot in the left sidebar and click Add Bot.
3. Under the Token section, click Reset Token and copy it. This is your bot token — treat it like a password.
4. 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:

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

Step 4: Start the Gateway

To run it as a background service:

Check status any time:

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

Create it with any text editor:

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:

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

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.

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

---

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.

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.

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:

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:

---

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.