Set Up a Personal AI Agent with Hermes

Install a self-improving AI agent that remembers you across sessions.

Introduction

30 Second Summary

Imagine having a personal assistant that lives on your computer, remembers everything you tell it, and gets better at helping you over time. That's what an AI agent can do.

In this project, you will install and configure Hermes Agent on your Mac. It's a free, open-source AI agent that remembers your preferences across sessions and builds reusable skills from experience.

What You'll Build

A fully configured personal AI agent running locally on your Mac, connected to Hugging Face's free inference tier, with persistent memory and a custom skill you taught it.

By the end of this project, you'll have:

A working Hermes Agent installation connected to Hugging Face's free inference for zero-cost AI conversations.
Persistent memory entries the agent saved about you and your environment, proving it remembers across sessions.
A custom skill the agent created from a task you walked it through, turning a one-off workflow into a reusable command.
Secret Mission: Connect Hermes to Telegram so you can message your agent from your phone.

Are there any prerequisites?

You need a Mac with Git installed. The Hermes installer handles everything else automatically. You'll also create a free Hugging Face account during setup.

Install Hermes Agent

Before your AI agent can remember anything or learn new skills, it needs a home on your machine. Hermes Agent is an open-source, self-improving agent by Nous Research that lives entirely on your Mac.

In this step, you'll install Hermes using a single command that handles all dependencies automatically. You'll then verify everything is working before moving on to connect it to a language model.

In this step, get ready to:

Run the one-line Hermes installer.
Reload your shell and verify the installation.
Understand where Hermes lives on your machine.

Run the Hermes installer

The Hermes installer is a single shell script that detects your system, downloads the source code, sets up a Python virtual environment, installs Node.js, and creates the global hermes command. The only prerequisite on macOS is Git, which you already have.

Press Cmd+Space to open Spotlight Search.
Type Terminal and press Enter to open it.
Install Hermes Agent by running this command:

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

What does this command do?

curl -fsSL downloads the install script silently from the Hermes website. Piping it to bash runs the script immediately.

The script automatically installs Python 3.11, Node.js v22, ripgrep, ffmpeg, a virtual environment, and the global hermes command. You do not need to install any of these manually.

The installer takes 1-2 minutes to finish. You'll see progress messages as it detects and installs each component.

Seeing a macOS dialog about Command Line Tools?

If a system dialog pops up asking you to install Apple Command Line Tools, click Install and accept the license. Once it finishes, re-run the installer command above.

🙋‍♀️ Seeing permission denied errors?

Do not use sudo with the installer. It installs to ~/.local/bin, which does not require root access. If you previously installed with sudo, remove the old binary first, then re-run the standard installer.

help me fix a permission denied error during Hermes Agent installation on macOS

Reload your shell and verify

The installer adds ~/.local/bin to your PATH, but your current Terminal session doesn't know about it yet. You need to reload your shell configuration so the hermes command becomes available.

Reload your shell by running this command:

source ~/.zshrc

Confirm Hermes is installed by checking the version:

hermes --version

You should see a version number printed (e.g. v2026.6.19 or similar).
Run the built-in diagnostic tool to check for any issues:

hermes doctor

You should see a summary of your environment with no critical errors. Warnings about missing provider configuration are expected at this stage.

Seeing hermes: command not found?

Your shell hasn't picked up the updated PATH. Try opening a brand new Terminal window instead of reloading. If it still doesn't work, verify the install location by running ls ~/.local/bin/hermes.

If the file exists but the command isn't found, manually add the PATH by running:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

help me fix hermes command not found after installation on macOS

Understand the install layout

Now that Hermes is installed, it helps to know where everything lives on your machine. This makes troubleshooting easier later if you need to find config files or memory data.

Where does Hermes live?

~/.hermes/hermes-agent/ contains the source code and virtual environment.
~/.local/bin/hermes is a symlink that makes the hermes command available globally.
~/.hermes/ is the root for all Hermes data: configuration, memory, skills, and session history.

Everything is contained within your home directory. Nothing runs in the background, and there are no ongoing costs from the installation itself.

Your agent is installed and ready. Next up, you'll connect it to a free language model so it can actually think and respond.

Connect to Hugging Face

Hermes Agent is installed, but it needs a brain. On its own, Hermes is just a shell that orchestrates tools and memory. It relies on an external LLM to generate responses.

In this step, you will connect Hermes to Hugging Face as its free LLM provider. Hugging Face gives every free account $0.10 per month of inference credit, which is more than enough to complete this project.

In this step, get ready to:

Create a Hugging Face account and API token.
Configure Hermes to use Hugging Face as its LLM provider.
Verify the connection works with a test prompt.

Create a Hugging Face account and token

Hermes needs an API token to authenticate with Hugging Face's inference servers. You will create a free account and generate a fine-grained token with the correct permission.

Open your browser and go to huggingface.co.
Click Sign Up to create a free account (or sign in if you already have one).
Once signed in, navigate to huggingface.co/settings/tokens in your browser.
Click Create new token.
Select Fine-grained as the token type.
Give your token a name (e.g. hermes-agent).
Under permissions, enable Make calls to Inference Providers.
Click Create token.
Copy the token immediately. You will not be able to see it again after leaving this page.

Why a fine-grained token?

Fine-grained tokens let you grant only the specific permissions an app needs. By enabling only the inference permission, your token cannot accidentally create or delete repositories on your account.

🙋‍♀️ Don't see the permission option?

Make sure you selected Fine-grained (not "Read" or "Write") as the token type. The inference permission only appears on fine-grained tokens.

help me find the Make calls to Inference Providers permission on Hugging Face

Configure Hermes to use Hugging Face

Hermes has a built-in setup wizard that walks you through choosing a provider and model. The wizard saves your token to a local config file so you never have to paste it again.

Launch the model configuration wizard by running this command:

hermes model

What does this command do?

The hermes model command opens an interactive wizard that lets you pick an LLM provider, enter your credentials, and choose a model. Your selections are saved to ~/.hermes/.env so Hermes can use them in every future session.

The wizard will present a list of providers. Select Hugging Face from the list.
When prompted for your token, paste the token you copied from the previous substep.
The wizard will show available models. Select Qwen/Qwen3.5-32B.

Why this model?

Hermes requires a model with at least 64,000 tokens of context. Models with smaller windows are rejected at startup. Qwen/Qwen3.5-32B meets this requirement while staying token-efficient on the free tier's $0.10 monthly credit.

Once the wizard finishes, your token is saved as HF_TOKEN in ~/.hermes/.env. You will not need to enter it again.

Wizard not showing Hugging Face?

Make sure you are running hermes model outside of a chat session. If you are inside a session, type /quit first, then run the command from your regular terminal prompt.

help me troubleshoot the hermes model command not showing providers

Verify the connection works

Time to confirm that Hermes can actually talk to Hugging Face. You will start a chat session and send a simple test message.

Start a chat session by running:

hermes

Type the following prompt and press Enter:

What's 2 + 2?

Wait for the agent to respond. You should see an answer (4) along with a welcome banner showing your chosen model and provider.
Type /quit and press Enter to exit the session.

Seeing an authentication error?

If Hermes responds with a 403 or permission error, your token is missing the inference permission. Go back to huggingface.co/settings/tokens, delete the old token, and create a new fine-grained token with the Make calls to Inference Providers permission enabled.

If you see a timeout or connection error, check that your internet connection is active. Hugging Face inference runs on remote servers.

help me fix the Hermes authentication error with Hugging Face

Your agent now has a working brain. Next up, you will put it through its paces by exploring its terminal tools and multi-turn conversation abilities.

Explore Agent Capabilities

In the previous step, you connected Hermes to Hugging Face and confirmed it can respond to messages.

A chatbot that answers questions is useful, but Hermes is an agent. That means it can take actions on your behalf, like running terminal commands to inspect your system.

In this step, you'll have a real conversation with Hermes, watch it use tools, and test whether it keeps context across sessions.

In this step, get ready to:

Use the agent's terminal tools to inspect your system.
Test multi-turn context and slash commands.
Exit and resume a session to verify conversation persistence.

Start a chat and use terminal tools

Hermes has access to your terminal as a tool. When you ask it something that requires system information, it can run shell commands on your behalf and report the results.

Start a new chat session by running this command:

hermes

The Hermes chat interface opens in your terminal. You'll see a welcome banner showing your model and provider.

Type the following message and press Enter:

What's in my home directory? Show me the top 5 largest folders.

Watch what happens next. The agent uses its terminal tool to run commands like du or ls on your behalf, then summarizes the results in natural language.

What is a terminal tool?

Unlike a regular chatbot that can only generate text, an AI agent has tools it can call to interact with the real world. Hermes's terminal tool lets it execute shell commands on your machine.

You'll see the commands it runs displayed in the chat. This transparency lets you verify what the agent is doing before it reports results.

Ask a follow-up question about something the agent found. For example, if it found a large folder, ask what's inside it.

The agent uses the context from its first answer to understand your follow-up without you needing to repeat anything.

Agent not running commands?

If the agent gives a generic answer without actually running terminal commands, try rephrasing your prompt to be more specific. For example, ask "Run a command to show me the 5 largest directories in my home folder."

If you see an error about the model or provider, your Hugging Face token may have expired or run out of credit. Run hermes doctor to check.

Help me troubleshoot why Hermes isn't using its terminal tool when I ask about my file system.

Test multi-turn context and slash commands

Hermes has built-in slash commands that let you control the agent's behavior without leaving the chat session.

In the same session, ask the agent to explain something it just did in simpler terms. This tests whether it remembers the full conversation context.
Type /tools and press Enter to see the list of tools available to your agent.
Type /help and press Enter to see all available slash commands.
Type /personality pirate and press Enter to change the agent's personality.
Ask the agent another question and notice how its tone has changed.

What are slash commands?

Slash commands are typed directly into the chat and start with /. They control Hermes itself rather than sending a message to the LLM.

For example, /tools lists what the agent can do, /help shows all commands, and /personality changes how the agent talks to you. You'll use more slash commands in later steps.

End the session and resume it

Hermes saves your sessions automatically. You can exit and pick up exactly where you left off later.

Type /quit and press Enter to exit the session.

You're back at your normal terminal prompt. The session is saved to disk.

Resume your last session by running this command:

hermes --continue

What does this command do?

The --continue flag (or its shorthand -c) tells Hermes to reload the most recent session instead of starting a fresh one. The full conversation history is restored.

Scroll up in the chat to confirm your earlier messages and the agent's responses are all present.
Ask the agent to summarize what you've talked about so far. It should reference the terminal commands and folder sizes from earlier.
Type /quit to exit the session again.

Session not resuming?

Make sure you exited cleanly with /quit rather than closing the terminal window. Closing the window may not save the session properly.

Check that session files exist at ~/.hermes/sessions/. If the folder is empty, your previous session was not saved.

Help me figure out why hermes --continue isn't restoring my previous conversation.

Your agent can take real actions, hold a conversation across multiple turns, and pick up right where it left off. Next up, you'll see how Hermes goes even further by remembering facts about you across completely separate sessions.

Experience Persistent Memory

In the last step, you explored how Hermes uses terminal tools and handles multi-turn conversations. But when you start a brand new session, does the agent remember anything about you?

Most chatbots start from scratch every time. Hermes Agent is different. It has a persistent memory system that saves what it learns about you to disk. In this step, you'll teach it about yourself and watch that knowledge carry across completely separate sessions.

In this step, get ready to:

Tell Hermes about yourself so it saves your details to memory.
Verify the agent remembers you across separate sessions.
Inspect the memory files on disk to see how persistence works.

Tell it about yourself

Hermes automatically saves information to memory when it learns something useful about you. You don't need to run a special command. Just tell it who you are in natural language.

Start a fresh session by running this command:

hermes

Once the session starts, introduce yourself by typing something like:

My name is Alex, I'm a beginner developer, and I prefer concise explanations over verbose ones

Make it your own

Use your real name, your actual role, and a genuine preference. The agent saves whatever you share, so make it useful for future sessions.

Watch the agent's response. You may see a notification like "Memory updated" confirming it saved your details.

How does memory auto-save work?

Hermes saves memory proactively whenever it learns user preferences, environment facts, corrections, or conventions. You don't need to ask it to remember something.

Memory changes persist to disk immediately but only appear in the system prompt at the start of the next session. This is the "frozen snapshot" design. The agent always starts a session with a consistent view of what it knows.

Verify memory persists across sessions

Saving memory in a single session is only half the picture. The real test is whether the agent remembers you in a completely new session.

Exit the current session by typing:

/quit

Start a brand new session by running:

hermes

Ask the agent what it remembers by typing:

What do you know about me?

The agent should recall your name, role, and preferences without you repeating them. This information came from the memory files it saved in the previous session.

Agent doesn't remember you?

Make sure you started a fresh session (not resumed with hermes --continue). The point of this test is to prove memory works across separate sessions, not just within a continued one.

If the agent still doesn't remember, it may not have saved your details in the first session. Go back, start a new session, re-introduce yourself, and look for the memory-updated confirmation before quitting.

Help me debug my Hermes memory not persisting across sessions

Exit this session by typing /quit.

Inspect memory on disk

Hermes stores its memory as plain Markdown files on your machine. You can read them directly to see exactly what the agent knows.

View your user profile by running this command:

cat ~/.hermes/memories/USER.md

You should see entries matching what you told the agent. Your name, role, and preferences are stored here.

View the agent's personal notes by running:

cat ~/.hermes/memories/MEMORY.md

This file contains the agent's own observations about your environment and anything else it decided was worth remembering.

Why are these files so small?

USER.md is capped at 1,375 characters and MEMORY.md at 2,200 characters. Both files are injected into the system prompt at the start of every session as a frozen snapshot.

Keeping them small ensures the agent's context window isn't wasted on memory. The agent learns to be selective about what it saves.

🙋‍♀️ Files don't exist?

If cat says "No such file or directory", the agent didn't save anything in your earlier session. Start a new hermes session, explicitly share your name and preferences, and confirm you see a memory-updated notification before exiting.

Help me troubleshoot missing Hermes memory files

Your agent now knows who you are and carries that knowledge forward into every future conversation. Next up, you'll teach it a reusable skill so it can do more than just remember.

Teach It a Skill

Your agent now remembers who you are and what you prefer. That's powerful, but memory only stores facts. What about procedures?

Hermes has a separate system for reusable workflows called skills. In this step, you'll teach the agent a multi-step procedure using the /learn command, then invoke it like any other slash command.

In this step, get ready to:

Teach the agent a reusable skill with the /learn command.
Invoke your new skill as a slash command and watch it work.
Verify the skill file on disk.

Teach a skill with /learn

Memory stores facts about you. Skills store procedures the agent can repeat on demand. The /learn command is the fastest way to create a skill. You describe a workflow, and the agent authors a structured SKILL.md file that captures each step.

Start a new Hermes session by running this command:

hermes

Once the session starts, teach the agent a new skill by typing this command:

/learn how to create a new directory, initialize a git repo inside it, and make a first commit with a README

Wait for the agent to finish authoring the skill. You'll see a confirmation message when it saves.

What happens when you use /learn?

The agent takes your description and authors a SKILL.md file following its internal standards. This file contains structured sections like a procedure, pitfalls, and a verification checklist.

Once saved, the skill automatically becomes a slash command you can invoke by name. No manual file editing required.

💡 Why skills instead of just asking again?

You could ask the agent to do the same task every time. Skills are better for repeatable workflows because they capture the exact procedure in a file on disk. The agent loads the skill's instructions directly rather than re-deriving the steps from scratch each time.

Invoke your new skill

Every installed skill becomes a slash command automatically. You can see your full list and then run your new skill to watch it work.

View your installed skills by typing this command in the same session:

/skills

Look for your new skill in the list. It will appear with the name the agent chose (likely something like git-init-project).
Invoke your skill by typing its slash command name with a project name:

/git-init-project set up a project called my-test-app

Watch the agent follow the skill's procedure to create a directory, initialize a git repo, create a README, and make a first commit.

What if my skill has a different name?

The agent picks a name based on your description. If it chose something different from git-init-project, use whatever name appeared in the /skills list. The name is always lowercase with hyphens.

🙋‍♀️ Skill not appearing in /skills?

If the skill doesn't show up, the agent may still be authoring it. Wait a moment and try /skills again. If it still doesn't appear, exit with /quit and start a new session. Skills are cached at session start, so a new skill created mid-session may need a fresh session to show in the list.

Help me troubleshoot why my skill isn't appearing in the /skills list after using /learn.

Verify the skill on disk

Skills are saved as files under ~/.hermes/skills/. Each skill gets its own directory with a SKILL.md file inside. Let's confirm everything landed correctly.

Exit your Hermes session by typing /quit.
Browse the skills directory by running this command:

ls ~/.hermes/skills/

You should see a directory matching your skill's name (e.g., git-init-project).
View the SKILL.md file the agent authored by running:

cat ~/.hermes/skills/git-init-project/SKILL.md

You should see a structured markdown file with YAML frontmatter at the top and sections like Procedure, Pitfalls, and Verification.

What's inside a SKILL.md?

The file starts with YAML frontmatter containing the skill's name, description, and metadata. Below that are structured sections the agent follows when you invoke the skill.

When to Use tells the agent when this skill is relevant.
Procedure lists the exact steps to follow.
Pitfalls documents common failure modes.
Verification describes how to confirm the skill worked.

🙋‍♀️ Directory path looks different?

If the agent chose a different name, substitute it in the cat command. Run ls ~/.hermes/skills/ to see the exact directory name the agent used.

Help me find my skill file on disk.

Secret mission

Connect Hermes to Telegram

Your agent lives in the terminal right now. What if you could message it from your phone instead? In this secret mission, you'll connect Hermes to Telegram and chat with your AI agent from anywhere.

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs entirely locally, so there are no ongoing costs.

Resources you used:

Hermes Agent installation at ~/.hermes/ (includes config, memory, skills, and sessions).
Hermes symlink at ~/.local/bin/hermes.
Test project directory at ~/my-test-app/.
Hugging Face API token (free tier, no credit card required).
Telegram bot via @BotFather (if you completed the Secret Mission).

Keep everything running

No action needed. Choose this if you plan to keep using Hermes as your personal agent.

Hermes runs locally with no ongoing charges. Your $0.10/month Hugging Face credit refreshes automatically.
Nothing runs in the background unless you manually started the Telegram gateway.
Your memory, skills, and sessions persist in ~/.hermes/ ready for your next hermes session.

Pause - I'll come back to this later

Shut down any running processes to free up your terminal. Your files stay on disk for next time.

If the Telegram gateway is running, press Ctrl+C in its terminal window to stop it.
If you have an active Hermes chat session, type /quit to exit.
All your memory, skills, and sessions remain saved in ~/.hermes/. Run hermes anytime to pick up where you left off.

Delete - I don't want to use this again

Remove all project resources and start fresh. This deletes your memory, skills, and session history permanently.

If the Telegram gateway is running, press Ctrl+C to stop it first.
Remove the entire Hermes installation (config, memory, skills, sessions) by running:

rm -rf ~/.hermes

Remove the Hermes symlink by running:

rm ~/.local/bin/hermes

Remove the test project directory created by the skill invocation by running:

rm -rf ~/my-test-app

Revoke your Hugging Face token: go to huggingface.co/settings/tokens, find your token, and click the delete button next to it.
If you completed the Secret Mission: open Telegram, message @BotFather, and delete your bot.

Nice Work!

You just set up a self-improving AI agent that lives on your Mac, remembers what you tell it, and builds reusable skills from experience.

You've learned how to:

Install and connect Hermes Agent to a free LLM provider (Hugging Face) and run real AI agent conversations from your terminal.
Experience persistent memory that lets the agent recall your name, preferences, and environment across completely separate sessions.
Teach the agent a reusable skill with /learn and invoke it as a slash command to automate a real workflow.
Secret Mission: Connect your agent to Telegram so you can message it from your phone with full memory and skills intact.

Ready to quiz yourself?