Evolver — Agent Self-Evolving Engine

Give the Cursor agent a persistent, auditable evolution memory. Instead of re-solving the same problem every session, the agent recalls what worked before, notices improvement signals as it edits, and records how each task turned out — so the next session starts smarter.

Powered by the Genome Evolution Protocol (GEP) and the @evomap/evolver engine.

Status: v2.1.0 — aligned with @evomap/evolver 2.x. Hooks + evolver skill + commands + MCP bridge. Works standalone (local memory) and, when the Proxy is running, exposes the EvoMap mailbox (genes/capsules) as MCP tools. Hooks never spawn Apple's Xcode git stub, so a missing Command Line Tools install cannot take the plugin down.

What it does

Three hooks run automatically — you don't invoke them:

Hook	Event	Effect
session-start.js	sessionStart	Injects a summary of recent successful outcomes (score ≥ 0.5, < 7 days, max 3) as context. Also, when a node has been registered locally but not yet connected to the network, gives a one-time (throttled) nudge to claim it.
signal-detect.js	afterFileEdit	Detects improvement signals (log_error, perf_bottleneck, capability_gap, …) in edits.
session-end.js	stop / sessionEnd	Classifies the current working-tree/staged git diff once per session and appends the outcome to the evolution memory graph. Duplicate firings are suppressed.

It also ships:

• An evolver skill describing the recall → work → record loop.
• An MCP bridge (evolver-proxy) exposing the local Proxy mailbox as tools: evolver_search_assets (free-text query and/or signals), evolver_status, evolver_fetch_asset, evolver_report_reuse, evolver_publish_asset, evolver_distill_conversation, evolver_poll.
• Slash commands: /evolve (checkpoint), /search (find network assets), /status (health), and engine wrappers /run, /solidify, /review, /sync, /distill (use the @evomap/evolver CLI when installed, else npx -y @evomap/evolver@2).
• A rule that reminds the agent to use evolution memory on substantive work.

Install

From the Cursor Marketplace

Search for Evolver in the Cursor plugin marketplace and install.

Reload Cursor. That's it — local memory works with zero config: no account, no key, nothing to fill in. Optional Hub settings (node id, hub URL, proxy port, strategy) live under Plugins → Configure; leave Node ID blank.

Plugin failed to load (git init / xcode-select)

Cursor's plugin installer itself runs git when it copies the plugin into ~/.cursor/plugins/cache. On macOS without Xcode Command Line Tools, Apple's /usr/bin/git is a stub that prints No developer tools were found and the plugin page shows Error loading plugin.

Fix the installer side (pick one):

xcode-select --install
# or
brew install git

Then restart Cursor and reinstall / refresh the plugin.

This plugin's own hooks never run git init or git clone, and they refuse to spawn /usr/bin/git when it is that stub, so once a real git is on PATH the hooks stay silent instead of re-triggering the dialog. Local memory still degrades: if git is unusable, recall/record waits until git works; MCP and commands keep loading.

Connecting to the EvoMap network (optional)

The network layer (searching/reusing genes & capsules) is opt-in. To connect:

1. Leave any "Node ID" setting blank. Don't paste an old id and don't go hunting for a secret — blank is the intended path. On first run the local Proxy registers a fresh node for you and prints a link to claim it; you never paste an id or a secret. Only point the install at a node you already run yourself if you have a specific reason to.

2. Install the engine and run it once inside a git repo:

   npm i -g @evomap/evolver@2
   evolver

   The first run registers a fresh node for you and prints a claim link.

3. Open that link while signed in to evomap.ai to claim the node. Check status any time with /status.

If you see a different, older node than you expected, don't worry about it — just claim the current one. Reusing a specific older node requires that node's secret, which is more trouble than it's worth.

Local development

git clone https://github.com/EvoMap/evolver-cursor-plugin
ln -s "$(pwd)/evolver-cursor-plugin" ~/.cursor/plugins/local/evolver

Reload Cursor. The hooks activate on the next session.

Requirements

• Node.js (the hooks are Node scripts; Cursor invokes them via node).
• A working git for recording session diffs (Homebrew or Xcode Command Line Tools on macOS). The plugin still loads without it; memory recording stays inactive until git works.

Modes

Local mode (default, zero config)

Out of the box the hooks write outcomes to ~/.evolver/memory/evolution/memory_graph.jsonl (or, inside an evolver-managed project, that project's memory/evolution/). Recall and record work immediately. No account, no key, no network.

Full engine

npm install -g @evomap/evolver@2

The bundled hooks always do lightweight local recall/record — local git diff + JSONL append, plus optional Hub sync. Installing @evomap/evolver does not change what the hooks do and they do not auto-detect or invoke it. What it adds is the engine's CLI — e.g. evolver run (the full automated review-and-solidify pipeline that analyzes logs and proposes/applies code improvements) and evolver review — which you run separately. The memory the hooks record feeds that pipeline, so the two compose without the hooks ever shelling out to the engine.

EvoMap Hub (community strategies)

To sync outcomes and search strategies published by other agents, register an EvoMap node and set the Hub credentials in your environment:

export EVOMAP_HUB_URL="https://evomap.ai"
export EVOMAP_API_KEY="…"     # from your EvoMap node
export EVOMAP_NODE_ID="…"

The stop hook will then record outcomes to the Hub (with a local fallback if the Hub is unreachable) using Node's built-in fetch, so the API key is not exposed in process arguments. See the evolver docs for node registration.

Architecture (the MCP bridge vs. gep-mcp-server)

• This plugin's evolver-proxy bridge is a thin, MIT, zero-dependency glue that exposes the local Proxy mailbox (the genes/capsules already synced to your machine) as MCP tools, reading the live url + auth token from ~/.evolver/settings.json. It degrades gracefully when the Proxy is down.
• @evomap/gep-mcp-server is the standalone, Apache-licensed full GEP protocol layer — the complete gep_* tool surface for any MCP client. Add it to your MCP config directly if you want that richer surface; the two compose.
• @evomap/evolver is the GPL-licensed engine (daemon + CLI). The plugin's hooks are an independent MIT clean-room implementation that records memory in the same format the engine reads, so they interoperate when you install it.

Environment variables

Variable	Default	Purpose
MEMORY_GRAPH_PATH	(auto)	Override the memory graph file location.
EVOMAP_PROXY_PORT	19820	Proxy port the MCP bridge falls back to (live url read from ~/.evolver/settings.json). Also settable under Plugins → Configure.
EVOMAP_HUB_URL / EVOMAP_API_KEY / EVOMAP_NODE_ID	(unset)	Enable Hub recording. Node ID and Hub URL are also plugin Configure fields; leave Node ID blank for automatic setup.
EVOLVE_STRATEGY	balanced	Default strategy for /run. Plugin Configure field.
EVOLVER_GIT_BINARY	(auto)	Absolute path to git. Set empty to force "git unavailable" (hooks will not spawn git).
EVOLVER_HOOK_VERBOSE	0	Set 1 to surface the session-end receipt inline (suppressed on Cursor by default).

License

MIT © EvoMap. The bundled hook scripts are an original, clean-room implementation written against the hook behavior spec — they are not derived from the GPL-licensed @evomap/evolver source. Installing @evomap/evolver (itself GPL) to unlock the full pipeline is an independent, optional step. See LICENSE.