@mastra/memory 0.0.0-studio-deploy-20260404182525 → 0.0.0-studio-cli-20260504022012

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

@@ -38,8 +38,45 @@ const memory = new Memory({
 
 See [configuration options](https://mastra.ai/reference/memory/observational-memory) for full API details.
 
+> **Warning:** When you use OM with a client application, send **only the new message** from the client instead of the full conversation history.
+>
+> Observational memory still relies on stored conversation history. Sending the full history is redundant and 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).
+
 > **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It uses background agents for managing memory. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
 
+## Temporal gap markers
+
+Temporal gap markers insert a short reminder before a new user message when enough time has passed since the previous message in the thread. They help the agent and the UI see that the conversation resumed after a meaningful pause.
+
+Temporal gap markers are off by default. Enable them with `temporalMarkers: true` in the `observationalMemory` config:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+
+export const agent = new Agent({
+  name: 'my-agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5-mini',
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        model: 'google/gemini-2.5-flash',
+        temporalMarkers: true,
+      },
+    },
+  }),
+})
+```
+
+Mastra inserts a temporal gap marker when the gap is at least 10 minutes. The marker is stored in memory and also emitted as a transient reminder event, so clients can render it as a lightweight timeline hint.
+
+The observer also sees these markers when it processes the thread, so the observations it writes can anchor memories to when they happened (for example, "User asked about deployment after a 2-day gap").
+
+See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
+
 ## Benefits
 
 - **Prompt caching**: OM's context is stable and observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
@@ -157,7 +194,7 @@ With retrieval mode enabled, OM:
 - Registers a `recall` tool the agent can call to:
 
   - Page through the raw messages behind any observation group range
-  - Search by semantic similarity (`mode: "search"` with a `query` string) — requires `vector: true`
+  - Search by semantic similarity (`mode: "search"` with a `query` string); requires `vector: true`
   - List all threads (`mode: "threads"`), browse other threads (`threadId`), and search across all threads (default `scope: 'resource'`)
   - When `scope: 'thread'`: restrict browsing and search to the current thread only
 
@@ -327,13 +364,33 @@ Reflection works similarly — the Reflector runs in the background when observa
 
 ### Settings
 
-| Setting                        | Default | What it controls                                                                                                                                                                      |
-| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`     | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).    |
-| `observation.bufferActivation` | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history. |
-| `observation.blockAfter`       | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                  |
-| `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                  |
-| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                           |
+| Setting                        | Default | What it controls                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`     | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                     |
+| `observation.bufferActivation` | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                  |
+| `observation.blockAfter`       | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                                                                                   |
+| `activateAfterIdle`            | none    | Forces buffered observations and buffered reflections to activate after a period of inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like `300_000`, `"5m"`, or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
+| `activateOnProviderChange`     | `false` | Forces buffered observations and reflections to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                   |
+| `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                   |
+| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                            |
+
+If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations or reflections first and send a smaller compressed context window.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      activateOnProviderChange: true,
+    },
+  },
+})
+```
+
+With a 5-minute prompt cache TTL, this activates buffered context after 5 minutes of inactivity so the next uncached prompt uses observations and reflections instead of a larger raw message window. If you prefer, `300_000` works the same way.
+
+Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered context to activate before the new provider runs. That avoids sending a large raw window to a provider that cannot reuse the previous prompt cache.
 
 ### Disabling
 

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

@@ -34,6 +34,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
 - [MongoDB](https://mastra.ai/reference/storage/mongodb)
 - [Upstash](https://mastra.ai/reference/storage/upstash)
+- [Redis](https://mastra.ai/reference/storage/redis)
 - [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
 - [Cloudflare KV & Durable Objects](https://mastra.ai/reference/storage/cloudflare)
 - [Convex](https://mastra.ai/reference/storage/convex)
@@ -118,8 +119,6 @@ export const agent = new Agent({
 })
 ```
 
-> **Warning:** Agent-level storage isn't 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 doesn't apply if you bring your own database.
-
 ## Threads and resources
 
 Mastra organizes conversations using two identifiers:

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

@@ -208,7 +208,7 @@ const paragraphMemory = new Memory({
 
 ## Structured working memory
 
-Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Zod](https://zod.dev/) schema. When using a schema, the agent will see and update working memory as a JSON object matching your schema.
+Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
 
 **Important:** You must specify either `template` or `schema`, but not both.
 
@@ -397,4 +397,4 @@ const response = await agent.generate('What do you know about me?', {
 
 - [Working memory with template](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-template)
 - [Working memory with schema](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-schema)
-- [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence
+- [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example): Complete example showing resource-scoped memory persistence

package/dist/docs/references/reference-memory-clone-utilities.md

@@ -153,8 +153,10 @@ async function manageClones() {
 
   // Have a conversation...
   await agent.generate("Hello! Let's discuss project options.", {
-    threadId: originalThread.id,
-    resourceId: 'user-123',
+    memory: {
+      thread: originalThread.id,
+      resource: 'user-123',
+    },
   })
 
   // Create multiple branches (clones) to explore different paths

package/dist/docs/references/reference-memory-cloneThread.md

@@ -93,8 +93,10 @@ const { thread: dateFilteredClone } = await memory.cloneThread({
 
 // Continue conversation on the cloned thread
 const response = await agent.generate("Let's try a different approach", {
-  threadId: fullClone.id,
-  resourceId: fullClone.resourceId,
+  memory: {
+    thread: fullClone.id,
+    resource: fullClone.resourceId,
+  },
 })
 ```
 

package/dist/docs/references/reference-memory-observational-memory.md

@@ -36,8 +36,12 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **scope** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
+**activateAfterIdle** (`number | string`): Time before buffered observations or buffered reflections are forced to activate after inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like \`300\_000\`, \`"5m"\`, or \`"1hr"\`. When the gap between the current time and the last assistant message part timestamp exceeds this value, buffered observational memory activates before the next prompt. Useful for aligning with prompt cache TTLs.
+
 **shareTokenBudget** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
+**temporalMarkers** (`boolean`): Insert temporal-gap reminder markers before new user messages when the previous message in the thread is at least 10 minutes older. The marker is persisted in memory, emitted as an inline reminder event so clients can render it specially, and shown to the observer so it can anchor observations to when events occurred. (Default: `false`)
+
 **retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. \`true\` enables cross-thread browsing by default. \`{ vector: true }\` also enables semantic search using Memory's vector store and embedder. \`{ scope: 'thread' }\` restricts the recall tool to the current thread only. Default scope is \`'resource'\`. (Default: `false`)
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.

package/dist/docs/references/reference-storage-redis.md

@@ -0,0 +1,266 @@
+# Redis Storage
+
+The Redis storage implementation provides a high-performance storage solution using direct Redis connections via [node-redis](https://github.com/redis/node-redis) (the official Redis client for Node.js). It supports standalone Redis, and through custom client configuration, Redis Sentinel and Cluster deployments.
+
+## Installation
+
+```bash
+npm install @mastra/redis
+```
+
+## Usage
+
+### Using Connection String
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  connectionString: 'redis://localhost:6379',
+})
+
+await storage.init()
+```
+
+### Using Host/Port Configuration
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  host: 'localhost',
+  port: 6379,
+  password: 'your-password',
+  db: 0,
+})
+
+await storage.init()
+```
+
+### Using Pre-configured Client
+
+For advanced configurations like Sentinel or Cluster, you can pass a pre-configured redis client:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+import { createClient } from 'redis'
+
+const client = createClient({
+  url: 'redis://localhost:6379',
+  socket: {
+    reconnectStrategy: retries => Math.min(retries * 50, 2000),
+  },
+})
+
+// Connect the client before passing to RedisStore
+await client.connect()
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  client,
+})
+```
+
+## Parameters
+
+**id** (`string`): Unique identifier for the storage instance
+
+**connectionString** (`string`): Redis connection URL (e.g., \`redis\://localhost:6379\` or \`redis\://:password\@localhost:6379\`)
+
+**host** (`string`): Redis host address
+
+**port** (`number`): Redis port number (Default: `6379`)
+
+**password** (`string`): Redis password for authentication
+
+**db** (`number`): Redis database number (Default: `0`)
+
+**client** (`RedisClient`): Pre-configured redis client (from the \`redis\` package) for advanced setups
+
+> **Note:** You must provide either `connectionString`, `host`, or `client`. These options are mutually exclusive.
+
+## Additional Notes
+
+### Key Structure
+
+The Redis storage implementation uses the following key patterns:
+
+- Threads: `mastra_threads:id:{threadId}`
+- Messages: `mastra_messages:threadId:{threadId}:id:{messageId}`
+- Message index: `msg-idx:{messageId}` (for fast lookups)
+- Thread messages sorted set: `thread:{threadId}:messages`
+- Workflow snapshots: `mastra_workflow_snapshot:namespace:{ns}:workflow_name:{name}:run_id:{id}`
+- Scores: `mastra_scorers:id:{scoreId}`
+- Resources: `mastra_resources:{resourceId}`
+
+### Redis Sentinel
+
+For high-availability deployments using Redis Sentinel, create a custom client:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+import { createClient } from 'redis'
+
+const client = createClient({
+  url: 'redis://sentinel-host:26379',
+  // Configure sentinel options as needed for your setup
+})
+
+await client.connect()
+
+const storage = new RedisStore({
+  id: 'redis-sentinel-storage',
+  client,
+})
+```
+
+### Redis Cluster
+
+For Redis Cluster deployments, use the cluster client:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+import { createCluster } from 'redis'
+
+const cluster = createCluster({
+  rootNodes: [
+    { url: 'redis://node-1:6379' },
+    { url: 'redis://node-2:6379' },
+    { url: 'redis://node-3:6379' },
+  ],
+})
+
+await cluster.connect()
+
+const storage = new RedisStore({
+  id: 'redis-cluster-storage',
+  client: cluster,
+})
+```
+
+### Accessing the Underlying Client
+
+You can access the underlying redis client for custom operations:
+
+```typescript
+const storage = new RedisStore({
+  id: 'redis-storage',
+  connectionString: 'redis://localhost:6379',
+})
+
+await storage.init()
+
+const client = storage.getClient()
+
+// Custom Redis operations
+await client.set('custom-key', 'value')
+const value = await client.get('custom-key')
+```
+
+### Closing Connections
+
+When shutting down your application, close the Redis connection:
+
+```typescript
+await storage.close()
+```
+
+## Usage Example
+
+### Adding memory to an agent
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { RedisStore } from '@mastra/redis'
+
+export const redisAgent = new Agent({
+  id: 'redis-agent',
+  name: 'Redis Agent',
+  instructions:
+    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
+  model: 'openai/gpt-4o',
+  memory: new Memory({
+    storage: new RedisStore({
+      id: 'redis-agent-storage',
+      connectionString: process.env.REDIS_URL!,
+    }),
+    options: {
+      lastMessages: 10,
+    },
+  }),
+})
+```
+
+### Using the agent
+
+```typescript
+import 'dotenv/config'
+
+import { mastra } from './mastra'
+
+const threadId = '123'
+const resourceId = 'user-456'
+
+const agent = mastra.getAgent('redisAgent')
+
+const message = await agent.stream('My name is Mastra', {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+})
+
+await message.textStream.pipeTo(new WritableStream())
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+  memoryOptions: {
+    lastMessages: 5,
+  },
+})
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+### Using with Mastra instance
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'mastra-storage',
+  host: 'localhost',
+  port: 6379,
+})
+
+const mastra = new Mastra({
+  storage, // init() called automatically
+})
+```
+
+If using storage directly without Mastra, call `init()` explicitly:
+
+```typescript
+import { RedisStore } from '@mastra/redis'
+
+const storage = new RedisStore({
+  id: 'redis-storage',
+  host: 'localhost',
+  port: 6379,
+})
+
+await storage.init()
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory')
+const thread = await memoryStore?.getThreadById({ threadId: '...' })
+```

package/dist/docs/references/reference-vectors-mongodb.md

@@ -107,8 +107,6 @@ Searches for similar vectors with optional metadata filtering.
 
 **includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
 
-**minScore** (`number`): Minimum similarity score threshold (Default: `0`)
-
 ### `describeIndex()`
 
 Returns information about the index (collection).