What is Hermes Agent? How it works, its structure and use cases

Hermes Agent is an open-source AI agent from Nous Research that runs on your own computer or server, uses tools to carry out tasks and remembers what it learned. This guide explains why to use it, its folder structure, how it works and learns, cron jobs, limits and use cases.

By Rahmatullah Musawi · 4 October 2026 · updated 8 November 2026 · 14 min read · sources checked 4 October 2026

Key points

Hermes Agent is an open-source AI agent framework by Nous Research: it works with the AI model you choose and uses tools to carry out tasks, on your own computer or a server.[1] [2]
An agent's settings, identity file, memory, skills and cron jobs sit in one home folder.[3]
It learns between sessions: memory holds short facts, skills hold step-by-step procedures, and the agent writes both itself.[4] [5]
Cron jobs let it work without you: a job has a schedule, a prompt and a delivery target, and each run starts in a fresh session.[6]

Hermes Agent can live on your own computer or on a cloud server, and you can write to it from a chat app such as Telegram while it works on that server.²

This guide covers what Hermes Agent is and why to use it, the folder it lives in, how it works and learns, cron jobs, what it connects to, its limits, its use cases and the first steps.

What Hermes Agent is

Hermes Agent is an open-source AI agent framework by Nous Research.¹ It belongs to the same category as Claude Code from Anthropic, Codex from OpenAI and OpenClaw: agents that carry out coding and other tasks on their own and act on your system by calling tools.¹ You use it in your terminal, in a desktop app, in messaging apps and in code editors.¹

You choose the AI model: Hermes Agent works with any OpenAI-compatible API, and the supported providers include OpenRouter, OpenAI, Anthropic and Google, as well as local models.⁷ When the model asks for a tool, Hermes Agent runs it and gives the result back to the model.⁸ The tools are functions that extend what the agent can do, from web search, terminal commands and file editing to memory and scheduled tasks.⁹ With a model that cannot call tools, Hermes Agent can only chat and takes no actions.¹⁰

Nous Research, the lab behind the Hermes, Nomos and Psyche models, describes Hermes Agent as an autonomous agent that gets more capable the longer it runs: not a coding copilot tied to an editor, and not a chatbot built around a single API.² The map shows the six parts of Hermes Agent that this guide works with: the interfaces, the agent core, the AI model, the tools, the storage and the skills.

Hermes Agent at a glance: its parts and how they connect

A task enters through an interface and reaches the agent core. A dashed line is the model's choice.

InterfacesThe terminal, the desktop app, the gateway for chat apps, code editors and an API server all use the same agent core.^11 12 So does the scheduler for cron jobs, which runs inside the gateway.^11 6
Agent coreOne class, AIAgent, builds the prompt, selects the model provider and runs the tools the model asks for.¹¹
AI modelEach request goes to the provider you configured. If that provider fails, the core can switch to a backup provider from your settings.⁸
ToolsEvery tool registers in one central registry.¹¹ MCP servers add more tools.⁹
StorageSettings, memory, skills, sessions and cron jobs are stored in the folder ~/.hermes/.³
SkillsThe prompt contains a list of the installed skills. When a task matches one, the model loads its full text with the tool skill_view.^13 5

Why use Hermes Agent

This guide picks six features as the reasons to choose Hermes Agent over a chat assistant or a coding tool in an editor.

Six reasons to use Hermes Agent

Each reason is a documented feature, in short.

It learnsIt saves facts to memory and turns solved tasks into reusable skills, so a later session starts with what an earlier one learned.²

It is not tied to one modelYou choose the model provider, your own endpoint included, and switch it with one command, without code changes.¹⁴

It is where you areOne gateway serves 20+ platforms, among them Telegram, Discord, Slack, WhatsApp, Signal and email.²

It works without youCron jobs run tasks at set times and deliver the result to any connected platform.²

It runs anywhereIt runs on a laptop, on a low-cost server, or on serverless infrastructure such as Daytona and Modal, which hibernates when idle and costs nearly nothing then.²

It is yoursThe software is open source under the MIT license, collects no telemetry and stores conversations, memory and skills on your machine.⁷

Inside the Hermes Agent folder

The settings, identity, memory, skills, cron jobs and logs of one agent sit in a single home folder, ~/.hermes/.³ After the script installation on Linux or macOS, the program code is by default in the same folder, in hermes-agent/. On Windows the home folder is %LOCALAPPDATA%\hermes\.¹⁵

The home folder of Hermes Agent, with one skill and the program code

An arrow that points down marks a folder that is opened; the entries under it lie in that folder.^{3 4 5 6 11 16 15}

A profile is a further home folder under ~/.hermes/profiles/, with its own settings, identity, memory, skills and cron jobs. Profiles let several independent agents run on one machine, for example one for coding and one for research.¹⁶

How Hermes Agent works

Every request runs through the same loop: Hermes Agent builds the prompt, calls the model, runs the tools the model asks for, and repeats this until the model answers in text.⁸

TopicWhat is an agent harness? How it works, its parts and use cases describes the loop that every harness runs, with its permission check, its context management and its hooks.

A message sent from a chat app such as Telegram first reaches the gateway. It checks that the sender is allowed, finds the matching session and then starts the agent.¹¹

One request, from message to reply

Follow the arrows from top to bottom. A dashed line is the model's choice.

Build the promptThe system prompt is put together from the identity file SOUL.md, project files, the memory entries and the list of skills.¹³ It stays the same during a conversation, apart from explicit actions such as switching the model.¹¹
Shorten if neededWhen the conversation grows past a set share of the model's context window, the middle turns are replaced by a summary and the latest messages stay as they are.⁸
Call the modelThe request goes to the provider. A new message from you can interrupt it.⁸
Run the toolsIf the model asks for tools, Hermes Agent runs them and adds the results to the conversation. Several tool calls run at the same time, unless one of them needs your input.⁸
Save and replyWhen the model answers in text, the messages are saved to the session database, memory changes are written to disk and the answer is returned.⁸

How Hermes Agent learns

Hermes Agent carries knowledge from one session to the next in three stores: memory, skills and the record of past sessions.^4 5 Nous Research calls it a self-improving agent, because it creates skills from experience and saves knowledge on its own.²

What Hermes Agent keeps between two sessions

A solid line happens every time. A dashed line is the model's choice.

Memory holds short factsTwo files with default size limits: MEMORY.md for the agent's notes about the environment (2,200 characters) and USER.md for your preferences (1,375 characters). Both are placed in the prompt when a session starts.⁴
Skills hold proceduresWhen the agent has worked out a task with several steps, it can save the steps as a skill. The prompt contains only the list of skills, and the full text of a skill is loaded when a task needs it.^5 13
Sessions hold everything saidEvery conversation is kept. The agent searches the stored sessions with a tool when it needs something from an earlier conversation.⁴

A preference such as short answers belongs in memory, and the steps of a task that comes back, such as collecting the daily news, belong in a skill.^4 5

TopicWhat is Hindsight? Agent memory, knowledge graph and use cases describes a memory system that stores facts in a database and links them through entities. TopicKeyword, semantic and knowledge graph search: hybrid search explained describes how AI agents, Hermes Agent among them, search what they have stored.

Saving happens in two ways. The agent can save during a task, and a background review after a turn can add a memory entry or update a skill. Two optional settings, off by default, one for memory and one for skills, hold these writes until you confirm them.^4 5

Skills are also cleaned up. A maintenance pass called the curator looks after the skills that the background review created: by default it marks a skill as stale after 14 days without use and archives it after 30 days, and it never deletes one automatically.¹⁷ Skills are compatible with the open agentskills.io standard, and more can be installed from online registries, each after a security scan.⁵

Cron jobs in Hermes Agent

A cron job is a task that Hermes Agent runs on a schedule without being asked: a daily report, a nightly backup or a weekly audit.¹⁴ A job can be created in chat with /cron add, on the command line with hermes cron create, or by asking in plain language, for example to send a summary of AI news to Telegram every morning.⁶

Jobs are stored in the file ~/.hermes/cron/jobs.json and survive updates and restarts.⁶ The table lists the six fields that this guide uses; the documentation has more.

Field	What it sets	Example from the documentation
Schedule	When the job runs.⁶	`every 2h`
Prompt	The task for the agent.⁶	`Check server status`
Skills	Skills that are loaded before the prompt runs. Optional.⁶	`blogwatcher`
Delivery	Where the answer goes.⁶	`telegram`
Repeat	How many times the job runs. By default a one-time job runs once and a recurring job runs until it is removed.⁶	`repeat=5`
Script	A script that runs before the agent or, in no-agent mode, in its place with no model call. Optional.⁶	`memory-watchdog.sh`

The diagram follows one run of a job.

One run of a cron job, from the scheduler to the delivery

Read from top to bottom.

The scheduler finds a due jobThe gateway runs the scheduler and checks every 60 seconds which jobs are due. Scheduled runs therefore fire only while the gateway is running.⁶
A fresh agent startsEach job runs in a new session without chat history, so its prompt has to contain everything the agent needs.⁶
Attached skills are loadedSkills attached to the job are loaded in order, before the prompt.⁶
The model uses toolsThe agent works with the toolset configured for cron jobs, and by default it cannot create, edit or remove cron jobs from inside a job.⁶ A dangerous command is blocked by default, because a cron job runs without a person to approve it.¹⁸
The answer is deliveredThe final answer goes to the chat the job came from, to a platform such as Telegram or to a local file. The output of job runs is also saved in ~/.hermes/cron/output/.⁶

A schedule can be written in five formats:

Format	Example	Meaning
Relative delay	`in 30m`	Runs once, in 30 minutes.⁶
Interval	`every 2h`	Runs every 2 hours.⁶
Day and time	`weekdays at 9am`	Runs on weekdays at 9:00 AM.⁶
Cron expression	`0 9 * * *`	Runs daily at 9:00 AM.⁶
ISO timestamp	`2026-03-15T09:00:00`	Runs once, at that date and time.⁶

Existing jobs are handled with list, pause, resume, run, edit and remove, in chat and on the command line.⁶ Two more details are worth knowing. A successful run whose final answer contains [SILENT] delivers nothing, which suits monitoring that should speak only when something is wrong; a failed run is always delivered.⁶ And one job can receive the latest output of another job as context.⁶

Tools, models and chat platforms

Hermes Agent connects to four kinds of things: model providers, tools, chat platforms and the places where its commands run.

What Hermes Agent connects to

One row per group, with a selection of its entries; the documentation lists more.^7 9 19

Chat platformsAll served by one gateway process.

TelegramDiscordSlackWhatsAppSignalEmailSMSMatrixMattermostMicrosoft TeamsHome AssistantLINE

Model providers and local serversAny OpenAI-compatible API works.

Nous PortalOpenRouterOpenAIAnthropicGooglez.aiKimiMiniMaxOllamavLLMllama.cpp

ToolsGrouped into toolsets, switched on or off per platform.

Web searchTerminalFilesBrowserVisionImage generationText to speechCode executionSubagentsMemoryCron jobsMCP servers

Where commands runThe seven environments of the terminal tool.

LocalDockerSSHSingularityModalDaytonaVercel Sandbox

In a project folder, Hermes Agent also loads instruction files such as AGENTS.md, CLAUDE.md or .cursorrules, which shape how it behaves in that project.²⁰

TopicWhat is MCP (Model Context Protocol)? How it works and its use cases describes how an MCP server offers tools to an AI application.

Security and limits

The security model of Hermes Agent has eight layers.¹⁸

The eight security layers of Hermes Agent

In the order of the security documentation.¹⁸

User authorizationWho may talk to the agent: lists of allowed users and pairing codes.

Dangerous command approvalA person confirms destructive operations.

File write safetyA list of protected paths and an optional sandbox for file writes.

Container isolationCommands can run in Docker, Singularity or Modal with hardened settings.

MCP credential filteringMCP servers run with isolated environment variables.

Context file scanningProject files are checked for prompt injection.

Cross-session isolationSessions cannot access each other's data or state.

Input sanitizationWorking-directory inputs of the terminal tool are validated.

In practice, eight points are worth knowing before the first real task:

Point	What to know
Context window	The model needs a context window of at least 64,000 tokens. Models with a smaller window are rejected at startup.²¹
Dangerous commands	A command that matches a list of dangerous patterns needs approval. In the default mode a helper model rates the risk: low-risk commands pass, dangerous ones are denied and unclear ones are shown to you. A few destructive commands, such as wiping the whole filesystem, are always blocked. When commands run in a container, these checks are skipped.¹⁸TopicJev explained shows the same three outcomes (approve, block, ask a person) with a fast model that answers yes/no questions.
Access from chat apps	By default, without a list of allowed users, every user is denied. You enter the allowed user IDs, or approve a one-time pairing code that the bot sends to a new user.¹⁸
Where commands run	By default commands run on your own machine. A Docker container isolates them, and the documentation recommends a remote server over SSH for security, because the agent then cannot change its own code.⁹
The gateway must run	The gateway, a background process, serves the chat apps and runs the cron jobs. A recurring job whose time passed while the gateway was down runs once when it is back.^19 6
Memory writes	A fact is saved only when the model really calls the memory tool. Small local models often say they saved something without doing it.⁴
Long chats	A chat in a messaging app is one continuous session. Starting a new one with `/new` after a finished task keeps the context short and cheap, and makes new memory entries visible to the agent.⁴
Several agents	Two agents must not share one home folder. Each agent gets its own profile.¹⁶

Hermes Agent use cases

The uses of Hermes Agent range from a coding assistant to the training of models.²² The table lists the documented use cases, how Hermes Agent covers each one and which parts do the work.

Use case	How Hermes Agent covers it	Parts used
Coding assistant in the terminal	Reads, edits and runs code in your project.²²	Terminal File tools
Chat assistant for one person or a team	The gateway keeps a separate session per chat, and several people can use the same agent.^19 7	Gateway Sessions
Scheduled reports and monitoring	Cron jobs run at set times and deliver the result to a chat.⁶	Cron Skills
Automation triggered by events	A webhook from a service such as GitHub starts an agent run, which can post a comment on a pull request.²³	Webhooks
Research and large tasks	The agent hands parts of a task to subagents that work in separate conversations. Only the final summary of each one returns.²⁴	Subagents
A team of specialist bots	In the desktop app, named bots each have their own model, memory and skills, share group chats and message each other.²⁵	Desktop app Profiles
Part of your own software	The agent can be used as a Python library, as an API server in the OpenAI format, or inside editors such as VS Code, Zed and JetBrains.^22 20	Python library API server
Training and evaluation data	Batch runs process hundreds or thousands of prompts in parallel and save the runs in a structured format for training data or evaluation.²⁰	Batch runs

First steps with Hermes Agent

This guide groups the setup into five steps. One rule applies to them: get one normal chat working first, and add the gateway, cron jobs and skills only after that.²¹

From installation to the first scheduled task

One row per step: what you run or type, and what it does.

StepYou run or typeWhat it does

1Install

the Hermes Desktop installer on macOS or Windows, or the one-line install script for the command line

Installs Hermes Agent.²¹

2Set up

hermes setup

Configures the model provider and the tools.²¹

3Chat

hermes

Starts a conversation in the terminal.¹⁴

4Connect a chat app

hermes gateway setup

Connects Telegram, Discord, Slack or another platform.²¹

5Automate

/cron add or a request in plain language

Creates a scheduled task.⁶

The table lists eight commands to start with. The ones that begin with a slash are typed inside a conversation, in the terminal and in chat apps alike.¹⁴

Command	What it does
`hermes model`	Chooses the model provider and the model.¹⁴
`hermes tools`	Sets which tools are enabled.¹⁴
`hermes gateway`	Starts the messaging gateway.¹⁴
`hermes doctor`	Diagnoses problems.¹⁴
`hermes update`	Updates to the latest version.¹⁴
`/new`	Starts a fresh conversation.¹⁴
`/model`	Changes the model inside a conversation.¹⁴
`/compress`	Compresses the context of a long conversation.¹⁴

Sources

Hermes Agent — Use, configure, theme, extend, and orchestrate Hermes Agent Hermes Agent docs
Hermes Agent Documentation Hermes Agent docs
Hermes Agent Configuration Hermes Agent docs
Persistent Memory Hermes Agent docs
Skills System Hermes Agent docs
Scheduled Tasks (Cron) Hermes Agent docs
FAQ & Troubleshooting Hermes Agent docs
Agent Loop Internals Hermes Agent docs
Tools & Toolsets Hermes Agent docs
Run Hermes Locally with Ollama — Zero API Cost Hermes Agent docs
Architecture Hermes Agent docs
Hermes Desktop Hermes Agent docs
Prompt Assembly Hermes Agent docs
NousResearch/hermes-agent: The agent that grows with you GitHub
Installation Hermes Agent docs
Profiles: Running Multiple Agents Hermes Agent docs
Curator Hermes Agent docs
Security Hermes Agent docs
Messaging Gateway Hermes Agent docs
Features Overview Hermes Agent docs
Hermes Agent Quickstart Hermes Agent docs
Learning Path Hermes Agent docs
Webhooks Hermes Agent docs
Subagent Delegation Hermes Agent docs
Bot Mode Hermes Agent docs

Written by Rahmatullah Musawi with the help of an AI assistant.