ACTIVE again — 2026-09-06. This repository was frozen on 2026-08-01 and closed with a pointer to
ai-os.ai-oshas now come home: it is a subtree here, with its history intact, and this is where the organisation's active work lives.Nothing was rewritten to make the arrival look tidy. The 2025 toolkit stays in
legacy/eat/, the flat results stay in Evidence below, and two more have been added — because they point the same way as the first, which is the finding.
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 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.
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.
ai-os/ |
The active project. 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/ |
The version control itself — 220 tests, no dependencies. Not on PyPI; install from source |
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 |
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.
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;
HALThad 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
SmartMemoryand itsContextBuilderToolrest on the premise that recalling similar past work improves the next attempt. Measured three times inai-osand 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 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.
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 from source:
pip install "git+https://github.com/EvolvingAgentsLabs/evolving-agents#subdirectory=packages/agentvcs"The 2025 package sits at legacy/eat/ with its original setup.py, unchanged.
By Matias Molinas and Ismael Faro · Apache 2.0