Valkey

The Valkey storage implementation provides persistent storage and server-side caching through the Valkey GLIDE client. Use it when your deployment runs Valkey or needs GLIDE features such as native Valkey configuration and authentication.

Use @mastra/redis for Redis deployments that use the official redis client. The packages are tested independently against their respective servers.

Installation

npm

npm install @mastra/valkey

pnpm

pnpm add @mastra/valkey

Yarn

yarn add @mastra/valkey

Bun

bun add @mastra/valkey

Usage

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { ValkeyStore } from '@mastra/valkey'

export const mastra = new Mastra({
  storage: new ValkeyStore({
    id: 'valkey-storage',
    host: 'localhost',
    port: 6379,
    password: process.env.VALKEY_PASSWORD,
  }),
})

You can also provide a native GLIDE configuration:

import { ValkeyStore } from '@mastra/valkey'

const storage = new ValkeyStore({
  id: 'valkey-storage',
  config: {
    addresses: [{ host: 'localhost', port: 6379 }],
    useTLS: true,
  },
})

For an existing GlideClient, connect it before passing it to ValkeyStore. The caller remains responsible for closing injected clients.

Constructor parameters

id:

string

Unique identifier for the storage instance.

host?:

string

Valkey host address. Use with the direct connection fields.

port?:

number

= 6379

Valkey port.

username?:

string

= default

Valkey authentication username.

password?:

string

Valkey authentication password.

db?:

number

= 0

Valkey database number.

useTLS?:

boolean

Enables TLS for direct connections.

config?:

GlideClientConfiguration

Native GLIDE standalone client configuration.

client?:

GlideClient

Preconfigured GLIDE standalone client.

disableInit?:

boolean

Disables automatic storage initialization.

Provide exactly one connection form: client, config, or host with its optional direct connection fields.

Closing connections

Close clients created by ValkeyStore during graceful shutdown:

await storage.close()

close() doesn't close an injected GlideClient.