Skip to content

Version-Controlled Agent Context (Git Context Controller)

Checkpoint agent memory to a durable file tree and re-read it at a chosen level of detail instead of inheriting one lossy summary.

Version-controlled agent context gives memory the operations of a version control system: commit a milestone, branch to try an alternative, merge the useful result back, and read the store at whatever abstraction level the current step needs. The store is plain files on disk, so a fresh session recovers state the way a new engineer reads git history (Git Context Controller, arxiv 2508.00031).

The gains do not come from checkpointing, which is why the condition leads. In the source paper's ablation, adding a roadmap and commit records moved SWE-bench Verified resolution from 67.2% to 69.1%; adding fine-grained logs plus the read operation that retrieves them moved it from 69.1% to 75.3% (arxiv 2508.00031). Skip the read path and you land in the smaller number.

When it pays

Adopt this only where all three conditions hold:

  • The work outgrows one context window, or spans sessions. Anything that finishes inside a single window pays the overhead and collects none of the recovery benefit.
  • The agent can read the store back at more than one granularity. One progress file read whole is a partial adoption.
  • Something prunes the store. Notes from finished work stay weighted the same as current notes and pollute later answers (The MEMORY.md Problem).

The four operations

The paper defines four operations over a plain-text store (arxiv 2508.00031):

Operation What it does When the agent calls it
Commit Records intent, a coarse summary, and detailed progress as a checkpoint A milestone resolves
Branch Opens an isolated trace for an alternative approach The agent wants a second design without disturbing the first
Merge Folds a branch summary back into the main roadmap The alternative resolved and is worth keeping
Read Returns the store at a chosen level: roadmap, commit, raw log, or metadata The agent needs orientation, or one specific earlier detail

The layout is a directory of markdown and YAML: a top-level roadmap file, and per-branch files holding the commit log, the fine-grained action trace, and structural metadata such as file layout and dependencies (arxiv 2508.00031). Nothing in it requires a database.

Why it works

Compaction is a one-shot lossy decision made before you know which details will matter. Anthropic names the failure directly: "overly aggressive compaction can result in the loss of subtle but critical context whose importance only becomes apparent later" (Anthropic: effective context engineering). A summary fixes one abstraction level at write time. A structured store defers that choice to read time, so the agent pulls the roadmap for orientation and the raw trace for a specific earlier detail.

That is why the ablation credits retrieval rather than checkpointing or branching. The same mechanism explains the cross-session claim: a durable file tree lets a fresh agent recover state without inheriting an earlier author's compression choices. Anthropic's long-running-agent harness reaches the same shape from practice, starting each session by reading git logs and a progress file "to get up to speed on what was recently worked on" (Anthropic: effective harnesses for long-running agents).

When this backfires

  • Tasks that fit one window. The overhead is measured: 101.5 tool calls against 95.3 for the compaction baseline on SWE-bench Verified, and 24.5 against 14.2 for a ReAct baseline on BrowseComp-Plus (arxiv 2508.00031). With no window pressure that buys nothing back.
  • Checkpoints without retrieval. Teams build the write path first and stop, which collects the 1.9-point gain and leaves the 6.2-point one on the table.
  • Branches explored by concurrent agents. Isolation is what makes branching useful and also what breaks it: separate contexts act on assumptions never stated upfront, and the merge inherits the conflict. Cognition's second principle is that "actions carry implicit decisions, and conflicting decisions carry bad results", and their default is a single-threaded agent with one compression step (Cognition: Don't Build Multi-Agents). Branch and merge is also the smallest ablation contributor, at 2.4 points.
  • Stores nobody prunes. Metadata updates depend on the agent noticing a change and recording it, and when that lapses later reads return confidently wrong structure.
  • Borrowing the numbers for an unscaffolded setup. The results come from a controller that exposes these operations as tools and enforces them, so telling an agent to write notes like git commits is a different intervention.

The experiments also exposed only the most recent commit record, so the gains do not demonstrate deep recall across a long commit chain (arxiv 2508.00031).

Example

The paper's own store is four plain files, and the read path — not the commit template — is the part worth copying (arxiv 2508.00031):

.GCC/
  main.md                    # global roadmap: goals, milestones, to-do list
  branches/
    <branch-name>/
      commit.md              # one entry per milestone: intent, summary, detail
      log.md                 # fine-grained observation-thought-action trace
      metadata.yaml          # file structures, dependencies, configs

The agent starts a session by reading main.md alone. It opens commit.md when the roadmap is too coarse to place the current step, and log.md only when it needs an exact earlier command, error, or decision that a summary dropped. Three depths, and the choice made at read time.

A second directory under branches/ is the optional fourth step. Keep it sequential — one agent, one trace at a time — so the merge does not have to reconcile assumptions two contexts never shared (Cognition: Don't Build Multi-Agents).

Key Takeaways

  • The read path carries the benefit: layered logs plus retrieval moved SWE-bench Verified from 69.1% to 75.3%, while commit records alone moved it 67.2% to 69.1%.
  • Store context as plain files at several depths — roadmap, commit log, raw trace, metadata — so the agent picks its abstraction level at read time.
  • It works because compaction commits to one level of detail before you know which details matter, and a durable store defers that choice.
  • Skip it for work that fits one context window: the source paper measures about 6% more tool calls on SWE-bench Verified and 70% more on BrowseComp-Plus.
  • Treat branch and merge as optional and keep them sequential; parallel branches produce the conflicting-assumption failure that argues against multi-agent splits.
  • The published gains assume a controller enforcing these operations as tools, so an unenforced notes file is a partial adoption.
Emerging — single recent source Last reviewed: 2026-07-28