Upstash 存储

🌐 Upstash Storage

Upstash 存储实现提供了一种无服务器友好的存储解决方案，使用 Upstash 的兼容 Redis 的键值存储。

🌐 The Upstash storage implementation provides a serverless-friendly storage solution using Upstash's Redis-compatible key-value store.

Pricing

When using Mastra with Upstash, the pay-as-you-go model can result in unexpectedly high costs due to the high volume of Redis commands generated during agent conversations. We strongly recommend using a fixed pricing plan for predictable costs. See Upstash pricing for details and GitHub issue #5850 for context.

Observability Not Supported

Upstash storage does not support the observability domain. Traces from the DefaultExporter cannot be persisted to Upstash, and Mastra Studio's observability features won't work with Upstash as your only storage provider. To enable observability, use composite storage to route observability data to a supported provider like ClickHouse or PostgreSQL.

安装

🌐 Installation

npm

npm install @mastra/upstash@latest

pnpm

pnpm add @mastra/upstash@latest

Yarn

yarn add @mastra/upstash@latest

Bun

bun add @mastra/upstash@latest

用法

🌐 Usage

import { UpstashStore } from "@mastra/upstash";

const storage = new UpstashStore({
  id: 'upstash-storage',
  url: process.env.UPSTASH_URL,
  token: process.env.UPSTASH_TOKEN,
});

参数

🌐 Parameters

url:

string

Upstash Redis URL

token:

string

Upstash Redis authentication token

prefix?:

string

= mastra:

Key prefix for all stored items

附加说明

🌐 Additional Notes

关键结构

🌐 Key Structure

Upstash 存储实现使用键值结构：

🌐 The Upstash storage implementation uses a key-value structure:

• 线程键：{prefix}thread:{threadId}
• 消息键：{prefix}message:{messageId}
• 元数据键：{prefix}metadata:{entityId}

无服务器的优势

🌐 Serverless Benefits

Upstash 存储特别适合无服务器部署：

🌐 Upstash storage is particularly well-suited for serverless deployments:

• 无需连接管理
• 按请求付费定价
• 全局复制选项
• 兼容 Edge

数据持久性

🌐 Data Persistence

Upstash 提供：

🌐 Upstash provides:

• 自动数据持久化
• 时间点恢复
• 跨区域复制选项

性能考虑

🌐 Performance Considerations

为了获得最佳性能：

🌐 For optimal performance:

• 使用适当的键前缀来整理数据
• 监控 Redis 内存使用情况
• 如有必要，请考虑数据过期策略

使用示例

🌐 Usage Example

为代理添加内存

🌐 Adding memory to an agent

要向代理添加 Upstash 内存，请使用 Memory 类，并使用 UpstashStore 创建一个新的 storage 密钥，以及使用 UpstashVector 创建一个新的 vector 密钥。配置可以指向远程服务或本地设置。

🌐 To add Upstash memory to an agent use the Memory class and create a new storage key using UpstashStore and a new vector key using UpstashVector. The configuration can point to either a remote service or a local setup.

src/mastra/agents/example-upstash-agent.ts

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { UpstashStore } from "@mastra/upstash";

export const upstashAgent = new Agent({
  id: "upstash-agent",
  name: "Upstash Agent",
  instructions:
    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
  model: "openai/gpt-5.1",
  memory: new Memory({
    storage: new UpstashStore({
      id: 'upstash-agent-storage',
      url: process.env.UPSTASH_REDIS_REST_URL!,
      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    }),
    options: {
      generateTitle: true, // Explicitly enable automatic title generation
    },
  }),
});

使用代理

🌐 Using the agent

使用 memoryOptions 来限定此请求的回忆范围。设置 lastMessages: 5 以限制基于最近性的回忆，使用 semanticRecall 获取最相关的 topK: 3 条消息，包括每个匹配消息周围的 messageRange: 2 条邻近消息以提供上下文。

🌐 Use memoryOptions to scope recall for this request. Set lastMessages: 5 to limit recency-based recall, and use semanticRecall to fetch the topK: 3 most relevant messages, including messageRange: 2 neighboring messages for context around each match.

src/test-upstash-agent.ts

import "dotenv/config";

import { mastra } from "./mastra";

const threadId = "123";
const resourceId = "user-456";

const agent = mastra.getAgent("upstashAgent");

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,
    semanticRecall: {
      topK: 3,
      messageRange: 2,
    },
  },
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}