Multi-user threads
A single Mastra thread can be shared by several users. Send each user's message with sendMessage() and put the speaker in the message's attributes. Mastra renders the message as a <user> tag carrying those attributes, so the agent can tell the participants apart, now and when the message is loaded from history later.
When to use multi-user threadsDirect link to When to use multi-user threads
Use multi-user threads when several people work on the same subject through one agent:
- Collaborative documents with editors, reviewers and approvers
- Group chats where one assistant serves many participants
- Reviews where different roles have different authority
Share one resourceId across all participantsDirect link to share-one-resourceid-across-all-participants
A thread belongs to exactly one resourceId, so everyone on a shared thread needs to pass the same value. Instead of a user ID (the default for single-user apps), key resourceId on the conversation itself, for example doc_${docId} for a shared document or room_${roomId} for a group chat. With everyone pointing at the same resourceId and threadId, they read and write the same history.
Send each message with the speaker's identityDirect link to Send each message with the speaker's identity
Pass the message as an object with contents and attributes. Each attribute becomes an XML attribute on the <user> tag the model reads:
agent.sendMessage(
{
contents: 'Please make the cover page teal.',
attributes: { name: 'Alice', role: 'editor' },
},
{ resourceId: 'doc_42', threadId: 'doc_42' },
)
The model receives:
<user name="Alice" role="editor">Please make the cover page teal.</user>
Mastra escapes attribute values for you. Attribute names must be valid XML names, such as name, role or user_id. Any other name fails with Invalid signal XML attribute name when the message is rendered for the model. The attributes are stored with the message, so when history loads on a later turn, the model still sees who said what.
Tell the agent how to read the tagDirect link to Tell the agent how to read the tag
Describe the <user> tag and its attributes in the agent's instructions. The agent needs memory so its messages are stored on the thread:
import { Agent } from '@mastra/core/agent'
import { LibSQLStore } from '@mastra/libsql'
import { Memory } from '@mastra/memory'
const memory = new Memory({
storage: new LibSQLStore({ id: 'collab-storage', url: 'file:./collab.db' }),
options: {
lastMessages: 20,
},
})
export const collabAgent = new Agent({
id: 'collab',
name: 'CollabAgent',
model: 'openai/gpt-6-luna',
memory,
instructions: `
You are a collaborative document assistant. Several people talk to you in the same thread.
Each user message arrives in a <user> tag whose attributes say who sent it:
<user name="Alice" role="editor">...message text...</user>
Address people by name. Editors propose changes and reviewers approve them.
When you refer to something said earlier, name the person who said it.
`.trim(),
})
Send every participant's message to the same thread. When the thread is idle, sendMessage() starts a run and accepted resolves with its output:
import { collabAgent } from './agents/collab'
const doc = { resourceId: 'doc_42', threadId: 'doc_42' }
async function send(speaker: { name: string; role: string }, text: string) {
const { accepted } = collabAgent.sendMessage({ contents: text, attributes: speaker }, doc)
const result = await accepted
if (result.action === 'wake') {
return (await result.output.getFullOutput()).text
}
}
await send({ name: 'Alice', role: 'editor' }, 'Please make the cover page teal.')
await send({ name: 'Bob', role: 'reviewer' }, 'I want QA sign-off before we publish.')
await send({ name: 'Alice', role: 'editor' }, 'Who asked for QA sign-off?')
// The agent answers that Bob asked for it.
When a message arrives while the agent is still answering someone else, Mastra delivers it into the running turn instead of starting a new one, and accepted resolves with action: 'deliver'. In a live app, render replies from the thread stream rather than from each sendMessage() call. That way every participant sees the same conversation.
Combining with memory layersDirect link to Combining with memory layers
Pick the memory layer by how long the conversation needs to remember each participant:
- Short conversations, or when you need a verbatim record of who said what: use message history alone.
- Long-running threads that outgrow the context window: use Observational Memory.
Message history aloneDirect link to Message history alone
lastMessages brings earlier messages back into context with their <user> attributes, so attribution survives across turns. The agent example above uses this setup.
With observational MemoryDirect link to With observational Memory
Observational Memory (OM) keeps a long shared thread inside the context window by replacing older messages with observations. Enable it on the same Memory:
import { LibSQLStore } from '@mastra/libsql'
import { Memory } from '@mastra/memory'
const memory = new Memory({
storage: new LibSQLStore({ id: 'collab-storage', url: 'file:./collab.db' }),
options: {
observationalMemory: true,
},
})
OM replaces lastMessages history loading, so leave lastMessages out when OM is on.
The Observer keeps the speaker's attributes, so observations say who said what. A message sent with attributes: { name: 'Alice', role: 'editor' } is labeled User (name="Alice" role="editor"). Messages sent without attributes are labeled plain User.
SecurityDirect link to Security
Set the attributes on your server from the authenticated user, never from the request body. If a client can choose its own name, one user can impersonate another. Use request context to read the verified user from your auth layer and build the attributes before calling sendMessage().