Key Takeaway:
Evolver turns noisy, ad‑hoc prompt tweaks into safe, auditable, and reusable evolution assets so your AI agents can continuously self‑repair, optimize, and innovate under protocol control.
Evolver is a GEP‑powered self‑evolution engine that analyzes an AI agent’s runtime history, extracts improvement signals, and emits strict Genome Evolution Protocol (GEP) prompts to drive safe, auditable evolution cycles.evomap-evolver.
Instead of manually hacking prompts after each failure, Evolver converts those tweaks into structured “genes” and “capsules” that can be versioned, replayed, and shared across agents.
Developed by the EvoMap team, Evolver acts as the core engine of the EvoMap self‑evolution network, allowing agents to inherit validated capabilities from each other rather than reinventing solutions in isolation.
The official implementation is available as an open‑source Node.js project and as a global CLI package at Evolver on GitHub, maintained under the @evomap/evolver namespace on npm.
Why traditional AI agents hit a wall
Most LLM‑based agents today are effectively static: once deployed, their prompts and workflows only improve when a human developer manually inspects logs and patches configuration or code.
That workflow is slow, brittle, and hard to audit—especially when you cannot explain which change improved performance, or why a regression appeared after a series of “quick fixes.”
Traditional fine‑tuning and RL pipelines help, but they typically operate offline and do not capture the day‑to‑day evolution of prompts and behaviors emerging from real traffic.
They also offer little in the way of standardized packaging or sharing, so one agent’s hard‑won fix rarely becomes a reusable building block for others.
GEP in the Evolver ecosystem
In classic Gene Expression Programming (GEP), candidate solutions are encoded as fixed‑length linear chromosomes that are expressed as variable‑shaped expression trees, combining the strengths of genetic algorithms and genetic programming.
This genotype–phenotype separation makes it easy to mutate and recombine compact genomes while exploring rich solution structures, which is exactly what you want when evolving programs or strategies over time.
Evolver adapts these ideas into the Genome Evolution Protocol (also abbreviated GEP), which defines how “genes” (evolution rules) and “capsules” (execution contexts) are packaged, validated, and inherited by AI agents.
Each successful fix or optimization becomes an evolution asset with a schema, metadata, and immutable event history, so later agents can reuse it under strict safety and compatibility constraints.
How Evolver’s self‑evolution loop works
At a high level, Evolver’s runtime loop follows three core phases: Analysis, Selection, and Execution.evomap-evolver.
- In the Analysis phase, Evolver scans session logs and memory directories for error patterns, performance anomalies, and other evolution signals.evomap-evolver.
- In the Selection phase, it queries a memory graph and local GEP asset pool to match signals to candidate genes and capsules, then builds a mutation directive with rationale and blast‑radius estimation.
- In the Execution phase, Evolver emits a strict GEP protocol prompt, validates changes via tests and guardrails, and records an immutable EvolutionEvent describing signals, genes used, mutations applied, and observed outcomes.
The memory graph maintains causal links between signals, genes, and outcomes, allowing Evolver to avoid looping on failed fixes and to prioritize strategies that historically improved success rates.
Crucially, Evolver uses Git to track changes, compute impact scope (“blast radius”), and enable automatic rollback when an evolution degrades behavior.
Prerequisites and environment setup
Evolver is implemented in Node.js and requires a modern runtime plus Git for version control and rollback.
Before installing, verify:
# Node.js must be >= 18
node --version
# Git must be available
git --versionRunning Evolver in a non‑Git directory is explicitly unsupported and will fail with a clear error, because Git metadata is used for rollback and blast‑radius calculations.
You should therefore install it inside a project that is already initialized as a Git repository (or initialize one with git init).
Installing Evolver step by step
Evolver supports both a global CLI via npm and a local installation by cloning the GitHub repository.
Option 1: Global CLI via npm (recommended)
For most workflows, the simplest path is to install the Evolver CLI globally:
# Install Evolver globally
npm install -g @evomap/evolver
# Verify installation
evolver --helpIf you see permission errors (for example EACCES) on Linux or macOS, configure a user‑level npm prefix instead of using sudo:
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @evomap/evolverOnce installed, the evolver binary exposes help, version info, and environment‑specific integrations such as setup-hooks for tools like Cursor and Claude Code.
Option 2: Clone the GitHub repository
If you prefer to run Evolver as a local project (or to inspect/extend the source), clone the official repository:
# Clone the Evolver repository
git clone https://github.com/EvoMap/evolver.git
# Enter the project directory
cd evolver
# Install dependencies
npm installThis gives you a workspace containing index.js (main entry point), package.json (dependencies and metadata), an assets directory for GEP artifacts, and a memory directory for evolution logs.
You can keep the local clone up to date with the upstream project by running git pull && npm install periodically.
Configuring Evolver for your agents
To connect Evolver to the EvoMap network and control its behavior, you configure environment variables—typically via a .env file in the project root.
Create .env with at least:
# EvoMap Network Identity
A2A_NODE_ID=node_xxxxxxxxxxxx
A2A_HUB_URL=https://evomap.ai
# Evolution Strategy
EVOLVE_STRATEGY=balanced
# Safety Settings
EVOLVE_ALLOW_SELF_MODIFY=false
EVOLVE_LOAD_MAX=2.0
# Rollback Strategy (safe mode)
EVOLVER_ROLLBACK_MODE=stashA2A_NODE_IDis your EvoMap node identity, obtained via the EvoMap onboarding orhelloflow; it should never be hard‑coded into shared scripts.A2A_HUB_URLdefaults tohttps://evomap.aiand is the endpoint for publishing, fetching, and reporting GEP assets to the EvoMap hub.EVOLVE_STRATEGYcontrols how aggressively Evolver balances repair, optimization, and innovation during evolution cycles.evomap-evolver.
For production environments, keep EVOLVE_ALLOW_SELF_MODIFY=false so Evolver never rewrites its own source code, and use Git‑based rollback modes such as stash or branch‑based strategies.
Running your first evolution cycle
Once installed and configured, you can run Evolver directly from the project directory.
Single evolution run
From your Evolver workspace:
# Run a single evolution cycle
node index.jsOn each run, Evolver will scan logs under the memory directory, extract signals, query the GEP asset pool, and emit a GEP‑guided evolution prompt describing the proposed changes.
If A2A_NODE_ID is set, you should also see heartbeat messages confirming that your node can reach the EvoMap hub.
Review and approval
You can enforce a human‑in‑the‑loop workflow where Evolver proposes changes but you approve or reject them before they are solidified:
# Approve and solidify changes
node index.js review --approve
# Reject and rollback
node index.js review --rejectThis mode is useful for teams that want auditable evolution events but still require manual oversight on what actually lands in the main branch.
Continuous loop mode
For always‑on agents, run Evolver in loop mode:
# Continuous evolution with default strategy
node index.js --loopYou can pin specific strategies to reflect your system’s maturity and risk tolerance:
# Maximize new features and exploration
EVOLVE_STRATEGY=innovate node index.js --loop
# Focus on stability and error reduction
EVOLVE_STRATEGY=harden node index.js --loop
# Emergency repair‑only mode
EVOLVE_STRATEGY=repair-only node index.js --loop
# Balanced (default) evolution
EVOLVE_STRATEGY=balanced node index.js --loopUnder the hood, these presets adjust the proportion of repair, optimization, and innovation cycles—for example, innovate biases heavily toward new capabilities, while repair-only concentrates almost entirely on fixing existing failures.evomap-evolver.
You can schedule loop mode via cron or a process manager like PM2; the official docs include examples such as a cron entry that runs node index.js --loop every six hours or a PM2 process using pm2 start "bash -lc 'node index.js --loop'" --name evolver.
Managing Evolver as a daemon
For more advanced setups, Evolver ships an operations module that can manage its lifecycle as a background daemon:
# Start Evolver loop in the background
node src/ops/lifecycle.js start
# Stop all running loops
node src/ops/lifecycle.js stop
# Restart Evolver
node src/ops/lifecycle.js restartThese commands handle PID tracking, graceful shutdown, forced termination if needed, and cleanup of lock files under the memory directory.
Understanding strategy presets and safety
Strategy presets provide a high‑level knob for how Evolver allocates its efforts across repair, optimization, and innovation.evomap-evolver.
For example:
balanced(default) focuses 20% on repair, 30% on optimization, and 50% on innovation, switching modes when it detects excessive repair loops.hardenprioritizes robustness with higher repair and optimization ratios and limited innovation, ideal after major refactors or before critical launches.evomap-evolver.repair-onlydisables innovation entirely and concentrates on emergency fixes when the system is in a degraded state.
Evolver’s safety model includes command whitelisting, blocking arbitrary shell operations, Git‑backed rollback, and strict blast‑radius evaluation so that even aggressive strategies remain within protocol‑defined bounds.
Because every evolution is recorded as an EvolutionEvent with inputs, chosen genes, and outcomes, you retain a full audit trail for debugging, governance, and compliance reviews.evomap-evolver.
Integrating with the EvoMap network
EvoMap is the broader infrastructure platform that lets agents publish, validate, and inherit capabilities via the Genome Evolution Protocol, turning successful evolutions into globally reusable assets.
Through hub endpoints such as hello, fetch, publish, and report, agents can register identities, request candidate genes, share new capsules, and feed back outcome metrics to improve selection over time.
Evolver is designed as the plug‑and‑play engine that speaks this protocol, so once your node is registered and A2A_NODE_ID is configured, your agents can participate in a collaborative evolution marketplace rather than evolving in isolation.
Checking the latest releases, changelog, and integration notes on Evolver’s GitHub repository will ensure your stack stays aligned with ongoing changes to the protocol and network.
