Threads

Threads organize your conversations into separate contexts. Each thread maintains its own conversation history, summaries, and settings — so a thread about work stays focused on work, while a thread about cooking stays focused on recipes.

How Threads Work

Every conversation in Iris belongs to a thread. When you send a message, it's recorded in the active thread. Summaries, context recall, and streaming all operate within that thread's boundary — nothing leaks between threads.

This isolation means you can have multiple ongoing conversations with Iris without context from one bleeding into another.

The Default Thread

When you first use Iris, a Default thread is automatically created and pinned to the top of your sidebar. This ensures you always have a thread ready to go.

If you delete your last remaining thread, Iris creates a new Default thread immediately — you'll never end up with an empty sidebar.

Creating Threads

Click the New Thread button in the sidebar to create a fresh thread. New threads start unnamed and appear in the sidebar immediately. Once you've exchanged a few messages, Iris automatically generates a name based on the conversation content.

Thread Naming

Iris auto-names threads after a few messages (default: 4) so you don't have to. The naming uses a fast, lightweight model to generate a short, descriptive title based on the conversation so far.

How auto-naming works:

1. You send messages in a new thread
2. Once the message count reaches the naming threshold, a background job queues
3. The job reads recent messages and generates a concise name
4. The name appears in the sidebar across all your connected devices

Manual renaming: You can rename any thread at any time through the sidebar context menu. Once you rename a thread manually, auto-naming won't overwrite your choice.

Pinning Threads

Pin important threads to keep them at the top of your sidebar. Pinned threads appear in a dedicated "Pinned" section above your regular threads.

To pin or unpin a thread, use the context menu (hover over the thread name in the sidebar).

Unread Indicators

When a new message arrives in a thread you're not currently viewing — like a proactive message or a completed delegated task — a small indicator appears next to the thread name. Clicking the thread marks it as read.

Deleting Threads

Delete a thread through the sidebar context menu. A confirmation dialog shows the thread name so you don't accidentally remove the wrong one.

WARNING

Deleting a thread permanently removes all its conversations and summaries. This action cannot be undone.

After deletion, Iris navigates you to your most recently active thread. If no threads remain, a new Default thread is created automatically.

Thread-Scoped Features

Threads aren't just visual organizers — they provide real isolation across Iris's core systems:

Conversation History

Each thread maintains its own message history. History is loaded token-budget-first — Iris pulls the most recent turns until the available token budget is exhausted, so each thread gets its full context allocation independent of the others.

Summarization

Summaries are generated and chained per thread. A long thread about a work project builds its own summary chain, separate from your other threads. The summarization threshold and buffer settings apply independently to each thread.

Streaming and Broadcasts

Response streams are scoped to the active thread. When Iris responds in one thread, only clients viewing that thread receive the stream events. This prevents messages from appearing in the wrong thread if you have multiple tabs open.

Pinned Skills

Each thread can have its own set of pinned skills — specialized knowledge injected into the system prompt for every message in that thread. Configure pinned skills through the thread settings modal (gear icon in the chat header).

Thread Briefs

Each thread automatically generates a brief — a 3-6 sentence digest of what the thread is about, key decisions made, and emotional context. Briefs are injected into other threads' system prompts, giving Iris cross-thread awareness without loading raw messages.

This means if you're discussing a database migration in one thread and API design in another, Iris can connect the two — suggesting that schema decisions in one affect endpoints in the other. See Thread Briefs for the full details.

Memories and Truths

Memories and truths are stored globally — your name, preferences, and relationships are available regardless of which thread you're in. Iris always knows who you are, even in a brand-new thread.

However, memory recall is thread-scoped. When Iris retrieves relevant memories, the search queries are generated from the current thread's conversation context — not from all threads combined. This means memories about cooking surface when you're discussing recipes in one thread, without being influenced by a debugging conversation in another thread. The full memory pool is always searchable; only the question "what's relevant right now?" is scoped to the thread you're in.

Thread Settings

Open the thread settings modal by clicking the gear icon in the chat header. Currently, thread settings let you manage pinned skills — skills whose full content is injected into the system prompt for every message in that thread.

Configuration

Thread behavior is configured in config/iris.php:

Setting	Default	Description
threads.naming_threshold	4	Messages before auto-naming triggers
threads.naming_provider	anthropic	Prism provider for name generation
threads.naming_model	claude-haiku-4-5	Model for generating thread names
threads.naming_timeout	15	Timeout in seconds for the naming job

Customizing Thread Naming

// config/iris-custom.php
return [
    'threads' => [
        'naming_threshold' => 6,  // Wait for more messages before naming
    ],
];

TIP

Auto-naming uses a fast, inexpensive model by default. If you want more creative names, you could swap in a larger model — but the cost-per-name goes up accordingly.