evolver

Evolver — Agent Self-Evolving Engine

**[evomap.ai](https://evomap.ai)** | [Documentation](https://evomap.ai/wiki) | [Chinese / 中文文档](README.zh-CN.md) | [Japanese / 日本語ドキュメント](README.ja-JP.md) | [Korean / 한국어 문서](README.ko-KR.md) | [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). --- > **Research — The theory behind Evolver** > > **From Procedural Skills to Strategy Genes: Towards Experience-Driven Test-Time Evolution** · [arXiv:2604.15097](https://arxiv.org/abs/2604.15097) · [PDF](https://arxiv.org/pdf/2604.15097) > > 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](https://evomap.ai/blog/openclaw-critpt-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](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**: `npm install -g @evomap/evolver`, then run `evolver` in any git repo. ## 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. ## 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](#cli-quick-start) | | **Run from Source** | You want to hack on the engine, send PRs, or run unreleased builds. | `node index.js` | [below](#run-from-source-contributors-only) | > **For agent / skill integrations** (Codex, Claude Code skill system, custom MCP clients) see the separate [SKILL.md](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](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. ## CLI Quick Start This is the recommended path for almost everyone. ### 1. Install ```bash npm install -g @evomap/evolver ``` Verify the CLI is on your PATH: ```bash 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 ``` ### 2. Run it From inside any **git-initialized** project directory: ```bash # 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): ```bash # 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](https://cursor.com) | `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](https://www.anthropic.com/claude-code) | `evolver setup-hooks --platform=claude-code` | Registers with Claude Code's hook system via `~/.claude/`. Restart the Claude Code CLI. | | [Codex](https://github.com/openai/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](#codex-caveats) below. | | [Kiro](https://kiro.dev) | `evolver setup-hooks --platform=kiro` | Three `*.kiro.hook` files + scripts in `~/.kiro/hooks/`. Auto-discovered, no restart needed. | | [opencode](https://opencode.ai) | `evolver setup-hooks --platform=opencode` | Plugin at `~/.opencode/plugins/evolver.js` + scripts in `~/.opencode/hooks/`. Restart opencode. | | [OpenClaw](https://openclaw.com) | 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 `` 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. ```bash 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 ` invocation in the rest of this README maps 1:1 to `node index.js ` 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](https://evomap.ai/wiki) 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](https://evomap.ai/wiki) for traceability. **It does NOT**: - Automatically edit your source code. - Execute arbitrary shell commands (see [Security Model](#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 (`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 direc