Argon 2.5: Diff and Merge Preview Now Follow the Change
Argon 2.5.0 builds diffs and merge plans from the documents a branch changed. Before and after at up to a million documents, and what still reads a whole collection.
Current capability notes: checkout materializes a physical database; native actor attribution is per branch/run; undo needs complete images and retained history. CLI sandboxes require watch and scheduled sweep. Read the capability matrix.
Argon gives AI agents MongoDB sandboxes: an agent works in a copy of your data, and you read the diff before anything is merged. Until this week, reading that diff cost as much as the whole database. A branch that changed 100 documents out of a million took seconds to diff and several gigabytes of memory, because Argon rebuilt every document to find the hundred.
DoltHub pointed this out in their comparison of Argon and DumboDB, we confirmed it in our response, and Argon 2.5.0 fixes it. A diff and a merge preview now do work in proportion to what the branch changed. This post has the measurements before and after, what did not change, and the cases where 2.5.0 still reads a whole collection.
What changed
A merge plan is a three-way comparison for each document: its state at the fork point, on the parent now, and on the branch now. Up to 2.4.1, argon diff and argon merge preview rebuilt those three states in full and compared every document in every collection.
Only a document the branch wrote after its fork can be part of a plan, and Argon's log already records those writes. In 2.5.0 the plan is built from the documents named by the branch's own entries. For each one, the branch's state is its newest entry, and the fork point and the parent are read from that document's own history through an index. The plans are identical: the engine's tests hold the new path to the old one on randomized histories. The change is pull request 117, and the design is written up in the architecture notes.
Before and after
We ran the same script on both versions, at ten thousand, a hundred thousand and a million documents of about 236 bytes, with 100 and with 10,000 documents changed on the branch. These are medians of whole CLI commands, 2.4.0 then 2.5.0. Every figure is from the 2.4.0 report and the 2.5.0 report, which have the raw samples.
| Step | 10,000 documents | 100,000 documents | 1,000,000 documents |
|---|---|---|---|
argon diff, 100 documents changed | 101 ms → 35 ms | 348 ms → 44 ms | 7,088 ms → 30 ms |
argon diff, 10,000 documents changed | 179 ms → 393 ms | 617 ms → 450 ms | 8,491 ms → 412 ms |
argon merge preview, 100 changed | 99 ms → 27 ms | 351 ms → 39 ms | 6,045 ms → 26 ms |
argon merge preview, 10,000 changed | 225 ms → 386 ms | 516 ms → 415 ms | 6,180 ms → 385 ms |
Peak memory of one argon diff | 112 MiB → 123 MiB | 541 MiB → 115 MiB | 5,016 MiB → 118 MiB |
Read across a row and the 2.5.0 figure barely moves: about 30 ms for a hundred changed documents and about 400 ms for ten thousand, whether the database holds ten thousand documents or a million. Memory is flat too. A diff no longer holds the database.
Two things the medians hide
The first diff on a branch
Each run diffed a branch three times, and the first of the three was much slower than the other two. For a workflow that diffs once, the first is the one that counts.
argon diff, 100 changed | 10,000 documents | 100,000 documents | 1,000,000 documents |
|---|---|---|---|
| 2.4.0, first diff | 146 ms | 584 ms | 8,269 ms |
| 2.5.0, first diff | 68 ms | 233 ms | 1,874 ms |
| 2.4.0, later diffs | 96 ms | 342 ms | 5,764 ms |
| 2.5.0, later diffs | 30 ms | 32 ms | 28 ms |
The extra time is not spent on the plan. In our run the main branch was checked out and nothing was running argon watch on it, so a diff first brought the main branch's capture up to date. MongoDB answers that by reading the oplog written since capture last stopped, and at that point the oplog held the new branch's whole checkout. MongoDB's log shows one such read of about two seconds for each first diff at a million documents. In a separate run where the main branch was not checked out, the first diff at a million documents took 29 ms.
So with a checked-out, unwatched parent, a first diff still pays for the size of the checkout before it. We have not measured whether keeping argon watch running on the parent, or letting argon console or argon mcp manage capture, removes that cost. It is open as issue 120.
A branch that changed everything
In the ten-thousand-document column, 10,000 changed documents means the branch rewrote the whole collection. There 2.5.0 is slower: 179 ms became 393 ms. Reading each document's history costs more per document than reading the collection once. By a hundred thousand documents with 10,000 changed, 2.5.0 is ahead again.
What did not change
- A sandbox is still a full copy. A new branch to its first read took a median of 7.5 seconds at a million documents in 2.5.0 and 8.5 seconds in 2.4.0, which is the same within the noise of a shared machine. 2.5.0 did not touch checkout.
- Applying a merge is the same.
argon merge applywrites each change of a saved plan, and every so often triggers an automatic snapshot of the target branch, which reads the whole branch. - Merge semantics are the same. A merge still goes from a branch into its parent, compares whole documents, and takes one strategy for all conflicts in a plan.
When 2.5.0 still reads a whole collection
After garbage collection, measured
argon gc deletes log entries that a snapshot already covers. Once it has deleted the parent's entries, a changed document's state at the fork point and on the parent has to come from the parent's snapshot. A snapshot cannot be read one document at a time, so it is loaded once per collection and side.
We measured it: after a gc that removed every entry of the main branch, a diff of 100 changed documents at a million documents took about 1.1 seconds and 1.5 to 1.8 GiB of memory, against about 20 ms before the gc in the same run. That is slower than the common case, and still several times faster than 2.4.0 with about a third of its memory.
Three cases that use the previous algorithm, not measured
In these the plan is computed the way 2.4 computed it. We describe them from the architecture notes and did not measure them:
- Garbage collection has deleted entries of the branch being merged, so its log no longer names every document it changed.
- The history holds entries written before Argon 2.1, which do not identify their document reliably.
- The branch holds more than 200,000 entries of its own.
How this was measured
- Argon 2.5.0 and 2.4.0 as
npm install -g argonctlinstalls them, MongoDB 7.0.45 as a one-node replica set, both in containers on one Apple M6 laptop. One collection with the_idindex only. Five branch workflows per cell, three diffs in each. - The run stops with an error unless every diff and merge plan lists exactly the documents that were updated and every merge is found in the main branch. Both versions passed at every size.
- The laptop was shared with unrelated work during every run, and each million-document tier ran once per version. We also ran 2.4.0 again straight after 2.5.0, under heavier load, and it came out slower than the 2.4.0 figures above. The tables use the earlier, lower 2.4.0 figures, so the improvement shown is the smaller of the two.
- We measured Argon only.
To run it yourself, with Docker and Python 3 on the host:
git clone https://github.com/argon-lab/benchmarks
cd benchmarks
scripts/cli_scale_docker.sh 2.5.0 results/cli-scale-2.5.0
scripts/gc_case_docker.sh 2.5.0 100000,1000000 results/gc-case.txtUpgrading
There are no data format changes between 2.4.1 and 2.5.0. Install the new version over the old one:
npm install -g argonctl@2.5.0 --allow-scripts=argonctlThanks to Neil Macneale and DoltHub for measuring Argon in public. Their numbers are the reason this release exists. The comparison, and what we would like to do with them next, is in our response. If you run the script on your own data and see something different, tell us in GitHub Discussions.
Frequently asked questions
- What changed in Argon 2.5.0?
- argon diff and argon merge preview build their plan from the documents a branch changed since its fork, instead of rebuilding the fork point, the branch and its parent in full and comparing every document. The plans are the same. Nothing about the data format changed.
- How much faster is argon diff in 2.5.0?
- In our measurement with a million documents and 100 changed, the median diff went from 7,088 ms in 2.4.0 to 30 ms in 2.5.0, and peak memory from about 5 GiB to about 120 MiB. The first diff on a branch was slower, a median of 1,874 ms, because it also caught up capture on a checked-out parent.
- Does the time of an Argon diff depend on how many documents changed?
- From 2.5.0, yes. With 100 documents changed a diff took a few tens of milliseconds at ten thousand, a hundred thousand and a million documents; with 10,000 changed it took about 400 ms at each. Up to 2.4.1 it depended on the size of the database instead.
- Is anything slower in 2.5.0?
- Yes. When a branch changed every document in a collection, reading each document's history costs more than reading the collection once. With 10,000 of 10,000 documents changed, a diff went from 179 ms to 393 ms.
- When does 2.5.0 still read a whole collection?
- After argon gc has deleted the parent's entries, a changed document's state is read from the parent's snapshot, which is loaded once per collection and side. And the previous algorithm is used when gc deleted entries of the branch itself, when the history holds entries written before 2.1, or when the branch holds more than 200,000 entries of its own.
- Is creating a sandbox faster in 2.5.0?
- No. A sandbox is still a full physical copy of the data, and its time and storage grow with the database. 2.5.0 changed diff and merge preview only.