Evolver: a GEP engine that turns agent prompt tweaks into auditable Genes and Capsules

The problem Evolver targets: prompt edits with no audit trail

Most agent projects change behaviour by editing a prompt string. The change works, nobody records why, and the next person cannot tell which earlier edit produced the current behaviour. Evolver's answer is to stop treating an improvement as text and start treating it as an asset: a Gene, a Capsule, or an Event, under a protocol the project calls GEP (Genome Evolution Protocol). The README states the pain it solves in one line, that it "turns ad hoc prompt tweaks into auditable, reusable evolution assets."

The audience is narrow. The README's own path table says the CLI Quick Start is for "99% of readers" who want to evolve an agent or project, and a second path exists for people who want to hack on the engine itself. If you are looking for a library you import into a running agent loop, this is not that shape. Evolver is a command you run against a repository, and it writes assets into that repository.

How the GEP loop works: logs in, a selected Gene out

The mechanism visible in the README is a pipeline, not a background service. You run evolver inside a git-initialized directory. It scans ./memory/ for logs and signals, creating that directory if it is missing. It then selects a matching Gene or Capsule from a built-in asset pool and prints a GEP prompt. A "successful first run" is described in four steps, and the fourth is that it prints that prompt. Nothing in the README says the prompt is applied automatically in the default mode.

Git is not a convenience here, it is load-bearing. The prerequisites section states that Evolver "uses git for rollback, blast radius calculation, and solidify," and that running in a non-git directory fails with a clear error message. Blast radius calculation implies the engine inspects how far a change would spread before proposing it. Solidify is exposed as its own command, npm run solidify, which suggests a separate step where a candidate evolution is committed as a durable asset rather than left as a suggestion.

The repository layout supports this reading: src/ holds the engine, cli-options.js holds flag definitions, conformance/ exists for protocol conformance checks, and examples/ ships a recipe.manifest.json alongside two walkthroughs. The dependencies in package.json include @evomap/gep-sdk and @evomap/atp-sdk, so the protocol layer is a separate package rather than something inlined. An arXiv paper, 2604.15097, is cited as the theory behind the Gene representation, and the README summarises its claim that documentation-oriented Skill packages give "unstable, sparse control signal" while a compact Gene representation performs better. Treat that as the project's own argument for its design, not as an independent finding.

Installing Evolver and running it once inside a git repo

The README gives a global npm install as the recommended path. Node.js 18 or newer is listed in the README badge, while package.json declares an engines field of >=22.12, so check your runtime against both before filing a bug.

npm install -g @evomap/evolver
evolver --help

The second command confirms the CLI is on your PATH. If the install fails with EACCES on Linux or macOS, the README says to configure a user-level prefix rather than reaching for sudo.

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Now move into a project that is already a git repository and run the default mode. This performs a single evolution run: it scans logs, selects a Gene, and outputs a GEP prompt.

evolver

According to the README you should see a banner naming the detected strategy preset, for example balanced, followed by the scan of ./memory/, the asset selection, and the prompt. If you would rather approve changes yourself, the review flag pauses before applying and waits for human confirmation.

evolver --review

For contributors who want unreleased code, the source path is npm start or node index.js from a clone. That path is explicitly labelled "contributors only" in the README's own table, so do not pick it just to try the tool.

Where Evolver is the wrong tool

The git requirement is the sharpest limit. Any agent project that keeps its prompts in a database, a hosted prompt manager, or a non-git directory cannot use the default flow at all, because the README says the run fails with an error rather than degrading. That rules out a large class of deployed agents whose configuration never touches a repository.

The second limit is autonomy. The README describes the default run as producing a prompt, and offers --review as a mode that waits for confirmation. It does not document what the loop mode does when an evolution makes things worse, and it does not describe a rollback command by name; rollback is mentioned only as a reason git is required. If you need a documented, one-command undo, the README does not give you one.

The third limit is licence direction. The README carries a notice that future releases will move from fully open source to source-available, and states that already-published MIT and GPL-3.0 versions remain usable under their original terms. That is a statement about intent, and it means the terms you get today may not be the terms of the next major release. Anyone building a product on top of Evolver should read that notice as part of the adoption decision, not as a footnote.

How Evolver differs from a skill-doc or prompt-library approach

The obvious alternative is the pattern most agent teams already use: keep a folder of Markdown skill files or a prompt library, and edit those files when behaviour needs to change. The difference is what carries the experience. In a skill-doc approach the carrier is prose, and the reviewer has to read the prose to judge the change. In Evolver the carrier is a Gene or Capsule selected from a pool, and the README's cited paper argues that this compact representation is the better carrier for iterative accumulation. The practical consequence is that a diff in Evolver is a selection and an activation, not a rewritten paragraph.

That trade is real in both directions. A prompt library needs no runtime, no git history discipline, and no protocol. Evolver needs all three, and it adds a dependency chain that includes @evomap/gep-sdk and @evomap/atp-sdk. If your team is small and your prompts change weekly by hand, the library is cheaper. Evolver starts to pay off when several people or several agents are changing the same behaviour and someone has to answer why version five behaves differently from version two.

Maintenance, release cadence and licence cost

The repository is not archived, and the last push was on 2026-09-06. Releases track closely behind: v2.0.33 on 2026-09-06, v2.0.32 the same day, and v2.0.30 on 2026-09-04. That cadence means upgrade cost is a real line item rather than a theoretical one, and the version numbering in package.json (1.94.0) does not match the v2.0.x release tags, so pin an exact version rather than assuming the two numbering schemes line up.

On licensing, package.json declares GPL-3.0-or-later and the repository ships a LICENSE file. The README's notice says future releases will be source-available while published versions keep their original terms. Whether GPL-3.0-or-later fits your distribution model is a question for your own counsel; the factual point is that the declared licence is copyleft, and the project has announced an intent to change terms for future releases.

Editorial conclusion

Adopt Evolver if you already keep an agent's logs in a git repository and you want each prompt or skill change to be traceable to a selected Gene or Capsule rather than to a hand edit. Do not adopt it if your project is not under git, if you cannot run Node.js 18 or newer, or if you need a permissive licence for a closed-source product, since package.json declares GPL-3.0-or-later. Before committing to it, run evolver --review in a scratch repository and read the generated GEP prompt to confirm the selected asset matches your domain, then check the licence file against how you intend to distribute the result.

Frequently asked questions

Official sources

1. EvoMap/evolver on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases