@mastra/memory 1.18.3-alpha.0 → 1.19.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.18.3-alpha.0"
+  version: "1.19.0"
 ---
 
 ## When to use
@@ -20,8 +20,10 @@ Read the individual reference documents for detailed explanations and code examp
 - [Background tasks](references/docs-agents-background-tasks.md) - Learn how to dispatch long-running tool calls in the background, keep the stream open until they complete, and orchestrate subagents asynchronously.
 - [Agent networks](references/docs-agents-networks.md) - Coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
 - [Supervisor agents](references/docs-agents-supervisor-agents.md) - Learn how to coordinate multiple agents with delegation hooks, iteration monitoring, message filtering, and task completion scoring.
+- [Evals with memory](references/docs-evals-evals-with-memory.md) - Run scorers against memory-enabled agents — including observational memory in thread scope — using runEvals and dataset experiments.
 - [Memory processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
 - [Message history](references/docs-memory-message-history.md) - Learn how to configure message history in Mastra to store recent messages from the current conversation.
+- [Multi-user threads](references/docs-memory-multi-user-threads.md) - Share one Mastra thread between multiple users by carrying speaker identity in the message body.
 - [Observational Memory](references/docs-memory-observational-memory.md) - Learn how Observational Memory keeps your agent's context window small while preserving long-term memory across conversations.
 - [Memory overview](references/docs-memory-overview.md) - Learn how Mastra's memory system works with working memory, message history, semantic recall, and observational memory.
 - [Semantic recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,120 +1,120 @@
 {
-  "version": "1.18.3-alpha.0",
+  "version": "1.19.0",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 745
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 786
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js"
+      "implementation": "dist/chunk-NZXH5WER.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 6922
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 7009
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 9496
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 9589
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 6371
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 6455
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 3682
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 3760
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 2990
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 3031
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 837
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 878
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 871
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 912
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 3796
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 3874
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 3408
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 3486
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 9708
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 9801
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 3784
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 3862
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 2538
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 2579
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 3807
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 3885
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 2511
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 2552
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 806
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 847
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 3692
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 3770
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 895
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 936
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 851
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 892
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 2568
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 2609
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 828
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 869
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-KLETR4RS.js",
-      "line": 799
+      "implementation": "dist/chunk-NZXH5WER.js",
+      "line": 840
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
@@ -149,7 +149,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-KLETR4RS.js",
+        "chunk-NZXH5WER.js",
         "chunk-LSJJAJAF.js"
       ]
     }

package/dist/docs/references/docs-agents-agent-approval.md

@@ -92,6 +92,8 @@ A tool can also pause _during_ its `execute` function by calling `suspend()`. Th
 
 The stream emits a `tool-call-suspended` chunk with a custom payload defined by the tool's `suspendSchema`. You resume by calling `resumeStream()` with data matching the tool's `resumeSchema`.
 
+> **Note:** `suspend()` does not throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
+
 ## Tool approval with `generate()`
 
 Tool approval also works with `generate()` for non-streaming use cases. When a tool requires approval, `generate()` returns immediately with `finishReason: 'suspended'`, a `suspendPayload` containing the tool call details (`toolCallId`, `toolName`, `args`), and a `runId`:

package/dist/docs/references/docs-agents-background-tasks.md

@@ -40,11 +40,12 @@ The full set of options is listed in the [backgroundTasks configuration referenc
 
 ## Run a tool in the background
 
-Enabling the manager doesn't run anything in the background by itself as every tool defaults to foreground execution. You can run a tool in the background at one of three layers, in priority order:
+Enabling the manager doesn't run anything in the background by itself as every tool defaults to foreground execution. Tools opt in at one of two layers:
 
-1. **LLM per-call override**: the model decides it should run in the background and includes a `_background` field in the tool arguments.
+1. **Tool-level config**: the tool itself declares it as background-eligible.
 2. **Agent-level config**: the agent declares which of its tools are background-eligible.
-3. **Tool-level config**: the tool itself declares it as background-eligible.
+
+Once a tool has opted in, the LLM can optionally include a `_background` field in the tool arguments to override the resolved config for a specific call (timeout, retries, or to flip the call back to foreground).
 
 ### Tool-level
 
@@ -103,13 +104,15 @@ When a tool is registered on an agent that has background tasks enabled, the mod
 }
 ```
 
+The `_background` override is a _modifier_ on tools the developer has already opted in at the tool or agent layer — it is not a standalone opt-in. If a tool hasn't been opted in, `_background.enabled: true` from the model is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
+
 ### Resolution order
 
 When a tool call is dispatched, the resolved background config is computed in this priority order:
 
-1. LLM `_background` override (if present in the call's arguments).
-2. Agent-level `backgroundTasks.tools` entry for the tool.
-3. Tool-level `backgroundTasks` config.
+1. Agent-level `backgroundTasks.tools` entry for the tool.
+2. Tool-level `backgroundTasks` config.
+3. LLM `_background.enabled` override (only used to enable background dispatch when the tool was opted in at one of the layers above).
 4. Manager defaults (`defaultTimeoutMs`, `defaultRetries`).
 
 If the agent has `backgroundTasks.disabled: true`, every tool call runs synchronously regardless of the layers above.

package/dist/docs/references/docs-evals-evals-with-memory.md

@@ -0,0 +1,146 @@
+# Evals with memory
+
+Agents that use memory in `thread` scope — including observational memory — require a thread ID at run time. When an eval invokes the agent without one, you'll see:
+
+```text
+ObservationalMemory (scope: 'thread') requires a threadId, but none was found in RequestContext or MessageList.
+```
+
+This page covers the three working patterns for running Mastra evals against memory-enabled agents, what each path supports, and which one to pick. A complete runnable repro for all three approaches lives in [`examples/evals-with-memory`](https://github.com/mastra-ai/mastra/tree/main/examples/evals-with-memory).
+
+## When to use which approach
+
+| Goal                                            | Approach                                                                                  |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| One shared conversation across every item       | [`runEvals` with global `targetOptions.memory`](#shared-thread-with-runevals)             |
+| One independent thread per item, simple CI loop | [`runEvals` per item](#per-item-threads-with-runevals)                                    |
+| Per-item threads driven by a stored `Dataset`   | [`dataset.startExperiment` with an inline task](#dataset-experiments-with-an-inline-task) |
+
+Pre-seeding `RequestContext` with `MastraMemory` is **not** a supported way to drive memory into an agent. Thread resolution reads `args.memory.thread` — `RequestContext.MastraMemory` is populated by `prepare-memory-step` after the agent has already resolved its thread.
+
+## Shared thread with `runEvals`
+
+`runEvals` accepts `targetOptions`, which is forwarded to `agent.generate()`. Passing `memory: { thread, resource }` runs every data item against the same thread — useful for testing recall across a multi-turn conversation.
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { supportAgent } from './support-agent'
+import { recallScorer } from '../scorers/recall-scorer'
+
+const memory = await supportAgent.getMemory()
+await memory!.createThread({ threadId: 'eval-thread', resourceId: 'ci-user' })
+
+const result = await runEvals({
+  target: supportAgent,
+  scorers: [recallScorer],
+  targetOptions: {
+    memory: { thread: 'eval-thread', resource: 'ci-user' },
+  },
+  data: [
+    { input: 'My order number is 12345' },
+    { input: 'What is my order number?', groundTruth: '12345' },
+  ],
+})
+```
+
+`targetOptions` is **global per call**. There is no per-item override on `RunEvalsDataItem` today.
+
+## Per-item threads with `runEvals`
+
+When each data item needs its own thread (the common CI shape), call `runEvals` once per item with a unique `targetOptions.memory` and aggregate the scores yourself.
+
+```typescript
+import { randomUUID } from 'node:crypto'
+import { runEvals } from '@mastra/core/evals'
+import { supportAgent } from './support-agent'
+import { recallScorer } from '../scorers/recall-scorer'
+
+const memory = await supportAgent.getMemory()
+const resourceId = 'ci-user'
+
+const items = [
+  { input: 'Cats are mammals', groundTruth: 'mammals' },
+  { input: 'Dogs are mammals too', groundTruth: 'mammals' },
+]
+
+// `runEvals` returns `{ scores: Record<string, number>; summary: { totalItems } }`.
+const scores: number[] = []
+for (const item of items) {
+  const threadId = `eval-${randomUUID()}`
+  await memory!.createThread({ threadId, resourceId, title: item.input })
+
+  const result = await runEvals({
+    target: supportAgent,
+    scorers: [recallScorer],
+    targetOptions: { memory: { thread: threadId, resource: resourceId } },
+    data: [item],
+  })
+
+  scores.push(result.scores[recallScorer.id])
+}
+
+const average = scores.reduce((a, b) => a + b, 0) / scores.length
+```
+
+> **Note:** Create the thread before running the eval. Observational memory in `thread` scope reads from a record that must already exist.
+
+## Dataset experiments with an inline task
+
+`dataset.startExperiment({ target: agent })` does **not** forward a `memory` option to the agent — only `requestContext`. To run a stored dataset against a memory-enabled agent, use an inline `task` function and stash `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
+
+```typescript
+import { randomUUID } from 'node:crypto'
+import { mastra } from '../index'
+import { supportAgent } from '../agents/support-agent'
+import { recallScorer } from '../scorers/recall-scorer'
+
+const memory = await supportAgent.getMemory()
+const resourceId = 'ci-user'
+
+const items = [
+  { input: 'Cats are mammals', groundTruth: 'mammals', thread: `ds-${randomUUID()}` },
+  { input: 'Dogs are mammals too', groundTruth: 'mammals', thread: `ds-${randomUUID()}` },
+]
+
+for (const it of items) {
+  await memory!.createThread({ threadId: it.thread, resourceId, title: it.input })
+}
+
+const dataset = await mastra.datasets.create({
+  name: 'support-recall',
+  description: 'Per-item memory via inline task + item metadata',
+})
+
+await dataset.addItems({
+  items: items.map(it => ({
+    input: it.input,
+    groundTruth: it.groundTruth,
+    metadata: { threadId: it.thread, resourceId },
+  })),
+})
+
+const summary = await dataset.startExperiment({
+  scorers: [recallScorer],
+  task: async ({ input, metadata }) => {
+    const { threadId, resourceId: rid } = (metadata ?? {}) as {
+      threadId: string
+      resourceId: string
+    }
+    const result = await supportAgent.generate(input as string, {
+      memory: { thread: threadId, resource: rid },
+    })
+    return result.text
+  },
+})
+```
+
+The inline `task` receives the item's `metadata`, so each row can drive its own thread without changing the agent or any scorer.
+
+> **Note:** Visit [runEvals reference](https://mastra.ai/reference/evals/run-evals) and [Dataset reference](https://mastra.ai/reference/datasets/dataset) for full configuration.
+
+## Related
+
+- [Running scorers in CI](https://mastra.ai/docs/evals/running-in-ci)
+- [Running experiments](https://mastra.ai/docs/evals/datasets/running-experiments)
+- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
+- [runEvals API reference](https://mastra.ai/reference/evals/run-evals)

package/dist/docs/references/docs-memory-multi-user-threads.md

@@ -0,0 +1,206 @@
+# Multi-user threads
+
+A single Mastra thread can be shared by multiple users, each with their own name and functional role. You carry speaker identity in the message body so the agent can tell users apart while reading from a single shared thread.
+
+## When to use multi-user threads
+
+Use multi-user threads when several people collaborate on the same subject through one agent:
+
+- Collaborative documents with editors, reviewers, and approvers
+- Group chats where one assistant serves many participants
+- Multi-stakeholder reviews where different roles have different authority
+
+## Share one `resourceId` across all participants
+
+A thread belongs to exactly one `resourceId`, so all participants on a shared thread need to pass the same value. Instead of using 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`, they read and write the same history.
+
+## Tag each user message with the speaker's identity
+
+The model needs to know who's talking on every turn. Since the message body is the one place that survives into history and back into context, wrap each user message in a small `<turn>` tag with the speaker's id, name, and role. The tag stays attached to the message, so when prior turns are recalled the model still sees who said what.
+
+Build the tag with a small helper. The example below is one way to do it — copy it into your project and adapt it to your shape of user data:
+
+```typescript
+export type Speaker = {
+  id: string
+  name: string
+  role: string
+}
+
+function escapeAttr(value: string) {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+export function asUserTurn(speaker: Speaker, text: string) {
+  const id = escapeAttr(speaker.id)
+  const name = escapeAttr(speaker.name)
+  const role = escapeAttr(speaker.role)
+  return {
+    role: 'user' as const,
+    content: `<turn author_id="${id}" author_name="${name}" functional_role="${role}">
+${text}
+</turn>`,
+  }
+}
+```
+
+Teach the agent how to read the `<turn>` tag in its instructions. The agent must have `memory` configured so it can be called with a `thread` and `resource`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  options: {
+    lastMessages: 20,
+  },
+})
+
+export const collabAgent = new Agent({
+  id: 'collab',
+  name: 'CollabAgent',
+  model: 'openai/gpt-5.4-mini',
+  memory,
+  instructions: `
+You are a collaborative document assistant. Multiple users talk to you in the SAME thread.
+
+Every user message is wrapped in a <turn> tag carrying the user's identity:
+
+  <turn author_id="u_alice" author_name="Alice" functional_role="editor">
+  ...message text...
+  </turn>
+
+Rules:
+1. Address users by their author_name.
+2. Respect functional_role: editors propose changes, reviewers approve.
+3. When attributing past statements, read author_name from the surrounding <turn> tag.
+4. Do not echo the <turn> tags back at users.
+  `.trim(),
+})
+```
+
+Call the agent with the wrapped message. Every participant shares the same `thread` and `resource`:
+
+```typescript
+import { asUserTurn } from './identity'
+
+const docResourceId = 'doc_42'
+const docThreadId = 'doc_42'
+
+const alice = { id: 'u_alice', name: 'Alice', role: 'editor' }
+const bob = { id: 'u_bob', name: 'Bob', role: 'reviewer' }
+
+await collabAgent.generate([asUserTurn(alice, 'My favorite color is teal.')], {
+  memory: { thread: docThreadId, resource: docResourceId },
+})
+
+await collabAgent.generate([asUserTurn(bob, 'I want QA sign-off before publish.')], {
+  memory: { thread: docThreadId, resource: docResourceId },
+})
+```
+
+The `<turn>` tag persists in the message body, so when history is recalled on later turns the model still sees who said what.
+
+## Combining with memory layers
+
+The user-tagging pattern composes with every memory layer. Pick the layer based on how long the conversation needs to remember per-user facts:
+
+- **Short conversations** (a single session, or a thread small enough to fit in `lastMessages`), or when you need a verbatim record of who said what: use [message history alone](#message-history-alone). The user tags in history are enough; no extra memory layer needed.
+- **Long-running threads** (conversations that outgrow `lastMessages`, where you need per-user facts to survive history eviction): use [observational memory](#with-observational-memory-recommended).
+- **Need a structured participants list, or your storage adapter doesn't support OM** (OM requires LibSQL, PG, or MongoDB): use [working memory](#with-working-memory).
+
+We recommend using observational memory or working memory, not both — they cover overlapping needs, and running both at once adds latency and token cost without much benefit.
+
+### Message history alone
+
+For short conversations, or when you need a verbatim record of who said what, the user tags in history are enough. `lastMessages` brings prior turns back into context with their attribution intact:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  options: {
+    lastMessages: 20,
+  },
+})
+```
+
+The model reads identity from the `<turn>` tag on the current message and from prior tagged messages brought back through `lastMessages`.
+
+### With observational memory (recommended)
+
+[Observational Memory](https://mastra.ai/docs/memory/observational-memory) (OM) extracts per-user facts into a background log without burning the agent's tool budget. The default Observer model reads `<turn>` tags natively and produces named attribution like `Alice stated her favorite color is teal.` and `Bob asked for QA sign-off before publish.`
+
+Prefer OM over working memory for multi-user threads when your storage supports it. OM extracts facts automatically, scales to any number of participants, and doesn't need template upkeep. Enable it with no overrides:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  options: {
+    lastMessages: 20,
+    observationalMemory: true,
+  },
+})
+```
+
+OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, or `@mastra/mongodb`.
+
+> **Note:** If you switch the Observer to a weaker model and see facts collapse to a generic `User`, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to teach the Observer how to read the `<turn>` tag.
+
+### With working memory
+
+Use working memory when OM isn't an option — for example, when your storage adapter doesn't support OM, or when you need a structured, deterministic participants list the agent can read and write on every turn.
+
+The default [working memory](https://mastra.ai/docs/memory/working-memory) template assumes one user per thread ("First Name", "Last Name", etc.). For multi-user threads, provide a template with a participants list:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  options: {
+    lastMessages: 20,
+    workingMemory: {
+      enabled: true,
+      scope: 'thread',
+      template: `# Document Collaboration State
+
+## Participants
+<!-- One entry per known collaborator. Use author_id as the stable key. -->
+<!-- - **<author_name>** (<author_id>, <functional_role>): <their position> -->
+
+## Open Questions
+
+## Decisions
+`,
+    },
+  },
+})
+```
+
+Set `scope: 'thread'` so the participants list belongs to the document, not to any individual user. Add one instruction telling the agent to append new participants to the list whenever a new `author_id` shows up in a `<turn>`.
+
+For more on templates, see [Custom templates](https://mastra.ai/docs/memory/working-memory).
+
+## Security
+
+Set the `speaker` from your authenticated request context, never from the request body. If a client can choose its own `author_id`, one user can impersonate another. Use [Request Context](https://mastra.ai/docs/server/request-context) to read the verified user from your auth layer and build the `<turn>` tag on the server before calling the agent.
+
+## Related
+
+- [Working memory](https://mastra.ai/docs/memory/working-memory)
+- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
+- [Share memory between agents](https://mastra.ai/docs/memory/overview)
+- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)