Skip to content

CONCEPT Cited by 1 source

Repo-per-agent-session

Repo-per-agent-session is the pattern-concept of giving every agent session its own Git repository that persists the session's filesystem state + prompt history + any other structured context, letting the session be time-travelled, forked, and diffed via standard Git data-model semantics.

Introduced to the wiki by Cloudflare's 2026-04-16 [[systems/ cloudflare-artifacts|Artifacts]] launch, where it's the named internal-dogfood use case:

"Inside Cloudflare, we're using Artifacts for our internal agents: automatically persisting the current state of the filesystem and the session history in a per-session Artifacts repo." — Artifacts launch post

What a session repo contains

  • Workspace filesystem state. Every file the agent has written / edited / created in its sandbox. Commits on every checkpoint or significant action. Recoverable even if the sandbox container was evicted and replaced.
  • Prompt history / conversation transcript. Each turn committed as a file or as a structured record; history is readable via git log.
  • Tool-call history. Each tool invocation + arguments + result can be stored as a commit or an additional file, with git-notes used for metadata (model ID, latency, judge scores) without mutating the objects themselves.

The load-bearing claim: the same data model that works for code works for agent state, because the ops an agent wants on its state are exactly the ops Git provides on code — commit, diff, log, revert, fork, merge.

What it enables

Three capabilities Cloudflare calls out explicitly from their internal use:

  1. "Persist sandbox state without having to provision (and keep) block storage around." — The session repo is persistent; the sandbox is ephemeral. Evict freely.
  2. "Share sessions with others and allow them to time-travel back through both session (prompt) state and file state, irrespective of whether there were commits to the 'actual' repository (source control)." — Time-travel works on all session state, not just tracked source files.
  3. "Fork a session from any point, allowing our team to share sessions with a co-worker and have them pick it up from them. Debugging something and want another set of eyes? Send a URL and fork it. Want to riff on an API? Have a co-worker fork it and pick up from where you left off." — A session is a Git repo, so forking a session is a Git fork.

Complementary to — not a replacement for — other agent-memory tiers

A session repo is one tier of agent memory. Cloudflare's 2026-04 stack deliberately uses different substrates for different memory shapes:

Memory shape Substrate Access pattern Canonical instance
Conversation transcript (tree-structured, forkable) DO SQLite + FTS5 Append / search / fork Project Think sessions
Semantic retrieval over docs + history AI Search instance Upload / hybrid search support-agent example
Filesystem state + versioned session history Artifacts repo Git commit / diff / fork this post

Repo-per-session is the filesystem + versioned-state tier; it composes with the others rather than subsuming them. A Cloudflare internal agent session uses all three at once.

Cost shape

Viable because Durable Objects hibernate at zero cost and Artifacts pricing is per-storage + per-operation with no hot/cold tier. 10M agent sessions × 1% active is the order-of-magnitude cost envelope: 100 k active repos and 9.9 M dormant repos, with the dormant repos paying only stored bytes. See concepts/scale-to-zero.

Open questions

  • When to commit. No established convention for when an agent harness should commit — after every file write? every tool call? every model turn? Too-frequent commits bloat the history; too-rare commits lose time-travel granularity.
  • Garbage collection policy. Session repos accumulate. Who decides when a session is "over" and collectable?
  • PII / sensitive-data handling. Session repos persist prompts and tool outputs that may contain user data; the repo is long-lived whereas a transcript might have had a shorter retention intent.
  • Interaction with the "actual" source-control repo. Cloudflare's post is careful to distinguish the session repo from any real source-control repo the agent might be working against; the boundary discipline (when to commit to session repo vs when to git push to real remote) is not fully spelled out.

Seen in

Last updated · 200 distilled / 1,178 read