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

# Threads

> Manage conversation history and context

Threads in Marvin provide a powerful mechanism for managing conversation history and context across your AI workflows. Unlike ControlFlow's flows, threads in Marvin are focused on conversation management and persistence rather than workflow orchestration.

## Understanding Threads

A thread in Marvin represents a conversation context that can span multiple interactions. Each thread:

* Maintains its own conversation history
* Can be persisted to a database
* Can be referenced across different parts of your application
* Supports attaching memories for long-term information storage

## Creating and Using Threads

### Basic Thread Creation

The simplest way to create a thread is to instantiate the `Thread` class:

```python theme={null}
import marvin

thread = marvin.Thread()
# A new thread is created with a unique ID
```

### Specifying a Thread ID

You can create a thread with a specific ID, which is useful for resuming conversations:

```python theme={null}
thread = marvin.Thread(id="user_123_lesson")
# This thread will use the specified ID
```

### Using Threads with Tasks

Threads can be passed to tasks to maintain conversation context:

```python theme={null}
import marvin

thread = marvin.Thread()

task = marvin.Task(
    instructions="Write a poem about AI",
    result_type=str
)

# Run the task with the thread
result = task.run(thread=thread)
```

### Adding Messages

You can manually add messages to a thread:

```python theme={null}
# Add a user message
thread.add_user_message("Hello!")

# Add multiple messages
from marvin.engine.llm import UserMessage, AssistantMessage
thread.add_messages([
    UserMessage(content="What's the weather?"),
    AssistantMessage(content="It's sunny today!")
])
```

## Retrieving History

### Getting Messages

You can retrieve messages from a thread with various filters:

```python theme={null}
# Get all messages
messages = thread.get_messages()

# Get messages with filters
messages = thread.get_messages(
    include_system_messages=False,  # Exclude system messages
    before=datetime.now(),          # Messages before a timestamp
    after=some_timestamp,           # Messages after a timestamp
    limit=10                        # Limit number of messages
)
```

### Tracking LLM Usage

Threads also track LLM API usage:

```python theme={null}
# Get all LLM calls
llm_calls = thread.get_llm_calls()

# Get usage statistics
usage = thread.get_usage()
```

## Thread Context Management

Marvin provides context management for threads, making it easy to set the current thread:

```python theme={null}
with thread:
    # This thread is now the current thread
    task1.run()  # Uses the thread automatically
    task2.run()  # Same thread is used

# Thread context is restored after the block
```

You can also get the current thread:

```python theme={null}
current_thread = marvin.get_current_thread()
```

## Parent-Child Relationships

Threads can have parent-child relationships:

```python theme={null}
parent_thread = marvin.Thread()
child_thread = marvin.Thread(parent_id=parent_thread.id)
```

## Database Integration

Threads are automatically persisted to a database when configured:

```python theme={null}
# Messages and LLM calls are automatically saved
thread.add_user_message("Save this message")

# Later, create a thread with the same ID to access history
same_thread = marvin.Thread(id=thread.id)
messages = same_thread.get_messages()  # Includes saved messages
```

## Threads and Memory

While threads provide short-term conversation context within a session, [Memory](/concepts/memory) offers long-term persistence across multiple sessions. The two can work together:

```python theme={null}
import marvin
from marvin import Thread, Memory, Agent

# Create a memory for storing user preferences
user_preferences = Memory(key="user_preferences")

# Create an agent with this memory
assistant = Agent(
    name="Personal Assistant",
    instructions="You are a helpful assistant",
    memories=[user_preferences]
)

# Use the agent in a thread
with Thread() as thread:
    # The agent can access both thread context (recent conversation)
    # and memory (long-term stored information)
    assistant.run("Remember that I prefer dark mode")
    assistant.run("What are my UI preferences?")  # Will recall from memory
```

Threads maintain the flow of conversation, while Memory stores specific information that should persist across different threads and sessions. See the [Memory](/concepts/memory) documentation for more details on working with persistent memory.