@mastra/libsql 0.0.0-error-handler-fix-20251020202607 → 0.0.0-everlasting-joggers-20260331153923

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

@@ -0,0 +1,262 @@
+# 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.
+
+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.
+
+## 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.
+
+**npm**:
+
+```bash
+npm install @mastra/memory@latest @mastra/libsql@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/memory@latest @mastra/libsql@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/memory@latest @mastra/libsql@latest
+```
+
+**Bun**:
+
+```bash
+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'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
+})
+```
+
+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'
+
+export const agent = new 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()**:
+
+```typescript
+await agent.generate('Hello', {
+  memory: {
+    thread: {
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
+    },
+    resource: 'user-456',
+  },
+})
+```
+
+**.stream()**:
+
+```typescript
+await agent.stream('Hello', {
+  memory: {
+    thread: {
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
+    },
+    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).
+
+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.
+
+> **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
+
+To access memory functions for querying, cloning, or deleting threads and messages, call `getMemory()` on an agent:
+
+```typescript
+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.
+
+## Querying
+
+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 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
+
+Use [`listThreads()`](https://mastra.ai/reference/memory/listThreads) to retrieve threads for a resource:
+
+```typescript
+const result = await memory.listThreads({
+  filter: { resourceId: 'user-123' },
+  perPage: false,
+})
+```
+
+Paginate through threads:
+
+```typescript
+const result = await memory.listThreads({
+  filter: { resourceId: 'user-123' },
+  page: 0,
+  perPage: 10,
+})
+
+console.log(result.threads) // thread objects
+console.log(result.hasMore) // more pages available?
+```
+
+You can also filter by metadata and control sort order:
+
+```typescript
+const result = await memory.listThreads({
+  filter: {
+    resourceId: 'user-123',
+    metadata: { status: 'active' },
+  },
+  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' })
+```
+
+### Messages
+
+Once you have a thread, use [`recall()`](https://mastra.ai/reference/memory/recall) to retrieve its messages. It supports pagination, date filtering, and [semantic search](https://mastra.ai/docs/memory/semantic-recall).
+
+Basic recall returns all messages from a thread:
+
+```typescript
+const { messages } = await memory.recall({
+  threadId: 'thread-123',
+  perPage: false,
+})
+```
+
+Paginate through messages:
+
+```typescript
+const { messages } = await memory.recall({
+  threadId: 'thread-123',
+  page: 0,
+  perPage: 50,
+})
+```
+
+Filter by date range:
+
+```typescript
+const { messages } = await memory.recall({
+  threadId: 'thread-123',
+  filter: {
+    dateRange: {
+      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' }],
+})
+```
+
+Fetch multiple messages by ID with surrounding context:
+
+```typescript
+const { messages } = await memory.recall({
+  threadId: 'thread-123',
+  include: [
+    { id: 'msg-123' },
+    {
+      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',
+  threadConfig: {
+    semanticRecall: true,
+  },
+})
+```
+
+### UI format
+
+Message queries return `MastraDBMessage[]` format. To display messages in a frontend, you may need to convert them to a format your UI library expects. For example, [`toAISdkV5Messages`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-v5-messages) converts messages to AI SDK UI format.
+
+## Thread cloning
+
+Thread cloning creates a copy of an existing thread with its messages. This is useful for branching conversations, creating checkpoints before a potentially destructive operation, or testing variations of a conversation.
+
+```typescript
+const { thread, clonedMessages } = await memory.cloneThread({
+  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.
+
+See [`cloneThread()`](https://mastra.ai/reference/memory/cloneThread) and [clone utilities](https://mastra.ai/reference/memory/clone-utilities) for the full API.
+
+## Deleting messages
+
+To remove messages from a thread, use [`deleteMessages()`](https://mastra.ai/reference/memory/deleteMessages). You can delete by message ID or clear all messages from a thread.

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

@@ -0,0 +1,240 @@
+# Memory
+
+Memory enables your agent to remember user messages, agent replies, and tool results across interactions, giving it the context it needs to stay consistent, maintain conversation flow, and produce better answers over time.
+
+Mastra agents can be configured to store [message history](https://mastra.ai/docs/memory/message-history). Additionally, you can enable:
+
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory) (Recommended): Uses background agents to maintain a dense observation log that replaces raw message history as it grows. This keeps the context window small while preserving long-term memory.
+- [Working memory](https://mastra.ai/docs/memory/working-memory): Stores persistent, structured user data such as names, preferences, and goals.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): Retrieves relevant past messages based on semantic meaning rather than exact keywords.
+
+If the combined memory exceeds the model's context limit, [memory processors](https://mastra.ai/docs/memory/memory-processors) can filter, trim, or prioritize content so the most relevant information is preserved.
+
+Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/memory/storage).
+
+## When to use memory
+
+Use memory when your agent needs to maintain multi-turn conversations that reference prior exchanges, recall user preferences or facts from earlier in a session, or build context over time within a conversation thread. Skip memory for single-turn requests where each interaction is independent.
+
+## Quickstart
+
+1. Install the `@mastra/memory` package.
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/memory@latest
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/memory@latest
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/memory@latest
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/memory@latest
+   ```
+
+2. Memory **requires** a storage provider to persist message history, including user messages and agent responses.
+
+   For the purposes of this quickstart, use `@mastra/libsql`.
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/libsql@latest
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/libsql@latest
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/libsql@latest
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/libsql@latest
+   ```
+
+   > **Note:** For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/memory/storage) documentation.
+
+3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
+
+   ```typescript
+   import { Mastra } from '@mastra/core'
+   import { LibSQLStore } from '@mastra/libsql'
+
+   export const mastra = new Mastra({
+     storage: new LibSQLStore({
+       id: 'mastra-storage',
+       url: ':memory:',
+     }),
+   })
+   ```
+
+4. Create a `Memory` instance and pass it to the agent's `memory` option.
+
+   ```typescript
+   import { Agent } from '@mastra/core/agent'
+   import { Memory } from '@mastra/memory'
+
+   export const memoryAgent = new Agent({
+     id: 'memory-agent',
+     name: 'Memory Agent',
+     memory: new Memory({
+       options: {
+         lastMessages: 20,
+       },
+     }),
+   })
+   ```
+
+   > **Note:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
+
+5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
+
+## Message history
+
+Pass a `memory` object with `resource` and `thread` to track message history.
+
+- `resource`: A stable identifier for the user or entity.
+- `thread`: An ID that isolates a specific conversation or session.
+
+```typescript
+const response = await memoryAgent.generate('Remember my favorite color is blue.', {
+  memory: {
+    resource: 'user-123',
+    thread: 'conversation-123',
+  },
+})
+```
+
+To recall information stored in memory, call the agent with the same `resource` and `thread` values used in the original conversation.
+
+```typescript
+const response = await memoryAgent.generate("What's my favorite color?", {
+  memory: {
+    resource: 'user-123',
+    thread: 'conversation-123',
+  },
+})
+
+// Response: "Your favorite color is blue."
+```
+
+> **Warning:** Each thread has an owner (`resourceId`) that can't be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.
+
+To list all threads for a resource, or retrieve a specific thread, [use the memory API directly](https://mastra.ai/docs/memory/message-history).
+
+## Observational Memory
+
+For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  memory: new Memory({
+    options: {
+      observationalMemory: true,
+    },
+  }),
+})
+```
+
+> **Note:** See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
+
+## Memory in multi-agent systems
+
+When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. No flag enables this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
+
+### How delegation scopes memory
+
+Each delegation creates a fresh `threadId` and a deterministic `resourceId` for the subagent:
+
+- **Thread ID**: Unique per delegation. The subagent starts with a clean message history every time it's called.
+- **Resource ID**: Derived as `{parentResourceId}-{agentName}`. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
+- **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance. If the subagent defines its own, that takes precedence.
+
+The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
+
+> **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Two different subagents under the same supervisor never share a resource ID through delegation.
+
+To go beyond this default isolation, you can share memory between agents by passing matching identifiers when you call them directly.
+
+### Share memory between agents
+
+When you call agents directly (outside the delegation flow), memory sharing is controlled by two identifiers: `resourceId` and `threadId`. Agents that use the same values read and write to the same data. This is useful when agents collaborate on a shared context — for example, a researcher that saves notes and a writer that reads them.
+
+**Resource-scoped sharing** is the most common pattern. [Working memory](https://mastra.ai/docs/memory/working-memory) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) default to `scope: 'resource'`. If two agents share a `resourceId`, they share observations, working memory, and embeddings — even across different threads:
+
+```typescript
+// Both agents share the same resource-scoped memory
+await researcher.generate('Find information about quantum computing.', {
+  memory: { resource: 'project-42', thread: 'research-session' },
+})
+
+await writer.generate('Write a summary from the research notes.', {
+  memory: { resource: 'project-42', thread: 'writing-session' },
+})
+```
+
+Because both calls use `resource: 'project-42'`, the writer can access the researcher's observations, working memory, and semantic embeddings. Each agent still has its own thread, so message histories stay separate.
+
+**Thread-scoped sharing** gives tighter coupling. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses `scope: 'thread'` by default. If two agents use the same `resource` _and_ `thread`, they share the full message history. Each agent sees every message the other has written. This is useful when agents need to build on each other's exact outputs.
+
+## Observability
+
+Enable [Tracing](https://mastra.ai/docs/observability/tracing/overview) to monitor and debug memory in action. Traces show you exactly which messages and observations the agent included in its context for each request, helping you understand agent behavior and verify that memory retrieval is working as expected.
+
+Open [Studio](https://mastra.ai/docs/studio/overview) and select the **Observability** tab in the sidebar. Open the trace of a recent agent request, then look for spans of LLMs calls.
+
+## Switch memory per request
+
+Use [`RequestContext`](https://mastra.ai/docs/server/request-context) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
+
+```typescript
+export type UserTier = {
+  'user-tier': 'enterprise' | 'pro'
+}
+
+const premiumMemory = new Memory()
+const standardMemory = new Memory()
+
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  memory: ({ requestContext }) => {
+    const userTier = requestContext.get('user-tier') as UserTier['user-tier']
+
+    return userTier === 'enterprise' ? premiumMemory : standardMemory
+  },
+})
+```
+
+> **Note:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+
+## Related
+
+- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
+- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
+- [Request Context](https://mastra.ai/docs/server/request-context)