Cache

Universal caching wrapper for AI SDK tools. Cache expensive tool executions with zero configuration - works with regular tools, streaming tools, and artifacts.

npm install @ai-sdk-tools/cache

Quick Start

import { cached } from '@ai-sdk-tools/cache'

const expensiveWeatherTool = tool({
  description: 'Get weather data',
  parameters: z.object({
    location: z.string()
  }),
  execute: async ({ location }) => {
    // Expensive API call
    return await weatherAPI.get(location)
  }
})

// Cache with one line
const weatherTool = cached(expensiveWeatherTool)

// First call: 2s API request
// Next calls: <1ms from cache ⚡

Universal Tool Support

Regular Tools (async function)

const apiTool = cached(tool({
  execute: async ({ query }) => {
    return await api.search(query) // Cached return value
  }
}))

Streaming Tools (async function*)

const streamingTool = cached(tool({
  execute: async function* ({ params }) {
    yield { text: "Processing..." } // Cached yields
    yield { text: "Complete!" }
  }
}))

Artifact Tools (with writer data)

const artifactTool = cached(tool({
  execute: async function* ({ data }) => {
    const analysis = artifact.stream({ ... })
    await analysis.update({ charts, metrics }) // Cached writer messages
    yield { text: "Done" }
  }
}))

Cache Backends

LRU Cache (Default)

import { cached } from '@ai-sdk-tools/cache'

// Uses LRU cache automatically
const weatherTool = cached(expensiveWeatherTool, {
  ttl: 10 * 60 * 1000, // 10 minutes
  maxSize: 1000, // Max 1000 cached items
})

Redis Cache (Production)

import { createCachedFunction, createCacheBackend } from '@ai-sdk-tools/cache'
import Redis from 'redis'

const redis = Redis.createClient({
  url: process.env.REDIS_URL
})

const redisBackend = createCacheBackend({
  type: 'redis',
  defaultTTL: 30 * 60 * 1000, // 30 minutes
  redis: {
    client: redis,
    keyPrefix: 'ai-tools:'
  }
})

export const cached = createCachedFunction(redisBackend)

Environment-Aware Setup

const backend = process.env.REDIS_URL 
  ? createCacheBackend({
      type: 'redis',
      defaultTTL: 30 * 60 * 1000,
      redis: { client: Redis.createClient({ url: process.env.REDIS_URL }) }
    })
  : createCacheBackend({
      type: 'lru',
      maxSize: 1000,
      defaultTTL: 10 * 60 * 1000
    })

export const cached = createCachedFunction(backend)
// Production: Redis, Development: LRU

Streaming Tools Requirements

For complete caching of streaming tools with artifacts, ensure your API route passes the writer:

// API route setup (required for artifact caching)
const stream = createUIMessageStream({
  execute: ({ writer }) => {
    setContext({ writer }) // Set up artifacts context
    
    const result = streamText({
      model: openai("gpt-4o"),
      tools: { analysis: cachedAnalysisTool },
      experimental_context: { writer }, // ← Essential for artifact caching
    })
    
    writer.merge(result.toUIMessageStream())
  }
})

Important: Without experimental_context: { writer }:

✅Streaming text is cached
❌Artifact data (charts, metrics) is missing on cache hits

With proper setup:

✅Complete data preservation - everything cached and restored

Performance Benefits

10x faster responses

for repeated requests

80% cost reduction

by avoiding duplicate calls

Smooth agent conversations

with instant cached results

Complete data preservation

streaming, artifacts, everything

API Reference

cached(tool, options?)

Wraps an AI SDK tool with caching capabilities.

Parameters

tool - Any AI SDK tool
options - Optional cache configuration

Options

ttl - Time to live in milliseconds (default: 5 minutes)
maxSize - Maximum cache size (default: 1000)
store - Custom cache backend
keyGenerator - Custom key generation function
shouldCache - Conditional caching function
onHit - Cache hit callback
onMiss - Cache miss callback
debug - Enable debug logging

createCachedFunction(store)

Creates a pre-configured cached function with a specific store.

createCacheBackend(config)

Creates a cache backend with the specified configuration.

Backend Types

lru - LRU cache (single instance)
redis - Redis cache (distributed)
memory - Simple memory cache
simple - Basic cache implementation

Best Practices

Use LRU cache for single instance applications

Use Redis cache for distributed/production applications

Set appropriate TTL values based on data freshness requirements

Use environment-aware configuration for seamless dev/prod switching

Enable debug mode during development to monitor cache behavior

Next Steps

Live Examples

Try interactive examples and see caching in action.

Try it out →

GitHub

View source code and more examples on GitHub.

View on GitHub →