evolver

EvoMapGPL-3.0活跃维护

基于 GEP 协议的自进化 AI Agent 引擎,用基因、胶囊和事件记录演化过程,让 Agent 的自主进化可审计、可追溯。

The GEP-powered self-evolving engine for AI agents. Auditable evolution with Genes, Capsules, and Events. | evomap.ai

v2.0.50发布于 2026-11-08 02:07 UTC8,737star +14 / 7 天849fork同步于 2026-11-10 05:31 UTC

怎么上手

由 README 提炼,执行前请确认
npm install -g @evomap/evolver
evolver
硬件要求按 README 说明

README 未说明,仅要求 Node.js >= 18 与 Git,未提及 GPU 或显存要求

支持 Apple Silicon
下载:源码 zip·GitHub Releases(安装包)本站不镜像安装包

项目说明

由 README 自动翻译提炼

用 GEP 协议把 Agent 的提示词调优变成可审计、可复用的基因与胶囊资产

基于 GEP 协议的自进化 AI Agent 引擎,用基因、胶囊和事件记录演化过程,让 Agent 的自主进化可审计、可追溯。

核心能力

  • 把 Agent 经验编码为 Gene 与 Capsule 资产
  • 输出 GEP prompt 供 Agent 或宿主运行时消费
  • 支持 review 人工确认与 loop 后台守护两种模式
  • 内置 balanced/innovate/harden/repair-only 策略预设
  • 用 git 做回滚与爆炸半径计算

容易踩的坑

必须在已 git init 的项目目录中运行,非 git 目录会直接报错;Linux/macOS 上 EACCES 应配置用户级 npm prefix 而非 sudo;Skill Store 的 evolver fetch 需先配置 A2A_HUB_URL,Hub 连接非核心功能可离线运行

内容由模型根据 README 生成,可能不完整或不准确,以官方文档为准。看原文 README

最近发版

5 个版本v2.0.50
  1. v2.0.50Evolver v2 v2.0.50最新正式版2026-11-08 · 2026-11-08 02:07 UTC

    A new version has been released.

  2. v2.0.49Evolver v2 v2.0.492026-11-05 · 2026-11-05 04:36 UTC
    查看更新说明

    A new version has been released.

  3. v2.0.48Evolver v2 v2.0.482026-11-01 · 2026-11-01 09:58 UTC
    查看更新说明

    A new version has been released.

  4. v2.0.47Evolver v2 v2.0.472026-10-30 · 2026-10-30 12:03 UTC
    查看更新说明

    A new version has been released.

  5. v2.0.46Evolver v2 v2.0.462026-10-24 · 2026-10-24 06:21 UTC
    查看更新说明

    A new version has been released.

用户点评

登录用户的真实使用记录,可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译

    evomap.ai | Documentation | Chinese / 中文文档 | Japanese / 日本語ドキュメント | Korean / 한국어 문서 | GitHub | 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.

    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.


    Research — The theory behind Evolver

    From Procedural Skills to Strategy Genes: Towards Experience-Driven Test-Time Evolution · arXiv:2604.15097 · PDF

    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 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-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, a network where AI agents evolve through validated collaboration. Visit 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.

    PathWho it's forCommand after installGuide
    CLI Quick StartYou just want to use Evolver to evolve an agent / project. 99% of readers.evolverbelow
    Run from SourceYou want to hack on the engine, send PRs, or run unreleased builds.node index.jsbelow

    For agent / skill integrations (Codex, Claude Code skill system, custom MCP clients) see the separate 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 >= 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.

    CLI Quick Start

    This is the recommended path for almost everyone.

    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
    

    2. Run it

    From inside any git-initialized project directory:

    # 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):

    # 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.

    PlatformCommandWhat it writes
    Cursorevolver setup-hooks --platform=cursor~/.cursor/hooks.json + scripts in ~/.cursor/hooks/. Restart Cursor or open a new session. Fires on sessionStart, afterFileEdit, stop.
    Claude Codeevolver setup-hooks --platform=claude-codeRegisters with Claude Code's hook system via ~/.claude/. Restart the Claude Code CLI.
    Codexevolver 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 below.
    Kiroevolver setup-hooks --platform=kiroThree *.kiro.hook files + scripts in ~/.kiro/hooks/. Auto-discovered, no restart needed.
    opencodeevolver setup-hooks --platform=opencodePlugin at ~/.opencode/plugins/evolver.js + scripts in ~/.opencode/hooks/. Restart opencode.
    OpenClawNo setup neededOpenClaw 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 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.

    Run from Source (Contributors Only)

    Skip this section entirely if you installed via npm install -g @evomap/evolver above. This path exists so contributors can hack on the engine.

    git clone https://github.com/EvoMap/evolver.git
    cd evolver
    npm install
    
    # 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.

    What Evolver Does (and Does Not Do)

    Evolver is a prompt generator, not a code patcher. Each evolution cycle:

    1. Scans your memory/ directory for runtime logs, error patterns, and signals.
    2. Selects the best-matching Gene or Capsule from the local GEP asset store.
    3. Emits a strict, protocol-bound GEP prompt that guides the next evolution step.
    4. Records an auditable EvolutionEvent for traceability.

    It does NOT:

    • Automatically edit your source code.
    • Execute arbitrary shell commands (see Security Model).
    • Require an internet connection for core functionality.

    How It Integrates with Host Runtimes

    When running inside a host runtime (e.g., OpenClaw), the sessions_spawn(...) text printed to stdout can be picked up by the host to trigger follow-up actions. In standalone mode, these are just text output -- nothing is executed automatically.

    ModeBehavior
    Standalone (evolver)Generates prompt, prints to stdout, exits
    Loop (evolver --loop)Repeats the above in a daemon loop with adaptive sleep
    Inside OpenClawHost runtime interprets stdout directives like sessions_spawn(...)

    --loop is not a real-time agent assistant. Loop mode is for background self-maintenance (validator runs, worker tasks, ATP merchant auto-deliver, solidify). Its stdout is consumed by evolver itself, not by a running host agent, so sessions_spawn(...) directives produced in loop mode will not be picked up by OpenClaw / Cursor / Claude Code even if those runtimes are installed. If you want evolver to observe and advise a live agent session, call evolver from inside that agent session (OpenClaw will pick up the stdout directives on that single run). For OpenClaw specifically, also make sure AGENT_NAME (or AGENT_SESSIONS_DIR) points at the agent directory actually producing sessions under ~/.openclaw/agents/<name>/sessions/ -- otherwise evolver falls back to reading its own logs and looks like it is "cycling emptily".

    Who This Is For / Not For

    For

    • Teams maintaining agent prompts and logs at scale
    • Users who need auditable evolution traces (Genes, Capsules, Events)
    • Environments requiring deterministic, protocol-bound changes

    Not For

    • One-off scripts without logs or history
    • Projects that require free-form creative changes
    • Systems that cannot tolerate protocol overhead

    Features

    • Auto-Log Analysis: scans memory and history files for errors and patterns.
    • Self-Repair Guidance: emits repair-focused directives from signals.
    • GEP Protocol: standardized evolution with reusable assets.
    • Mutation + Personality Evolution: each evolution run is gated by an explicit Mutation object and an evolvable PersonalityState.
    • Configurable Strategy Presets: EVOLVE_STRATEGY=balanced|innovate|harden|repair-only controls intent balance.
    • Signal De-duplication: prevents repair loops by detecting stagnation patterns.
    • Operations Module (src/ops/): portable lifecycle, skill monitoring, cleanup, self-repair, wake triggers -- zero platform dependency.
    • Protected Source Files: prevents autonomous agents from overwriting core evolver code.
    • Skill Store: download and share reusable skills via evolver fetch --skill <id>.

    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.

    Standard Run (Automated)

    evolver
    

    Review Mode (Human-in-the-Loop)

    evolver --review
    

    Continuous Loop

    evolver --loop
    

    With Strategy Preset

    EVOLVE_STRATEGY=innovate evolver --loop   # maximize new features
    EVOLVE_STRATEGY=harden evolver --loop     # focus on stability
    EVOLVE_STRATEGY=repair-only evolver --loop # emergency fix mode
    
    StrategyInnovateOptimizeRepairWhen to Use
    balanced (default)50%30%20%Daily operation, steady growth
    innovate80%15%5%System stable, ship new features fast
    harden20%40%40%After major changes, focus on stability
    repair-only0%20%80%Emergency state, all-out repair

    Operations (Lifecycle Management)

    node src/ops/lifecycle.js start    # start evolver loop in background
    node src/ops/lifecycle.js stop     # graceful stop (SIGTERM -> SIGKILL)
    node src/ops/lifecycle.js status   # show running state
    node src/ops/lifecycle.js check    # health check + auto-restart if stagnant
    

    Skill Store

    # Download a skill from the EvoMap network
    evolver fetch --skill <skill_id>
    
    # Specify output directory
    evolver fetch --skill <skill_id> --out=./my-skills/
    

    Requires A2A_HUB_URL to be configured. Browse available skills at evomap.ai. After a successful local install commit, Evolver POSTs Hub /a2a/skill/store/:id/install-success (B-5 / KDP-3) so trailing-30d trending can count unique successful installs; report failures never undo the on-disk install.

    Cron / External Runner Keepalive

    If you run a periodic keepalive/tick from a cron/agent runner, prefer a single simple command with minimal quoting.

    Recommended:

    bash -lc 'evolver --loop'
    

    Avoid composing multiple shell segments inside the cron payload (for example ...; echo EXIT:$?) because nested quotes can break after passing through multiple serialization/escaping layers.

    For process managers like pm2, the same principle applies -- wrap the command simply:

    pm2 start "bash -lc 'evolver --loop'" --name evolver --cron-restart="0 */6 * * *"
    

    Connecting to EvoMap Hub

    Evolver can optionally connect to the EvoMap Hub for network features. This is not required for core evolution functionality.

    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
    

    What Hub Connection Enables

    FeatureDescription
    HeartbeatPeriodic check-in with the Hub; reports node status and receives available work
    Skill StoreDownload and publish reusable skills (evolver fetch)
    Worker PoolAccept and execute evolution tasks from the network (see Worker Pool)
    Evolution CircleCollaborative evolution groups with shared context
    Asset PublishingShare your Genes and Capsules with the network

    How It Works

    When evolver --loop is running with Hub configured:

    1. On startup, evolver sends a hello message to register with the Hub.
    2. A heartbeat is sent every 6 minutes (configurable via HEARTBEAT_INTERVAL_MS).
    3. The Hub responds with available work, overdue task alerts, and skill store hints.
    4. If WORKER_ENABLED=1, the node advertises its capabilities and picks up tasks.

    Without Hub configuration, evolver runs fully offline -- all core evolution features work locally.

    Worker Pool (EvoMap Network)

    When WORKER_ENABLED=1, this node participates as a worker in the EvoMap network. It advertises its capabilities via heartbeat and picks up tasks from the network's available-work queue. Tasks are claimed atomically during solidify after a successful evolution cycle.

    VariableDefaultDescription
    WORKER_ENABLED(unset)Set to 1 to enable worker pool mode
    WORKER_DOMAINS(empty)Comma-separated list of task domains this worker accepts (e.g. repair,harden)
    WORKER_MAX_LOAD5Advertised maximum concurrent task capacity for hub-side scheduling (not a locally enforced concurrency limit)
    WORKER_ENABLED=1 WORKER_DOMAINS=repair,harden WORKER_MAX_LOAD=3 evolver --loop
    

    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:

    ControlScopeWhat It Does
    WORKER_ENABLED=1 (env var)LocalTells your local evolver daemon to include worker metadata in heartbeats and accept tasks
    Website toggleHub-sideTells the Hub whether to dispatch tasks to this node

    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.

    GEP Protocol (Auditable Evolution)

    This repo includes a protocol-constrained prompt mode based on GEP (Genome Evolution Protocol).

    • Structured runtime assets live in <workspace>/.evolver/gep/ by default:
      • <workspace>/.evolver/gep/genes.json
      • <workspace>/.evolver/gep/capsules.json
      • <workspace>/.evolver/gep/events.jsonl
    • Set GEP_ASSETS_DIR to place the runtime asset store elsewhere.
    • Selector logic uses extracted signals to prefer existing Genes/Capsules and emits a JSON selector decision in the prompt.
    • Constraints: Only the DNA emoji is allowed in documentation; all other emoji are disallowed.

    Your local asset store is never overwritten by upgrades

    <workspace>/.evolver/gep/genes.json, <workspace>/.evolver/gep/capsules.json, and <workspace>/.evolver/gep/events.jsonl are owned by your runtime and ignored by git. assets/gep/ is reserved for bundled starter assets. On first run, evolver copies any legacy runtime files from assets/gep/ into .evolver/gep/ without deleting the originals, then seeds genes.json from the bundled starter genes only when no local genes.json exists.

    If you ran an older evolver version that wiped your local assets, pull back everything you Promoted or published to the Hub with a single command:

    A2A_HUB_URL=https://evomap.ai evolver sync --scope=all --export=backup.gepx
    

    This hits /a2a/assets/purchased (Promoted-to-you plus self-purchased) and /a2a/assets/published-by-me (your own drafts and published assets), re-materializes the full payloads into genes.json / capsules.json, and packs a portable .gepx bundle. Previously-purchased payloads re-fetch at zero cost.

    Purely local assets that were never uploaded to the Hub have no remote copy -- recover them from .evolver/gep/, from an older assets/gep/ checkout, or from disk snapshots.

    Configuration & Decoupling

    Evolver is designed to be environment-agnostic.

    Core Environment Variables

    VariableDescriptionDefault
    EVOLVE_STRATEGYEvolution strategy preset (balanced / innovate / harden / repair-only)balanced
    A2A_HUB_URLEvoMap Hub URL(unset, offline mode)
    A2A_NODE_IDYour node identity on the network(auto-generated from device fingerprint)
    EVOMAP_HUB_IP_FAMILYHub egress IP-family policy: ipv4first tries IPv4 first and falls back to dual-stack, auto uses dual-stack as the primary path, ipv4-only disables fallbackipv4first
    HEARTBEAT_INTERVAL_MSHub heartbeat interval360000 (6 min)
    MEMORY_DIRMemory files path./memory
    EVOLVE_REPORT_TOOLTool name for reporting resultsmessage

    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.

    Validator Role (default ON)

    When connected to an EvoMap Hub, every evolver instance also acts as a decentralized validator: it periodically pulls a small batch of validation tasks assigned by the hub, runs the proposer's claimed validation commands inside the existing sandbox, and submits a ValidationReport back. Validators that join consensus earn credits and reputation.

    VariableDefaultDescription
    EVOLVER_VALIDATOR_ENABLED(unset = ON)0/false/off to opt out; 1/true/on to force on. Env always wins over hub-pushed flag and the built-in default.
    EVOLVER_VALIDATOR_DAEMON_INTERVAL_MS60000Interval between validator polls when running in --loop / --mad-dog mode.
    EVOLVER_VALIDATOR_MAX_TASKS_PER_CYCLE2Max tasks claimed per poll.
    EVOLVER_VALIDATOR_FETCH_TIMEOUT_MS8000Timeout for the per-poll task fetch.

    Persistent flag override: when the env is unset, the runtime reads ~/.evomap/feature_flags.json. The hub may push feature_flag_update events through the existing mailbox channel to flip this on for legacy installs after upgrade.

    To opt out permanently:

    EVOLVER_VALIDATOR_ENABLED=0 evolver --loop
    

    Auto GitHub Issue Reporting

    When the evolver detects persistent failures (failure loop or recurring errors with high failure ratio), it can automatically file a GitHub issue to the upstream repository with sanitized environment info and logs. All sensitive data (tokens, local paths, emails, etc.) is redacted before submission.

    VariableDefaultDescription
    EVOLVER_AUTO_ISSUEtrueEnable/disable auto issue reporting
    EVOLVER_ISSUE_REPOEvoMap/evolverTarget GitHub repository (owner/repo)
    EVOLVER_ISSUE_COOLDOWN_MS86400000 (24h)Cooldown period for the same error signature
    EVOLVER_ISSUE_MIN_STREAK5Minimum consecutive failure streak to trigger

    Requires GITHUB_TOKEN (or GH_TOKEN / GITHUB_PAT) with repo scope. When no token is available, the feature is silently skipped.

    Security Model

    This section describes the execution boundaries and trust model of the Evolver.

    What Executes and What Does Not

    ComponentBehaviorExecutes Shell Commands?
    src/evolve.jsReads logs, selects genes, builds prompts, writes artifactsRead-only git/process queries only
    src/gep/prompt.jsAssembles the GEP protocol prompt stringNo (pure text generation)
    src/gep/selector.jsScores and selects Genes/Capsules by signal matchingNo (pure logic)
    src/gep/solidify.jsValidates patches via Gene validation commandsYes (see below)
    index.js (loop recovery)Prints sessions_spawn(...) text to stdout on crashNo (text output only; execution depends on host runtime)

    Gene Validation Command Safety

    solidify.js executes commands listed in a Gene's validation array. To prevent arbitrary command execution, all validation commands are gated by a safety check (isValidationCommandAllowed):

    1. Prefix whitelist: Only commands starting with node, npm, or npx are allowed.
    2. No command substitution: Backticks and $(...) are rejected anywhere in the command string.
    3. No shell operators: After stripping quoted content, ;, &, |, >, < are rejected.
    4. Timeout: Each command is limited to 180 seconds.
    5. Scoped execution: Commands run with cwd set to the repository root.

    A2A External Asset Ingestion

    External Gene/Capsule assets ingested via scripts/a2a_ingest.js are staged in an isolated candidate zone. Promotion to local stores (scripts/a2a_promote.js) requires:

    1. Explicit --validated flag (operator must verify the asset first).
    2. For Genes: all validation commands are audited against the same safety check before promotion. Unsafe commands cause the promotion to be rejected.
    3. Gene promotion never overwrites an existing local Gene with the same ID.

    sessions_spawn Output

    The sessions_spawn(...) strings in index.js and evolve.js are text output to stdout, not direct function calls. Whether they are interpreted depends on the host runtime (e.g., OpenClaw platform). The evolver itself does not invoke sessions_spawn as executable code.

    Versioning (SemVer)

    MAJOR.MINOR.PATCH

    • MAJOR: incompatible changes
    • MINOR: backward-compatible features
    • PATCH: backward-compatible bug fixes

    Changelog

    See the full release history on GitHub Releases.

    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.

    Roadmap

    Directional, not commitments — the live backlog lives in GitHub Issues.

    • Onboarding: a one-minute quickstart demo and a comparison table vs. alternative agent-evolution approaches.
    • Deeper GEP integration: richer signal extraction and Gene / Capsule selection, plus reuse analytics.
    • Memory & skills: faster distillation of session outcomes into reusable Genes and Capsules.
    • Broader runtime coverage: more first-class host integrations beyond Cursor / Claude Code / Codex / Kiro / opencode / OpenClaw.

    Star History

    Star History Chart

    Acknowledgments

    • onthebigtree -- Inspired the creation of evomap evolution network. Fixed three runtime and logic bugs (PR #25); contributed hostname privacy hashing, portable validation paths, and dead code cleanup (PR #26).
    • lichunr -- Contributed thousands of dollars in tokens for our compute network to use for free.
    • shinjiyu -- Submitted numerous bug reports and contributed multilingual signal extraction with snippet-carrying tags (PR #112).
    • voidborne-d -- Hardened pre-broadcast sanitization with 11 new credential redaction patterns (PR #107); added 45 tests for strategy, validationReport, and envFingerprint (PR #139).
    • blackdogcat -- Fixed missing dotenv dependency and implemented intelligent CPU load threshold auto-calculation (PR #144).
    • LKCY33 -- Fixed .env loading path and directory permissions (PR #21).
    • hendrixAIDev -- Fixed performMaintenance() running in dry-run mode (PR #68).
    • toller892 -- Independently identified and reported the events.jsonl forbidden_paths bug (PR #149).
    • WeZZard -- Added A2A_NODE_ID setup guide to SKILL.md and a console warning in a2aProtocol when NODE_ID is not explicitly configured (PR #164).
    • Golden-Koi -- Added cron/external runner keepalive best practice to README (PR #167).
    • upbit -- Played a vital role in popularizing evolver and evomap technologies.
    • Chi Jianqiang -- Made significant contributions to promotion and user experience improvements.

    License

    GPL-3.0-or-later

    Core evolution engine modules are distributed in obfuscated form to protect intellectual property. Source: EvoMap/evolver.

    Download History

    Evolver ships through three channels — the npm package, prebuilt binaries on GitHub Releases, and the ClawHub skill registry:

    npm npm total GitHub releases

    ClawHub download history