@mastra/libsql 1.6.1 → 1.6.2-alpha.0

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

@@ -0,0 +1,209 @@
+# Agent memory
+
+Agents use memory to maintain context across interactions. LLMs are stateless and don't retain information between calls, so agents need memory to track message history and recall relevant information.
+
+Mastra agents can be configured to store message history, with optional [working memory](https://mastra.ai/docs/memory/working-memory) to maintain recent context, [semantic recall](https://mastra.ai/docs/memory/semantic-recall) to retrieve past messages based on meaning, or [observational memory](https://mastra.ai/docs/memory/observational-memory) for automatic long-term memory that compresses conversations as they grow.
+
+## 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.
+
+## Setting up memory
+
+To enable memory in Mastra, install the `@mastra/memory` package along with a storage provider.
+
+**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
+```
+
+## Storage providers
+
+Memory requires a storage provider to persist message history, including user messages and agent responses. For more details on available providers and how storage works in Mastra, see the [Storage](https://mastra.ai/docs/memory/storage) documentation.
+
+## Configuring memory
+
+1. Enable memory by creating a `Memory` instance and passing 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,
+       },
+     }),
+   })
+   ```
+
+   > **Info:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
+
+2. Add a 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:',
+     }),
+   })
+   ```
+
+   > **Info:** Visit [libSQL Storage](https://mastra.ai/reference/storage/libsql) for a full list of configuration options.
+
+Alternatively, add storage directly to an agent’s memory to keep data separate or use different providers per agent.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'mastra-storage',
+      url: ':memory:',
+    }),
+  }),
+})
+```
+
+> **Mastra Cloud Store limitation:** Agent-level storage is not supported when using [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
+
+## Message history
+
+Include a `memory` object with both `resource` and `thread` to track message history during agent calls.
+
+- `resource`: A stable identifier for the user or entity.
+- `thread`: An ID that isolates a specific conversation or session.
+
+These fields tell the agent where to store and retrieve context, enabling persistent, thread-aware memory across a conversation.
+
+```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',
+  },
+})
+```
+
+> **Warning:** Each thread has an owner (`resourceId`) that cannot be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.
+
+To learn more about memory see the [Memory](https://mastra.ai/docs/memory/overview) documentation.
+
+## 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,
+    },
+  }),
+})
+```
+
+Setting `observationalMemory: true` uses `google/gemini-2.5-flash` as the default model for the Observer and Reflector. To use a different model or customize thresholds, pass a config object:
+
+```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: {
+        model: 'deepseek/deepseek-reasoner',
+        observation: {
+          messageTokens: 20_000,
+        },
+      },
+    },
+  }),
+})
+```
+
+> **Info:** 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.
+
+## Using `RequestContext`
+
+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
+  },
+})
+```
+
+> **Info:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+
+## Related
+
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
+- [Working Memory](https://mastra.ai/docs/memory/working-memory)
+- [Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)
+- [Storage](https://mastra.ai/docs/memory/storage)
+- [Request Context](https://mastra.ai/docs/server/request-context)

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

@@ -0,0 +1,275 @@
+# Network Approval
+
+Agent networks can require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in individual agents and workflows. When a tool, subagent, or workflow within a network requires approval or suspends execution, the network pauses and emits events that allow your application to collect user input before resuming.
+
+## Storage
+
+Network approval uses snapshots to capture execution state. Ensure you've enabled a storage provider in your Mastra instance. If storage isn't enabled you'll see an error relating to snapshot not found.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: ':memory:',
+  }),
+})
+```
+
+## Approving network tool calls
+
+When a tool within a network has `requireApproval: true`, the network stream emits an `agent-execution-approval` chunk and pauses. To allow the tool to execute, call `approveNetworkToolCall` with the `runId`.
+
+```typescript
+const stream = await routingAgent.network('Process this query', {
+  memory: {
+    thread: 'user-123',
+    resource: 'my-app',
+  },
+})
+
+let runId: string
+
+for await (const chunk of stream) {
+  runId = stream.runId
+  // if the requirApproval is in a tool inside a subAgent or the subAgent has requireToolApproval set to true
+  if (chunk.type === 'agent-execution-approval') {
+    console.log('Tool requires approval:', chunk.payload)
+  }
+
+  // if the requirApproval is in a tool directly in the network agent
+  if (chunk.type === 'tool-execution-approval') {
+    console.log('Tool requires approval:', chunk.payload)
+  }
+}
+
+// Approve and resume execution
+const approvedStream = await routingAgent.approveNetworkToolCall({
+  runId,
+  memory: {
+    thread: 'user-123',
+    resource: 'my-app',
+  },
+})
+
+for await (const chunk of approvedStream) {
+  if (chunk.type === 'network-execution-event-step-finish') {
+    console.log(chunk.payload.result)
+  }
+}
+```
+
+## Declining network tool calls
+
+To decline a pending tool call and prevent execution, call `declineNetworkToolCall`. The network continues without executing the tool.
+
+```typescript
+const declinedStream = await routingAgent.declineNetworkToolCall({
+  runId,
+  memory: {
+    thread: 'user-123',
+    resource: 'my-app',
+  },
+})
+
+for await (const chunk of declinedStream) {
+  if (chunk.type === 'network-execution-event-step-finish') {
+    console.log(chunk.payload.result)
+  }
+}
+```
+
+## Resuming suspended networks
+
+When a primitive in the network calls `suspend()`, the stream emits an `agent-execution-suspended`/`tool-execution-suspended`/`workflow-execution-suspended` chunk with a `suspendPayload` containing context from the primitive. Use `resumeNetwork` to provide the data requested by the primitive and continue execution.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+const confirmationTool = createTool({
+  id: 'confirmation-tool',
+  description: 'Requests user confirmation before proceeding',
+  inputSchema: z.object({
+    action: z.string(),
+  }),
+  outputSchema: z.object({
+    confirmed: z.boolean(),
+    action: z.string(),
+  }),
+  suspendSchema: z.object({
+    message: z.string(),
+    action: z.string(),
+  }),
+  resumeSchema: z.object({
+    confirmed: z.boolean(),
+  }),
+  execute: async (inputData, context) => {
+    const { resumeData, suspend } = context?.agent ?? {}
+
+    if (!resumeData?.confirmed) {
+      return suspend?.({
+        message: `Please confirm: ${inputData.action}`,
+        action: inputData.action,
+      })
+    }
+
+    return { confirmed: true, action: inputData.action }
+  },
+})
+```
+
+Handle the suspension and resume with user-provided data:
+
+```typescript
+const stream = await routingAgent.network('Delete the old records', {
+  memory: {
+    thread: 'user-123',
+    resource: 'my-app',
+  },
+})
+
+for await (const chunk of stream) {
+  if (chunk.type === 'workflow-execution-suspended') {
+    console.log(chunk.payload.suspendPayload)
+    // { message: "Please confirm: delete old records", action: "delete old records" }
+  }
+}
+
+// Resume with user confirmation
+const resumedStream = await routingAgent.resumeNetwork(
+  { confirmed: true },
+  {
+    runId: stream.runId,
+    memory: {
+      thread: 'user-123',
+      resource: 'my-app',
+    },
+  },
+)
+
+for await (const chunk of resumedStream) {
+  if (chunk.type === 'network-execution-event-step-finish') {
+    console.log(chunk.payload.result)
+  }
+}
+```
+
+## Automatic primitive resumption
+
+When using primitives that call `suspend()`, you can enable automatic resumption so the network resumes suspended primitives based on the user's next message. This creates a conversational flow where users provide the required information naturally.
+
+### Enabling auto-resume
+
+Set `autoResumeSuspendedTools` to `true` in the agent's `defaultNetworkOptions` or when calling `network()`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+// Option 1: In agent configuration
+const routingAgent = new Agent({
+  id: 'routing-agent',
+  name: 'Routing Agent',
+  instructions: 'You coordinate tasks across multiple agents',
+  model: 'openai/gpt-4o-mini',
+  tools: { confirmationTool },
+  memory: new Memory(),
+  defaultNetworkOptions: {
+    autoResumeSuspendedTools: true,
+  },
+})
+
+// Option 2: Per-request
+const stream = await routingAgent.network('Process this request', {
+  autoResumeSuspendedTools: true,
+  memory: {
+    thread: 'user-123',
+    resource: 'my-app',
+  },
+})
+```
+
+### How it works
+
+When `autoResumeSuspendedTools` is enabled:
+
+1. A primitive suspends execution by calling `suspend()` with a payload
+
+2. The suspension is persisted to memory along with the conversation
+
+3. When the user sends their next message on the same thread, the network:
+
+   - Detects the suspended primitive from message history
+   - Extracts `resumeData` from the user's message based on the tool's `resumeSchema`
+   - Automatically resumes the primitive with the extracted data
+
+### Example
+
+```typescript
+const stream = await routingAgent.network('Delete the old records', {
+  autoResumeSuspendedTools: true,
+  memory: {
+    thread: 'user-123',
+    resource: 'my-app',
+  },
+})
+
+for await (const chunk of stream) {
+  if (chunk.type === 'workflow-execution-suspended') {
+    console.log(chunk.payload.suspendPayload)
+    // { message: "Please confirm: delete old records", action: "delete old records" }
+  }
+}
+
+// User provides confirmation in their next message
+const resumedStream = await routingAgent.network('Yes, confirmed', {
+  autoResumeSuspendedTools: true,
+  memory: {
+    thread: 'user-123',
+    resource: 'my-app',
+  },
+})
+
+for await (const chunk of resumedStream) {
+  if (chunk.type === 'network-execution-event-step-finish') {
+    console.log(chunk.payload.result)
+  }
+}
+```
+
+**Conversation flow:**
+
+```text
+User: "Delete the old records"
+Agent: "Please confirm: delete old records"
+
+User: "Yes, confirmed"
+Agent: "Records deleted successfully"
+```
+
+### Requirements
+
+For automatic tool resumption to work:
+
+- **Memory configured**: The agent needs memory to track suspended tools across messages
+- **Same thread**: The follow-up message must use the same memory thread and resource identifiers
+- **`resumeSchema` defined**: The tool (either directly in the network agent or in a subAgent) / workflow (step that gets suspended) must define a `resumeSchema` so the agent knows what data to extract from the user's message
+
+### Manual vs automatic resumption
+
+| Approach                               | Use case                                                                 |
+| -------------------------------------- | ------------------------------------------------------------------------ |
+| Manual (`resumeNetwork()`)             | Programmatic control, webhooks, button clicks, external triggers         |
+| Automatic (`autoResumeSuspendedTools`) | Conversational flows where users provide resume data in natural language |
+
+Both approaches work with the same tool definitions. Automatic resumption triggers only when suspended tools exist in the message history and the user sends a new message on the same thread.
+
+## Related
+
+- [Agent Networks](https://mastra.ai/docs/agents/networks)
+- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Human-in-the-Loop](https://mastra.ai/docs/workflows/human-in-the-loop)
+- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)