@mastra/libsql 1.6.1 → 1.6.2

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

@@ -0,0 +1,260 @@
+# 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',
+  }),
+})
+```
+
+Give your agent a `Memory`:
+
+```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).
+
+There are two ways to use this history:
+
+- **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.
+
+## 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()
+```
+
+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 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.
+
+### 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,45 @@
+# 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 supports four complementary memory types:
+
+- [**Message history**](https://mastra.ai/docs/memory/message-history) - keeps recent messages from the current conversation so they can be rendered in the UI and used to maintain short-term continuity within the exchange.
+- [**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 messages from older conversations based on semantic meaning rather than exact keywords, mirroring how humans recall information by association. Requires a [vector database](https://mastra.ai/docs/memory/semantic-recall) and an [embedding model](https://mastra.ai/docs/memory/semantic-recall).
+- [**Observational memory**](https://mastra.ai/docs/memory/observational-memory) - uses background Observer and Reflector agents to maintain a dense observation log that replaces raw message history as it grows, keeping the context window small while preserving long-term memory across conversations.
+
+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.
+
+## Getting started
+
+Choose a memory option to get started:
+
+- [Message history](https://mastra.ai/docs/memory/message-history)
+- [Working memory](https://mastra.ai/docs/memory/working-memory)
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall)
+- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
+
+## Storage
+
+Before enabling memory, you must first configure a storage adapter. Mastra supports several databases including PostgreSQL, MongoDB, libSQL, and [more](https://mastra.ai/docs/memory/storage).
+
+Storage can be configured at the [instance level](https://mastra.ai/docs/memory/storage) (shared across all agents) or at the [agent level](https://mastra.ai/docs/memory/storage) (dedicated per agent).
+
+For semantic recall, you can use a separate vector database like Pinecone alongside your primary storage.
+
+See the [Storage](https://mastra.ai/docs/memory/storage) documentation for configuration options, supported providers, and examples.
+
+## Debugging memory
+
+When [tracing](https://mastra.ai/docs/observability/tracing/overview) is enabled, you can inspect exactly which messages the agent uses for context in each request. The trace output shows all memory included in the agent's context window - both recent message history and messages recalled via semantic recall.
+
+![Trace output showing memory context included in an agent request](https://mastra.ai/_next/image?url=%2Ftracingafter.png\&w=1920\&q=75)
+
+This visibility helps you understand why an agent made specific decisions and verify that memory retrieval is working as expected.
+
+## Next steps
+
+- Learn more about [Storage](https://mastra.ai/docs/memory/storage) providers and configuration options
+- Add [Message history](https://mastra.ai/docs/memory/message-history), [Working memory](https://mastra.ai/docs/memory/working-memory), [Semantic recall](https://mastra.ai/docs/memory/semantic-recall), or [Observational memory](https://mastra.ai/docs/memory/observational-memory)
+- Visit [Memory configuration reference](https://mastra.ai/reference/memory/memory-class) for all available options

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -0,0 +1,272 @@
+# Semantic Recall
+
+If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
+
+> **Watch 📹:** What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
+
+## How Semantic Recall Works
+
+Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent message history](https://mastra.ai/docs/memory/message-history).
+
+It uses vector embeddings of messages for similarity search, integrates with various vector stores, and has configurable context windows around retrieved messages.
+
+![Diagram showing Mastra Memory semantic recall](/assets/images/semantic-recall-fd7b9336a6d0d18019216cb6d3dbe710.png)
+
+When it's enabled, new messages are used to query a vector DB for semantically similar messages.
+
+After getting a response from the LLM, all new messages (user, assistant, and tool calls/results) are inserted into the vector DB to be recalled in later interactions.
+
+## Quick Start
+
+Semantic recall is enabled by default, so if you give your agent memory it will be included:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+const agent = new Agent({
+  id: 'support-agent',
+  name: 'SupportAgent',
+  instructions: 'You are a helpful support agent.',
+  model: 'openai/gpt-5.1',
+  memory: new Memory(),
+})
+```
+
+## Using the recall() Method
+
+While `listMessages` retrieves messages by thread ID with basic pagination, [`recall()`](https://mastra.ai/reference/memory/recall) adds support for **semantic search**. When you need to find messages by meaning rather than just recency, use `recall()` with a `vectorSearchString`:
+
+```typescript
+const memory = await agent.getMemory()
+
+// Basic recall - similar to listMessages
+const { messages } = await memory!.recall({
+  threadId: 'thread-123',
+  perPage: 50,
+})
+
+// Semantic recall - find messages by meaning
+const { messages: relevantMessages } = await memory!.recall({
+  threadId: 'thread-123',
+  vectorSearchString: 'What did we discuss about the project deadline?',
+  threadConfig: {
+    semanticRecall: true,
+  },
+})
+```
+
+## Storage configuration
+
+Semantic recall relies on a [storage and vector db](https://mastra.ai/reference/memory/memory-class) to store messages and their embeddings.
+
+```ts
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+
+const agent = new Agent({
+  memory: new Memory({
+    // this is the default storage db if omitted
+    storage: new LibSQLStore({
+      id: 'agent-storage',
+      url: 'file:./local.db',
+    }),
+    // this is the default vector db if omitted
+    vector: new LibSQLVector({
+      id: 'agent-vector',
+      url: 'file:./local.db',
+    }),
+  }),
+})
+```
+
+Each vector store page below includes installation instructions, configuration parameters, and usage examples:
+
+- [Astra](https://mastra.ai/reference/vectors/astra)
+- [Chroma](https://mastra.ai/reference/vectors/chroma)
+- [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
+- [Convex](https://mastra.ai/reference/vectors/convex)
+- [Couchbase](https://mastra.ai/reference/vectors/couchbase)
+- [DuckDB](https://mastra.ai/reference/vectors/duckdb)
+- [Elasticsearch](https://mastra.ai/reference/vectors/elasticsearch)
+- [LanceDB](https://mastra.ai/reference/vectors/lance)
+- [libSQL](https://mastra.ai/reference/vectors/libsql)
+- [MongoDB](https://mastra.ai/reference/vectors/mongodb)
+- [OpenSearch](https://mastra.ai/reference/vectors/opensearch)
+- [Pinecone](https://mastra.ai/reference/vectors/pinecone)
+- [PostgreSQL](https://mastra.ai/reference/vectors/pg)
+- [Qdrant](https://mastra.ai/reference/vectors/qdrant)
+- [S3 Vectors](https://mastra.ai/reference/vectors/s3vectors)
+- [Turbopuffer](https://mastra.ai/reference/vectors/turbopuffer)
+- [Upstash](https://mastra.ai/reference/vectors/upstash)
+
+## Recall configuration
+
+The three main parameters that control semantic recall behavior are:
+
+1. **topK**: How many semantically similar messages to retrieve
+2. **messageRange**: How much surrounding context to include with each match
+3. **scope**: Whether to search within the current thread or across all threads owned by a resource (the default is resource scope).
+
+```typescript
+const agent = new Agent({
+  memory: new Memory({
+    options: {
+      semanticRecall: {
+        topK: 3, // Retrieve 3 most similar messages
+        messageRange: 2, // Include 2 messages before and after each match
+        scope: 'resource', // Search across all threads for this user (default setting if omitted)
+      },
+    },
+  }),
+})
+```
+
+## Embedder configuration
+
+Semantic recall relies on an [embedding model](https://mastra.ai/reference/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
+
+### Using the Model Router (Recommended)
+
+The simplest way is to use a `provider/model` string with autocomplete support:
+
+```ts
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+
+const agent = new Agent({
+  memory: new Memory({
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  }),
+})
+```
+
+Supported embedding models:
+
+- **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
+- **Google**: `gemini-embedding-001`
+
+The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`).
+
+### Using AI SDK Packages
+
+You can also use AI SDK embedding models directly:
+
+```ts
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+
+const agent = new Agent({
+  memory: new Memory({
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  }),
+})
+```
+
+### Using FastEmbed (Local)
+
+To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
+
+**npm**:
+
+```bash
+npm install @mastra/fastembed@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/fastembed@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/fastembed@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/fastembed@latest
+```
+
+Then configure it in your memory:
+
+```ts
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { fastembed } from '@mastra/fastembed'
+
+const agent = new Agent({
+  memory: new Memory({
+    embedder: fastembed,
+  }),
+})
+```
+
+## PostgreSQL Index Optimization
+
+When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.
+
+PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an IVFFlat index, but HNSW indexes typically provide better performance, especially with OpenAI embeddings which use inner product distance.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { PgStore, PgVector } from '@mastra/pg'
+
+const agent = new Agent({
+  memory: new Memory({
+    storage: new PgStore({
+      id: 'agent-storage',
+      connectionString: process.env.DATABASE_URL,
+    }),
+    vector: new PgVector({
+      id: 'agent-vector',
+      connectionString: process.env.DATABASE_URL,
+    }),
+    options: {
+      semanticRecall: {
+        topK: 5,
+        messageRange: 2,
+        indexConfig: {
+          type: 'hnsw', // Use HNSW for better performance
+          metric: 'dotproduct', // Best for OpenAI embeddings
+          m: 16, // Number of bi-directional links (default: 16)
+          efConstruction: 64, // Size of candidate list during construction (default: 64)
+        },
+      },
+    },
+  }),
+})
+```
+
+For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg).
+
+## Disabling
+
+There is a performance impact to using semantic recall. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.
+
+Semantic recall is enabled by default but can be disabled when not needed:
+
+```typescript
+const agent = new Agent({
+  memory: new Memory({
+    options: {
+      semanticRecall: false,
+    },
+  }),
+})
+```
+
+You might want to disable semantic recall in scenarios like:
+
+- When message history provides sufficient context for the current conversation.
+- In performance-sensitive applications, like realtime two-way audio, where the added latency of creating embeddings and running vector queries is noticeable.
+
+## Viewing Recalled Messages
+
+When tracing is enabled, any messages retrieved via semantic recall will appear in the agent's trace output, alongside recent message history (if configured).