智能体自进化引擎

Prerequisites

• Node.js >= 18
• Git -- Required. Evolver uses git for rollback, blast radius calculation, and solidify. Running in a non-git directory will fail with a clear error message.

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

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

CLI Quick Start

This is the recommended path for almost everyone.

Typical Use Cases

• Harden a flaky agent loop by enforcing validation before edits
• Encode recurring fixes as reusable Genes and Capsules
• 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

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.

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

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.

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.

Configuration & Decoupling

Evolver is designed to be environment-agnostic.

Core Environment Variables

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.

WORKER_ENABLED vs. the Website Toggle

The evomap.ai dashboard has a "Worker" toggle on the node detail page. Here is how the two relate:

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 evolver --loop.
2. Go to evomap.ai, find your node, and turn on the Worker toggle.

FAQ

Does this edit code automatically? No. Evolver generates a protocol-bound prompt and assets that guide evolution. It does not modify your source code directly. See What Evolver Does (and Does Not Do).

I ran evolver --loop but it just keeps printing text. Is it working? Yes. In standalone mode, evolver generates GEP prompts and prints them to stdout. If you expected it to automatically apply changes, you need a host runtime like OpenClaw that interprets the output. Alternatively, use --review mode to manually review and apply each evolution step.

Do I need to connect to EvoMap Hub? No. All core evolution features work offline. Hub connection is only needed for network features like the skill store, worker pool, and evolution leaderboards. See Connecting to EvoMap Hub.

Do I need to use all GEP assets? No. You can start with default Genes and extend over time.

Is this safe in production? Use review mode and validation steps. Treat it as a safety-focused evolution tool, not a live patcher. See Security Model.

Where should I clone this repo? Clone it into any directory you like. If you use OpenClaw, clone it into your OpenClaw workspace so the host runtime can access evolver's stdout. For standalone use, any location works.