autoevolve CLAUDE.md

CLAUDE.md — autoevolve

This file is the constitution of this repository. Every session, every agent, every unit of work obeys it. When a decision here conflicts with your instinct, this file wins. When something here is genuinely wrong, write a BLOCKERS.md entry with evidence and stop — do not silently deviate.

---

1. What autoevolve is

AutoEvolve is an open, agent-native evolutionary optimization and discovery system. A person states a goal in english — an issue, a CLI arg, a chat message. The system synthesizes a scoring contract, measures the baseline, checks feasibility, then evolves code toward the target with a parallel population of coding-agent workers, and ships the result as a report or a PR.

It exists to produce new things: faster kernels, better algorithms, new model architecture components, rediscovered and novel equations. Machines get an optimization substrate; humans get "if you can say it, you can evolve it."

The five invariants (the product — never trade these away)

1. The agent IS the mutation operator. Claude Code / Codex sessions mutate candidates. They can profile, read compiler output, debug the evaluator, reason about failures. Never reduce mutation to a blind LLM diff call as the only path.
2. The population outlives sessions. All evolution state lives in one store (SQLite) owned by the autoevolve server process. Worker sessions are stateless and disposable. Any MCP-speaking agent can join a run mid-flight.
3. English in, contract out. Before any compute burns: synthesize evaluate.py, measure the baseline, compute a feasibility ceiling where possible, and lock the contract. The promise is always: hit the target, OR deliver best-found plus an evidence-backed explanation of the ceiling. Both are successful outcomes.
4. It gets smarter every run. Top lineage diffs are distilled into natural-language discoveries persisted in the discovery ledger. Future runs sample relevant discoveries into mutation context. Knowledge compounds across runs and across problems.
5. It evolves itself. Operator selection is a persistent per-domain UCB bandit over measured child-improvement rates. The system's own strategy is under optimization at all times.