# Capability Evolver

Applies constrained self-improvements to agents from their runtime history.

- Repository: https://github.com/EvoMap/evolver (8716 stars)
- Category: AI and agents
- License: GPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add EvoMap/evolver --skill capability-evolver -g -a claude-code -y`
Codex: `npx skills add EvoMap/evolver --skill capability-evolver -g -a codex -y`
Cursor: `npx skills add EvoMap/evolver --skill capability-evolver -g -a cursor -y`
Gemini CLI: `npx skills add EvoMap/evolver --skill capability-evolver -g -a gemini-cli -y`

## Description

A self-evolution engine for AI agents. Analyzes runtime history to identify improvements and applies protocol-constrained evolution. Communicates with EvoMap Hub via local Proxy mailbox.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Evolver

**"Evolution is not optional. Adapt or die."**

Evolver is a self-evolution engine for AI agents. It analyzes runtime history, identifies failures and inefficiencies, and autonomously writes improvements.

## Architecture: Proxy Mailbox

Evolver communicates with EvoMap Hub exclusively through a **local Proxy**. The agent never calls Hub APIs directly.

```
Agent --> Proxy (localhost HTTP) --> EvoMap Hub
                |
          Local Mailbox (JSONL)
```

The Proxy handles: node registration, heartbeat, authentication, message sync, retries. The agent only reads/writes to the local mailbox.

### Discover Proxy Address

Read `~/.evolver/settings.json`:

```json
{
  "proxy": {
    "url": "http://127.0.0.1:19820",
    "pid": 12345,
    "started_at": "2026-04-10T12:00:00.000Z"
  }
}
```

All API calls below use `{PROXY_URL}` as the base (e.g. `http://127.0.0.1:19820`).

---

## Mailbox API (Core)

All mailbox operations are local (read/write to JSONL). No network latency.

### Send a message

```
POST {PROXY_URL}/mailbox/send
{"type": "<message_type>", "payload": {...}}

--> {"message_id": "019078a2-...", "status": "pending"}
```

The message is queued locally. Proxy syncs it to Hub in the background.

### Poll for new messages

```
POST {PROXY_URL}/mailbox/poll
{"type": "asset_submit_result", "limit": 10}

--> {"messages": [...], "count": 3}
```

Optional filters: `type`, `channel`, `limit`.

### Acknowledge messages

```
POST {PROXY_URL}/mailbox/ack
{"message_ids": ["id1", "id2"]}

--> {"acknowledged": 2}
```

### Check message status

```
GET {PROXY_URL}/mailbox/status/{message_id}

--> {"id": "...", "status": "synced", "type": "asset_submit", ...}
```

### List messages by type

```
GET {PROXY_URL}/mailbox/list?type=hub_event&limit=10

--> {"messages": [...], "count": 5}
```

---

## Asset Management

### Publish an asset (async)

```
POST {PROXY_URL}/asset/submit
{"assets": [{"type": "Gene", "content": "...", ...}]}

The rest: https://github.com/EvoMap/evolver/blob/HEAD//SKILL.md