Hermes Agent Self-Evolution: Evolving SKILL.md Files with DSPy and GEPA
⚒ Evolutionary self-improvement for Hermes Agent — optimize skills, prompts, and code using DSPy + GEPA
At a glance
- What is it?
- Hermes Agent Self-Evolution is a Python tool that mutates Hermes Agent skill files, evaluates the variants against a dataset, and opens a pull request with the winner. Only Phase 1 is implemented, and the README is explicit that every change still goes through human review.
- Who is it for?
- Adopt it if you already run Hermes Agent and have a skill whose failures you can actually observe in session history: Phase 1 is implemented, the guardrails are enumerated in the README, and the output is a pull request rather than a commit. Do not adopt it if you need tool description, system prompt or code optimization, because those phases are listed as planned, and do not adopt it if you cannot supply a usable eval dataset, because the loop has nothing to select on.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 151 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- NousResearch/hermes-agent-self-evolution5,715 ★ · +319
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| NousResearch/hermes-agent-self-evolution | 5.4k | 5.7k |
319 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What Hermes Agent Self-Evolution is actually for
Hermes Agent is Nous Research's agent project, and its behaviour is partly defined by text: skill files such as SKILL.md, tool descriptions, and system prompt sections. Those texts are written by hand and then rarely revisited, even when the agent keeps failing at the same step. Hermes Agent Self-Evolution is a separate repository whose job is to rewrite that text automatically and propose the result back upstream.
The README frames the target audience narrowly. This is for someone who already runs a hermes-agent checkout and can point a tool at it. The quick start exports HERMES_AGENT_REPO, which means the evolution process operates on a local copy of the agent repository rather than on anything hosted. If you do not have that checkout, the tool has nothing to evolve.
The scope is also narrower than the repository name suggests. The README's phase table marks Phase 1, skill files (SKILL.md), as implemented. Tool descriptions, system prompt sections, tool implementation code, and a continuous improvement loop are listed as planned. So the honest description in mid-2026 is a skill-file optimizer with a roadmap attached, not a general self-improvement system for the whole agent.
The GEPA loop: traces in, candidate variants out
The mechanism is reflective evolutionary search, not gradient training. The README states plainly that no GPU training is required and that everything operates via API calls, with a stated cost of roughly $2 to $10 per optimization run. That cost estimate is the project's own, not a measured figure, and it will move with the size of your eval dataset and the number of iterations you pass on the command line.
The data flow in the README runs like this: read the current skill, prompt or tool description; generate an eval dataset; feed execution traces into the GEPA optimizer; produce candidate variants; evaluate them; pass them through constraint gates; and take the best variant to a pull request against hermes-agent. The distinguishing claim is in the middle of that loop. GEPA reads execution traces to understand why things fail, not merely that they failed, and proposes targeted improvements on that basis. That is the difference between mutating a prompt at random and mutating the part of the prompt that the trace implicates.
Two dataset sources are documented. The synthetic option generates eval data for you, which is the low-friction path. The sessiondb option draws on real session history from Claude Code, Copilot, and Hermes, which should produce a sharper signal because the failures are real. The README does not describe the sessiondb schema or how sessions are selected, so that is a piece you will have to read the code for. GEPA itself is described as ICLR 2026 Oral and MIT licensed, which is a claim about the upstream optimizer rather than about this wrapper.
Installing it and running a first evolution
The README gives a clone-and-editable-install sequence. The dev extra pulls in pytest and pytest-asyncio, which you want because the test suite is one of the guardrails.
git clone https://github.com/NousResearch/hermes-agent-self-evolution.git
cd hermes-agent-self-evolution
pip install -e ".[dev]"Next, point the tool at your local hermes-agent checkout. The README uses ~/.hermes/hermes-agent as the example path; substitute wherever yours actually lives.
export HERMES_AGENT_REPO=~/.hermes/hermes-agentThen run one evolution against a skill. The README's worked example is github-code-review with ten iterations and synthetic eval data.
python -m evolution.skills.evolve_skill \
--skill github-code-review \
--iterations 10 \
--eval-source syntheticThe same command with --eval-source sessiondb uses real session history instead. Expect API spend proportional to iterations and dataset size, since every candidate has to be evaluated through API calls. The README does not document what the command prints at the end, how the winning variant is stored, or where the generated PR lands, so treat the first run as an exploration of the tool's output rather than a known quantity. The pyproject.toml requires Python 3.10 or newer, and the runtime dependencies are dspy, openai, pyyaml, click and rich.
The guardrails are the interesting design decision
An optimizer that can rewrite an agent's instructions is a system that can quietly make the agent worse, so the guardrails matter more than the search. The README lists five gates that every evolved variant must pass: the full test suite via pytest tests/ -q at 100 percent, size limits of 15KB for skills and 500 characters for tool descriptions, caching compatibility meaning no mid-conversation changes, semantic preservation meaning the variant must not drift from the original purpose, and human review of every pull request with no direct commits.
The size limit is the most concrete of these and the easiest to reason about. A skill file that grows past 15KB is rejected regardless of how well it scores, which caps the prompt bloat that evolutionary search tends to produce when it is rewarded only on eval performance. The caching constraint is the subtler one: anything that changes mid-conversation breaks prompt caching, so the optimizer is restricted to edits that are stable for the life of a conversation.
The weakest gate is semantic preservation. "Must not drift from original purpose" is a judgement, and the README does not say whether it is enforced by a model, by a similarity threshold, or by the human reviewer. That is the gate most likely to fail silently, and it is the one I would read the code for before trusting a run.
Where it breaks down, and when it is the wrong tool
The clearest limitation is coverage. If your problem is a badly worded tool description or a system prompt section that misleads the agent, this repository does not fix it today: those are Phase 2 and Phase 3, both marked planned. You can read the phase table as a roadmap, but you cannot run it.
The second limitation is the eval dataset. Evolutionary search selects whatever your metric rewards. With --eval-source synthetic, the eval data is generated rather than observed, so the optimizer is optimizing against a proxy for your real usage. A variant that scores well on synthetic data and fails on the sessiondb data is a real possibility, and the README offers no guidance on which source to prefer or how to compare them.
The third is the cost model. The README's $2 to $10 per run is a range, not a guarantee, and it scales with iterations and dataset size. Running ten iterations on a large sessiondb dataset is a different proposition from the synthetic example. There is no documented dry-run mode or cost ceiling, so budget control is on you.
The fourth is the human review gate doing real work. Because every change arrives as a pull request, the tool does not remove the review burden; it moves it. Someone still has to read the diff and judge whether the evolved skill is better, and that judgement is exactly the thing the eval metric was supposed to approximate.
DSPy plus GEPA versus the Darwinian Evolver path
The repository names two engines with genuinely different approaches. DSPy plus GEPA does reflective prompt evolution: it reads execution traces, proposes targeted mutations to text, and selects among variants. Darwinian Evolver does code evolution with Git-based organisms, which is a different unit of change entirely. Text mutations are cheap to evaluate and easy to revert; code mutations touch behaviour and need a test suite strong enough to catch regressions.
The licensing split is the practical difference. DSPy and GEPA are MIT licensed. Darwinian Evolver is AGPL v3, and the README qualifies it as external CLI only. That qualification is doing a lot of work: if the AGPL component is invoked as a separate command-line tool rather than linked into the Python package, the obligations land differently than if it were a library dependency. The pyproject.toml reflects this by putting darwinian-evolver in a separate optional extra named darwinian, so a default install never pulls it in. The repository's own LICENSE situation is stated as MIT in the README and as license = {text = "MIT"} in pyproject.toml; the license field in the repository metadata is listed as unknown, so confirm the LICENSE file yourself rather than taking either statement on faith.
If you want prompt and skill optimization only, you never touch the AGPL path. If you later want Phase 4 code evolution, you are invoking an AGPL v3 tool, and that is a decision worth making deliberately rather than by installing an extra.
Maintenance, upgrade cost and what to verify
The last push to the default branch was on 2026-06-17. That is more than four months before 2026-11-03, so the repository is not stale, but it is also not a project with a visible release cadence: the repository has no published releases, and the version in pyproject.toml is 0.1.0. Treat it as early software from a research group.
The dependency surface is small and mostly stable. dspy>=3.0.0 is the one to watch, because DSPy is the engine and a major-version change there is the most likely source of breakage. openai, pyyaml, click and rich are ordinary and low-risk. The dev extra adds pytest and pytest-asyncio. Upgrading means re-running your evolutions, because a new DSPy or GEPA version can change which variants win; there is no documented way to pin a prior optimization result for comparison.
The upgrade cost that is easy to miss is the interaction with your hermes-agent checkout. The tool reads and proposes changes against HERMES_AGENT_REPO, so an evolution run is coupled to the state of that repository at the time you run it. If hermes-agent moves underneath you, a variant that passed the gates last month may not apply cleanly now. The README does not document rollback, so the pull request is your rollback mechanism: reject it and nothing changes.
Editorial conclusion
Adopt it if you already run Hermes Agent and have a skill whose failures you can actually observe in session history: Phase 1 is implemented, the guardrails are enumerated in the README, and the output is a pull request rather than a commit. Do not adopt it if you need tool description, system prompt or code optimization, because those phases are listed as planned, and do not adopt it if you cannot supply a usable eval dataset, because the loop has nothing to select on. Before running anything, verify two things in the repository: that your hermes-agent checkout is the one HERMES_AGENT_REPO points at, and that pytest tests/ -q passes there, since the README makes a full green test suite a gate on every evolved variant.
Frequently asked questions
How is Hermes Agent self-improving?
According to the README, Hermes Agent Self-Evolution uses DSPy and GEPA to read execution traces, understand why a skill failed, and propose targeted mutations to the skill text. Candidate variants are evaluated and must pass constraint gates, and the best one becomes a pull request against hermes-agent rather than a direct commit.
Does Hermes Agent Self-Evolution need a GPU?
No. The README states that no GPU training is required and that everything operates via API calls, with a stated cost of roughly $2 to $10 per optimization run.
Which parts of Hermes Agent can Hermes Agent Self-Evolution optimize?
Only Phase 1, skill files such as SKILL.md, is marked as implemented in the README's phase table. Tool descriptions, system prompt sections, tool implementation code, and a continuous improvement loop are all listed as planned.
How do I install Hermes Agent Self-Evolution?
The README gives a clone followed by an editable install with the dev extra, then exporting HERMES_AGENT_REPO to point at your local hermes-agent checkout. The package requires Python 3.10 or newer.
What happens to an evolved skill before it reaches Hermes Agent?
The README lists five gates: the full test suite must pass 100 percent, skills must stay at or under 15KB and tool descriptions at or under 500 characters, caching compatibility must be preserved, the variant must not drift semantically from the original purpose, and every change goes through human PR review.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/nousresearch-hermes-agent-self-evolution)Star history chart for your README
[](https://hysenlabs.com/projects/nousresearch-hermes-agent-self-evolution)Was this useful?