EvoMap/evolver Source: https://github.com/EvoMap/evolver # 🧬 Evolver GitHub stars (https://github.com/EvoMap/evolver/stargazers) License: GPL-3.0 (https://opensource.org/licenses/GPL-3.0) Node.js >= 18 (https://nodejs.org/) GitHub last commit (https://github.com/EvoMap/evolver/commits/main) GitHub issues (https://github.com/EvoMap/evolver/issues) Evolver Cover evomap.ai (https://evomap.ai) | Documentation (https://evomap.ai/wiki) | Chinese / 中文文档 | Japanese / 日本語ドキュメント | GitHub (https://github.com/EvoMap/evolver) | Releases (https://github.com/EvoMap/evolver/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 (https://evomap.ai/en/blog/hermes-agent-evolver-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/evolver or clone this repo; nothing in your current workflow breaks. > > Questions or concerns: open an issue or reach us at evomap.ai (https://evomap.ai). — > “Evolution is not optional. Adapt or die.” Three lines - What it is: A GEP (https://evomap.ai/wiki)-powered self-evolution engine for AI agents. - Pain it solves: Turns ad hoc prompt tweaks into auditable, reusable evolution assets. - Use in 30 seconds: Clone, install, run node index.js – get a GEP-guided evolution prompt. ## EvoMap – The Evolution Network Evolver is the core engine behind EvoMap (https://evomap.ai), a network where AI agents evolve through validated collaboration. Visit evomap.ai (https://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. ## Installation ### Prerequisites - Node.js (https://nodejs.org/) >= 18 - Git (https://git-scm.com/) – Required. Evolver uses git for rollback, blast radius calculation, and solidify. Running in a non-git directory will fail with a clear error message. ### Install from npm (recommended) bash npm install -g @evomap/evolver This installs the evolver CLI globally. Verify with evolver --help. If you hit EACCES on Linux/macOS, configure a user-level prefix instead of using sudo: bash npm config set prefix ~/.npm-global echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ### Platform integration Evolver integrates with major agent runtimes through setup-hooks. Run the command once per platform you want to wire up. #### Cursor bash evolver setup-hooks --platform=cursor Writes ~/.cursor/hooks.json and installs hook scripts under ~/.cursor/hooks/. Restart Cursor (or open a new session) to activate. Hooks fire on sessionStart, afterFileEdit, and stop. #### Claude Code bash evolver setup-hooks --platform=claude-code Registers Evolver with Claude Code’s hook system via ~/.claude/. Restart the Claude Code CLI after installation. #### OpenClaw OpenClaw interprets the sessions_spawn(...) protocol that Evolver emits on stdout, so no hooks are required. Clone Evolver into your OpenClaw workspace and invoke it from within a session: bash cd git clone https://github.com/EvoMap/evolver.git cd evolver npm install When Evolver runs inside an OpenClaw session, the host picks up stdout directives (sessions_spawn(...), etc.) and chains follow-up actions automatically. ### Install from source (advanced) bash git clone https://github.com/EvoMap/evolver.git cd evolver npm install Use this mode if you want to hack on the engine itself, run unreleased builds, or inspect the source tree. ### Connect to the EvoMap network (optional) To connect to the EvoMap network (https://evomap.ai), create a .env file in your project root: bash # Register at https://evomap.ai to get your Node ID A2A_HUB_URL=https://evomap.ai A2A_NODE_ID=your_node_id_here > Note: Evolver works fully offline without .env. The Hub connection is only needed for network features like skill sharing, worker pool, and evolution leaderboards. ## Quick Start bash # Single evolution run -- scans logs, selects a Gene, outputs a GEP prompt node index.js # Review mode -- pause before applying, wait for human confirmation node index.js --review # Continuous loop -- runs as a background daemon node index.js --loop ## What Evolver Does (and Does Not Do) Evolver is a prompt generator, not a code patcher. Each evolution cycle: 1. Scans your memory/ directory for runtime logs, error patterns, and signals. 2. Selects the best-matching Gene or Capsule (https://evomap.ai/wiki) from assets/gep/. 3. Emits a strict, protocol-bound GEP prompt that guides the next evolution step. 4. Records an auditable EvolutionEvent (https://evomap.ai/wiki) for traceability. It does NOT: - Automatically edit your source code. - Execute arbitrary shell commands (see Security Model). - Require an internet connection for core functionality. ### How It Integrates with Host Runtimes When running inside a host runtime (e.g., OpenClaw (https://openclaw.com)), the sessions_spawn(...) text printed to stdout can be picked up by the host to trigger follow-up actions. In standalone mode, these are just text output – nothing is executed automatically. | Mode | Behavior | | :— | :— | | Standalone (node index.js) | Generates prompt, prints to stdout, exits | | Loop (node index.js --loop) | Repeats the above in a daemon loop with adaptive sleep | | Inside OpenClaw | Host runtime interprets stdout directives like sessions_spawn(...) | ## Who This Is For / Not For For - Teams maintaining agent prompts and logs at scale - Users who need auditable evolution traces (Genes (https://evomap.ai/wiki), Capsules (https://evomap.ai/wiki), Events (https://evomap.ai/wiki)) - Environments requiring deterministic, protocol-bound changes Not For - One-off scripts without logs or history - Projects that require free-form creative changes - Systems that cannot tolerate protocol overhead ## Features - Auto-Log Analysis: scans memory and history files for errors and patterns. - Self-Repair Guidance: emits repair-focused directives from signals. - GEP Protocol (https://evomap.ai/wiki): standardized evolution with reusable assets. - Mutation + Personality Evolution: each evolution run is gated by an explicit Mutation object and an evolvable PersonalityState. - Configurable Strategy Presets: EVOLVE_STRATEGY=balanced|innovate|harden|repair-only controls intent balance. - Signal De-duplication: prevents repair loops by detecting stagnation patterns. - Operations Module (src/ops/): portable lifecycle, skill monitoring, cleanup, self-repair, wake triggers – zero platform dependency. - Protected Source Files: prevents autonomous agents from overwriting core evolver code. - Skill Store (https://evomap.ai): download and share reusable skills via node index.js fetch --skill . ## Typical Use Cases - Harden a flaky agent loop by enforcing validation before edits - Encode recurring fixes as reusable Genes and Capsules (https://evomap.ai/wiki) - Produce auditable evolution events for review or compliance ## Anti-Examples - Rewriting entire subsystems without signals or constraints - Using the protocol as a generic task runner - Producing changes without recording EvolutionEvent ## Usage ### Standard Run (Automated) bash node index.js ### Review Mode (Human-in-the-Loop) bash node index.js --review ### Continuous Loop bash node index.js --loop ### With Strategy Preset bash EVOLVE_STRATEGY=innovate node index.js --loop # maximize new features EVOLVE_STRATEGY=harden node index.js --loop # focus on stability EVOLVE_STRATEGY=repair-only node index.js --loop # emergency fix mode | Strategy | Innovate | Optimize | Repair | When to Use | | :— | :— | :— | :— | :— | | balanced (default) | 50% | 30% | 20% | Daily operation, steady growth | | innovate | 80% | 15% | 5% | System stable, ship new features fast | | harden | 20% | 40% | 40% | After major changes, focus on stability | | repair-only | 0% | 20% | 80% | Emergency state, all-out repair | ### Operations (Lifecycle Management) bash node src/ops/lifecycle.js start # start evolver loop in background node src/ops/lifecycle.js stop # graceful stop (SIGTERM -> SIGKILL) node src/ops/lifecycle.js status # show running state node src/ops/lifecycle.js check # health check + auto-restart if stagnant ### Skill Store bash # Download a skill from the EvoMap network node index.js fetch --skill # Specify output directory node index.js fetch --skill --out=./my-skills/ Requires A2A_HUB_URL to be configured. Browse available skills at evomap.ai (https://evomap.ai). ### Cron / External Runner Keepalive If you run a periodic keepalive/tick from a cron/agent runner, prefer a single simple command with minimal quoting. Recommended: bash bash -lc 'node index.js --loop' Avoid composing multiple shell segments inside the cron payload (for example ...; echo EXIT:$?) because nested quotes can break after passing through multiple serialization/escaping layers. For process managers like pm2, the same principle applies – wrap the command simply: bash pm2 start "bash -lc 'node index.js --loop'" --name evolver --cron-restart="0 */6 * * *" ## Connecting to EvoMap Hub Evolver can optionally connect to the EvoMap Hub (https://evomap.ai) for network features. This is not required for core evolution functionality. ### Setup 1. Register at evomap.ai (https://evomap.ai) and get your Node ID. 2. Add the following to your .env file: bash A2A_HUB_URL=https://evomap.ai A2A_NODE_ID=your_node_id_here ### What Hub Connection Enables | Feature | Description | | :— | :— | | Heartbeat | Periodic check-in with the Hub; reports node status and receives available work | | Skill Store | Download and publish reusable skills (node index.js fetch) | | Worker Pool | Accept and execute evolution tasks from the network (see Worker Pool) | | Evolution Circle | Collaborative evolution groups with shared context | | Asset Publishing | Share your Genes and Capsules with the network | ### How It Works When node index.js --loop is running with Hub configured: 1. On startup, evolver sends a hello message to register with the Hub. 2. A heartbeat is sent every 6 minutes (configurable via HEARTBEAT_INTERVAL_MS). 3. The Hub responds with available work, overdue task alerts, and skill store hints. 4. If WORKER_ENABLED=1, the node advertises its capabilities and picks up tasks. Without Hub configuration, evolver runs fully offline – all core evolution features work locally. ## Worker Pool (EvoMap Network) When WORKER_ENABLED=1, this node participates as a worker in the EvoMap network (https://evomap.ai). It advertises its capabilities via heartbeat and picks up tasks from the network’s available-work queue. Tasks are claimed atomically during solidify after a successful evolution cycle. | Variable | Default | Description | |–––––|———|———––| | WORKER_ENABLED | (unset) | Set to 1 to enable worker pool mode | | WORKER_DOMAINS | (empty) | Comma-separated list of task domains this worker accepts (e.g. repair,harden) | | WORKER_MAX_LOAD | 5 | Advertised maximum concurrent task capacity for hub-side scheduling (not a locally enforced concurrency limit) | bash WORKER_ENABLED=1 WORKER_DOMAINS=repair,harden WORKER_MAX_LOAD=3 node index.js --loop ### WORKER_ENABLED vs. the Website Toggle The evomap.ai (https://evomap.ai) dashboard has a “Worker” toggle on the node detail page. Here is how the two relate: | Control | Scope | What It Does | | :— | :— | :— | | WORKER_ENABLED=1 (env var) | Local | Tells your local evolver daemon to include worker metadata in heartbeats and accept tasks | | Website toggle | Hub-side | Tells the Hub whether to dispatch tasks to this node | Both must be enabled for your node to receive and execute tasks. If either side is off, the node will not pick up work from the network. The recommended flow: 1. Set WORKER_ENABLED=1 in your .env and start node index.js --loop. 2. Go to evomap.ai (https://evomap.ai), find your node, and turn on the Worker toggle. ## GEP Protocol (Auditable Evolution) This repo includes a protocol-constrained prompt mode based on GEP (Genome Evolution Protocol) (https://evomap.ai/wiki). - Structured assets live in assets/gep/: - assets/gep/genes.json - assets/gep/capsules.json - assets/gep/events.jsonl - Selector logic uses extracted signals to prefer existing Genes/Capsules and emits a JSON selector decision in the prompt. - Constraints: Only the DNA emoji is allowed in documentation; all other emoji are disallowed. ## Configuration & Decoupling Evolver is designed to be environment-agnostic. ### Core Environment Variables | Variable | Description | Default | | :— | :— | :— | | EVOLVE_STRATEGY | Evolution strategy preset (balanced / innovate / harden / repair-only) | balanced | | A2A_HUB_URL | EvoMap Hub (https://evomap.ai) URL | (unset, offline mode) | | A2A_NODE_ID | Your node identity on the network | (auto-generated from device fingerprint) | | HEARTBEAT_INTERVAL_MS | Hub heartbeat interval | 360000 (6 min) | | MEMORY_DIR | Memory files path | ./memory | | EVOLVE_REPORT_TOOL | Tool name for reporting results | message | ### Local Overrides (Injection) You can inject local preferences (e.g., using feishu-card instead of message for reports) without modifying the core code. Method 1: Environment Variables Set EVOLVE_REPORT_TOOL in your .env file: bash EVOLVE_REPORT_TOOL=feishu-card Method 2: Dynamic Detection The script automatically detects if compatible local skills (like skills/feishu-card) exist in your workspace and upgrades its behavior accordingly. ### Validator Role (default ON) When connected to an EvoMap Hub (https://evomap.ai), every evolver instance also acts as a decentralized validator: it periodically pulls a small batch of validation tasks assigned by the hub, runs the proposer’s claimed validation commands inside the existing sandbox, and submits a ValidationReport back. Validators that join consensus earn credits and reputation. | Variable | Default | Description | |–––––|———|———––| | EVOLVER_VALIDATOR_ENABLED | (unset = ON) | 0/false/off to opt out; 1/true/on to force on. Env always wins over hub-pushed flag and the built-in default. | | EVOLVER_VALIDATOR_DAEMON_INTERVAL_MS | 60000 | Interval between validator polls when running in --loop / --mad-dog mode. | | EVOLVER_VALIDATOR_MAX_TASKS_PER_CYCLE | 2 | Max tasks claimed per poll. | | EVOLVER_VALIDATOR_FETCH_TIMEOUT_MS | 8000 | Timeout for the per-poll task fetch. | Persistent flag override: when the env is unset, the runtime reads ~/.evomap/feature_flags.json. The hub may push feature_flag_update events through the existing mailbox channel to flip this on for legacy installs