# Conversation tree

Every conversation in AI Transport is a tree of messages. The tree keeps every branch; a view is the linear path through it that a participant sees.

Every conversation in AI Transport is a tree of messages. Each message has a unique identity and a position in the tree, and the tree preserves every path through the conversation. Edits and regenerations create branches, so every earlier version stays in the tree.

![Diagram showing a branching conversation tree with two independent Views selecting different paths](https://raw.githubusercontent.com/ably/docs/main/src/images/content/diagrams/ait-concepts-conversation-tree.png)

## Understand messages 

A message is one unit of content in the conversation: a user's input, an assistant's response, a tool call, or a tool result. Each message has a unique identity and a position in the tree defined by pointers to its parent or its siblings.

A message arrives on the session either as one published message or as a sequence of operations that share one message ID. A streamed assistant response starts with one published message and builds up through a series of appends, one per chunk of model output, until a final append marks it complete. Those appends are not separate messages.

## Understand the conversation tree 

The tree holds the complete branching history of a conversation. Every message that has ever been part of the [session](https://ably.com/docs/ai-transport/durable-sessions/sessions.md) is a node in the tree, whether it is currently visible or not.

The tree is not a linear list. When you regenerate a response, the new response becomes a sibling of the old one instead of replacing it. When you edit a message, the edited version forks from the same parent as the original, and the earlier version stays in the tree as a sibling on an alternative branch. [Conversation branching](https://ably.com/docs/ai-transport/durable-sessions/branching.md) covers how to create branches and navigate between siblings.

Messages are ordered by their serial, so tree construction is deterministic. The same sequence of messages always produces the same tree, which is why two clients reading the same session agree on the shape of the conversation.

## Understand views 

A view is one linear path through the tree. It selects one sibling at each branch point and produces the flat sequence of messages a client works with: the conversation as it appears in a chat UI, or the message history an agent sends to a model.

When a conversation has been regenerated three times at one point, the tree holds all three responses as siblings. The view selects one and presents the conversation as though that response is the only one, while still allowing navigation to the others.

Each view handles three jobs on top of that selection:

- Branch selection. Each client holds its own selections, so two clients looking at the same session view different branches.
- Pagination. Older messages are withheld and loaded on demand. The view tracks the boundary between visible and withheld messages and exposes `loadOlder` to widen the window.
- Scoped events. The view emits update and lifecycle events only for the branch it is showing, so your UI subscribed to a view re-renders only when something it displays changes.

You also write through the view. Sending a message, regenerating a response, and editing a message are all operations on a view, and the view uses its current position in the tree to set the correct parent and fork pointers on whatever it publishes.

## Work with the tree and views 

On the client, the session exposes a default view as a property. Iterate the visible messages on the selected branch through `getMessages()`, where each entry pairs the domain message with its codec message id:

<Code>

### Javascript

```
// Client: read the visible messages on the selected branch.
const view = session.view;

for (const { codecMessageId, message } of view.getMessages()) {
  const text = message.parts
    .filter((p) => p.type === 'text')
    .map((p) => p.text)
    .join('');
  console.log(codecMessageId, message.role, text);
}
```
</Code>

Create additional views over the same tree with `session.createView()`.

## Read next 

- [Sessions](https://ably.com/docs/ai-transport/durable-sessions/sessions.md): the persistent, shared conversation state the tree belongs to.
- [Runs](https://ably.com/docs/ai-transport/streaming/runs-and-steps.md): how agent work is structured within the session.
- [Conversation branching](https://ably.com/docs/ai-transport/durable-sessions/branching.md): create branches with edit and regenerate, and navigate between them.
- [Optimistic updates](https://ably.com/docs/ai-transport/durable-sessions/optimistic-updates.md): insert messages locally and reconcile them with the published tree.
- [Conversation tree internals](https://ably.com/docs/ai-transport/internals/conversation-tree.md): sibling resolution, regenerate groups, and the header pointers that build the tree.

## Related Topics

- [Overview](https://ably.com/docs/ai-transport/durable-sessions.md): A drop-in durable session layer for AI applications. AI Transport holds the conversation and the message state your UI renders, including branching, and you render from its React hooks.
- [Sessions](https://ably.com/docs/ai-transport/durable-sessions/sessions.md): Understand sessions in AI Transport: persistent, shared conversation state that exists independently of any connection, and the ClientSession and AgentSession objects that attach to it.
- [Optimistic updates](https://ably.com/docs/ai-transport/durable-sessions/optimistic-updates.md): User messages appear instantly in Ably AI Transport. Optimistic insertion with automatic reconciliation when the server confirms.
- [Branching, edit, and regenerate](https://ably.com/docs/ai-transport/durable-sessions/branching.md): Edit user messages, regenerate AI responses, and navigate branches with Ably AI Transport. The full history is preserved in the conversation tree.
- [Tool calling](https://ably.com/docs/ai-transport/durable-sessions/tool-calling.md): Stream tool invocations and results through Ably AI Transport. Server-executed and client-executed tools with persistent state.
- [Human-in-the-loop](https://ably.com/docs/ai-transport/durable-sessions/human-in-the-loop.md): Add human approval gates to AI agent workflows with Ably AI Transport. Approve tool executions and provide input across devices.
- [Database hydration](https://ably.com/docs/ai-transport/durable-sessions/database-hydration.md): Hydrate an AI conversation from your own database with AI Transport and reconcile it with the live Ably channel, with no gaps and no duplicate messages.
- [Migrate from Streaming](https://ably.com/docs/ai-transport/durable-sessions/move-up-from-streaming.md): What changes in an application already streaming with Ably AI Transport when it moves the conversation into a durable session, and what stays exactly as it is.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.