Evolving Agents

An open lab for agents that learn how a team works — and can show what they learned.

A director keeps the team's way of working as a memory of small, linked, verifiable statements. It plans
by walking that memory, hands each step to a frontier model or to small local specialists, and learns from
every task — each lesson a gated, versioned patch that can be blamed or bisected. Every number below was
measured, including the ones that came back flat.

Your CLAUDE.md, actually followed

You wrote the rules down. Your agent still breaks them under pressure — on 14 real situations, a Claude Code
session with the rules loaded planned by them 0.589 of the time; the director, walking the same rules compiled
into linked statements, 0.929. If you keep a CLAUDE.md, an AGENTS.md or Claude Code's memory, this is for you:

• it recalls the rule at the moment it applies — and cites the statement it followed in every step of its plan;
• it learns from your corrections — each lesson proposed, checked against what it already knew, and kept only
  if you accept it, as a reversible, versioned patch;
• it learns where you want work done — move a task from the frontier to your local model once, and it plans the
  next one like it there.

Try it on your own instructions

git clone https://github.com/EvolvingAgentsLabs/evolving-agents && cd evolving-agents/packages/director
# compile your instructions into a memory (Claude Code with Opus; one compile of ~60 files: about US$5)
python3 -m director.compile --claude-md ~/your-project/CLAUDE.md \
    --memory-dir ~/.claude/projects/<your-project>/memory --workdir ~/your-project
python3 -m director.server --config ~/.config/director/director.json      # open http://127.0.0.1:8740

Needs Python 3.10+ and Claude Code (claude on your PATH). Standard library only. The
memory stays on your machine. What it costs, what it does not do yet, and every measurement:
packages/director/ · the plan ahead: ROADMAP.md.

The system

How the pieces connect — built, and planned. Built: the director delegates to Claude Code and to any
OpenAI-compatible local server (it ran on llama.cpp on a 16 GB laptop), and every memory edit it keeps is an
agentvcs patch, gated and applied (blame credits the learning patch with its +0.781); agentvcs reads
lora-kernel's configuration as a manifest and gates changes to it. Planned: the director's local lane through
lora-kernel's specialists and router, rather than a bare model; gene-evidence's reports drafted by a lora-kernel
specialist and versioned by agentvcs.

The director, in three pictures

plan by walking the memory	learn from a task	learn where work runs

What it is, how to run its interface, and every measurement with its brief: packages/director/.

The organisation's public projects

Twenty-five more repositories are archived and read-only; each is listed, with
where it moved, at evolvingagentslabs.github.io/archive.

The Agent SDK plugin (paused)

The loop is solved. What happens after the fork is not. A plugin for the
Claude Agent SDK that versions an agent's evolution — diff
it, merge it, refuse to ship it when the eval fails. Its ideas continued in agentvcs; the director is where they
now run.

The gap

The Agent SDK runs the loop, ships the tools, manages context, and enforces
permissions. It also branches: fork gives you a second session starting from a
copy of the first.

Nothing brings the two back together. There is no merge, no diff between two
sessions, nothing that refuses to promote an agent whose eval regressed, and the
transcript is plain JSONL that anyone can edit. Sessions persist the
conversation — the skills, subagents, model and goal that produced it are not
versioned alongside it.

That gap is this repository. Most of it is closed; the last row is not, and it is
the one worth being precise about.

The unit avcs_diff and avcs_merge operate on is an agentvcs commit, not an
SDK session. Both work today, and neither will take two session IDs: a session is
an append-only event log, and the adapter that turns one into something mergeable
does not exist yet. Two forked sessions do share a prefix, so the common ancestor
is findable — the open question is what a conflict means when both branches are
conversations that reached different conclusions about the same file.

That adapter is M1, it has not started, and it is the reason this
repository exists rather than a detail of it.

Install the plugin

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    plugins=[{"type": "local", "path": "/path/to/evolving-agents/plugin"}],
)

Full details in plugin/README.md. The MCP server has zero
runtime dependencies — standard library only, with a test that fails if that
ever stops being true.

What is here

Why this repository has a 2025 in it

It was the Evolving Agents Toolkit: 18,680 lines across twelve subsystems — a
component library, an agent bus, smart memory, an evolution loop, and a
governance layer called Firmware. Backed by MongoDB Atlas.

It had three test functions.

That number is the story. EAT was not a product that failed; it was an
architecture written down and never pinned to anything that could contradict it.

Most of it is now deleted, because the SDK does it better —
docs/WHAT-WAS-DELETED.md lists the 10,165 lines and
what replaced each one. Firmware asked a model to "never use dangerous
imports" in a string; a PreToolUse hook returning permissionDecision: "deny"
stops the call whatever the model decided. We do not ship our own version of a
problem that is already solved.

What survives in legacy/eat/ is the ancestry of what ships today. Read
evolution/ if you read one thing: 337 lines that closed the loop between an
agent changing and that change being kept, with nothing to verify the change was
an improvement. avcs_freeze is the same idea with the missing half added.

Evidence

Claims here are measured, including the ones that came back flat.

• The dual-embedding resolver does not help. EAT indexed every component
  twice — once for what it is, once for what it is for. Rebuilt and measured:
  80% acc@1 either way, no difference. The second axis is genuinely distinct
  (cosine = 0.753); it just buys nothing on a modern encoder.
• This organisation's "byte-identical wire format" claim was wrong. Two of
  three opcode regexes matched; HALT had diverged in a way that changes what
  parses. Found by writing the test instead of repeating the sentence.
• Retrieving past experience buys nothing on the task. EAT's SmartMemory
  and its ContextBuilderTool rest on the premise that recalling similar past
  work improves the next attempt. Measured three times in ai-os and the runtime
  beside it: −4 against a retriever handed the solved similar cases with
  their answers, +0 (p = 1.0000) against the strongest retriever
  constructible, and −6 against an oracle retriever — below doing nothing.
  What did move was a compact statement of a rule induced from the same
  trajectories: +21 over the oracle.
• The memory hierarchy loses to lexical search. ai-storage implements the
  four levels EAT's smart memory argued for. Its first benchmark, at the ceiling
  with a perfect navigator: exact search 3/3 at every corpus size, hierarchical
  navigation 1–2/3 and out of steps, the flat file refusing to fit at all.

Three flat results, three architectures, one direction. The dual axis in
2025, the experience retrieval in 2026, the hierarchy after it. Each was the
obvious next structure and each was asked for a number. That is what this
repository is for, and it is why the toolkit is in legacy/ rather than
deleted: it was right about where to look and wrong about what would be there.

Breaking change

pip install git+https://github.com/EvolvingAgentsLabs/evolving-agents no longer
installs an evolving_agents package — this is a monorepo now. Install what you
want by name:

agentvcs was never published to PyPI — the release workflow exists but its
Trusted Publisher was never registered, so pip install agentvcs returns 404.
Install the frozen copy from source:

pip install "git+https://github.com/EvolvingAgentsLabs/evolving-agents#subdirectory=packages/agentvcs"

The maintained agentvcs is EvolvingAgentsLabs/agentvcs
(Rust runtime and its Python SDK; build instructions in its README).

The 2025 package sits at legacy/eat/ with its original setup.py, unchanged.

_{By Matias Molinas and
Ismael Faro · Apache 2.0}