evolver README

The project's README from github.com/EvoMap/evolver. As one markdown file: README.md.

Evolver

Evolver — Agent Self-Evolving Engine

EvoMap%2Fevolver | Trendshift

GitHub stars License: GPL-3.0 Node.js >= 18 npm downloads arXiv

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/evolver or 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

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

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:

  1. Evolver prints a banner with the detected strategy preset (e.g. balanced).
  2. It scans ./memory/ (creates it if missing) for logs and signals.
  3. It selects a matching Gene / Capsule from its built-in asset pool.
  4. 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.
  5. It writes an EvolutionEvent into ./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.

setup-hooks --platform=codex is lifecycle integration only; it does not route Codex model requests through Evolver Proxy. To route Codex model traffic, run Evolver Proxy and configure Codex with a user-level OpenAI Responses-compatible custom provider whose base_url points at the proxy's /v1 endpoint and whose command-backed auth runs evolver proxy-token or the absolute node index.js proxy-token --settings ... helper emitted by scripts/internal-proxy-env.sh --codex-config from a source checkout.

Evolver compensates by reading, in order:

  1. MEMORY.md / USER.md in the workspace root (if you maintain them);
  2. the <!-- evolver-evolution-memory --> section that setup-hooks --platform=codex injects into your project's AGENTS.md;
  3. 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 entirely if you installed via npm install -g @evomap/evolver above. This path exists so contributors can hack on the engine.

git clone https://github.com/EvoMap/evolver.git
cd evolver
npm install

# Then use node index.js wherever the CLI docs say evolver
node index.js            # equivalent to: evolver
node index.js --review   # equivalent to: evolver --review
node index.js --loop     # equivalent to: evolver --loop

Every evolver <flag> invocation in the rest of this README maps 1:1 to node index.js <flag> when running from source.

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 from the local GEP asset store.
  3. Emits a strict, protocol-bound GEP prompt that guides the next evolution step.
  4. Records an auditable EvolutionEvent for traceability.

It does NOT:

How It Integrates with Host Runtimes

When running inside a host runtime (e.g., OpenClaw), 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 (evolver) Generates prompt, prints to stdout, exits
Loop (evolver --loop) Repeats the above in a daemon loop with adaptive sleep
Inside OpenClaw Host runtime interprets stdout directives like sessions_spawn(...)

--loop is not a real-time agent assistant. Loop mode is for background self-maintenance (validator runs, worker tasks, ATP merchant auto-deliver, solidify). Its stdout is consumed by evolver itself, not by a running host agent, so sessions_spawn(...) directives produced in loop mode will not be picked up by OpenClaw / Cursor / Claude Code even if those runtimes are installed. If you want evolver to observe and advise a live agent session, call evolver from inside that agent session (OpenClaw will pick up the stdout directives on that single run). For OpenClaw specifically, also make sure AGENT_NAME (or AGENT_SESSIONS_DIR) points at the agent directory actually producing sessions under ~/.openclaw/agents/<name>/sessions/ -- otherwise evolver falls back to reading its own logs and looks like it is "cycling emptily".

Who This Is For / Not For

For

Not For

Features

Typical Use Cases

Anti-Examples

Usage

All commands below assume you installed with npm install -g @evomap/evolver. If you are running from source, substitute node index.js for evolver -- they are equivalent.

Standard Run (Automated)

evolver

Review Mode (Human-in-the-Loop)

evolver --review

Continuous Loop

evolver --loop

With Strategy Preset

EVOLVE_STRATEGY=innovate evolver --loop   # maximize new features
EVOLVE_STRATEGY=harden evolver --loop     # focus on stability
EVOLVE_STRATEGY=repair-only evolver --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)

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

# Download a skill from the EvoMap network
evolver fetch --skill <skill_id>

# Specify output directory
evolver fetch --skill <skill_id> --out=./my-skills/

Requires A2A_HUB_URL to be configured. Browse available skills at evomap.ai. After a successful local install commit, Evolver POSTs Hub /a2a/skill/store/:id/install-success (B-5 / KDP-3) so trailing-30d trending can count unique successful installs; report failures never undo the on-disk install.

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 -lc 'evolver --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:

pm2 start "bash -lc 'evolver --loop'" --name evolver --cron-restart="0 */6 * * *"

Connecting to EvoMap Hub

Evolver can optionally connect to the EvoMap Hub for network features. This is not required for core evolution functionality.

Setup

  1. Register at evomap.ai and get your Node ID.
  2. Add the following to your .env file:
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 (evolver 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 evolver --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. 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) 
WORKER_ENABLED=1 WORKER_DOMAINS=repair,harden WORKER_M

evolver (EvoMap/evolver)

a2a
Searching Database…

8.7K ·GitHub
Evolver
What is this?Evolver is a self-evolution engine for AI agents. It reads an agent's runtime logs and signals, distills them into auditable, reusable evolution assets called Genes and Capsules, and emits a protocol-bound GEP prompt that guides the agent's next step.
So is it a library I import into my project, or a standalone tool?A standalone CLI: you install it globally with npm and run 'evolver' in a project directory. For agent and skill integrations there is also a Proxy mailbox API documented in a separate SKILL.md.
How do I get it running?Run 'npm install -g @evomap/evolver', then run 'evolver' inside any git-initialized project — it needs Node.js >= 18 and Git, and fails outside a git repo. A first run scans ./memory/, selects a matching Gene or Capsule, prints a GEP prompt to stdout, and logs an EvolutionEvent.
Which agent runtimes can it plug into?Cursor, Claude Code, Codex, Kiro, and opencode each get wired up with one command: 'evolver setup-hooks --platform= '. OpenClaw needs no setup at all — it natively interprets the stdout directives Evolver emits.
Will it edit my agent's code by itself?No — Evolver is a prompt generator, not a code patcher. Each cycle it scans memory, selects an asset, and prints a protocol-bound GEP prompt; it never auto-edits source files or executes shell commands. In standalone mode nothing runs for you.
Is this meant for quick personal scripts or bigger agent setups?Bigger setups: teams maintaining agent prompts and logs at scale, users who need auditable evolution traces, and environments requiring deterministic, protocol-bound changes. It is explicitly not for one-off scripts without logs or free-form creative changes.
Does it need an internet connection, and where does my data go?Core functionality runs fully offline. Connecting to the EvoMap hub is optional and only unlocks network features like skill sharing, the worker pool, and evolution leaderboards; you opt in with a .env file in the project directory.
Is it really open source, or is the license about to change?Currently yes, under GPL-3.0-or-later (it started out MIT). Future releases will move to a source-available model, but all already-published MIT and GPL-3.0 versions stay freely usable under their original terms.
What exactly are Genes and Capsules?They are the reusable evolution assets at the heart of the GEP protocol: compact, structured encodings of agent experience rather than ad hoc prompts or long skill docs. Each cycle Evolver picks the best-matching Gene or Capsule from its local asset store.
Is there research showing this approach works?Yes — the linked arXiv paper (2604.15097) ran 4,590 controlled trials across 45 scientific code-solving scenarios and found compact Genes give a stronger, more robust control signal than documentation-style skill packages. On CritPt, gene-evolved systems lifted paired base models from 9.1% to 18.57% and from 17.7% to 27.14%.
Can it run continuously in the background?Yes — 'evolver --loop' repeats cycles in a daemon loop with adaptive sleep for background self-maintenance such as validator runs and solidify. Its stdout is consumed by Evolver itself, so a live agent session should call 'evolver' directly instead.
Can I control what kind of evolution it pushes toward?Yes — a strategy preset controls the intent balance: balanced, innovate, harden, or repair-only. Evolver also de-duplicates signals to prevent repair loops, and every run is gated by an explicit Mutation object plus an evolvable PersonalityState.
What are similar projects?Raven, harness-sdk, Agentlas-OS, GenericAgent, brigade, penguin-harness, gitagent, claude-skills
Which topics is it in?autonomous-agent, memory-system, a2a, llm-agent, self-evolving, openclaw, autonomous-agents, agent-framework, agent-memory, prompt-engineering, skills, offline
Creator
EvoMap
Size
154.9 MB
Stars
8.7K
Updated
CommitSep 04Releasev2.0.44Oct 16
Age
8mo
Commits · 90 Days