Skip to content
reaatechREAATECH
Book a conversation

@reaatech/llm-cache-adapters-redis

pending npm

Provides a Redis storage adapter for the `llm-cache` library, enabling persistent key-value caching with support for batch operations and metadata-based invalidation. It exports a `RedisAdapter` class that implements the `StorageAdapter` interface for use with the `CacheEngine`.

source →

@reaatech/llm-cache-adapters-redis

npm version License: MIT CI

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Redis storage adapter for llm-cache exact-match metadata. Provides sub-millisecond key-value operations with automatic TTL via SETEX, connection pooling with reconnection, and key-space scanning for metadata queries.

Installation

terminal
npm install @reaatech/llm-cache-adapters-redis
# or
pnpm add @reaatech/llm-cache-adapters-redis

Feature Overview

  • Automatic TTL — every set() call uses SETEX for automatic Redis-side expiration
  • Connection pooling — single node-redis client with configurable reconnect strategy
  • Batch operations — getBatch, setBatch, and deleteBatch for bulk workloads
  • Metadata queries — findByUseCase and findByModelVersion via SCAN with in-process filtering
  • Invalidation — invalidateByCriteria supports useCase, modelVersion, generationConfigHash, embeddingModel, olderThan, and promptHash
  • Stats — getStats() returns keys count from Redis INFO keyspace
  • Health check — healthCheck() pings Redis and reports status

Quick Start

typescript
import { CacheEngine, OpenAIEmbedder } from "@reaatech/llm-cache";
import { RedisAdapter } from "@reaatech/llm-cache-adapters-redis";
 
const storage = new RedisAdapter({ url: "redis://localhost:6379" });
await storage.connect();
 
const cache = new CacheEngine({
  storage,
  vectorStorage: /* QdrantAdapter or InMemoryAdapter */,
  embedder: new OpenAIEmbedder({
    provider: "openai",
    model: "text-embedding-3-small",
    dimensions: 1536,
    apiKey: process.env.OPENAI_API_KEY,
  }),
  config: { /* ... */ },
});

API Reference

RedisAdapter (class)

Implements StorageAdapter from @reaatech/llm-cache.

typescript
import { RedisAdapter } from "@reaatech/llm-cache-adapters-redis";
 
const adapter = new RedisAdapter({ url: "redis://localhost:6379" });
await adapter.connect();

RedisAdapterConfig

PropertyTypeDefaultDescription
urlstring(required)Redis connection URL (supports redis://, rediss://, password in URL)
keyPrefixstringllm-cache:Prefix prepended to all Redis keys

Methods

MethodReturnsDescription
connect()Promise<void>Open the Redis connection (idempotent)
disconnect()Promise<void>Close the Redis connection
get(key)Promise<CacheEntry | null>Retrieve and deserialize a cache entry (auto-deletes if expired)
set(key, entry)Promise<void>Store an entry with TTL via SETEX (deletes instead if TTL ≤ 0)
delete(key)Promise<boolean>Remove a key
exists(key)Promise<boolean>Check if a key exists
getBatch(keys)Promise<(CacheEntry | null)[]>Batch retrieve via MGET
setBatch(items)Promise<void>Batch store via pipelined MULTI/EXEC
deleteBatch(keys)Promise<number>Batch delete via DEL (multiple keys)
findByUseCase(useCase, limit?)Promise<CacheEntry[]>Scan keyspace for entries matching a use case
findByModelVersion(modelVersion, limit?)Promise<CacheEntry[]>Scan keyspace for entries matching a model version
invalidateByCriteria(criteria)Promise<number>Delete all entries matching criteria (walks full keyspace)
getStats()Promise<StorageStats>Get approximate entry count from Redis INFO keyspace
healthCheck()Promise<HealthStatus>Ping Redis and report { healthy: boolean }

Usage Patterns

Custom Key Prefix

typescript
const adapter = new RedisAdapter({
  url: "redis://localhost:6379",
  keyPrefix: "myapp:cache:",
});
// Keys stored as: myapp:cache:<promptHash>:<generationConfigHash>

Authentication

typescript
// Password in URL
const adapter = new RedisAdapter({ url: "redis://:mypassword@localhost:6379" });
 
// TLS
const adapter = new RedisAdapter({ url: "rediss://localhost:6380" });

Performance Notes

  • get() and set() operate at sub-millisecond latency for typical payloads.
  • findByUseCase, findByModelVersion, and invalidateByCriteria use SCAN and walk the full keyspace — O(N) in cache size. Avoid calling these on hot request paths. Run from background jobs or deploy Redis Stack with RediSearch for indexed metadata queries.
  • setBatch pipelines operations through a single MULTI/EXEC block for efficiency.
  • This adapter implements exact-match metadata storage only. Semantic search requires a VectorStorageAdapter (e.g., QdrantAdapter).

Related Packages

License

MIT

All packagesllm-cache overview