Start here (2026-10). This repository holds the 2025 Evolving Agents Toolkit — agents that create, route to and evolve other agents — with the Agent SDK
plugin and the ai-os subtree that followed it. It is paused; the lab's current work continued each idea where it could be measured. **Evolving a harness,
gated and merged on evidence → agentvcs (packages/agentvcs/ here is a frozen copy). Routing to
specialists on one small local model → lora-kernel. Every claim pinned to what could contradict it** —
the lesson of the toolkit's three test functions, below — → gene-evidence. All projects, with status:
evolvingagentslabs.github.io.
Evolving Agents
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.
The organisation's public projects
| | | status |
|---|---|---|
| lora-kernel | An operating layer for specialized local AI agents: one small resident model, many specialists (adapter + library + scoped tools), a router that abstains to a frontier model | active — the flagship |
| agentvcs | Version control for live-patched agent systems; a Rust core and a merge in which Claude Code resolves conflicts between harness manifests | revived 2026-10-06 — validation in progress |
| evolving-agents (this repository) | The Agent SDK plugin, the ai-os subtree, packages/, the robot demo and the 2025 toolkit | paused |
| physics-verifiers | RL environments whose reward is computed by physics; what stands is a generator of tasks with exact truth | paused — last change 2026-08-16 |
| nightshift | A procedural and epistemic memory engine, as a Claude Code plugin | proof of concept — last change 2026-08-31 |
| evolvingagentslabs.github.io | The website, with a nightly check of every number it publishes | active |
| .github | The organisation's GitHub profile | paused — last change 2026-07-25 |
Twenty-five more repositories are archived and read-only; each is listed, with where it moved, at evolvingagentslabs.github.io/archive.
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.
| | Agent SDK | This plugin |
|---|---|---|
| Branch a session | fork | — |
| Snapshot code, goal, models and trace as one unit | — | avcs_commit |
| Compare two snapshots | — | avcs_diff, per dimension |
| Rejoin two snapshots | — | avcs_merge, with a --reconcile seam for goal and trace |
| Refuse to ship a regression | — | avcs_freeze, which fails unless the eval passes |
| Prove a transcript wasn't edited | — | Ed25519-signed commits |
| Keep the trace past compaction | summarised away | archived by the PreCompact hook |
| Diff or merge two forked _sessions_ | — | not yet — M1 |
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
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
| | |
|---|---|
| ai-os/ | Paused — last changed 2026-09-06, the day it arrived as a subtree; the lab's work has since moved to lora-kernel. An agent-based operating system on a vendored QM base: flows, a desk you arrange, agents as markdown, memory at four levels. 851 tests, CI, a running stack |
| plugin/ | The Agent SDK plugin: MCP server + three hooks |
| packages/agentvcs/ | Frozen copy. agentvcs lives again in EvolvingAgentsLabs/agentvcs (Rust runtime, revived 2026-10-06) |
| packages/memory/ | Structured recall above the SDK's flat .claude/ memory files. Works; measures no better than naive matching — see PLAN.md |
| demos/robot/ | A 2D robot that evolves its own skills, versioned with agentvcs |
| legacy/eat/ | The Evolving Agents Toolkit, 2025. Kept readable; see below |
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
cosine = 0.753); it just buys nothing on a modern encoder.
- This organisation's "byte-identical wire format" claim was wrong. Two of
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
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-storageimplements the
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