EVA — Evolvable Virtual Agent

#Not a framework — a meta-architecture

EVA is not a finished agent architecture. It is a meta-architecture for evolving agent-architectures:

That makes EVA bounded architecture-agnostic: architecture is not shipped, it is a gated, reversible, evolvable state. Frameworks ship structure — gateway, skill registry, channels, scheduler. EVA ships the mechanism to grow that structure under control: two different uses can, over generations, grow two different EVAs — without ever weakening the kernel, gates, or policies.

The seed is deliberately not a product but the smallest viable organism plus an immune system (gates, ratchet, policies, manifest hashes). New organs and skills are earned through use and friction.

Bootstrap once, then evolve forever

• organism.py — the kernel: ~900 lines, baked into the image. It seeds the genome (verifying SHA-256 manifest hashes), runs the final gate, keeps the ledger.
• seed/v001/ — the genome: real, reviewable, hash-pinned Python files.
• runtime/releases/vN/ — the live, evolvable generations. EVA builds a candidate and, only when the gates pass, swaps itself for it.

#How it evolves

EVA evolves the way organisms do: a mutation (the candidate) is expressed in a copy, selection pressure (the gates) decides whether it survives, and only then does a new generation go live. The crucial difference to nature: selection here is not random death but an explicit, layered test — and every generation is in the ledger, so evolution can step backwards.

Self-change comes in two modes; both land the same way — candidate → tests → gated promotion — and differ only in who picks the mutation:

Live improve run (real, unedited session — 3 minutes): EVA is asked to "give yourself a soul". It creates a candidate, writes soul.md, protects it with a new ratchet check, passes 87/87 checks and both gates — and is promoted to v002. Milestones are marked on the timeline (jump with [/]):

Live skill evolution (real, unedited session — long waits compressed): EVA is asked to evolve a browser-automation skill. In one gated cycle it installs Playwright + headless Chromium, apt-installs 24 native libraries in the FREE sandbox and persists them to the system-deps manifest, writes a new browser tool into a candidate, hits a real ratchet failure and debugs its own test suite, proves the tool live against example.com, passes 122 checks and both gates — and is promoted. The new skill survives the throwaway container:

Grown from friction, not designed up front

Where does the pressure to evolve come from? From the environment — real usage. Every session feeds a persistent friction backlog: failed shell commands, provider errors, crashes and capability gaps are each recorded under a stable, error-specific signature. When the same signature recurs, EVA offers to pivot to an improve cycle aimed at the root cause — a clean phase change, never live mutation.

Beyond failures, EVA learns from user needs: when a request reveals a capability it lacks, it notes it under a stable signature (note_evolution_need). A one-off is simply handled; only a need that recurs across sessions is proposed as a real skill — new abilities are earned from what you actually keep asking for.

#Every self-change must survive this

The seed ships with an immune system, and this is it at work: anything foreign to EVA's constitution — a weakened check, a lying manifest, a manipulated prompt — is rejected before it can become part of the organism.

A candidate goes live only after the release's full LLM-free suite — unit checks, smoke, dry-runs of every mode, qualification rounds, and golden traces that replay recorded provider responses through the real adapters — plus the standing guarantees on top:

#EVA knows itself

Call it proprioception: EVA senses its own body. Self-inspection is a first-class capability — and it cannot go stale, because EVA's self-model is generated from the live code on every run: anatomy from the release manifest, skills from its tool definitions, guaranteed capabilities from its own test suite, its security boundaries from the mode-policy table. Ask it (inspect_self — overview · anatomy · skills · capabilities · policy · sandbox · model · vitals) and it answers from the release it is actually running, down to which sandbox and model it is on right now.

Beyond anatomy, EVA also knows how it has been doing: vitals aggregate friction pressure, evolution outcomes and turn feedback; a lessons journal keeps durable insights; and a cross-session episodic memory digests every session into a compact episode — recalled on demand (recall tool) and auto-surfaced when a new task clearly relates to past work. All of it plain JSONL under ./data/state, LLM-free and inspectable.

#Modes & everyday use

Quickstart

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/arturkorb3/eva-evolutional-agent/main/install.sh | bash

# Windows (PowerShell)
iex (irm https://raw.githubusercontent.com/arturkorb3/eva-evolutional-agent/main/install.ps1)

eva                    # first run: a short wizard sets up provider → model → key, then chat

Inside a session, just talk to EVA in plain language; /help lists the in-chat commands (/model switches the model, /resume picks another work session, /paste attaches a screenshot, exit ends). Everything else is eva <command> — with tab-completion for PowerShell, bash and zsh.

Providers

The core is provider-neutral: it talks to a ModelAdapter, never to a provider directly. Pick the adapter explicitly in .env:

Inspecting & resetting

Everything EVA does is persisted on the host under ./data/ (git-ignored): workspace/ (work product), runtime/releases/ (every release + CURRENT/LAST_GOOD), and state/ (event log, blobs, friction backlog, ledgers). Delete data/ or run reseed to start fresh. Evolution lives only in data/ — back valuable changes into seed/ (and commit) or a reseed loses them.

#Contained, not "safe"

Self-modification is only safe if EVA can't quietly weaken its own guardrails. Every self-change already has to survive the gate stack; the remaining defenses run at runtime, and each lives where the layer it protects can't edit it.

Humans stay in the loop. Risky actions (shell, writes, promotion) need an explicit y; anything else is not approval — a free-text reply steers EVA instead of being obeyed blindly. Secrets come from .env and are never logged.

#Components

#Honest limitations

A research experiment, not production software.

• The standing gate runs offline: golden traces replay recorded provider responses; a live check exists but is opt-in — a provider silently changing its wire format won't fail the gate until you run it.
• The ratchet counts executed checks; a kernel substance floor (AST) rejects hollow check bodies and the constitutional checks are pinned by body hash — but the semantic quality of an arbitrary check still can't be proven mechanically.
• Context compaction is deterministic and heuristic: it preserves constraints and milestones, but budgets by characters, not tokens, and understands no semantics.
• Network egress is open by default (see residual risk above).