AI research edits need a diff, not a sparkle animation
An agent that rewrites your literature review should produce a bounded, reviewable change set: commands with reasons, word-level diffs, undoable restores, and snapshots that survive the history cap. The version-control design behind agent edits in a research workspace.

The most dangerous edit an AI can make to your research is a good-looking one. An agent restructures a section of your literature review, and the result reads better: cleaner hierarchy, tighter phrasing. What the polished surface does not show is that a qualification, "only in longitudinal samples," now sits two nodes away from the claim it used to constrain, or that "is associated with" quietly became "causes" during a merge. The after state looks plausible. The risk lives entirely in the delta.
Software engineering solved this social problem decades ago: nobody merges a colleague's work by reading the final file and thinking "seems fine." You review the diff, because the diff is where the intent and the damage are both visible. An AI editing scholarly work deserves exactly the same treatment, and most AI writing tools give you the opposite: an animation, a rewritten artifact, and a leap of faith.
This post is the version-control design we built for agent edits in a research mindmap: what gets stored, what gets diffed, and what a diff can and cannot protect you from.
Store intent as commands, state as versions
The foundation is that the agent never "writes the new mindmap." It emits an explicit batch of edit commands: add_node, edit_node, move_node, remove_node, each carrying the target, the payload, and a required reason string. The batch is applied transactionally to produce a new version, and the version records both the resulting tree and the command batch that produced it, tagged with its source: agent or user.
Commands turn out to be the load-bearing choice, for three reasons.
They bound the change. A batch is an enumerable set of operations, so "what did the agent just do" has a finite, displayable answer, not "compare these two documents and guess."
They carry intent. Every command's reason string ("split claim: citations support only the first clause") is provenance you can read six weeks later, next to the change it explains.
They make history mechanical. A version is reproducible from its predecessor plus its batch, which is what makes replay, diff review, and undo cheap enough to be default behavior rather than a premium feature.
Word-level diffs, because epistemic force lives in single words
The diff engine computes structural changes, nodes added, removed, moved, and for modified nodes, a word-level diff via longest-common-subsequence over the node text.
Word granularity is not a nicety. In research writing, the difference between defensible and indefensible is routinely one word wide: "causes" versus "is associated with," "shows" versus "suggests," a dropped "in this sample," a deleted "however." A node-level "this node changed" indicator forces you to re-read and re-compare the whole claim, which in practice means you will not. The word-level rendering puts the strengthened verb and the vanished hedge directly in front of you.
A structural edit that moves nodes and a wording edit that shifts epistemic force are different risks, and the diff has to expose both, because the agent performs both, sometimes in the same batch.
The history cap and the snapshots that ignore it
Rolling version history covers the recent past: the last 20 versions of a map, each undoable and redoable, with fork-on-write semantics when you edit from an earlier point. Twenty is plenty for "undo the last agent run" and useless for "compare against the version I trusted three weeks ago," which is a different need with a different lifetime.
So snapshots are a separate, durable store, deliberately immune to the version cap. A researcher saves a named snapshot at a moment that matters, before a major restructuring, at the version a chapter was submitted from, and it persists until deleted, up to 50 per mindmap. Compare-to-snapshot runs the same diff playback engine against the live map, so "what changed since the version my advisor saw" is one click, rendered with the same word-level precision as an agent-edit review.
The design principle underneath: short-term history should be automatic and capped, long-term reference points should be deliberate and durable. Conflating them gives you either an unbounded history nobody curates or reference versions that silently age out.
Restoring an old version is a forward operation
Restore is where version-control designs usually betray their users, by making restoration destructive: roll back, and the versions after the restore point are gone, including, ironically, the state you were comparing against.
Our restore is modeled as just another edit command. restore_snapshot carries the full snapshot tree embedded in the command itself and applies through the same pipeline as every other edit, producing a new forward version whose content is the old state. Nothing is rewound. The restore is immediately undoable, it appears in history like any edit, and because the tree is embedded in the command, the version remains replayable even if the source snapshot is later deleted.
History destruction is never on the menu, which changes the psychology of the feature: restoring stops being a commitment and becomes an experiment.
Review is a mode, not a modal
The last piece is what a reviewer actually touches. After an agent run, a review mode replays the last change as a diff overlay on the map itself: added nodes highlighted, removed ones ghosted, modified text showing word-level markup, with the batch's reasons attached. The same playback machinery serves undo review, version browsing, and snapshot comparison, one engine, four entry points, which is less an elegance flex than an honesty guarantee: every review surface shows the same computed truth.
What we deliberately did not build is an approval gate, an "accept these 14 changes?" modal between the agent and the map. Gates optimize for the feeling of control, and in practice they train users to click accept, the same way cookie banners trained everyone to click whatever dismisses them fastest. Immediate application plus one-click review-and-undo keeps the researcher in charge without making vigilance a tax on every single run. Skeptics are right that this trades a hard guarantee for an ergonomic one; our bet is that a review you actually perform beats a gate you learn to ignore.
What a diff cannot tell you
Honesty section, because version control is sometimes sold as a safety property it does not have.
A diff exposes change. It does not judge truth. A word-level diff will show you that "suggests" became "demonstrates"; it will not tell you whether the cited passage supports the stronger verb. That judgment needs the evidence itself, which is why every claim node keeps its citations one click from the passage and page behind them, and why verification against passages is a separate mechanism from edit review. Nor does a diff catch what never changed: a claim that was wrong before the agent touched the map is wrong in every version, invisibly.
And there is a long-range blind spot: a sequence of small, individually reasonable edits can drift an argument somewhere no single diff makes alarming. Snapshot comparison exists partly for this, diffing against a deliberate reference point instead of the previous version, but detecting drift still requires a human who remembers what the argument was supposed to be.
The checklist
If you are building, or evaluating, any tool where an AI edits work you must defend: edits should arrive as bounded change sets with stated reasons, not rewritten artifacts. Diffs should reach word level, because epistemic force is word-sized. History should be automatic and capped, reference points deliberate and durable. Restore should move forward, never destroy. And provenance, who changed this, when, why, should be queryable per element, not reconstructed from memory.
This is how agent edits work in Agent Bayes, where the review mode is one toolbar toggle away. The evaluation test I would run on any competitor, or on us: let the AI restructure something you care about, then try to answer, in under a minute, "exactly which words changed, and why." If the product cannot answer that, it is asking for trust it has not built the machinery to deserve.
New posts, straight to your inbox
No newsletter fluff, just an email when we publish something new.
Email me when a new post is published on the Agent Bayes blog. You can unsubscribe anytime. We'll first send a confirmation email, and we only use your details for this. See our Privacy Policy.