Evolver

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

Security Scan

The package mostly implements a plausible self-evolution engine, but there are multiple inconsistencies and powerful capabilities (code-write, network A2A hub integration, optional self-modify) that are not fully reflected in registry metadata—review carefully and sandbox before enabling network/worker modes or giving secrets.

Purpose & Capability

The skill's code and runtime instructions match the stated purpose (an engine that analyzes logs, selects Genes/Capsules, and can produce or apply evolution artifacts). Required binaries (node, git) and use of git for rollback/solidify are coherent. However, the registry metadata lists only A2A_NODE_ID as required env, while SKILL.md and code expect many additional envs (A2A_NODE_SECRET, GITHUB_TOKEN, MEMORY_GRAPH_REMOTE_KEY, EVOLVE_ALLOW_SELF_MODIFY, WORKER_ENABLED, etc.). That mismatch between declared registry requirements and the actual runtime expectations is notable.

Instruction Scope

SKILL.md and the bundled code instruct the agent to read runtime 'memory' and workspace files, run node/npm/git, write to workspace/assets and workspace/src (e.g., evolved code), emit stdout directives (sessions_spawn(...)) intended for host execution, and communicate with the EvoMap hub. The skill explicitly can modify source files when a change is 'solidified' and includes scripts for ingesting and promoting external assets. Although the repo includes safety checks (e.g., validation-command whitelist for Gene validation), the runtime instructions grant broad file, shell, and network access that go beyond simple analysis and include code-modification and network-based asset ingestion/publishing—actions that materially expand the agent's privileges and require careful human oversight.

Install Mechanism

There is no external download/install spec in the registry (lowest-install-risk model), and the bundle contains full Node.js source code (no remote extract of arbitrary binaries). The code depends only on dotenv at runtime per package.json. This is lower risk than arbitrary remote downloads, but the skill includes scripts that can fetch/publish assets from the EvoMap hub and GitHub, so runtime network behavior remains a concern even if installation itself is local.

Credentials

Registry metadata lists a single required env var (A2A_NODE_ID) but SKILL.md and code expect/declare many additional environment variables including sensitive ones (A2A_NODE_SECRET for hub auth, optional GITHUB_TOKEN for creating issues/releases, MEMORY_GRAPH_REMOTE_KEY, EVOLVE_ALLOW_SELF_MODIFY). The SKILL.md also accesses a config path (~/.evomap/node_id) despite registry saying no required config paths. The discrepancy between what the registry claims and what the skill actually uses is a red flag—granting the optional secrets or enabling worker/publish features would allow network-authenticated actions and GitHub writes.

Persistence & Privilege

always:false and standard autonomous invocation are fine, but the skill requests the ability to write to workspace/src/** (evolved code) and can run npm/node commands and spawn child processes (self-restart, daemon mode). It exposes an explicit opt-in (EVOLVE_ALLOW_SELF_MODIFY) to permit autonomous modification of its own source (default false), but the code already supports code modifications during 'solidify' and supports ingesting external assets that can be promoted into local Genes/Capsules. Combined, these capabilities represent high persistence/privilege and should be tightly controlled (disable worker mode, keep EVOLVE_ALLOW_SELF_MODIFY=false, avoid providing hub secrets) unless you intentionally want an autonomous self-modifying agent.

What to consider before installing

What to consider before installing: - Mismatched metadata: The published registry entry only lists A2A_NODE_ID, but the SKILL.md and code expect additional environment variables and read ~/.evomap/node_id. Treat the registry declaration as incomplete—expect more runtime requirements. - Sensitive secrets: Do not provide A2A_NODE_SECRET or GITHUB_TOKEN unless you trust the maintainer and have audited the code. Those secrets allow authenticated network actions (hub heartbeats, publishing, GitHub issues/releases). - Code-modifying behavior: Evolver can write to workspace/src/** and 'solidify' changes to code. This is consistent with its purpose but powerful. Keep EVOLVE_ALLOW_SELF_MODIFY unset/false, run in review mode (--review), and run it with restricted filesystem access until you audit behavior. - Network + ingestion: The skill will contact evomap.ai by default when hub config is present and includes scripts to ingest/export assets. If you do not want any network activity, do not set A2A_HUB_URL or A2A_NODE_SECRET and run in offline mode; also avoid enabling WORKER_ENABLED. - Validation protections exist but are not foolproof: Gene validation commands are restricted to node/npm/npx without shell operators, and scripts refuse to promote without --validated. Nevertheless, external assets can be staged locally and a human can mistakenly promote them—audit staged candidates before promotion. - Recommended precautions: run in an isolated sandbox or VM, review the repo (especially src/gep/solidify.js, a2aProtocol, a2a_ingest/a2a_promote, and index.js startup/daemon logic), start in --review mode, do not provide hub/GitHub credentials initially, disable WORKER_ENABLED, and monitor outbound network connections and filesystem writes. If you need higher assurance, validate the package against an official upstream release (git remote/sha) and verify owner identity. What would increase confidence: a registry update that lists all env/config requirements and explicit gating for network/worker/publish features, an authoritative upstream GitHub release URL with matching commit hashes, and a short security-readme describing threat model and how to run fully offline safely.

"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