|
| 1 | +--- |
| 2 | +title: 'Fork — branching for Durable Streams' |
| 3 | +description: >- |
| 4 | + Fork is branching for Durable Streams. Branch any stream at any point with a single API call. Rewind history, fan out agents in parallel, or probe without polluting context. Live on Electric Cloud. |
| 5 | +excerpt: >- |
| 6 | + Fork adds branching to Durable Streams. Branch any stream at any point — rewind history, fan out agents, or probe without polluting context. |
| 7 | +authors: [balegas, samwillis] |
| 8 | +image: /img/blog/fork-branching-for-durable-streams/header.jpg |
| 9 | +tags: [release, durable-streams, cloud, agentic, AI] |
| 10 | +outline: [2, 3] |
| 11 | +post: true |
| 12 | +published: true |
| 13 | +--- |
| 14 | + |
| 15 | +[Durable Streams](/primitives/durable-streams) is the [data primitive for the agent loop](/blog/2026/04/08/data-primitive-agent-loop). Today we're shipping fork — a single API call that branches a stream at any point. Rewind history, fan out agents in parallel, or probe an agent without polluting its context. |
| 16 | + |
| 17 | +A fork creates a new stream from any point in an existing one. It shares everything before the fork point with its source and evolves independently after it. One API call, two headers. |
| 18 | + |
| 19 | +## Streams are sessions |
| 20 | + |
| 21 | +Agent infrastructure is converging on a pattern: the session — the complete log of messages, tool calls, and decisions — lives in a durable stream that lives outside the agent itself. Anthropic's recent post on [Managed Agents](https://www.anthropic.com/engineering/managed-agents) describes exactly this architecture: an append-only session log that the harness writes to, reads from, and resumes after a crash. Durable Streams provide exactly this primitive. |
| 22 | + |
| 23 | +A session log is linear but agent workflows aren't. An agent goes down a path that isn't working and you want to rewind a few turns. Multiple agents need to fan out from the same starting point. You want to ask an agent a question without putting it in its history. These all require the same operation that a linear log doesn't have: the ability to take the session at any point and diverge. |
| 24 | + |
| 25 | +## Fork: branching for streams |
| 26 | + |
| 27 | +A [Durable Stream](/primitives/durable-streams) assigns an offset to each message as it's appended. When you fork a stream, you specify a source stream and a fork offset. The system creates a new stream that inherits all messages from the source up to that offset. After the fork point, the new stream lives independently — its own URL, its own appends, its own subscribers. |
| 28 | + |
| 29 | +Forks don't copy data. They use copy-on-write (COW): the shared history between a fork and its source is genuinely shared at the storage level, and only new writes diverge. This means forking is instant regardless of stream length — a stream with ten thousand messages forks just as quickly as one with three. |
| 30 | + |
| 31 | +Because forks are themselves regular Durable Streams, they can be forked. This gives you trees of arbitrary depth where every node is an addressable stream with the full set of stream operations available. |
| 32 | + |
| 33 | +### The API |
| 34 | + |
| 35 | +Create a conversation stream and append some messages: |
| 36 | + |
| 37 | +```http |
| 38 | +PUT /v1/stream/{service}/chat-123 |
| 39 | +``` |
| 40 | + |
| 41 | +```http |
| 42 | +POST /v1/stream/{service}/chat-123 |
| 43 | +Content-Type: application/json |
| 44 | +
|
| 45 | +{"role": "user", "content": "How do I deploy to prod?"} |
| 46 | +``` |
| 47 | + |
| 48 | +```http |
| 49 | +POST /v1/stream/{service}/chat-123 |
| 50 | +Content-Type: application/json |
| 51 | +
|
| 52 | +{"role": "assistant", "content": "Two main options: containerized with Fly or Railway, or a VM setup on EC2. The tradeoffs are..."} |
| 53 | +``` |
| 54 | + |
| 55 | +Fork from offset `002f_0cf0` — right after the assistant's first response: |
| 56 | + |
| 57 | +```http |
| 58 | +PUT /v1/stream/{service}/chat-123-containers |
| 59 | +Stream-Forked-From: /v1/stream/{service}/chat-123 |
| 60 | +Stream-Fork-Offset: 002f_0cf0 |
| 61 | +``` |
| 62 | + |
| 63 | +`chat-123-containers` now exists with the first two messages as shared history. Anything appended from here is independent. Fork again from the same offset for a second branch: |
| 64 | + |
| 65 | +```http |
| 66 | +PUT /v1/stream/{service}/chat-123-vms |
| 67 | +Stream-Forked-From: /v1/stream/{service}/chat-123 |
| 68 | +Stream-Fork-Offset: 002f_0cf0 |
| 69 | +``` |
| 70 | + |
| 71 | +Clients reading any branch see a single continuous sequence — the shared prefix followed by branch-specific messages — without any special handling. |
| 72 | + |
| 73 | +### Properties |
| 74 | + |
| 75 | +- **Instant** — metadata operation, not a data copy. Cost doesn't scale with stream length. |
| 76 | +- **Independent** — no lifecycle coupling between source and forks. Delete or append to one without affecting the other. |
| 77 | +- **Transparent** — readers see one continuous sequence. The fork boundary is invisible unless you inspect stream metadata. |
| 78 | +- **Composable** — fork a fork for trees of any depth. |
| 79 | +- **Plain HTTP** — same protocol, same SSE, same offset-based reads. Two new headers on the PUT. |
| 80 | + |
| 81 | +## What fork enables |
| 82 | + |
| 83 | +### Conversation trees |
| 84 | + |
| 85 | +ChatGPT shipped branch conversations as a user-facing feature. LangGraph added checkpoint-based forking to their agent framework. The pattern keeps showing up because agent conversations aren't linear — users want to go back, try a different direction, compare alternatives. |
| 86 | + |
| 87 | +With Durable Streams, a conversation tree is a set of streams related by forks. The root is the original conversation. Each branch point is a fork. Every node is a regular stream with the full set of stream operations — reads, writes, real-time subscriptions. Branching lives at the data layer, not inside a specific framework's checkpoint system, so any client that can read a Durable Stream can work with forked streams without modification. |
| 88 | + |
| 89 | +We built a demo that shows this: a chat application where users can fork any point in a conversation and explore a different direction. [Try the fork demo](https://fork-ai-chat.examples.electric-sql.com). |
| 90 | + |
| 91 | +<div class="embed-container" style="padding-bottom: 84.4%"> |
| 92 | + <YoutubeEmbed video-id="gmkqygh9ezo" /> |
| 93 | +</div> |
| 94 | + |
| 95 | +### Parallel paths |
| 96 | + |
| 97 | +Conversation trees branch sequentially — a user or agent tries one direction, then goes back and tries another. Parallel paths are different: multiple agents fork from the same point and run simultaneously. |
| 98 | + |
| 99 | +Fork the session once per agent. Each gets its own branch while the shared history exists once at the storage level. A fleet of agents can fan out from the same session to tackle a problem from different angles. A lead agent can fork when the current approach isn't working and hand the branch to a specialist. Each branch is fully isolated, but the common context is shared. Compare the results and pick the best path. |
| 100 | + |
| 101 | +<figure> |
| 102 | + <img src="/img/blog/fork-branching-for-durable-streams/fork-parallel-paths-diagram.svg" alt="Parallel paths: a shared session forks into three agents, each pursuing a different strategy independently" /> |
| 103 | +</figure> |
| 104 | + |
| 105 | +### Scratch contexts |
| 106 | + |
| 107 | +Sometimes you need to interrogate an agent without changing its state. A developer debugging a misbehaving agent wants to ask "what do you think the user wants?" without that meta-question influencing the next real turn. A harness wants to test whether the agent can answer a factual question before committing to a tool call. |
| 108 | + |
| 109 | +Fork the session, run the side conversation in the fork, read the result. The main session is untouched — no phantom turns in the history, no context pollution. If the answer is useful, the harness can bring it forward explicitly. If not, the fork is just abandoned. |
| 110 | + |
| 111 | + |
| 112 | +## Getting started |
| 113 | + |
| 114 | +Fork is available now on all Durable Streams services on [Electric Cloud](/cloud). Sign up, create a stream service, and start using it. |
| 115 | + |
| 116 | +The [protocol spec](https://github.com/durable-streams/durable-streams) covers the full fork semantics — offset behavior across forks, concurrent readers, deletion propagation. The [API docs](/docs/intro) have the reference for all stream operations including fork. |
| 117 | + |
| 118 | +*** |
| 119 | + |
| 120 | +- [Sign up for Electric Cloud](/cloud) |
| 121 | +- [Try the fork demo](https://fork-ai-chat.examples.electric-sql.com) |
| 122 | +- [Read the docs](/docs/intro) |
| 123 | +- [Join the Discord](https://discord.electric-sql.com) |
| 124 | + |
| 125 | +<div class="actions cta-actions page-footer-actions left"> |
| 126 | + <div class="action cloud-cta"> |
| 127 | + <VPButton |
| 128 | + href="https://dashboard.electric-sql.cloud/?intent=create&serviceType=streams" |
| 129 | + text="Sign up" |
| 130 | + theme="brand" |
| 131 | + /> |
| 132 | + |
| 133 | + <VPButton |
| 134 | + href="/docs/intro" |
| 135 | + text="Docs" |
| 136 | + theme="alt" |
| 137 | + /> |
| 138 | + |
| 139 | + <VPButton |
| 140 | + href="https://discord.electric-sql.com" |
| 141 | + text="Discord" |
| 142 | + theme="alt" |
| 143 | + /> |
| 144 | + </div> |
| 145 | +</div> |
0 commit comments