Hermes Agent Fundamentals — The Complete Course

Introduction

Picture this. You wake up, you haven't touched your computer yet, and your AI agent has already summarized your inbox, pulled the top three things in your industry worth knowing about this week, and flagged a server issue it detected overnight. You open your laptop, and the work is already started.

That's not a product pitch. That's what Hermes actually does — when you set it up right.

Most people's relationship with AI is: you open a chat window, you type something, you get an answer, you close the tab. The conversation is over. The next time you open that tab, it has no idea who you are or what you were working on. You start from zero every single time.

Hermes is different. It's not a chat window. It's an agent runtime — software that runs on your own machine, gives your AI a persistent identity, a memory that carries over between sessions, and the ability to act on a schedule or respond to messages even when you're not there.

This video is the full course. All nine lessons, top to bottom, nothing cut. By the end, you'll have a working Hermes agent with its own personality, project awareness, and memory. Let's get into it.

Who This Is For

This is for people who are already comfortable using AI tools and want to go deeper — developers, technical hobbyists, anyone who's thought "there has to be a better way to work with AI than opening a chat window every time."

You don't need to be an expert programmer. You do need to be comfortable running commands in a terminal and editing a text file. That's the baseline.

By the end of this, you'll have installed Hermes, configured it with your preferred model, given it a personality and project context, set up memory, and run through a real first-week workflow. The advanced track — scheduling, messaging platforms, multi-agent setups — comes after this. But everything we cover here works on its own, right now.

Chapter 1: What Is Hermes?

Let's start with the most important thing to understand: Hermes is not a chatbot wrapper.

That distinction matters more than it sounds. A chatbot answers questions in a window. An agent runtime — which is what Hermes is — runs persistent, autonomous agents on your own machine. Agents with their own identity. Their own memory. Their own ability to act on a schedule or in response to messages, without you having to initiate anything.

Think about the difference like this: a chatbot is a service desk you walk up to when you need something. An agent is a colleague who's already working on things, knows your projects, and checks in with updates.

The three core concepts — profiles, the gateway, and SOUL.md — are the building blocks of everything else in this course.

Let's run through each one briefly so you have a mental model before we get into the setup.

Profiles are isolated agent identities. Each one lives in its own directory under ~/.hermes/profiles/. Separate configuration, separate memory, separate skills. You can run multiple agents simultaneously — one for your development work, one for your content workflow, one that monitors your infrastructure. They don't share state unless you set that up intentionally.

The gateway is a background process that connects your Hermes agent to messaging platforms — Telegram, Discord, Slack. This is what enables your agent to receive messages and take action even when your terminal isn't open. You're not always going to be sitting at the keyboard prompting it. The gateway is how it operates independently.

SOUL.md and memory are how your agent maintains a consistent identity and remembers things across sessions. SOUL.md is the personality file — it defines the tone, the communication style, the way the agent presents itself. Memory is the running log of what the agent has learned about you and your environment through actual use.

Together, those three things — profiles for isolation, the gateway for reach, SOUL.md and memory for continuity — are what separate Hermes from a chat window with extra steps.

So what do people actually use it for? The list is broader than you'd expect.

Personal assistance is the obvious one — inbox summaries, task management, journaling, even things like fitness coaching or medication reminders. But it goes further.

Information retrieval at a schedule — agents that pull news summaries every morning, deliver curated content to you on a channel you already use, run research briefs before you need them.

Development workflows — code review automation, multi-agent coordination where one agent hands off to another, running local models for cost-sensitive tasks.

Business operations — ticket triage, lead generation, competitor analysis, CRM work that would otherwise eat hours every week.

Content creation — social posting automation, video research, generating outlines or drafts in your voice. If you've ever wished you could clone yourself for the repetitive creative work, this is the closest thing.

Home and infrastructure — smart home control, server monitoring, vehicle tracking.

And for the cost-conscious: running Hermes on a low-cost VPS with smart model routing is genuinely cheap. You're not locked into one expensive model for every task. You pick the right model for the job, and Hermes routes accordingly.

The track you're watching right now covers nine lessons. Here's where we're going:

We just finished the conceptual overview — you know what Hermes is.
Next: installation and your first live session.
Then: the CLI, daily usage, and the commands you'll use constantly.
Configuration — the config.yaml and .env files, profiles.
SOUL.md — giving your agent a real personality.
AGENTS.md — giving it project awareness so it knows your codebase or workflow.
The @ syntax — injecting context directly into your messages.
The memory system — how it learns and retains information across sessions.
And finally: putting it all together in a real first-week walkthrough.

Let's get it installed.

Chapter 2: Installing Hermes and Your First Session

Before you install anything, there's one thing you need to sort out first: model access.

Hermes does not come with AI model access built in. It's a runtime — it's the infrastructure that runs agents. The models themselves come from providers you sign up with separately. You'll need an API key from at least one provider before you can have a real conversation.

That said, there's a free path to get started. OpenRouter offers access to more than 20 models with no cost and no credit card required — including capable options like DeepSeek R1 and Llama 3.3 70B. Any model on OpenRouter with an ID ending in :free is zero cost. If you want to start without spending anything, that's the way in.

The only requirement for whichever provider you choose: at least 64,000 tokens of context. Major providers — Claude, GPT-4, Gemini, Qwen, DeepSeek — all exceed this. Just make sure whatever you pick clears that bar.

Now, installation. The prerequisites are minimal.

On macOS, Linux, and WSL2, the only thing you need pre-installed is Git. That's it. The installer handles everything else automatically — Python 3.11, Node.js v22, ripgrep, ffmpeg. You don't need to set those up yourself.

Pick your installation path based on your platform:

Linux, macOS, WSL2, or Android via Termux — the CLI path:

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

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

That source ~/.bashrc line after the curl command — don't skip it. This is the most common first-install complaint. The installer adds Hermes to your PATH, but your current terminal session doesn't know that until you reload your shell config. If you see "command not found" after installing, this is almost always why. Run source ~/.bashrc or source ~/.zshrc, or just open a new terminal window.

The second most common issue: outdated Python. Hermes requires Python 3.11 minimum. If your system shipped with an older version and the automatic installation didn't resolve it, you'll need to upgrade manually.

Configuring your model provider is next. Once Hermes is installed, run:

hermes model

This launches an interactive setup that walks you through provider selection. If you're a Nous Portal user, run:

hermes setup --portal

Your first session. Two commands to start:

hermes            # Classic interface
hermes --tui      # Modern terminal UI (recommended)

The TUI is nicer. Use that.

When you start, test something specific and measurable rather than just saying "hello." Ask it to check the weather, summarize a webpage, or look something up. You want to verify that it's actually using tools, not just generating text. A successful first session means: you see your model and provider in the startup banner, the agent responds without errors, and it can do multi-turn conversation coherently.

Sessions persist after you close the terminal. To pick up where you left off:

hermes --continue    # or hermes -c

When you reconnect, ask something that only the prior conversation would have context for. If it knows, the session resumed correctly.

Where your configuration lives — two locations, each for a different type of data:

~/.hermes/.env — API keys and secrets
~/.hermes/config.yaml — model selection and behavior settings

The principle is simple: secrets in .env, everything else in config.yaml. You can edit these files directly or use command-line shortcuts:

hermes config set model anthropic/claude-opus-4.6
hermes config set OPENROUTER_API_KEY sk-or-...

Diagnostic commands to know before you need them:

hermes doctor                 # End-to-end configuration check
hermes sessions list          # View all saved conversations
hermes gateway status         # Check messaging platform connection

When something isn't working, hermes doctor is always the first move. It checks your entire installation and surfaces exactly what's misconfigured. Don't start manually debugging before running it.

You're installed. You've had a first conversation. Now let's talk about how to actually use this thing day to day.

Chapter 3: The CLI and Daily Driving Hermes

Once you're past the initial setup, most of your time with Hermes is spent in the CLI. There are a handful of flags and commands you'll use constantly — let's go through them.

-q — one-shot query. You ask something, you get an answer, the session ends. Useful for scripting or quick lookups you don't want to save to a session.

--model — override the model for a single run without changing your config. Great for testing a different model on a specific task.

--toolsets — selectively load certain tool groups. When you don't want the agent to use every tool available for a particular task.

-s — start with a specific session by name or ID.

-c or --continue — resumes your most recent session. This is the one you'll use most.

--resume — resumes a specific session by ID. Useful when you're juggling multiple conversations.

-w — opens an isolated git worktree session. When you want to experiment without touching your actual project state. Think of it as a sandbox mode for Hermes conversations.

Scripted output — this one's worth knowing if you ever pipe Hermes into other tools:

hermes -z

-z mode strips everything out — no banner, no spinner, no tool-call previews. You get the final response text and nothing else. If you're piping Hermes output into a shell script, grep, or another process, this is the flag you want.

Slash commands — accessible inside any interactive session with a forward slash. The ones you'll actually use:

/help — lists everything available
/tools — shows which tools are currently loaded
/model — switch models mid-session
/save — save the current session
/title — give the session a meaningful name
/status — show agent state
/sessions — browse your conversation history
/skills browse — see available skills

The most interesting one for heavy users is /busy. If you send a new message while your agent is still processing a previous request, /busy queue|steer|interrupt|status controls what happens. queue lines up your message to be processed after the current task. steer tries to adjust the current operation. interrupt cancels what it's doing. This matters more as your agents get more autonomous.

hermes sessions list
hermes sessions rename

These work without entering a session — useful for keeping your conversation history organized when you're managing multiple project contexts.

The tools question everyone asks at setup: out of the box, you get web search, terminal execution, and file editing — all enabled by default, zero configuration required. You don't have to wire anything up to get a capable agent immediately. That's intentional.

Multi-line input: Alt+Enter, Ctrl+J, or Shift+Enter to add lines without submitting.

Multi-line paste: Hermes auto-detects when you're pasting a block and handles it correctly. You don't need to do anything special.

If you want to interrupt an operation mid-run, you can type a new message while the agent is working — it will surface the interrupt options.

Clipboard images: Ctrl+V pastes directly from your clipboard. Handy for asking questions about screenshots or diagrams without saving files first.

Skins — the visual appearance of the CLI can be customized with the /skin command. It's cosmetic and has no effect on agent behavior. Change it if you spend a lot of time in the TUI and want it to feel like your own space.

That covers daily usage. The next layer is configuration — how to tune the actual behavior of your agent beyond the defaults.

Chapter 4: Configuration — config.yaml, .env, and Profiles

Let's get into how Hermes actually resolves settings, because understanding this will save you debugging time later.

Settings follow a priority hierarchy: CLI arguments override config.yaml, which overrides .env, which overrides built-in defaults. If you set something from the command line, it wins over everything. If config.yaml says one thing and a default says another, config.yaml wins.

The guiding principle — and this is worth repeating — is: secrets in .env, everything else in config.yaml.

Your API keys, tokens, and credentials live in ~/.hermes/.env. Everything else — model selection, behavior settings, terminal backend — lives in ~/.hermes/config.yaml. Don't mix them up. This separation is deliberate.

The full contents of ~/.hermes/ looks like this:

config.yaml — primary settings file
.env — API keys and secrets
auth.json — OAuth credentials
SOUL.md — agent personality (we'll get to this in the next chapter)
memories/ — persistent memory files
skills/ — agent-created skills
sessions/ — gateway conversation data

Inside config.yaml, there are several sections you'll actually care about:

model — which provider and model to use by default. This is what hermes model configures.

terminal — the backend that handles code execution. We'll go deeper on this in a moment.

memory — whether the memory system is enabled and character limits. (Full memory lesson is Chapter 8.)

compression — whether Hermes compresses older conversation history to stay within context limits, and what threshold triggers it.

agent — maximum turns per session and the reasoning effort level.

tts — text-to-speech provider and voice, if you want a voice interface.

display — whether tool call previews show up while the agent is working, streaming settings.

Terminal backends — a quick note because this is where people get confused:

The terminal.backend setting determines where code actually runs. The default is local — your machine, no setup. But you can point it to a Docker container, an SSH connection, a Modal instance, or specialized environments like Daytona or Singularity. If you're doing anything security-sensitive or want to sandbox code execution, this is the knob for that.

Environment variable substitution — you can reference environment variables in your config.yaml using ${VAR_NAME} syntax. This is useful when you want a setting to pull from an environment variable at runtime rather than being hardcoded. Important: only the braced form ${VAR_NAME} works. A bare $VAR is not expanded. Easy mistake to make.

Profiles — this is powerful.

The -p flag lets you launch completely isolated agent identities:

hermes -p work
hermes -p personal
hermes -p content

Each profile lives in its own directory: ~/.hermes/profiles//. Completely separate config, memory, sessions, and skills. The default profile — when you run hermes without -p — uses the root ~/.hermes/ directory directly.

You can run multiple profiles simultaneously. One agent for your development environment, one for a content workflow, one that handles something else entirely. They don't share memory or config unless you deliberately set that up.

hermes config          # Show current settings
hermes config edit     # Open in your editor
hermes config set KEY VAL    # Set a value directly
hermes config check    # Validate — catches syntax errors before they cause problems

Run hermes config check after any manual edits to config.yaml. A YAML syntax error will break your entire config silently if you don't.

With configuration down, let's do the thing that actually makes your agent feel like yours: the personality.

Chapter 5: SOUL.md and Personality

This is the file that most people either skip too fast or overcomplicate. Don't do either.

SOUL.md is at ~/.hermes/SOUL.md. It's the first file loaded into your agent's system prompt — which means it shapes every single response, before anything else. And it persists across every session. It's not a conversation setting. It's the agent's identity.

When you install Hermes, it auto-generates a starter SOUL.md for you. That file is a scaffold, not a finished product. And here's the important thing: Hermes will never overwrite your edits. Once you change it, that's what it uses.

What belongs in SOUL.md:

Communication tone and style. How direct the agent should be. How it handles uncertainty — does it hedge, does it ask for clarification, does it just commit to an answer and move on? What it should avoid — jargon, filler phrases, over-explaining simple things.

What does NOT belong in SOUL.md:

Project-specific details. File paths, framework choices, deployment workflows, coding conventions. Those belong in AGENTS.md, which we'll cover in the next chapter. The reason to keep them separate: your project knowledge changes constantly. Your agent's personality shouldn't. If you put both in SOUL.md, you end up editing the personality file every time your project changes, and it becomes stale and messy fast.

The 13 built-in personality presets:

Hermes ships with preset personalities you can activate for a single session using /personality followed by the preset name:

helpful, concise, technical, creative, teacher, kawaii, catgirl, pirate, shakespeare, surfer, noir, uwu, philosopher, hype

These are temporary. They layer on top of your SOUL.md for that session only, then disappear. They're useful for experimenting, or for switching modes — run /personality teacher when you want the agent to explain something at a beginner level, then drop back to your default.

Custom personalities can be defined in config.yaml under agent.personalities and activated with the same /personality command. Same interface as built-in presets, but these are yours.

SOUL.md vs. /personality — the mental model:

SOUL.md is your agent's baseline voice. It's always on.

/personality is a session-level overlay. It's temporary.

There's a practical test here: if you keep running the same /personality command every time you start a session because you want that trait permanently, that trait belongs in SOUL.md instead.

Writing your actual SOUL.md:

Open the file and write three or four paragraphs. Address these things specifically:

How direct should responses be? (Don't hedge when confidence is high, or: always ask for clarification before acting?)
How should uncertainty be handled? (Flag it and proceed, or ask first?)
What's the right tone? (Peer to peer, mentor, neutral technical voice?)
What should the agent actively avoid? (Lists for everything, unnecessary caveats, starting responses with "Certainly!"?)

Write it the way you'd describe what you want from a really good collaborator. Be specific. Vague personality files produce vague agents.

Then test it immediately. Ask your agent something, notice how it responds, and adjust if it's off. The difference between a well-written SOUL.md and the default is usually obvious in the first exchange.

Now that your agent has a personality, let's give it project awareness.

Chapter 6: Context Files — AGENTS.md and Project Awareness

Here's the problem that AGENTS.md solves:

You use Hermes across multiple projects. Each one has its own architecture, its own conventions, its own quirks. Without AGENTS.md, every time you start working in a different context, you're either explaining it again from scratch or relying on the agent to figure it out by exploring files.

AGENTS.md eliminates that. You document the context once. Hermes reads it automatically every time you start a session in that directory.

There's a priority order: .hermes.md or HERMES.md first, then AGENTS.md, then CLAUDE.md, then .cursorrules. The first match wins. If you have an AGENTS.md and a CLAUDE.md in the same directory, Hermes uses AGENTS.md and ignores the other.

Most people write AGENTS.md because that's the most descriptive name for what the file does.

SOUL.md loads separately and independently. It doesn't compete with these.

When you start a session, Hermes scans upward from your current directory to the git root, loading the first context file it finds. During the session, as you navigate into subdirectories, it progressively discovers context files in those directories only as they're accessed. It doesn't pre-load everything at startup.

This is intentional. Pre-loading every context file in every subdirectory would bloat the system prompt and thrash the prompt cache — making every response slower and more expensive. Progressive discovery keeps the initial prompt lean, adding context precisely when and where it's needed.

What belongs in AGENTS.md:

Think about what you'd explain to a new developer on day one. The file should cover:

Architecture overview: what are the main components, how do they relate?
Coding conventions: naming patterns, file organization, anything non-obvious
Restrictions: things the agent should not do (don't run destructive database commands without confirmation, don't push to production directly, etc.)
Key paths and ports: where does the app live, what port does dev run on, where are config files?
Technology stack: frameworks, dependencies, anything relevant to understanding the codebase

The practical test for whether something belongs here: if you find yourself explaining it to the agent repeatedly across different sessions, document it. That's the signal.

Security — context files are not trusted blindly:

Every context file Hermes loads goes through prompt injection scanning. It's looking for attempts to override the agent's instructions, credential patterns, and other red flags.

Files over 20,000 characters are truncated, not rejected. It takes the first 70% and the last 20%, inserts a removal marker in between, and proceeds. You won't get an error — you'll just lose the middle of a very long file. Keep your AGENTS.md focused enough that this doesn't apply to you.

A practical first AGENTS.md — write it now:

Open a new file at the root of a project you actually work in. Write four or five sentences covering:

What is the entrypoint? (e.g., "This is a PHP application; the main entry is index.php")
How does database migration work? What command runs tests?
How does deployment happen?
Any key conventions or restrictions worth knowing up front?

That's enough for a first version. You'll add to it as you notice yourself re-explaining things across sessions.

With personality set and project context in place, let's talk about a different way to inject context — one that happens inline, in the moment, using the @ syntax.

Chapter 7: Context References — The @ Syntax

Here's the situation the @ syntax is designed for: you know exactly what file or diff is relevant to what you're asking about, and you want to hand it to the agent directly instead of asking it to find it.

The distinction matters. When you ask an agent to "look at the main.py file," it uses its file-reading tool to find and read that file. That works. But when you use @file:src/main.py in your message, Hermes expands that reference before the message is even sent — the content is already there when the agent starts processing. No tool call needed. Faster. Cleaner.

Think of it as the difference between telling a colleague "go look up the report" versus handing them the report.

The full syntax table — seven reference types:

@file:path/to/file.py — complete file contents

@file:path/to/file.py:10-25 — just lines 10 through 25 (1-indexed, inclusive)

@folder:path/to/dir — directory tree with file metadata

@diff — your current unstaged git changes

@staged — your staged changes

@git:5 — the last 5 commits with their patches (maximum 10)

@url:https://example.com — fetched content from a web page

The references embed naturally into regular sentences. Some examples:

"Review @file:src/main.py and suggest improvements."

"What changed? @diff"

"What does this function do? @file:src/utils.py:42-80"

"Check out this documentation and tell me if our implementation matches it: @url:https://docs.example.com/api"

You don't need to put references on their own line or use special formatting. They work inline. And if you write something like "@file:src/main.py, what's wrong here?" — the trailing comma strips automatically. Punctuation after a reference doesn't break it.

Line ranges are more useful than they look. When you're dealing with a 2,000-line file and you know the relevant function is around line 400, @file:src/main.py:390-450 gets you exactly that without dumping the whole file into context.

There are two thresholds:

Soft limit: 25% of your context window. Hermes warns you but still expands the reference.
Hard limit: 50% of your context window. Hermes refuses to expand the reference. The message goes through, but without the context injection.

@folder: shows a maximum of 200 files. @git: is capped at 10 commits.

If you hit the hard limit, the solution is usually either a line range instead of the full file, or breaking the request into smaller pieces.

Security — blocked paths:

Some locations are always blocked from @file: access regardless of what you request. The blocked list includes ~/.ssh/, ~/.aws/, ~/.gnupg/, and ~/.kube/. Path traversal attempts are also blocked. Binary files don't expand. This is a hard restriction, not a warning.

Where this works and where it doesn't:

@ syntax is a CLI feature. It has tab completion — start typing @file: and you'll get filesystem autocomplete. That alone is worth knowing.

Messaging platform integrations — Telegram, Discord, Slack — do not expand @ syntax. Your agent still has file and git access through its tools in those environments, but the shorthand injection doesn't work there.

The practical decision — when to use @ vs. when to just ask:

Use @ when you know exactly which file or diff is relevant. Use it when precision matters more than discovery.

Let the agent use its own tools when you're not sure where the relevant code lives, or when you want it to decide what's worth reading. Both approaches work. They complement each other.

Now we get to the thing that makes your agent genuinely persistent — the memory system.

Chapter 8: The Memory System — MEMORY.md, USER.md, and External Providers

Here's the distinction that matters before we go anywhere else:

SOUL.md is identity — who the agent is, authored by you, static.

AGENTS.md is project knowledge — what the agent knows about your work, also authored by you.

Memory is different. Memory is what the agent learns independently over time through actual use. Facts that neither party explicitly documented. Things the agent noticed and filed away. That's a fundamentally different kind of information, and it lives in a different place.

Two files, two purposes:

Memory lives in ~/.hermes/memories/. There are two files:

MEMORY.md — 2,200 character limit (roughly 800 tokens). Stores agent observations about your environment, your conventions, and lessons learned. The kind of thing you'd expect a great assistant to just know after working with you for a few weeks.

USER.md — 1,375 character limit (roughly 500 tokens). Specifically focused on you — your preferences, your communication style, your expectations from the agent.

The split is intentional. When both files start filling up, the separation keeps each one focused. Environmental observations don't crowd out personal preferences, and vice versa.

How entries get written — three operations:

The agent uses a dedicated memory tool supporting:

add — creates a new entry

replace — updates an existing entry via substring matching

remove — deletes an entry via substring matching

The substring matching for replace and remove is a small but practical detail: the agent doesn't need to reproduce an entry word-for-word to update or delete it. If the entry says "User prefers concise responses" and it wants to update that, it just needs enough of that string to match. It doesn't have to quote it exactly.

The frozen snapshot behavior — this is the part that surprises everyone:

Memory loads once when you start a session. It does not update during that session, even if the agent writes new entries.

When the agent writes something to memory, that write happens immediately to disk. It's saved. But you won't see the effect in the current conversation — those memory entries appear in the system prompt only when the next session starts.

Why? Prompt cache stability. If memory updated mid-conversation, the entire prefix cache would invalidate every time the agent learned something. That would make responses dramatically slower and more expensive. So the tradeoff is: memory is a session-start snapshot. Real, immediate on disk, but not live within the current session.

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  write_approval: false

The write_approval flag is worth knowing. Set it to true and the agent will prompt you for approval before committing anything to memory. You review pending writes with /memory pending. If you're protective of what gets stored, turn this on. If you trust the agent to make reasonable decisions about what to retain, leave it off.

This is important: you cannot verify memory within the same session where it was written. The frozen snapshot means what you just taught it won't be visible until the next session.

The proper test: tell the agent something specific in one session. Close it. Start a completely new session. Ask a question that would require knowing that thing. If it knows, memory is working. If you test within the same session, you'll always get a false negative.

When built-in memory isn't enough:

The built-in MEMORY.md and USER.md files work for most people. If you have more advanced requirements, there are nine external memory providers:

Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory, Memori.

These range from local, free options (Holographic runs fully local) to cloud-hosted services (Mem0). Only one external provider can be active alongside the built-in files. Configure via hermes memory setup or manually in config.yaml.

Most users — especially starting out — never need to go beyond the built-in files. The character limits feel tight at first but are actually enough to maintain a useful working memory for most contexts.

You now have all the individual pieces. The final chapter is about putting them together.

Chapter 9: Your First Week with Hermes

Let's recap what you've built across the last eight lessons:

Hermes installed, model configured, first session running
CLI fluency — the flags, slash commands, and session management you'll use daily
Configuration sorted — config.yaml, .env, profiles if you need them
A real SOUL.md with the agent's personality defined in your own words
An AGENTS.md in at least one project directory
The @ syntax for inline context injection
The memory system active and understood

Now we make it real. The walkthrough for your first week is seven steps, and they use an actual project — not a demo directory.

Step 1: Pick a project you actually work in. Not a toy. Not a template. Something real.

Step 2: Open ~/.hermes/SOUL.md and read what's there. Edit it to match what you actually want. If you haven't already done this after Lesson 5, do it now. Run the session once and see if the tone is right. Adjust.

Step 3: Create or update AGENTS.md at the root of your chosen project. Cover the architecture, conventions, restrictions, and key paths. Write it like you're onboarding someone who's competent but knows nothing about your specific project.

Step 4: Start a fresh session with hermes --tui and immediately ask the agent something that requires knowing your project — "what does this codebase do?" or "how does deployment work?" If it answers correctly from AGENTS.md without needing to explore files, you've set it up well.

Step 5: Reference actual files or changes with the @ syntax. Pick something you're currently working on, paste an @diff or @file: reference into a real question you have about it.

Step 6: Deliberately teach the agent one genuine preference about yourself. Something like: "I prefer that you always give me the direct answer first and explain second, never the other way around." That kind of instruction will get written to USER.md.

Step 7: Close the session. Open a new one. Ask something that requires knowing what you just taught it. Verify it remembers.

If something went wrong — common issues and fixes:

HTTP 429 errors — you've hit your provider's rate limit. Switch providers temporarily with --model, or use OpenRouter's free tier while you wait.

"Context length exceeded" — your conversation has grown longer than the model's context window. Run /compress — this summarizes older parts of the conversation and brings you back under the limit without losing what matters.

Model identifier mismatches — if your config.yaml specifies a model that doesn't exist exactly as written, Hermes doesn't fuzzy-match it. There's no fallback. The exact spelling has to match what your provider uses. Double-check with your provider's documentation.

Command-approval blocks — if the agent asks for your approval before running a destructive command, that's not a bug. That's the safety behavior working as intended. The agent is checking before it does something that's hard to reverse.

Memory-timing confusion — if you test memory within the same session where something was taught, it will always seem like memory isn't working. It is working. The write hit disk. Start a new session to actually verify it.

You have a complete, functional, personalized agent. It has a consistent voice. It knows your project. It can read files and diffs inline. It remembers things across sessions. It's running on your machine, under your control, with whatever model you've chosen.

That's the fundamentals track.

The advanced track builds on this: scheduling tasks on a cron, connecting the agent to Telegram or Discord through the gateway, building custom tools and skills, voice integration, multi-agent coordination where agents hand off to each other, and production security practices for running Hermes on a server.

But you don't need the advanced track to get real value from what you've built right now. The setup you have — personality, project awareness, context injection, memory — is already a serious upgrade from a chat window.

Recap

Here's what we covered:

What Hermes is: a persistent agent runtime, not a chatbot. Profiles for isolated identities. The gateway for reach. SOUL.md and memory for continuity across sessions.

Installation: minimal prerequisites, a free path through OpenRouter, and three install methods depending on your platform. Source your shell config after install. Run hermes doctor when something isn't working.

The CLI: the flags you'll use constantly (-q, --continue, -w, -z), slash commands, session management. Tools are active by default — no setup needed to get web search, terminal access, and file editing.

Configuration: secrets in .env, settings in config.yaml, and a clear priority hierarchy. Profiles let you run isolated agent identities simultaneously.

SOUL.md: the most important file you'll edit. Loads first, persists across sessions, defines the agent's voice. Write it in your own words, be specific, test immediately.

AGENTS.md: project knowledge that loads automatically. Progressive discovery keeps prompts lean. The test for what belongs there: if you're explaining it repeatedly across sessions, document it.

@ syntax: seven reference types for injecting context inline. Soft and hard context limits to know about. Blocked from credential paths. CLI-only — doesn't work on messaging platforms.

Memory: MEMORY.md for environmental learning, USER.md for personal preferences. Writes hit disk immediately but appear only in the next session. Frozen snapshot by design for cache stability.

First week walkthrough: seven steps on a real project. Verify memory with a fresh session, not within the same conversation.