EvolvingAgentsLabs/evolving-agents: version control for agents that change themselves

The gap this fills: an agent SDK branches, but nothing rejoins the branches

The Claude Agent SDK runs the loop, manages context, enforces permissions, and gives you `fork` to start a second session from a copy of the first. What it does not give you is a way to bring two sessions back together. There is no merge, no diff between two sessions, and nothing that refuses to promote an agent whose eval regressed. The transcript is plain JSONL, editable by anyone with a text editor.

That is the problem this repository targets. Sessions persist the conversation. The skills, subagents, model and goal that produced it are not versioned alongside it, so the artifact you would want to compare is not the artifact that gets stored. The plugin's answer is to define a different unit, an agentvcs commit, which snapshots code, goal, models and trace together, and then to build diff, merge and freeze on top of that unit.

What an agentvcs commit actually contains, and where the seam is

The comparison table in the README is the clearest statement of the design. Branching is the SDK's job. Snapshotting code, goal, models and trace as one unit is `avcs_commit`. Comparing two snapshots is `avcs_diff`, per dimension. Rejoining two snapshots is `avcs_merge`, with a `--reconcile` seam for goal and trace. Refusing to ship a regression is `avcs_freeze`, which fails unless the eval passes. Commits are Ed25519-signed, so a transcript that was edited after the fact can be shown to have been edited.

One row of that table is empty on purpose. Diffing or merging two forked sessions is listed as not yet implemented, and the README is explicit about why: the unit `avcs_diff` and `avcs_merge` operate on is an agentvcs commit, not an SDK session, and neither command will accept two session IDs. A session is an append-only event log. The adapter that turns one into something mergeable does not exist. Two forked sessions do share a prefix, so a common ancestor is findable, but the README names the unresolved question rather than dodging it: what is a conflict when both branches are conversations that reached different conclusions about the same file?

That adapter is M1 in PLAN.md, it has not started, and the README says it is the reason the repository exists rather than a detail of it. Take that at face value. The governance and versioning parts are real; the session-level reconciliation is the part you would be waiting on.

Trace survival is handled by a `PreCompact` hook, which archives the trace rather than letting compaction summarise it away. That matters because a snapshot whose trace has been summarised is a snapshot you cannot diff meaningfully against the original.

Installing the plugin and making a first signed commit

The README installs the plugin by pointing ClaudeAgentOptions at a local path. There is no package registry step for the plugin itself.

from claude_agent_sdk import query, ClaudeAgentOptions

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

Substitute the real checkout path for `/path/to/evolving-agents/plugin`. Full details are in `plugin/README.md`. The README states the MCP server has zero runtime dependencies, standard library only, with a test that fails if that stops being true, so there is nothing to install for the server itself.

The version control layer is a separate package and the README is direct about distribution: `packages/agentvcs/` is not on PyPI and installs from source. It carries 220 tests and no dependencies. The README does not give the exact install command, so check the package directory before assuming a name or an editable-install flag.

Once the plugin is loaded, the workflow the README describes is: commit the agent state, diff two commits per dimension, merge them with `--reconcile` when goal or trace diverge, and freeze before shipping. Freeze is the gate. The README states it fails unless the eval passes, which means the value of the gate is exactly the value of the eval you point it at.

The measured results in this repository are mostly negative, and that is the point

The Evidence section is unusual. It reports flat and negative outcomes rather than wins. The dual-embedding resolver, which indexed every component twice, once for what it is and once for what it is for, came back at 80% acc@1 either way, no difference. The README notes the second axis is genuinely distinct, with a cosine of 0.753, and still buys nothing on a modern encoder.

The memory result is stronger. Retrieving past experience, the premise behind EAT's SmartMemory and its ContextBuilderTool, was measured three times and did not help. The README reports −4 against a retriever handed the solved similar cases with their answers, +0 with p = 1.0000 against the strongest retriever constructible, and −6 against an oracle retriever, which is below doing nothing. What did move the number was a compact statement of a rule induced from the same trajectories, at +21 over the oracle. The memory hierarchy in `ai-storage` also lost to lexical search at the ceiling with a perfect navigator: exact search 3/3 at every corpus size, hierarchical navigation 1 to 2 out of 3 and out of steps, and the flat file refusing to fit at all.

Read those together and the repository is arguing against a premise its own 2025 ancestor was built on. That is worth knowing before you adopt the memory package: the README says `packages/memory/` works but measures no better than naive matching, and points at PLAN.md. If you came for recall that beats lexical search, the README says it does not.

The 2025 toolkit is still in the tree, and it is not the thing you install

`legacy/eat/` holds the Evolving Agents Toolkit from 2025: 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. The README treats that number as the whole story, describing EAT as an architecture written down and never pinned to anything that could contradict it.

Most of it is deleted. `docs/WHAT-WAS-DELETED.md` lists the 10,165 lines and what replaced each one. The example given is Firmware, which asked a model in a string to never use dangerous imports, against a `PreToolUse` hook returning `permissionDecision: "deny"`, which stops the call regardless of what the model decided. That is the right trade: replace a prompt-level request with a mechanism that does not depend on the model agreeing.

One file is called out as worth reading. `legacy/eat/evolution/` is 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 described as the same idea with the missing half added. If you are deciding whether the current design is coherent, that pairing is the argument.

The active project is `ai-os/`, described as an agent-based operating system on a vendored QM base, with flows, a desk you arrange, agents as markdown, memory at four levels, 851 tests, CI and a running stack. `demos/robot/` is a 2D robot that evolves its own skills, versioned with agentvcs.

Where this is the wrong tool

If your problem is reconciling two forked SDK sessions, this is not the tool yet. The README states plainly that neither `avcs_diff` nor `avcs_merge` will take two session IDs, and that the adapter is M1 in PLAN.md and has not started. You can commit, diff, merge and freeze agentvcs commits today. You cannot hand it two sessions and get a merge.

If you are not on the Claude Agent SDK, the plugin framing is a poor fit. The install path is a local plugin entry in ClaudeAgentOptions, and the hooks are SDK hooks. There is no documented path for another runtime.

If you need a published package, note that `packages/agentvcs/` is not on PyPI and installs from source. That is a real constraint for CI images and for anyone who expects a version pin from an index.

And if what you want is memory that retrieves better than lexical search, the repository's own measurements say no. The README reports the hierarchy losing to exact search and past-experience retrieval scoring at or below an oracle-free baseline. Adopting `packages/memory/` for a recall win would be adopting it against its own evidence.

Finally, the freeze gate is only as good as its eval. The README says `avcs_freeze` fails unless the eval passes, and does not describe how the eval is chosen or what happens when it is wrong. A signed, refusing gate over a weak eval gives you a confident record of a bad decision.

How it differs from the self-evolving agent work people search for

Searches around this space tend to land on survey papers and on group-evolving or self-evolving agent systems, where the interesting question is how agents share experience and improve each other. The approach here is different in kind. It does not propose an evolution algorithm. It proposes version control and a gate for the changes an evolution algorithm produces.

That distinction decides whether you want it. A framework that shares experience across agents is trying to make the population better. This plugin is trying to make each change auditable, comparable and refusable. The README's own framing puts it that way: the loop is solved, what happens after the fork is not.

The comparison it draws is against the Agent SDK alone, and the difference is concrete. The SDK forks a session; the plugin snapshots code, goal, models and trace as one unit, diffs per dimension, merges with a `--reconcile` seam, and signs commits with Ed25519. The SDK summarises the trace away at compaction; the plugin archives it through the `PreCompact` hook. Nothing in that list is an evolution mechanism. It is the record-keeping and the refusal.

If you are evaluating it against a broader self-evolving agent stack, the honest comparison is not feature against feature. It is whether you need provenance and a failing gate more than you need another improvement loop.

Maintenance status, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-06. The README's own banner says the repository was frozen on 2026-08-01 and closed with a pointer to `ai-os`, and that `ai-os` has now come home as a subtree with its history intact. So the freeze is recent history, not a distant event, and the stated position is that this is where the organisation's active work lives.

There are no releases retrieved, which fits the layout: the plugin installs from a local path, and `packages/agentvcs/` installs from source rather than from an index. Upgrade cost therefore falls on you. There is no version to bump in a requirements file for agentvcs, so a source install means tracking the repository yourself. The plugin is a path, so moving it is a path change. If you vendor either into a build, plan for that.

The licence is Apache-2.0, declared in the README badge and present as a LICENSE file at the top level. That is a permissive licence with an explicit patent grant and a notice requirement, which matters if you redistribute a modified copy, because you would carry the NOTICE obligations. This is a description of the licence, not legal advice; read the LICENSE file and the Apache-2.0 text for your own situation, particularly if you are combining it with code under a different licence.

Editorial conclusion

Adopt it if you are already building on the Claude Agent SDK and you need a signed, diffable record of what an agent was at each step, plus a gate that fails when an eval regresses. Do not adopt it if your workflow is two forked sessions that you want to reconcile: the adapter that turns a session into something mergeable does not exist, and the README points at M1 in PLAN.md as the work that has not started. Before wiring it into a pipeline, verify the three things the README leaves open: that packages/agentvcs installs cleanly from source on your Python, that the plugin path in ClaudeAgentOptions resolves on your SDK version, and that the eval avcs_freeze checks is one you actually trust, because the freeze is only as meaningful as the eval behind it.

Frequently asked questions

Official sources

1. EvolvingAgentsLabs/evolving-agents on GitHub
2. Issues
3. License: Apache-2.0
4. README