Evolver

A self-evolution engine for AI agents. Analyzes runtime history to identify improvements and applies protocol-constrained evolution.

Security Scan

The Evolver skill broadly matches its stated purpose (self-evolution for agents) but contains several surprising capabilities and documentation inconsistencies—most importantly the ability to read local workspace/memory and to publish/ingest assets over the network and to run validation commands that may execute code—so you should treat it as risky unless you audit and constrain it first.

Purpose & Capability

Name/description (self-evolver) align with required binaries (node, git), workspace file access, and network endpoints (evomap.ai, api.github.com). However README and SKILL.md make two conflicting claims: the README repeatedly states "Evolver is a prompt generator, not a code patcher," while the declared file_access and code (src/gep/solidify, index.js, asset store) explicitly allow writing evolved code to workspace/src/** when changes are "solidified" (and there is an env flag EVOLVE_ALLOW_SELF_MODIFY to permit self-modification). This is an important semantic gap that could be misleading to users.

Instruction Scope

Runtime instructions and code allow reading workspace/** and memory/**, generating evolution assets, exporting eligible assets and (optionally) sending them to the EvoMap Hub, ingesting external assets, and running validation commands. The skill's a2a_export/a2a_ingest/a2a_promote flows can send or accept assets across network. Solidify runs declared validation commands (with a whitelist check) which still permit arbitrary node/npm/npx invocations — these scripts can in turn perform arbitrary actions. The skill therefore has scope to transmit local logs/memory and to run code derived from external assets; these behaviors are coherent with a networked evolution engine but materially expand the trust boundary (data exfil and remote-origin code execution vectors).

Install Mechanism

No external download/install mechanism is specified (instruction-only with many included source files). No remote archive/extract or third-party package installs are performed by the registry entry itself. The package expects Node and Git to be present; npm usage is limited to running validation or dependency healing. This is low-install risk in the registry context.

Credentials

Only A2A_NODE_ID is declared as required; other credentials (A2A_NODE_SECRET, GITHUB_TOKEN, MEMORY_GRAPH_REMOTE_KEY) are optional. These optional variables match described network features (hub auth, GitHub issue/release publishing, optional KG sync). However the docs contain inconsistencies: SKILL.md lists EVOLVER_AUTO_ISSUE default as "0" (off) while README text/table earlier implies auto-issue may default on; this mismatch matters because enabling auto-issue requires a GitHub token with repo permissions. Overall the requested env variables are explainable for the stated networked functionality, but supplying hub secrets or GitHub tokens grants significant powers (publishing assets, creating issues, heartbeats/worker participation).

Persistence & Privilege

always:false (good). The skill can run as an autonomous loop/daemon (index.js --loop) and start a heartbeat to the Hub; that is expected for a networked worker. It can spawn child processes to restart itself. Crucially, when configured to 'solidify' an evolution it can write evolved code into workspace/src/**; EVOLVE_ALLOW_SELF_MODIFY is provided (default 'false') but if changed this grants the skill the privilege to modify local source. Autonomous invocation + network access + write-to-src capability increases blast radius if misconfigured or if external assets are promoted without careful validation.

Scan Findings in Context

[child_process.spawn_or_exec] expected: index.js uses child_process.spawn to restart the daemon and the codebase runs node/npm commands as part of validation/solidify. For a self-evolution engine that can restart itself and run validation scripts this is expected, but it also increases risk because spawned processes can perform arbitrary actions.

[network_send_to_external_host] expected: scripts and a2aProtocol build/send publish messages to the EvoMap Hub (evomap.ai) and GitHub API interactions are present. This is consistent with the skill's description (hub, skill store, auto-issue), but it also means workspace/memory data and assets can be transmitted off-host when hub features are enabled.

What to consider before installing

Plain-language checklist before installing or enabling Evolver: - Understand the trust boundary: Evolver reads your agent logs and workspace and can (when configured) publish assets and events to evomap.ai and optionally create GitHub issues/releases. If you set A2A_NODE_SECRET or GITHUB_TOKEN, you are granting network-authenticated capabilities. - Audit and sandbox first: Run the package in an isolated/test environment (no sensitive logs, no production credentials) and observe what it reads and what it sends (e.g., by blocking network or using a fake hub URL). - Control self-modification: Keep EVOLVE_ALLOW_SELF_MODIFY unset or explicitly 'false' unless you have reviewed the solidify logic and are willing to allow the tool to write to workspace/src/**. Also prefer review mode (--review) instead of fully automated Mad Dog mode. - Restrict credentials: Do not provide A2A_NODE_SECRET or GITHUB_TOKEN unless you fully trust the hub and need network features. If you do provide them, prefer tokens with minimal scope and rotate them after testing. - Inspect validation steps before promoting external assets: External Genes/Capsules include 'validation' commands. The code blocks shell operators but allows node/npm/npx commands; review any external asset's validation commands before promoting them to local Genes. - Prefer offline/local use if you only need prompt-generation: The README claims core functionality works offline; if you don't need networked skill store/worker pool features, run without A2A_HUB_URL/WORKER_ENABLED to reduce risk. - If you lack time to audit code, consider not installing or run with network blocked and EVOLVE_ALLOW_SELF_MODIFY=false until you can review src/gep/solidify, scripts/a2a_*.js, and any code that writes to workspace. What would change this assessment: explicit guarantees or code-level controls that ensure any code-writing action is always gated by an unambiguous human approval step (e.g., always require a manual review token or interactive confirmation), or cryptographic verification of remote assets and stricter sandboxing of validation commands. As-is, the skill is coherent with its stated purpose but contains several high-impact privileges and some doc/code inconsistencies — treat it as suspicious and validate before use.

"Evolution is not optional. Adapt or die."

The Evolver is a meta-skill that allows OpenClaw agents to inspect their own runtime history, identify failures or inefficiencies, and autonomously write new code or update their own memory to improve performance.

Features

• Auto-Log Analysis: Automatically scans memory and history files for errors and patterns.
• Self-Repair: Detects crashes and suggests patches.
• GEP Protocol: Standardized evolution with reusable assets.
• One-Command Evolution: Just run /evolve (or node index.js).

Usage

Standard Run (Automated)

Runs the evolution cycle. If no flags are provided, it assumes fully automated mode (Mad Dog Mode) and executes changes immediately.

node index.js

Review Mode (Human-in-the-Loop)

If you want to review changes before they are applied, pass the --review flag. The agent will pause and ask for confirmation.

node index.js --review

Mad Dog Mode (Continuous Loop)

To run in an infinite loop (e.g., via cron or background process), use the --loop flag or just standard execution in a cron job.

node index.js --loop

Setup

Before using this skill, register your node identity with the EvoMap network:

1. Run the hello flow (via evomap.js or the EvoMap onboarding) to receive a node_id and claim code
2. Visit https://evomap.ai/claim/<claim-code> within 24 hours to bind the node to your account
3. Set the node identity in your environment:

export A2A_NODE_ID=node_xxxxxxxxxxxx

Or in your agent config (e.g., ~/.openclaw/openclaw.json):

{ "env": { "A2A_NODE_ID": "node_xxxxxxxxxxxx", "A2A_HUB_URL": "https://evomap.ai" } }

Do not hardcode the node ID in scripts. getNodeId() in src/gep/a2aProtocol.js reads A2A_NODE_ID automatically -- any script using the protocol layer will pick it up without extra configuration.

Configuration

Required Environment Variables

Variable	Default	Description
A2A_NODE_ID	(required)	Your EvoMap node identity. Set after node registration -- never hardcode in scripts.

Optional Environment Variables

Variable	Default	Description
A2A_HUB_URL	https://evomap.ai	EvoMap Hub API base URL.
A2A_NODE_SECRET	(none)	Node authentication secret issued by Hub on first hello. Stored locally after registration.
EVOLVE_STRATEGY	balanced	Evolution strategy: balanced, innovate, harden, repair-only, early-stabilize, steady-state, or auto.
EVOLVE_ALLOW_SELF_MODIFY	false	Allow evolution to modify evolver's own source code. NOT recommended for production.
EVOLVE_LOAD_MAX	2.0	Maximum 1-minute load average before evolver backs off.
EVOLVER_ROLLBACK_MODE	hard	Rollback strategy on failure: hard (git reset --hard), stash (git stash), none (skip). Use stash for safer operation.
EVOLVER_LLM_REVIEW	0	Set to 1 to enable second-opinion LLM review before solidification.
EVOLVER_AUTO_ISSUE	0	Set to 1 to auto-create GitHub issues on repeated failures. Requires GITHUB_TOKEN.
EVOLVER_ISSUE_REPO	(none)	GitHub repo for auto-issue reporting (e.g. EvoMap/evolver).
EVOLVER_MODEL_NAME	(none)	LLM model name injected into published asset model_name field.
GITHUB_TOKEN	(none)	GitHub API token for release creation and auto-issue reporting. Also accepts GH_TOKEN or GITHUB_PAT.
MEMORY_GRAPH_REMOTE_URL	(none)	Remote knowledge graph service URL for memory sync.
MEMORY_GRAPH_REMOTE_KEY	(none)	API key for remote knowledge graph service.
EVOLVE_REPORT_TOOL	(auto)	Override report tool (e.g. feishu-card).
RANDOM_DRIFT	0	Enable random drift in evolution strategy selection.

Network Endpoints

Evolver communicates with these external services. All are authenticated and documented.

Endpoint	Auth	Purpose	Required
{A2A_HUB_URL}/a2a/*	A2A_NODE_SECRET (Bearer)	A2A protocol: hello, heartbeat, publish, fetch, reviews, tasks	Yes
api.github.com/repos/*/releases	GITHUB_TOKEN (Bearer)	Create releases, publish changelogs	No
api.github.com/repos/*/issues	GITHUB_TOKEN (Bearer)	Auto-create failure reports (sanitized via redactString())	No
{MEMORY_GRAPH_REMOTE_URL}/*	MEMORY_GRAPH_REMOTE_KEY	Remote knowledge graph sync	No

Shell Commands Used

Evolver uses child_process for the following commands. No user-controlled input is passed to shell.

Command	Purpose
git checkout, git clean, git log, git status, git diff	Version control for evolution cycles
git rebase --abort, git merge --abort	Abort stuck git operations (self-repair)
git reset --hard	Rollback failed evolution (only when EVOLVER_ROLLBACK_MODE=hard)
git stash	Preserve failed evolution changes (when EVOLVER_ROLLBACK_MODE=stash)
ps, pgrep, tasklist	Process discovery for lifecycle management
df -P	Disk usage check (health monitoring fallback)
npm install --production	Repair missing skill dependencies
node -e "..."	Inline script execution for LLM review (no shell, uses execFileSync)

File Access

Direction	Paths	Purpose
Read	~/.evomap/node_id	Node identity persistence
Read	assets/gep/*	GEP gene/capsule/event data
Read	memory/*	Evolution memory, narrative, reflection logs
Read	package.json	Version information
Write	assets/gep/*	Updated genes, capsules, evolution events
Write	memory/*	Memory graph, narrative log, reflection log
Write	src/**	Evolved code (only during solidify, with git tracking)

GEP Protocol (Auditable Evolution)

This package embeds a protocol-constrained evolution prompt (GEP) and a local, structured asset store:

• assets/gep/genes.json: reusable Gene definitions
• assets/gep/capsules.json: success capsules to avoid repeating reasoning
• assets/gep/events.jsonl: append-only evolution events (tree-like via parent id)

Emoji Policy

Only the DNA emoji is allowed in documentation. All other emoji are disallowed.

Configuration & Decoupling

This skill is designed to be environment-agnostic. It uses standard OpenClaw tools by default.

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:

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.

Safety & Risk Protocol

1. Identity & Directives

• Identity Injection: "You are a Recursive Self-Improving System."
• Mutation Directive:
  • If Errors Found -> Repair Mode (Fix bugs).
  • If Stable -> Forced Optimization (Refactor/Innovate).

2. Risk Mitigation

• Infinite Recursion: Strict single-process logic.
• Review Mode: Use --review for sensitive environments.
• Git Sync: Always recommended to have a git-sync cron job running alongside this skill.

Before Troubleshooting -- Check Your Version First

If you encounter unexpected errors or behavior, always verify your version before debugging:

node -e "const p=require('./package.json'); console.log(p.version)"

If you are not on the latest release, update first -- most reported issues are already fixed in newer versions:

# If installed via git
git pull && npm install

# If installed via npm
npm install -g @evomap/evolver@latest

Latest releases and changelog: https://github.com/EvoMap/evolver/releases

License

MIT