Hermes Handbook

A living, bilingual field guide for running Hermes as a reliable personal AI system.

Hermes is documented here as it is installed, used, tested, and improved. English is the default language at hermes.skywirex.com; the Vietnamese edition is available from the language switcher.

What This Handbook Covers

Provisioning a small Linux server and securing remote access.
Installing Hermes, connecting models, and choosing the right interface.
Designing safe gateways, context files, tools, memory, and reusable skills.
Automating research, development, content, business, and monitoring workflows.
Recording decisions and turning repeated work into better procedures.

How To Read It

Start with VPS and Installation, then configure Security and Context. The remaining sections are reference material: read them when a workflow requires them and update them with verified notes.

Each topic should eventually contain four things: the purpose, a tested procedure, failure modes, and the date or source of the latest verification. Unverified assumptions belong in notes, not in operational commands.

Documentation Status

This is a working handbook, not a finished product. Empty or short topics are intentional starting points for the learning journey. The Improvement Loop records how knowledge becomes reusable practice.

📂 HERMES
┃
┣ 📂 VPS
┃ ┣ 📂 Small Linux Server
┃ ┣ 📂 Dedicated User
┃ ┣ 📂 SSH Access
┃ ┣ 📂 Firewall
┃ ┣ 📂 Tailscale
┃ ┗ 📂 Backups
┃
┣ 📂 Installation
┃ ┣ 📂 Official Installer
┃ ┣ 📂 Python and Dependencies
┃ ┣ 📂 Hermes Doctor
┃ ┣ 📂 Updates
┃ ┗ 📂 Systemd Service
┃
┣ 📂 Models
┃ ┣ 📂 Nous Portal
┃ ┣ 📂 OpenAI Codex
┃ ┣ 📂 Anthropic
┃ ┣ 📂 OpenRouter
┃ ┣ 📂 Local Models
┃ ┗ 📂 On-the-Fly Switching
┃
┣ 📂 Interfaces
┃ ┣ 📂 Terminal
┃ ┣ 📂 TUI
┃ ┣ 📂 Desktop Application
┃ ┣ 📂 Web Dashboard
┃ ┣ 📂 IDE via ACP
┃ ┗ 📂 OpenAI-Compatible API
┃
┣ 📂 Gateway
┃ ┣ 📂 Discord
┃ ┣ 📂 Telegram
┃ ┣ 📂 Slack
┃ ┣ 📂 WhatsApp
┃ ┣ 📂 Email
┃ ┗ 📂 20+ Platforms
┃
┣ 📂 Security
┃ ┣ 📂 Authorized Users
┃ ┣ 📂 DM / Code Pairing
┃ ┣ 📂 Validation of Dangerous Commands
┃ ┣ 📂 Protection of Sensitive Files
┃ ┣ 📂 Docker or SSH Isolation
┃ ┗ 📂 Blocking of Irreversible Commands
┃
┣ 📂 Context
┃ ┣ 📂 SOUL.md
┃ ┣ 📂 AGENTS.md
┃ ┣ 📂 Project Rules
┃ ┗ 📂 Channel-Specific Context
┃
┣ 📂 Tools
┃ ┣ 📂 Terminal
┃ ┣ 📂 File Reading and Writing
┃ ┣ 📂 Web Search
┃ ┣ 📂 Web Browsing
┃ ┣ 📂 Vision
┃ ┣ 📂 Image Generation
┃ ┗ 📂 Speech Synthesis
┃
┣ 📂 Memory
┃ ┣ 📂 User Profile (USER.md)
┃ ┣ 📂 Work Conventions (MEMORY.md)
┃ ┣ 📂 Technical Environment
┃ ┣ 📂 Inter-Session Reminders
┃ ┗ 📂 Search in Past Conversations (session_search)
┃
┣ 📂 Skills
┃ ┣ 📂 Reusable Procedures
┃ ┣ 📂 Community Catalog
┃ ┣ 📂 Slash Commands
┃ ┣ 📂 Custom Skills
┃ ┣ 📂 Improvement During Use
┃ ┗ 📂 Auto-Archiving (Curator)
┃
┣ 📂 Integrations
┃ ┣ 📂 MCP Servers
┃ ┣ 📂 GitHub
┃ ┣ 📂 Databases
┃ ┣ 📂 SaaS Tools
┃ ┣ 📂 Home Assistant
┃ ┗ 📂 Custom Plugins
┃
┣ 📂 Automation
┃ ┣ 📂 Scheduled Tasks
┃ ┣ 📂 Crons with Skills
┃ ┣ 📂 Webhooks
┃ ┣ 📂 Scripts without LLM
┃ ┣ 📂 Multiplatform Delivery
┃ ┗ 📂 Alerts Only If Necessary
┃
┣ 📂 Delegation
┃ ┣ 📂 Isolated Sub-Agents
┃ ┣ 📂 Parallel Work
┃ ┣ 📂 Multi-Agent Board (Kanban)
┃ ┣ 📂 Background Sessions
┃ ┣ 📂 Multi-Step Pipelines
┃ ┗ 📂 Automatic Result Feedback
┃
┣ 📂 Research
┃ ┣ 📂 Automatic Monitoring
┃ ┣ 📂 Multi-Source Search
┃ ┣ 📂 Competitor Analysis
┃ ┣ 📂 Document Synthesis
┃ ┗ 📂 Sourced Reports
┃
┣ 📂 Development
┃ ┣ 📂 Repository Inspection
┃ ┣ 📂 Feature Creation
┃ ┣ 📂 Bug Fixes
┃ ┣ 📂 Tests and Lint
┃ ┣ 📂 Pull Requests
┃ ┗ 📂 Code Review
┃
┣ 📂 Content
┃ ┣ 📂 Idea Research
┃ ┣ 📂 Writing
┃ ┣ 📂 Newsletters
┃ ┣ 📂 Social Networks
┃ ┣ 📂 Images
┃ ┗ 📂 Audio
┃
┣ 📂 Business
┃ ┣ 📂 Email Sorting
┃ ┣ 📂 Meeting Minutes
┃ ┣ 📂 CRM Updates
┃ ┣ 📂 KPI Reports
┃ ┣ 📂 Data Analysis
┃ ┗ 📂 Document Preparation
┃
┣ 📂 Monitoring
┃ ┣ 📂 Server Status
┃ ┣ 📂 Site Changes
┃ ┣ 📂 News
┃ ┣ 📂 Prices
┃ ┣ 📂 Logs
┃ ┗ 📂 Alerts in Discord
┃
┣ 📂 Daily Use
┃ ┣ 📂 Messages from Phone
┃ ┣ 📂 Work While PC Is Off
┃ ┣ 📂 Session Resumption
┃ ┣ 📂 Multiple Profiles (Bots/Personas)
┃ ┣ 📂 Corrections in Progress
┃ ┣ 📂 Results Delivered to the Right Channel
┃ ┗ 📂 Human Validation Before Sensitive Actions
┃
┗ 📂 Improvement Loop
┣ 📂 Memorize What Matters
┣ 📂 Retrieve Past Decisions
┣ 📂 Turn a Method into a Skill
┣ 📂 Reuse the Skill
┣ 📂 Improve It with Each Use
┗ 📂 Learning Journey (/journey)

VPS

Hermes works best on a small Linux server that is easy to understand, easy to rebuild, and boring enough to trust.

Small Linux Server

Pick a minimal Ubuntu or Debian install.
Keep only the packages the stack actually needs.
Separate the application layer from persistent data.

Dedicated User

Run Hermes under a non-root user.
Lock down sudo to the exact commands that need it.
Keep shell history and dotfiles auditable.

SSH Access

Prefer key-based login.
Disable password login once keys are confirmed.
Restrict SSH to trusted source networks when possible.

Firewall

Allow only required inbound ports.
Default deny for everything else.
Log changes so the current state is reviewable later.

Tailscale

Use it for private admin access across devices.
Prefer it over exposing extra public ports.

Backups

Back up config, prompts, credential references, and data.
Test restore at least once before trusting the backup.

Current Notes

Record provider, region, IP, access path, and restore date.

Small Linux Server

Dedicated User

SSH Access

Firewall

Tailscale

Backups

Installation

Hermes should install cleanly on a fresh machine and remain easy to update.

Official Installer

Prefer the official install path first.
Capture the exact command and version used.
If the install changes, record the delta immediately.

Python and Dependencies

Pin the Python version that is known good.
Keep third-party packages minimal.
Separate runtime dependencies from optional tools.

Docker

Install Docker following the official documentation for your OS.
Pull the Hermes image and run with mounted config/environment files.
Use docker-compose for easier management of volumes and environment variables.

Hermes Doctor

Run a local health check after install and after upgrades.
Treat missing paths, permissions, and config drift as first-class failures.

Updates

Update in small steps, not in a single blind jump.
Verify release notes, then update, then rerun checks.

Systemd Service

Run Hermes as a service when the host should recover after reboot.
Keep service files simple and explicit.

Current Notes

Keep one tested install path per environment and document the fallback.

Official Installer

Python and Dependencies

Docker

Hermes Doctor

Updates

Systemd Service

Models

Hermes can route requests to remote or local models. The important part is making that decision visible and reversible.

Nous Portal

Use it as a managed starting point for experimentation.
Track which prompts and tasks behave best there.

OpenAI Codex

Use for code-heavy work, refactoring, and structured task completion.
Record where its behavior is stronger or weaker than other providers.

Anthropic

Use when long reasoning, careful prose, or safer instruction following matters.

OpenRouter

Treat it as a routing layer when you want provider flexibility.
Keep provider names and model names explicit in notes.

Local Models

Use local models for privacy-sensitive, offline, or cheap tasks.
Watch quality, latency, and hardware limits.

On-the-Fly Switching

Switching should depend on task type, not habit.
Keep the policy simple enough to explain to another operator.

Current Notes

Write down the exact model used for each verified workflow.

Nous Portal

OpenAI Codex

Anthropic

OpenRouter

Local Models

On-the-Fly Switching

Interfaces

Hermes should feel reachable from the places where work already happens.

Terminal

Best for automation, scripts, and direct troubleshooting.
Keep commands short, explicit, and repeatable.

TUI

Best for scanning state quickly and reducing context switching.
Prioritize keyboard flow and readable status.

Desktop Application

Best for long-running sessions and visual management.
Make sure windows, logs, and actions stay clear.

Web Dashboard

Best for remote access and broader visibility.
Keep the dashboard focused on actions, not decoration.

IDE via ACP

Use when Hermes should assist inside the editor.
Prefer stable workflows over clever integrations.

OpenAI-Compatible API

Expose a simple API boundary for external tools and automations.
Document auth, rate limits, and failure responses.

Current Notes

Track which interface is the primary one for each workflow.

Terminal

TUI

Desktop Application

Web Dashboard

IDE via ACP

OpenAI-Compatible API

Gateway

Gateway channels move Hermes work between people, devices, and external services.

Discord

Good for quick alerts, approvals, and conversational ops.

Good for mobile-first control and lightweight task delivery.

Slack

Good for team workflows and structured channels.

Good for direct reach when speed matters.

Email

Good for durable, asynchronous summaries.

20+ Platforms

Add more channels only when the workflow is stable enough to justify it.
Prefer fewer integrations that are well maintained over many that are half-working.

Current Notes

For each channel, document who can send, who can receive, and what triggers a message.

Discord

Slack

Email

20+ Platforms

Security

Hermes needs clear security rules before it is trusted with real work.

Authorized Users

Define who may use the system.
Separate read-only access from action-bearing access.

DM / Code Pairing

Use a human verification step for sensitive actions.
Keep the verification path short and auditable.

Validation of Dangerous Commands

Stop commands that can delete data, rotate credentials, or break the host unless they are explicitly confirmed.

Protection of Sensitive Files

Guard secrets, credentials, and private notes.
Never assume a file is safe just because it is local.

Docker or SSH Isolation

Use isolation to reduce blast radius.
Prefer the simplest boundary that still protects the host.

Blocking of Irreversible Commands

Detect irreversible actions before they run.
Require a manual override when the risk is real.

Current Notes

Write down the exact approval rule for each sensitive operation.

Authorized Users

DM / Code Pairing

Validation of Dangerous Commands

Protection of Sensitive Files

Docker or SSH Isolation

Blocking of Irreversible Commands

Context

Context files tell Hermes what to remember and how to behave for a project.

AGENTS.md and SOUL.md

AGENTS.md — when it is read

At session startup, Hermes scans the current working directory in priority order: .hermes.md → AGENTS.override.md → AGENTS.md → CLAUDE.md → .cursorrules — only the first matching file is loaded, and only in the current directory (no recursion up/down at startup).

During the session, when the agent moves into a subdirectory (via read_file, terminal, search_files…), it lazy-discovers AGENTS.md/CLAUDE.md/.cursorrules in those subdirectories and inserts them into the tool call result (not the original system prompt) — a “hint loading” mechanism based on the context being operated on.

Technical details:

Content is scanned for prompt-injection before loading
Startup file: configuration-limited, trimmed using head/tail (70% top, 20% bottom) if too long
Subdirectory file (lazy): hard-capped at 8,000 characters/file
If AGENTS.override.md exists next to AGENTS.md → the override is loaded instead (used for personal versions, usually gitignored)

SOUL.md — when it is read

Always loaded independently at the start of each session, going directly into slot #1 of the system prompt (the agent identity slot), independent of working directory:

From current docs: “SOUL.md is now global to the Hermes instance and is loaded from HERMES_HOME only” — meaning it only reads from ~/.hermes/SOUL.md, not searched per project cwd like AGENTS.md.
No wrapper text around it — SOUL.md content goes straight into the prompt.
If the file is empty, contains only whitespace, or cannot be read → fallback to default identity (“You are Hermes Agent, an intelligent AI assistant created by Nous Research…”).
This fallback also applies when skip_context_files is set — for example in subagent/delegation context, meaning child subagents do not automatically inherit the parent agent’s SOUL.md.

Quick summary: AGENTS.md = project-specific rules/context (changes based on which directory you run hermes in), SOUL.md = fixed personality/identity of the agent across the entire system, independent of the project being worked on.

Project Rules

Record the boundaries that should not be broken.
Keep examples near the rule they support.

Channel-Specific Context

Give each channel the minimum context it needs.
Avoid sending everything everywhere.

Current Notes

Treat context as a maintenance surface, not as a dump file.

SOUL.md

AGENTS.md

Project Rules

Channel-Specific Context

Tools

Tools are the practical capabilities Hermes uses to do the work.

Terminal

Use the terminal for direct execution and inspection.

File Reading and Writing

Read only what is needed.
Write only after confirming the target and the expected shape.

Web Search

Use search when the answer depends on current public information.

Web Browsing

Use browsing when the page itself matters.

Vision

Use image understanding when text is not enough.

Image Generation

Use generated visuals only when they add real value.

Speech Synthesis

Use voice output when the task benefits from spoken delivery.

Current Notes

Keep tool guidance operational, not aspirational.

Terminal

File Reading and Writing

Web Search

Web Browsing

Vision

Image Generation

Speech Synthesis

Memory

Memory keeps Hermes from relearning the same facts every session.

User Profile

Store durable user preferences that matter later.

Work Conventions

Record how the user likes tasks done.

Technical Environment

Capture the current environment once it is verified.

Inter-Session Reminders

Keep reminders short and actionable.

Search in Past Conversations

Prefer retrieval over guessing when the information already exists.

Current Notes

Write memory only when it improves the next decision.

Classification and Memory Management Principles

General Classification Rules

File	What it contains	What it does not contain
MEMORY.md	Facts/conventions about the environment (path, IP, commands, storage conventions) — “what”	Multi-step procedures (“how”) → put into Skill
USER.md	Who the user is, how they prefer to communicate/work (persona, pet peeves, communication style)	Domain-specific knowledge being learned
Skill (separate SKILL.md)	Reusable, multi-step repetitive procedures	Single-line static facts (should be in Memory)

Short rule: Memory = what, User = who/how they like being talked to, Skill = how (procedure). If a task has ≥5 steps and will repeat → split into a separate Skill.

Technical Limits

MEMORY.md: ~2,200 character limit (~800 tokens), entries separated by §.
Each entry should be dense, specific (real paths/IPs/commands), avoid vague statements like “User has a project”.
Do not use extra markdown headings within Memory.
When usage exceeds ~80% → merge duplicate entries on the same topic before hitting the write block.
Merge rule: multiple entries about the same topic (“project uses X” x3) → merge into one comprehensive entry.

Case Study — MEMORY.md (GBrain)

Original state: 1,517/2,200 characters (~69%), 7 entries, valid § syntax.

What worked well:

Entries are specific, with real addresses/commands/paths (e.g., MCP server IP, docker exec commands).
No raw data dumps, no ephemeral info from a single session.

Problems:

5/7 entries all talk about “GBrain ingestion”, occupying most of the capacity → need merging, saving ~30–40%.
Some entries describe detailed processing procedures (“how”) instead of just stating facts → detailed procedures should go into SKILL.md of the relevant skill (e.g., gbrain-resolver), Memory only needs one line pointing to that skill.
One entry describes user behavioral/communication expectations (“report blocker directly instead of stopping silently”) → this belongs in USER.md, not MEMORY.md.

Condensed sample version (reduces old capacity to ~55%):

GBrain: MCP server http://10.10.38.1:7333/mcp. CLI in Docker container `gbrain`; run `docker exec gbrain gbrain extract --stale` (or `docker compose exec -T gbrain ...`) when Docker daemon is accessible.
§
GBrain ingestion convention: save user-uploaded files under `sources/` first (raw layer, immutable); derived pages reference `source_slug` in `sources/`, not just cache path `/opt/data/gbrain/...`. For generic filenames (README.md), set slug based on content/project name, keep original name.
§
GBrain ingestion trigger ("load knowledge/data into brain"): use mcp_gbrain_* + gbrain-resolver skill — skill handles routing, preserve Compiled Truth + Timeline-append, confirm slug/path saved.
§
Updating gbrain-resolver skill: read live `resolver` page via GBrain MCP first, patch skill from there, do not rely on local memory/assumptions.

→ Entry about “report blocker directly” moves to USER.md, e.g.:

User expects agent to proceed with GBrain ingestion even when MCP is down (using resolver rules/local fallback) and report blocker directly instead of silently stopping.

Case Study — USER.md

Original state: 502/1,375 characters (~37%), 2 entries, valid § syntax.

USER.md should contain: name/role/timezone, communication preferences, pet peeves, workflow habits, technical skill level — i.e., “who is the user / how they like being talked to”, not domain knowledge being learned.

Entry 1 — correct place, good quality: persona “Mít” (sharp, blunt, concise, evidence-calibrated) + specific communication rules for Hermes/Buzz troubleshooting (separate transport vs agent/model/tool latency). Good example entry: packs multiple related facts, specific, actionable.

Entry 2 — wrong file: content about learning SMC trading, wants explanations based on stored SMC docs → this is domain-knowledge/task context, not “who is the user”. Correct handling:

Fact about used resources (e.g., SMC book path/slug) → MEMORY.md.
Reusable procedure (always answer SMC questions using entry/OB/FVG/BOS format based on original docs) → separate Skill (e.g., smc-explainer).
Only keep general style preference (likes based on original docs, dislikes generic theory) in USER.md.

Condensed sample version:

User wants Vietnamese replies in the Mít persona: sharp, blunt, concise by default, evidence-calibrated, filler-free, brief in result reports. For Hermes/Buzz troubleshooting, prefers live gateway/log evidence with clear split between transport issues and agent/model/tool latency.
§
When explaining any technical/reference topic (e.g. trading), user prefers answers grounded in the stored reference material, not generic textbook theory.

Detailed SMC content split out:

MEMORY.md: 1-line fact — “SMC reference book stored at [source]” (if specific path/slug exists).
Separate Skill (smc-explainer): procedure to always lookup original docs first when answering SMC questions, using entry/OB/FVG/BOS terminology.

Quick Checklist When Adding New Entry

Is this a static fact about the environment (path/IP/command/convention)? → Memory
Is this a ≥5-step procedure that will repeat? → Skill
Is this a user expectation/communication style? → User
Is the entry specific and dense with information, or vague?
Are there entries on the same topic that can be merged?
Has Memory usage exceeded ~80% — needs cleanup before adding more?

Tip: Check Contradictions with Claude

Use Claude to cross-check for contradictions between MEMORY.md, USER.md, AGENTS.md, and SOUL.md. Run this audit periodically to ensure consistency across Hermes configuration files.

Example prompt for Claude:

Review the files MEMORY.md, USER.md, AGENTS.md, and SOUL.md in the Hermes directory. Identify any contradictions, overlapping content, or inconsistencies between them. Report conflicting statements and suggest resolutions.

Keyboard shortcuts

Hermes Handbook