> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Threads Overview

## What is a thread?

A **thread** is the persisted conversation or work history an agent can use to continue from where it left off.

In MeshAgent, a thread is addressed by a thread path and stored by the agent's configured thread storage backend. Process agents store thread history in the room dataset; the legacy MeshDocument-backed thread storage path is no longer supported. A thread is the durable state behind things like:

* an ongoing conversation with a process-backed agent
* a resumable process-backed toolkit workflow
* queue or mail work history you want to keep and revisit

The main idea is:

* **Session/context** is the in-memory state for the current run
* **Thread** is the persisted state that future runs can reload

If you want continuity across turns, runs, or agents, you usually need a thread.

## Threads vs rooms, sessions, tools, and skills

These concepts work together, but they are not the same:

* **Room**: the shared collaboration environment where people, agents, files, tools, and documents live
* **Session/context**: the current in-memory LLM conversation state for one run
* **Thread**: the persisted transcript or work log that an agent session can resume from
* **Tool**: a callable capability such as storage, shell, or web search
* **Skill**: reusable guidance that helps an agent decide how to approach a task

The key distinction is:

* **Sessions are live**
* **Threads persist**

An agent may create a fresh session every time it runs, but still choose to reload that session from an existing thread.

## What lives in a thread?

A MeshAgent thread can store more than plain chat text. A thread can contain:

* user and assistant messages
* file attachments
* tool and command output
* reasoning summaries
* UI events
* generated images and related status

That makes a thread useful as both:

* a memory source for future agent runs
* a durable audit trail of what happened

## Do all agents use threads?

Different agents use threads in different ways.

### Process-backed chat agents

For a process-backed agent with a `chat` channel, threads are the normal model. A chat conversation is typically backed by a thread path, and the agent reopens that thread to reload prior history and continue the conversation.

If a chat UI supports multiple conversations, each conversation is usually a different thread.

### Toolkit-style process calls

A toolkit-style process invocation does **not** have to use threads, but it can. If the same invocation flow reuses a thread path, the agent can continue from that persisted history later.

Use this when you want a callable agent workflow to be resumable or inspectable over time.

### Queue-backed process work

Queue-backed process work also does **not** have to use threads. A queue channel can process jobs with fresh context each time, or it can write the work into thread storage so jobs have durable history.

Use this when queued work should leave behind a readable log, or when later work should build on earlier work.

### Process-backed agents

Process-backed agents also use threads, but the boundary is still the thread path rather than the overall process.

In practice, that means:

* one `meshagent process` runtime can accept turns from chat, mail, queues, or toolkit calls
* each turn is still routed by its resolved thread path
* context is only shared when those inputs reuse the same thread path

So a process-backed agent can have one runtime and still keep unrelated work separate.

## When should I think about threads?

You should think about threads when you want:

* conversations to continue across turns or sessions
* a user or agent to reopen earlier work
* multiple runs to build on the same history
* an auditable record of tool use, outputs, or reasoning
* multiple agents to collaborate through shared persisted state

You usually do **not** need to think much about threads when:

* every run should start fresh
* the output is purely one-shot
* there is no need to reopen or inspect the history later

## Shared threads

Agents can share threads.

This is not a separate special feature or agent mode. It simply means that multiple agents or clients read from and write to the same thread path.

That is useful when:

* a conversational agent and a background agent should collaborate on the same work
* one agent creates work and another agent continues it
* you want a user-facing conversation and background processing to stay in one shared history

The important rule is:

* **same thread path = same persisted history**

If two agents use different thread paths, they have different histories even if they are working in the same Room.

## What is a thread directory?

A **thread directory** is a path prefix used to organize many thread paths together.

For example:

```text theme={null}
.threads/support-bot/
```

A thread directory typically contains:

* one thread path per conversation or work item
* one thread list path that lists the known threads

Example:

```text theme={null}
dataset://.threads/support-bot/
  2d8b6f0e-0c9a-4f50-8e1c-2d83d6a64d4f
  660ef9d1-c70c-46e6-b309-4fe2b8c73b90
  index
```

## Example: process chat channel with thread-related CLI flags

Here is a simple `meshagent process` command that enables a thread-aware chat UI and stores its thread history under a dedicated thread directory:

```bash theme={null}
meshagent process join \
  --room gettingstarted \
  --agent-name support-bot \
  --channel chat \
  --threading-mode default-new \
  --thread-dir ".threads/support-bot" \
  --storage \
  --room-rules "agents/support-bot/rules.md" \
  --rule "You are a helpful support assistant."
```

The thread-related flags here are:

* `--threading-mode default-new`: tells chat UIs to treat this agent as thread-oriented and to show a new-thread composer before loading an existing thread
* `--thread-dir ".threads/support-bot"`: tells the agent where its thread history and thread list should live

With the default dataset-backed thread storage, MeshAgent normalizes that directory into dataset-backed thread paths like:

```text theme={null}
dataset://.threads/support-bot/
  <thread>
  index
```

When you write a process-agent YAML file directly, use the explicit dataset-backed annotations that `meshagent process spec` emits:

```yaml theme={null}
annotations:
  meshagent.agent.type: ChatBot
  meshagent.chatbot.threading: default-new
  meshagent.chatbot.thread-dir: dataset://.threads/support-bot
  meshagent.chatbot.thread-list: dataset://.threads/support-bot/index
```

`meshagent.chatbot.thread-list` can be derived by MeshAgent clients when `thread-dir` is present, which is why some built-in service templates only set `meshagent.chatbot.thread-dir`. Public examples should include both values so the YAML is self-contained and matches generated process-agent specs.

This is a good default when:

* one chatbot should support many separate conversations
* you want a UI to show a thread list
* you want to keep this agent's threads separate from other agents in the same Room

If you omit `--thread-dir`, the chat-oriented process runtime will choose a default thread directory for you. If you omit thread-related settings entirely, you can still chat with the agent, but you are no longer explicitly configuring thread list behavior or thread organization.

## What is the thread list?

The thread list is the index for a thread directory.

It is not the source of truth for the thread contents. Each thread path holds the actual history. The index exists so UIs and agents can:

* list available threads
* sort them by recent activity
* show readable names
* open a thread by path

In other words:

* a thread path stores the conversation or work itself
* the thread list stores the list of known threads

## How UIs use threads

Many chat-style UIs need two things:

1. a thread list
2. a selected thread path

The thread list usually comes from the thread directory's index path, and the selected conversation comes from a specific thread path.

This is why thread directories matter most for process-backed agents with a chat channel: they let a UI show many conversations instead of only one.

## Choosing the right model

Use one of these mental models:

* **No thread**: best for isolated, one-off work
* **One thread per user/agent pair**: best for simple persistent chat
* **One thread per task or case**: best for work that evolves over time
* **One shared thread across agents**: best for collaboration on the same persisted history
* **A thread directory with many threads**: best for multi-conversation chat UIs

## Where to go next

* [Process Agents Overview](./process/overview): the main thread-aware runtime for new CLI agents
* [Key Concepts](../introduction/introduction): Rooms, agents, tools, and services