@mastra/libsql 0.0.0-workflow-timeout-issue-20260220185702 → 0.0.0-workflow-graph-crash-20260527191009

package/dist/docs/references/docs-memory-memory-processors.md

@@ -1,4 +1,4 @@
-# Memory Processors
+# Memory processors
 
 Memory processors transform and filter messages as they pass through an agent with memory enabled. They manage context window limits, remove unnecessary content, and optimize the information sent to the language model.
 
@@ -6,11 +6,11 @@ When memory is enabled on an agent, Mastra adds memory processors to the agent's
 
 Memory processors are [processors](https://mastra.ai/docs/agents/processors) that operate specifically on memory-related messages and state.
 
-## Built-in Memory Processors
+## Built-in memory processors
 
 Mastra automatically adds these processors when memory is enabled:
 
-### MessageHistory
+### `MessageHistory`
 
 Retrieves message history and persists new messages.
 
@@ -19,7 +19,7 @@ Retrieves message history and persists new messages.
 ```typescript
 memory: new Memory({
   lastMessages: 10,
-});
+})
 ```
 
 **Mastra internally:**
@@ -36,27 +36,27 @@ memory: new Memory({
 **Example:**
 
 ```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { LibSQLStore } from "@mastra/libsql";
-import { openai } from "@ai-sdk/openai";
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+import { openai } from '@ai-sdk/openai'
 
 const agent = new Agent({
-  id: "test-agent",
-  name: "Test Agent",
-  instructions: "You are a helpful assistant",
-  model: 'openai/gpt-4o',
+  id: 'test-agent',
+  name: 'Test Agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.4',
   memory: new Memory({
     storage: new LibSQLStore({
-      id: "memory-store",
-      url: "file:memory.db",
+      id: 'memory-store',
+      url: 'file:memory.db',
     }),
     lastMessages: 10, // MessageHistory processor automatically added
   }),
-});
+})
 ```
 
-### SemanticRecall
+### `SemanticRecall`
 
 Retrieves semantically relevant messages based on the current input and creates embeddings for new messages.
 
@@ -67,7 +67,7 @@ memory: new Memory({
   semanticRecall: { enabled: true },
   vector: myVectorStore,
   embedder: myEmbedder,
-});
+})
 ```
 
 **Mastra internally:**
@@ -85,36 +85,36 @@ memory: new Memory({
 **Example:**
 
 ```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { LibSQLStore } from "@mastra/libsql";
-import { PineconeVector } from "@mastra/pinecone";
-import { OpenAIEmbedder } from "@mastra/openai";
-import { openai } from "@ai-sdk/openai";
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+import { PineconeVector } from '@mastra/pinecone'
+import { OpenAIEmbedder } from '@mastra/openai'
+import { openai } from '@ai-sdk/openai'
 
 const agent = new Agent({
-  name: "semantic-agent",
-  instructions: "You are a helpful assistant with semantic memory",
-  model: 'openai/gpt-4o',
+  name: 'semantic-agent',
+  instructions: 'You are a helpful assistant with semantic memory',
+  model: 'openai/gpt-5.4',
   memory: new Memory({
     storage: new LibSQLStore({
-      id: "memory-store",
-      url: "file:memory.db",
+      id: 'memory-store',
+      url: 'file:memory.db',
     }),
     vector: new PineconeVector({
-      id: "memory-vector",
+      id: 'memory-vector',
       apiKey: process.env.PINECONE_API_KEY!,
     }),
     embedder: new OpenAIEmbedder({
-      model: "text-embedding-3-small",
+      model: 'text-embedding-3-small',
       apiKey: process.env.OPENAI_API_KEY!,
     }),
     semanticRecall: { enabled: true }, // SemanticRecall processor automatically added
   }),
-});
+})
 ```
 
-### WorkingMemory
+### `WorkingMemory`
 
 Manages working memory state across conversations.
 
@@ -123,7 +123,7 @@ Manages working memory state across conversations.
 ```typescript
 memory: new Memory({
   workingMemory: { enabled: true },
-});
+})
 ```
 
 **Mastra internally:**
@@ -140,59 +140,59 @@ memory: new Memory({
 **Example:**
 
 ```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { LibSQLStore } from "@mastra/libsql";
-import { openai } from "@ai-sdk/openai";
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+import { openai } from '@ai-sdk/openai'
 
 const agent = new Agent({
-  name: "working-memory-agent",
-  instructions: "You are an assistant with working memory",
-  model: 'openai/gpt-4o',
+  name: 'working-memory-agent',
+  instructions: 'You are an assistant with working memory',
+  model: 'openai/gpt-5.4',
   memory: new Memory({
     storage: new LibSQLStore({
-      id: "memory-store",
-      url: "file:memory.db",
+      id: 'memory-store',
+      url: 'file:memory.db',
     }),
     workingMemory: { enabled: true }, // WorkingMemory processor automatically added
   }),
-});
+})
 ```
 
-## Manual Control and Deduplication
+## Manual control and deduplication
 
-If you manually add a memory processor to `inputProcessors` or `outputProcessors`, Mastra will **not** automatically add it. This gives you full control over processor ordering:
+If you manually add a memory processor to `inputProcessors` or `outputProcessors`, Mastra **won't** automatically add it. This gives you full control over processor ordering:
 
 ```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { MessageHistory } from "@mastra/core/processors";
-import { TokenLimiter } from "@mastra/core/processors";
-import { LibSQLStore } from "@mastra/libsql";
-import { openai } from "@ai-sdk/openai";
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { MessageHistory } from '@mastra/core/processors'
+import { TokenLimiter } from '@mastra/core/processors'
+import { LibSQLStore } from '@mastra/libsql'
+import { openai } from '@ai-sdk/openai'
 
 // Custom MessageHistory with different configuration
 const customMessageHistory = new MessageHistory({
-  storage: new LibSQLStore({ id: "memory-store", url: "file:memory.db" }),
+  storage: new LibSQLStore({ id: 'memory-store', url: 'file:memory.db' }),
   lastMessages: 20,
-});
+})
 
 const agent = new Agent({
-  name: "custom-memory-agent",
-  instructions: "You are a helpful assistant",
-  model: 'openai/gpt-4o',
+  name: 'custom-memory-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.4',
   memory: new Memory({
-    storage: new LibSQLStore({ id: "memory-store", url: "file:memory.db" }),
+    storage: new LibSQLStore({ id: 'memory-store', url: 'file:memory.db' }),
     lastMessages: 10, // This would normally add MessageHistory(10)
   }),
   inputProcessors: [
     customMessageHistory, // Your custom one is used instead
     new TokenLimiter({ limit: 4000 }), // Runs after your custom MessageHistory
   ],
-});
+})
 ```
 
-## Processor Execution Order
+## Processor execution order
 
 Understanding the execution order is important when combining guardrails with memory:
 
@@ -218,7 +218,7 @@ This means memory loads message history before your processors can validate or f
 
 This ordering is designed to be **safe by default**: if your output guardrail calls `abort()`, the memory processors never run and **no messages are saved**.
 
-## Guardrails and Memory
+## Guardrails and memory
 
 The default execution order provides safe guardrail behavior:
 
@@ -231,37 +231,35 @@ Output guardrails run **before** memory processors save messages. If a guardrail
 - **No messages are persisted to storage**
 
 ```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { openai } from '@ai-sdk/openai'
 
 // Output guardrail that blocks inappropriate content
 const contentBlocker = {
-  id: "content-blocker",
+  id: 'content-blocker',
   processOutputResult: async ({ messages, abort }) => {
-    const hasInappropriateContent = messages.some((msg) =>
-      containsBadContent(msg)
-    );
+    const hasInappropriateContent = messages.some(msg => containsBadContent(msg))
     if (hasInappropriateContent) {
-      abort("Content blocked by guardrail");
+      abort('Content blocked by guardrail')
     }
-    return messages;
+    return messages
   },
-};
+}
 
 const agent = new Agent({
-  name: "safe-agent",
-  instructions: "You are a helpful assistant",
-  model: 'openai/gpt-4o',
+  name: 'safe-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.4',
   memory: new Memory({ lastMessages: 10 }),
   // Your guardrail runs BEFORE memory saves
   outputProcessors: [contentBlocker],
-});
+})
 
 // If the guardrail aborts, nothing is saved to memory
-const result = await agent.generate("Hello");
+const result = await agent.generate('Hello')
 if (result.tripwire) {
-  console.log("Blocked:", result.tripwire.reason);
+  console.log('Blocked:', result.tripwire.reason)
   // Memory is empty - no messages were persisted
 }
 ```
@@ -278,24 +276,24 @@ Input guardrails run **after** memory processors load history. If a guardrail ab
 ```typescript
 // Input guardrail that validates user input
 const inputValidator = {
-  id: "input-validator",
+  id: 'input-validator',
   processInput: async ({ messages, abort }) => {
-    const lastUserMessage = messages.findLast((m) => m.role === "user");
+    const lastUserMessage = messages.findLast(m => m.role === 'user')
     if (isInvalidInput(lastUserMessage)) {
-      abort("Invalid input detected");
+      abort('Invalid input detected')
     }
-    return messages;
+    return messages
   },
-};
+}
 
 const agent = new Agent({
-  name: "validated-agent",
-  instructions: "You are a helpful assistant",
-  model: 'openai/gpt-4o',
+  name: 'validated-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.4',
   memory: new Memory({ lastMessages: 10 }),
   // Your guardrail runs AFTER memory loads history
   inputProcessors: [inputValidator],
-});
+})
 ```
 
 ### Summary
@@ -309,8 +307,8 @@ Both scenarios are safe - guardrails prevent inappropriate content from being pe
 
 ## Related documentation
 
-- [Processors](https://mastra.ai/docs/agents/processors) - General processor concepts and custom processor creation
-- [Guardrails](https://mastra.ai/docs/agents/guardrails) - Security and validation processors
-- [Memory Overview](https://mastra.ai/docs/memory/overview) - Memory types and configuration
+- [Processors](https://mastra.ai/docs/agents/processors): General processor concepts and custom processor creation
+- [Guardrails](https://mastra.ai/docs/agents/guardrails): Security and validation processors
+- [Memory Overview](https://mastra.ai/docs/memory/overview): Memory types and configuration
 
 When creating custom processors avoid mutating the input `messages` array or its objects directly.

package/dist/docs/references/docs-memory-message-history.md

@@ -1,4 +1,4 @@
-# Message History
+# Message history
 
 Message history is the most basic and important form of memory. It gives the LLM a view of recent messages in the context window, enabling your agent to reference earlier exchanges and respond coherently.
 
@@ -6,6 +6,12 @@ You can also retrieve message history to display past conversations in your UI.
 
 > **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](https://mastra.ai/docs/memory/storage) for more detail.
 
+> **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
+>
+> Sending the full history is redundant because Mastra loads messages from storage, and it can cause message ordering bugs when client-side timestamps conflict with stored timestamps.
+>
+> For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
+
 ## Getting started
 
 Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/memory/storage) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
@@ -37,79 +43,81 @@ bun add @mastra/memory@latest @mastra/libsql@latest
 Message history requires a storage adapter to persist conversations. Configure storage on your Mastra instance if you haven't already:
 
 ```typescript
-import { Mastra } from "@mastra/core";
-import { LibSQLStore } from "@mastra/libsql";
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
 
 export const mastra = new Mastra({
   storage: new LibSQLStore({
     id: 'mastra-storage',
-    url: "file:./mastra.db",
+    url: 'file:./mastra.db',
   }),
-});
+})
 ```
 
-Give your agent a `Memory`:
+Instantiate a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance in your agent:
 
 ```typescript
-import { Memory } from "@mastra/memory";
-import { Agent } from "@mastra/core/agent";
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
-  id: "test-agent",
+  id: 'test-agent',
   memory: new Memory({
     options: {
       lastMessages: 10,
     },
   }),
-});
+})
 ```
 
 When you call the agent, messages are automatically saved to the database. You can specify a `threadId`, `resourceId`, and optional `metadata`:
 
-**Generate**:
+**.generate()**:
 
 ```typescript
-await agent.generate("Hello", {
+await agent.generate('Hello', {
   memory: {
     thread: {
-      id: "thread-123",
-      title: "Support conversation",
-      metadata: { category: "billing" },
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
     },
-    resource: "user-456",
+    resource: 'user-456',
   },
-});
+})
 ```
 
-**Stream**:
+**.stream()**:
 
 ```typescript
-await agent.stream("Hello", {
+await agent.stream('Hello', {
   memory: {
     thread: {
-      id: "thread-123",
-      title: "Support conversation",
-      metadata: { category: "billing" },
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
     },
-    resource: "user-456",
+    resource: 'user-456',
   },
-});
+})
 ```
 
 > **Info:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
 
-There are two ways to use this history:
+You can use this history in two ways:
+
+- **Automatic inclusion**: Mastra automatically fetches and includes recent messages in the context window. By default, it includes the last 10 messages, keeping agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
+- [**Manual querying**](#querying): For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
 
-- **Automatic inclusion** - Mastra automatically fetches and includes recent messages in the context window. By default, it includes the last 10 messages, keeping agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
-- [**Manual querying**](#querying) - For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
+> **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 
-## Accessing Memory
+## Accessing memory
 
 To access memory functions for querying, cloning, or deleting threads and messages, call `getMemory()` on an agent:
 
 ```typescript
-const agent = mastra.getAgent("weatherAgent");
-const memory = await agent.getMemory();
+const agent = mastra.getAgentById('test-agent')
+const memory = await agent.getMemory()
 ```
 
 The `Memory` instance gives you access to functions for listing threads, recalling messages, cloning conversations, and more.
@@ -118,7 +126,7 @@ The `Memory` instance gives you access to functions for listing threads, recalli
 
 Use these methods to fetch threads and messages for displaying conversation history in your UI or for custom memory retrieval logic.
 
-> **Warning:** The memory system does not enforce access control. Before running any query, verify in your application logic that the current user is authorized to access the `resourceId` being queried.
+> **Warning:** The memory system doesn't enforce access control. Before running any query, verify in your application logic that the current user is authorized to access the `resourceId` being queried.
 
 ### Threads
 
@@ -126,22 +134,22 @@ Use [`listThreads()`](https://mastra.ai/reference/memory/listThreads) to retriev
 
 ```typescript
 const result = await memory.listThreads({
-  filter: { resourceId: "user-123" },
+  filter: { resourceId: 'user-123' },
   perPage: false,
-});
+})
 ```
 
 Paginate through threads:
 
 ```typescript
 const result = await memory.listThreads({
-  filter: { resourceId: "user-123" },
+  filter: { resourceId: 'user-123' },
   page: 0,
   perPage: 10,
-});
+})
 
-console.log(result.threads); // thread objects
-console.log(result.hasMore); // more pages available?
+console.log(result.threads) // thread objects
+console.log(result.hasMore) // more pages available?
 ```
 
 You can also filter by metadata and control sort order:
@@ -149,17 +157,17 @@ You can also filter by metadata and control sort order:
 ```typescript
 const result = await memory.listThreads({
   filter: {
-    resourceId: "user-123",
-    metadata: { status: "active" },
+    resourceId: 'user-123',
+    metadata: { status: 'active' },
   },
-  orderBy: { field: "createdAt", direction: "DESC" },
-});
+  orderBy: { field: 'createdAt', direction: 'DESC' },
+})
 ```
 
 To fetch a single thread by ID, use [`getThreadById()`](https://mastra.ai/reference/memory/getThreadById):
 
 ```typescript
-const thread = await memory.getThreadById({ threadId: "thread-123" });
+const thread = await memory.getThreadById({ threadId: 'thread-123' })
 ```
 
 ### Messages
@@ -170,70 +178,70 @@ Basic recall returns all messages from a thread:
 
 ```typescript
 const { messages } = await memory.recall({
-  threadId: "thread-123",
+  threadId: 'thread-123',
   perPage: false,
-});
+})
 ```
 
 Paginate through messages:
 
 ```typescript
 const { messages } = await memory.recall({
-  threadId: "thread-123",
+  threadId: 'thread-123',
   page: 0,
   perPage: 50,
-});
+})
 ```
 
 Filter by date range:
 
 ```typescript
 const { messages } = await memory.recall({
-  threadId: "thread-123",
+  threadId: 'thread-123',
   filter: {
     dateRange: {
-      start: new Date("2025-01-01"),
-      end: new Date("2025-06-01"),
+      start: new Date('2025-01-01'),
+      end: new Date('2025-06-01'),
     },
   },
-});
+})
 ```
 
 Fetch a single message by ID:
 
 ```typescript
 const { messages } = await memory.recall({
-  threadId: "thread-123",
-  include: [{ id: "msg-123" }],
-});
+  threadId: 'thread-123',
+  include: [{ id: 'msg-123' }],
+})
 ```
 
 Fetch multiple messages by ID with surrounding context:
 
 ```typescript
 const { messages } = await memory.recall({
-  threadId: "thread-123",
+  threadId: 'thread-123',
   include: [
-    { id: "msg-123" },
+    { id: 'msg-123' },
     {
-      id: "msg-456",
+      id: 'msg-456',
       withPreviousMessages: 3,
       withNextMessages: 1,
     },
   ],
-});
+})
 ```
 
 Search by meaning (see [Semantic recall](https://mastra.ai/docs/memory/semantic-recall) for setup):
 
 ```typescript
 const { messages } = await memory.recall({
-  threadId: "thread-123",
-  vectorSearchString: "project deadline discussion",
+  threadId: 'thread-123',
+  vectorSearchString: 'project deadline discussion',
   threadConfig: {
     semanticRecall: true,
   },
-});
+})
 ```
 
 ### UI format
@@ -246,9 +254,9 @@ Thread cloning creates a copy of an existing thread with its messages. This is u
 
 ```typescript
 const { thread, clonedMessages } = await memory.cloneThread({
-  sourceThreadId: "thread-123",
-  title: "Branched conversation",
-});
+  sourceThreadId: 'thread-123',
+  title: 'Branched conversation',
+})
 ```
 
 You can filter which messages get cloned (by count or date range), specify custom thread IDs, and use utility methods to inspect clone relationships.