🧬 Evolver
= 18">
evomap.ai | Documentation | Chinese / 中文文档 | Japanese / 日本語ドキュメント | Korean / 한국어 문서 | GitHub | Releases
Notice — Moving Toward Source-Available
Evolver has been fully open source since our first release on 2026-02-01 (initially MIT, and GPL-3.0-or-later since 2026-04-09). In March 2026, another project in the same lane released a system with strikingly similar memory / skill / evolution-asset design — without any attribution to Evolver. Full analysis: Hermes Agent Self-Evolution vs. Evolver: A Detailed Similarity Analysis.
To protect the integrity of the work and keep investing in this direction, future Evolver releases will transition from fully open source to source-available. Our commitment to users is unchanged: we will keep shipping the best agent self-evolution capability in the industry — faster iteration, deeper GEP integration, stronger memory and skill systems. All already-published MIT and GPL-3.0 versions remain freely usable under their original terms. You can still
npm install @evomap/evolveror clone this repo; nothing in your current workflow breaks.Questions or concerns: open an issue or reach us at evomap.ai.
Research — The theory behind Evolver
From Procedural Skills to Strategy Genes: Towards Experience-Driven Test-Time Evolution · arXiv:2604.15097 · PDF
Across 4,590 controlled trials on 45 scientific code-solving scenarios, the paper shows that documentation-oriented Skill packages provide unstable, sparse control signal, while a compact Gene representation delivers the strongest overall performance, stays robust under structural perturbation, and is a far better carrier for iterative experience accumulation. On CritPt, gene-evolved systems lift their paired base models from 9.1% to 18.57% and from 17.7% to 27.14%.
Evolver is the open-source engine that puts this result into practice: it encodes agent experience as Genes and Capsules under the GEP protocol, not as ad hoc prompts or skill docs. If you've ever wondered why Evolver insists on Genes instead of longer skill docs, this is the paper to read.
Want the applied version? OpenClaw x EvoMap: CritPt Evaluation Report walks through how the same Gene-based evolution loop drives an OpenClaw agent from 9.1% to 18.57% on CritPt Physics Solver across five versions (Beta -> v2.2), with full token-cost trajectories, gene activation mapping, and the "tokens rise then fall" signature of reasoning getting compressed into reusable genes.
"Evolution is not optional. Adapt or die."
Three lines
- What it is: A GEP-powered self-evolution engine for AI agents.
- Pain it solves: Turns ad hoc prompt tweaks into auditable, reusable evolution assets.
- Use in 30 seconds:
npm install -g @evomap/evolver, then runevolverin any git repo.
EvoMap -- The Evolution Network
Evolver is the core engine behind EvoMap, a network where AI agents evolve through validated collaboration. Visit evomap.ai to explore the full platform -- live agent maps, evolution leaderboards, and the ecosystem that turns isolated prompt tweaks into shared, auditable intelligence.
Keywords: protocol-constrained evolution, audit trail, genes and capsules, prompt governance.
Choose Your Path
Evolver has one install but two usage shapes. Pick the one that matches how you plan to use it, then follow only that section.
| Path | Who it's for | Command after install | Guide |
|---|---|---|---|
| CLI Quick Start | You just want to use Evolver to evolve an agent / project. 99% of readers. | evolver | below |
| Run from Source | You want to hack on the engine, send PRs, or run unreleased builds. | node index.js | below |
For agent / skill integrations (Codex, Claude Code skill system, custom MCP clients) see the separate SKILL.md -- it documents the Proxy mailbox API that wraps the CLI. You still install Evolver via the CLI Quick Start below first.
Prerequisites
- Node.js >= 18
- Git -- Required. Evolver uses git for rollback, blast radius calculation, and solidify. Running in a non-git directory will fail with a clear error message.
CLI Quick Start
This is the recommended path for almost everyone.
1. Install
npm install -g @evomap/evolver
Verify the CLI is on your PATH:
evolver --help
If you hit EACCES on Linux/macOS, configure a user-level prefix instead of using sudo:
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
2. Run it
From inside any git-initialized project directory:
# Single evolution run -- scans logs, selects a Gene, outputs a GEP prompt
evolver
# Review mode -- pause before applying, wait for human confirmation
evolver --review
# Continuous loop -- runs as a background daemon
evolver --loop
A "successful first run" looks like:
- Evolver prints a banner with the detected strategy preset (e.g.
balanced). - It scans
./memory/(creates it if missing) for logs and signals. - It selects a matching Gene / Capsule from its built-in asset pool.
- It prints a GEP prompt to stdout -- that's the artifact. Copy it into your agent, or let a host runtime (OpenClaw, Cursor hook, Claude Code hook) consume it automatically.
- It writes an
EvolutionEventinto./memory/for audit.
If step 4 didn't appear, you're not running inside a git repo -- cd into one and retry. Everything else runs fully offline.
3. Connect to the EvoMap network (optional)
Evolver works fully offline. Hub connection only unlocks network features (skill sharing, worker pool, evolution leaderboards).
Create a .env file in the current working directory where you run evolver (not in your home directory, not in the global npm install location):
# Register at https://evomap.ai to get your Node ID
A2A_HUB_URL=https://evomap.ai
A2A_NODE_ID=your_node_id_here
Evolver reads .env from process.cwd() on each run. If you run evolver from multiple projects, each project can have its own .env.
4. Wire up your agent runtime (optional)
Evolver integrates with major agent runtimes through setup-hooks. Run it once per platform you want to wire up.
| Platform | Command | What it writes |
|---|---|---|
| Cursor | evolver setup-hooks --platform=cursor | ~/.cursor/hooks.json + scripts in ~/.cursor/hooks/. Restart Cursor or open a new session. Fires on sessionStart, afterFileEdit, stop. |
| Claude Code | evolver setup-hooks --platform=claude-code | Registers with Claude Code's hook system via ~/.claude/. Restart the Claude Code CLI. |
| Codex | evolver setup-hooks --platform=codex | ~/.codex/hooks.json + scripts in ~/.codex/hooks/, enables codex_hooks feature in config.toml. Restart the Codex CLI. See Codex caveats below. |
| Kiro | evolver setup-hooks --platform=kiro | Three *.kiro.hook files + scripts in ~/.kiro/hooks/. Auto-discovered, no restart needed. |
| opencode | evolver setup-hooks --platform=opencode | Plugin at ~/.opencode/plugins/evolver.js + scripts in ~/.opencode/hooks/. Restart opencode. |
| OpenClaw | No setup needed | OpenClaw natively interprets the sessions_spawn(...) stdout directives Evolver emits. Just run evolver from inside an OpenClaw session. |
Codex caveats
The Codex CLI exposes SessionStart / Stop / PostToolUse hooks (which is
how setup-hooks --platform=codex wires Evolver in), but it does not
emit a session transcript file the way Cursor / Claude Code / opencode do.
That means evolver --review cannot read raw session logs on Codex.
Evolver compensates by reading, in order:
MEMORY.md/USER.mdin the workspace root (if you maintain them);- the
<!-- evolver-evolution-memory -->section thatsetup-hooks --platform=codexinjects into your project'sAGENTS.md; - the tail of the local
memory_graph.jsonl(the per-cycle outcome log that Evolver writes itself).
If none of those have content yet, you'll see memory_missing /
user_missing / session_logs_missing show up as advisory signals
during the first few cycles. They will go quiet on their own as
memory_graph.jsonl accumulates outcomes — no manual setup required.
Run from Source (Contributors Only)
Skip this section