Evomap Evolver

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

Security Scan

The skill appears to implement the claimed self‑evolution functionality and mostly requests proportional resources, but there are documentation/permission inconsistencies and features (networked worker mode, optional code modification, writing to source paths) that require careful review before enabling in a production agent.

Purpose & Capability

The name/description align with the actual files and runtime needs: a Node.js tool that uses git, reads evolution memory, and optionally talks to an EvoMap Hub and GitHub. Required binaries (node, git) and A2A_NODE_ID are coherent for the stated EvoMap integration. Optional env vars (A2A_HUB_URL, A2A_NODE_SECRET, GITHUB_TOKEN, MEMORY_GRAPH_REMOTE_KEY) match published network features. Minor concern: the README repeatedly claims 'does NOT automatically edit your source code' while the SKILL.md and codebase permit writing to workspace/src/** during 'solidify' and an env flag (EVOLVE_ALLOW_SELF_MODIFY) exists to enable self-modification — this is a capability/claim mismatch that should be clarified.

Instruction Scope

SKILL.md grants read access to memory and workspace, write access to workspace/assets and workspace/memory and conditional write to workspace/src/**, allows executing git/node/npm, and declares network endpoints (evomap.ai and api.github.com). The engine can run in loop and start a heartbeat to the Hub, accept network tasks (worker pool) when enabled, and produce 'sessions_spawn(...)' stdout directives that a host runtime could act on. Although safeguards are described (validation command whitelist, --validated required for promotion, EVOLVE_ALLOW_SELF_MODIFY default false), the instructions are broad and include ambiguous deny entries (see below). The combination of remote task intake + ability to modify local assets/source (under some modes) expands the attack surface and requires operator control and review before enabling.

Install Mechanism

This is instruction-only from the skill registry (no remote install URL), and the bundled code is present in the skill package. package.json lists only a small dependency (dotenv). No arbitrary downloads or extract-from-URL install steps are present in the provided metadata.

Credentials

Only one required env var (A2A_NODE_ID) is declared; other secrets (A2A_NODE_SECRET, GITHUB_TOKEN, MEMORY_GRAPH_REMOTE_KEY) are optional and only needed for network features. That is proportional for a networked evolver. Operators should still treat optional secrets as sensitive: enabling hub/worker features and providing A2A_NODE_SECRET/GITHUB_TOKEN gives the skill authenticated network access and (depending on config) the ability to advertise/accept tasks or create GitHub issues/releases.

Persistence & Privilege

always:false (good), but the skill is allowed to run autonomously (normal). The larger concern is that if you enable network worker mode (WORKER_ENABLED=1 and Hub-side worker switch), the node will advertise and accept tasks from evomap.ai. Combined with the skill's ability to persist assets and (optionally) write evolved code to workspace/src/**, that creates a significant privilege: remote-originated tasks could cause changes to local assets if operator safeguards are not strictly enforced. The code includes safeguards (promotion requires --validated; validation command whitelist), but remote tasking + self-modification is a high‑impact configuration and should be treated cautiously.

What to consider before installing

This package appears to implement a genuine self‑evolver and the requested permissions mostly match its purpose, but there are a few important things to check before you enable it: - Clarify the 'does not modify code' claim: by default it writes only to asset/memory directories, but code shows it can write to workspace/src/** when a change is 'solidified' and EVOLVE_ALLOW_SELF_MODIFY exists. Keep EVOLVE_ALLOW_SELF_MODIFY explicitly set to "false" unless you fully trust the workflow and have manual review in place. - Keep network worker features off by default: do not set WORKER_ENABLED=1 or provide A2A_NODE_SECRET / A2A_HUB_URL unless you trust evomap.ai and intend to participate in the Hub. Worker mode + Hub switch allows remote tasks to be assigned to your node. - Use review mode: run node index.js --review or run single runs (no --loop) and inspect outputs before allowing any automatic solidification or promotion. - Inspect solidify/validation logic: review src/gep/solidify.js and the validation whitelist (isValidationCommandAllowed) to ensure it enforces only safe commands in your environment. The promotion path (scripts/a2a_promote.js) enforces --validated; do not bypass that. - Protect secrets and tokens: only provide GITHUB_TOKEN or MEMORY_GRAPH_REMOTE_KEY if you need those features and understand what data will be sent; consider running offline initially. - The SKILL.md contains some ambiguous deny/allow entries (negated entries like "!api.github.com"), so confirm platform-level runtime permissions that the agent host will actually enforce. If you are not comfortable with remote tasking or any possibility of automatic code changes, run the evolver in an isolated environment, with EVOLVE_ALLOW_SELF_MODIFY=false, WORKER_ENABLED unset, and only after manual inspection of evolution proposals.

🧬 Evolver

"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