Hermes Evolution 🧬

A self-improving version of Hermes Agent — it researches improvements, proposes them, and updates itself daily. You keep using Hermes as usual; it gets better on its own.

The self-improving AI agent built by Nous Research. It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.

Use any model you want — Nous Portal, OpenRouter, OpenAI, your own endpoint, and many others. Switch with hermes model — no code changes, no lock-in.

A real terminal interface	Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.
Lives where you do	Telegram, Discord, Slack, WhatsApp, Signal, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.
A closed learning loop	Agent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. Honcho dialectic user modeling. Compatible with the agentskills.io open standard.
Scheduled automations	Built-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.
Delegates and parallelizes	Spawn isolated subagents for parallel workstreams. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.
Runs anywhere, not just your laptop	Seven terminal backends — local, Docker, SSH, Singularity, Modal, Daytona, and Vercel Sandbox. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.
Research-ready	Batch trajectory generation, trajectory compression for training the next generation of tool-calling models.

---

⭐ Install or upgrade — one command

Whether you're starting from scratch or already running Hermes, paste one line into your terminal. If Hermes isn't installed yet, it installs our version fresh; if it is, it switches your existing Hermes onto Evolution (your chats, memory, and settings are kept):

curl -fsSL https://raw.githubusercontent.com/Lexus2016/hermes-agent-evolution/main/upgrade.sh | bash

That's it. The script does everything for you, safely:

• backs up your data (nothing is lost),
• switches your Hermes to this version,
• turns on the evolution features,
• sets up daily auto-updates so it keeps improving on its own.

You can re-run it any time — it won't break anything. Your existing chats, memory, and settings stay exactly as they were.

Don't want unattended daily updates? Add --no-star and/or --no-auto-update when you run it (from a clone): bash upgrade.sh --no-auto-update.

Troubleshooting

Running Hermes in Docker?

The container image is built without a git working tree (.git is excluded from the build context), so there are no remotes to repoint from the inside — the same reason hermes update refuses to run there. You have two options.

A. Rebuild the image on the host — durable, survives container recreate:

git clone https://github.com/Lexus2016/hermes-agent-evolution.git
cd hermes-agent-evolution
docker build -t hermes-agent-evolution:latest .

# point your compose file / run command at that image, then:
docker compose up -d --force-recreate

B. Upgrade the running container in place — when you only have a shell inside it (NAS or panel deployments, no host docker, no build daemon):

docker exec -u 0 -it <container> bash
curl -fsSL https://raw.githubusercontent.com/Lexus2016/hermes-agent-evolution/main/upgrade.sh | bash -s -- --in-container
docker restart <container>   # or let the script bounce the s6 service

This works because the image installs Hermes as an editable checkout (uv pip install -e .), so the virtualenv imports straight out of /opt/hermes — replacing the source tree is the upgrade. The script turns /opt/hermes into a real git checkout of this fork; everything the repo does not track (.venv/, node_modules/, the bin/hermes shim, hermes_cli/web_dist/) is left untouched.

Two caveats for option B:

• The change lives in the container's writable layer. docker restart keeps it; recreating the container from the image (compose up --force-recreate, an image pull) reverts to stock Hermes — which is also your rollback. Re-run the command to reapply.
• There is no daily self-update inside the container (the image ships no cron). Re-run the same command whenever you want the latest commit; after the first run it is a fast git fetch.

In both cases your config, chats and memory live on the $HERMES_HOME volume (/opt/data) and are never touched.

Windows Defender or antivirus flags uv.exe as malware

If your antivirus (Bitdefender, Windows Defender, etc.) quarantines uv.exe from the Hermes bin folder (%LOCALAPPDATA%\hermes\bin\uv.exe), this is a false positive. The file is Astral's uv — the Rust Python package manager Hermes bundles to manage its Python environment. ML-based antivirus engines commonly flag unsigned Rust binaries that download and install packages.

To verify your copy is authentic:

# Install GitHub CLI if needed
winget install --id GitHub.cli

# Login to GitHub
gh auth login

# Run verification
$uv = "$env:LOCALAPPDATA\hermes\bin\uv.exe"
$ver = (& $uv --version).Split(' ')[1]
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$zip = "$env:TEMP\uv.zip"
Invoke-WebRequest "https://github.com/astral-sh/uv/releases/download/$ver/uv-x86_64-pc-windows-msvc.zip" -OutFile $zip -UseBasicParsing
gh attestation verify $zip --repo astral-sh/uv
Expand-Archive $zip "$env:TEMP\uv_x" -Force
(Get-FileHash "$env:TEMP\uv_x\uv.exe").Hash -eq (Get-FileHash $uv).Hash

If attestation says "Verification succeeded" and the last line prints True, you're good.

To whitelist Hermes:

• Windows Defender: Run PowerShell as Admin → Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"
• Bitdefender: Add an exception in the Bitdefender console (Protection > Antivirus > Settings > Manage Exceptions)
• Whitelist the folder, not the file hash — Hermes updates uv and the hash changes every version

For more context, see the upstream Astral reports: astral-sh/uv#13553, astral-sh/uv#15011, astral-sh/uv#10079.

---

🔑 Set up a GitHub token

The agent needs a GitHub token to work with GitHub. There are two cases — pick the one that's you. (~2 minutes, no coding.)

👤 Regular user — let the agent open improvement issues

The agent opens issues on the shared Hermes Evolution repo. That repo isn't yours, so a fine-grained token can't target it — use a classic token with the public_repo scope:

1. Open github.com/settings/tokens/new — this is Personal access token (classic).
2. Note: hermes-evolution. Expiration: 90 days (or longer).
3. Tick public_repo (under repo → “Access public repositories”). That's the only box you need — it lets the agent open issues/PRs on public repos.
4. Click Generate token → copy it (starts with ghp_…; shown once).
5. Give it to your agent:

   echo 'GITHUB_TOKEN=PASTE_YOUR_TOKEN_HERE' >> ~/.hermes/.env
   

Done — your Hermes can now research and open improvement issues.

🛠️ Repo owner — full self-evolution (issues, PRs, commits, pushes, releases)

If you own hermes-agent-evolution, the agent can also implement changes, open pull requests, push branches, and cut releases. You own the repo, so use a fine-grained token scoped to it:

1. Open github.com/settings/personal-access-tokens/new — this is the Fine-grained token page.
2. Token name: hermes-evolution-owner. Expiration: 90 days (or longer).
3. Repository access: Only select repositories → pick hermes-agent-evolution (you can select it because it's yours).
4. Permissions → Repository permissions — set to Read and write:
   • Contents — commits, pushes, tags and releases
   • Issues
   • Pull requests
5. Click Generate token → copy it (starts with github_pat_…; shown once).
6. Give it to your agent. The owner runs the full cycle, which uses two roles, so set both env vars (this is the part people miss):

   # PRIVATE role — analysis, implementation, push, PRs, releases (owner):
   echo 'GITHUB_PRIVATE_TOKEN=PASTE_OWNER_TOKEN_HERE' >> ~/.hermes/.env
   # PUBLIC role — research + opening issues reads GITHUB_TOKEN.
   # Simplest: reuse the SAME owner token here too.
   echo 'GITHUB_TOKEN=PASTE_OWNER_TOKEN_HERE' >> ~/.hermes/.env
   

   Why both? The agent forces the right token per role: issues/research use GITHUB_TOKEN, while analysis/implementation use GITHUB_PRIVATE_TOKEN. If only one is set, half the cycle silently does nothing. Reusing the same owner token in both is fine. For a clean "proposals come from a separate account" split, put a second account's classic public_repo token in GITHUB_TOKEN instead (see the Regular user section above) — but never swap the two: GITHUB_TOKEN must be the proposer, GITHUB_PRIVATE_TOKEN the owner.

Keep tokens private — treat them like passwords. Never share them or paste them into a chat. If one leaks, delete it on GitHub and create a new one.

---

🧬 What you get

• Daily research — scans other AI agents, papers, and trends for ideas.
• Introspection — reviews its own past sessions with you to find what blocked real tasks, and proposes fixes for those (not just shiny features).
• Proposals — opens GitHub issues with concrete improvement suggestions.
• Self-update — pulls the latest improvements automatically every day.
• Stays current — periodically brings in useful changes from the original Hermes Agent.

Everything you already love about Hermes Agent still works exactly the same.

---

🆕 Starting from scratch?

No need to install the original Hermes first — the one command above installs our fork directly (you do NOT end up on the original and then migrate). It pulls Hermes Evolution, sets it up, and turns on the evolution features in one go.

Windows works natively too — a PowerShell installer (scripts/install.ps1) is included; see AUTO_UPGRADE.md.

---

🛡️ Is it safe?

Yes. The agent can propose changes but cannot silently rewrite itself: every change goes through a pull request with automated tests, and important parts require your approval before they're merged. Updates are backed up and roll back automatically if anything looks wrong.

Details: EVOLUTION_README.md · SECURITY_EVOLUTION.md

---

📖 Learn more

Document	What's inside
AUTO_UPGRADE.md	Install/upgrade in detail, Windows, manual steps
EVOLUTION_README.md	How evolution works, modes, the safety gate
SECURITY_EVOLUTION.md	Security policy
AGENTS.md	Original Hermes Agent documentation

---

📄 License & credits

MIT License (see LICENSE). Built on Hermes Agent by Nous Research — huge thanks to them and the Hermes community.

• Repository: github.com/Lexus2016/hermes-agent-evolution
• Upstream: github.com/nousresearch/hermes-agent

Quick start for contributors — use the standard installer, then work from the full git checkout it creates at $HERMES_HOME/hermes-agent (usually ~/.hermes/hermes-agent). This matches the layout used by hermes update, the managed venv, lazy dependencies, gateway, and docs tooling.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
uv pip install -e ".[all,dev]"
scripts/run_tests.sh

Manual clone fallback (for throwaway clones/CI where you intentionally do not want the managed install layout):

Create the venv outside the cloned source tree — a venv inside the directory the agent operates from can be wiped by a relative-path command the agent runs against its own checkout, destroying the running runtime mid-session.

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv ~/.hermes/venvs/hermes-dev --python 3.11
source ~/.hermes/venvs/hermes-dev/bin/activate
uv pip install -e ".[all,dev]"
scripts/run_tests.sh

---

Community

• 💬 Discord
• 📚 Skills Hub
• 🐛 Issues
• 🔌 computer-use-linux — Linux desktop-control MCP server for Hermes and other MCP hosts, with AT-SPI accessibility trees, Wayland/X11 input, screenshots, and compositor window targeting.
• 🔌 HermesClaw — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.

---

License

MIT — see LICENSE.

Built by Nous Research.