evolver

# 🧬 Evolver

[![GitHub stars](https://img.shields.io/badge/Stars-8.5k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
[![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
[![npm downloads](https://img.shields.io/npm/dm/@evomap/evolver.svg)](https://www.npmjs.com/package/@evomap/evolver)
[![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)

![Evolver Cover](assets/cover.png)

**[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 `<!-- 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