Implementation:LMCache LMCache Valkey Connector

Knowledge Sources	LMCache
Domains	Caching, Storage Connectors, Valkey
Last Updated	2026-02-09 00:00 GMT

Overview

The Valkey connector module provides two RemoteConnector implementations for storing KV cache data in Valkey (a Redis-compatible key-value store): standalone (ValkeyConnector) and cluster (ValkeyClusterConnector), both using the Glide client library.

Description

This module implements two Valkey-backed storage connectors using the glide Python client library (Valkey Glide). ValkeyConnector connects to a single Valkey instance using GlideClient with optional authentication credentials and database ID selection. ValkeyClusterConnector connects to a Valkey cluster using GlideClusterClient, employing hash tags ({key}:metadata and {key}:kv_bytes) to ensure both metadata and data keys are routed to the same cluster slot. Both connectors store metadata and KV bytes as separate keys, using Batch or ClusterBatch operations to set both atomically in a single round-trip. The mget command is used to retrieve both metadata and data in one call. All operations are routed through an AsyncPQExecutor priority queue with four priority levels (PEEK, PREFETCH, GET, PUT). Connection initialization is performed asynchronously and bridged to the sync context via run_coroutine_threadsafe.

Usage

Use ValkeyConnector for single-instance Valkey deployments (URL format: valkey://host:port). Use ValkeyClusterConnector for Valkey cluster deployments (URL format: valkey-cluster://host1:port1,host2:port2). These connectors are preferred when using Valkey instead of Redis as the remote caching backend.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/storage_backend/connector/valkey_connector.py
• Lines: 1-395

Signature

class Priorities(IntEnum):
    PEEK = auto()
    PREFETCH = auto()
    GET = auto()
    PUT = auto()

class ValkeyConnector(RemoteConnector):
    def __init__(
        self,
        url: str,
        loop: asyncio.AbstractEventLoop,
        local_cpu_backend: LocalCPUBackend,
        username: str,
        password: str,
        database_id: Optional[int] = None,
    ): ...
    async def exists(self, key: CacheEngineKey) -> bool: ...
    def exists_sync(self, key: CacheEngineKey) -> bool: ...
    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]: ...
    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj): ...
    async def list(self) -> List[str]: ...
    async def close(self): ...

class ValkeyClusterConnector(RemoteConnector):
    def __init__(
        self,
        loop: asyncio.AbstractEventLoop,
        local_cpu_backend: LocalCPUBackend,
        username: str,
        password: str,
        hosts_and_ports: Optional[List[Tuple[str, int]]],
    ): ...
    async def exists(self, key: CacheEngineKey) -> bool: ...
    def exists_sync(self, key: CacheEngineKey) -> bool: ...
    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]: ...
    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj): ...
    async def list(self) -> List[str]: ...
    async def close(self): ...

Import

from lmcache.v1.storage_backend.connector.valkey_connector import (
    ValkeyConnector,
    ValkeyClusterConnector,
)

I/O Contract

Inputs

Name	Type	Required	Description
url	str	Yes (ValkeyConnector)	Valkey host:port string (e.g., "localhost:6379")
loop	asyncio.AbstractEventLoop	Yes	Asyncio event loop for async operations
local_cpu_backend	LocalCPUBackend	Yes	CPU backend for memory allocation
username	str	Yes	Valkey authentication username (can be empty)
password	str	Yes	Valkey authentication password (can be empty)
database_id	Optional[int]	No	Valkey database ID for standalone connector (default: None)
hosts_and_ports	Optional[List[Tuple[str, int]]]	Yes (ValkeyClusterConnector)	List of (host, port) tuples for cluster nodes

Outputs

Name	Type	Description
ValkeyConnector	RemoteConnector	Standalone Valkey connector using GlideClient with batch operations
ValkeyClusterConnector	RemoteConnector	Cluster Valkey connector using GlideClusterClient with hash-tag slot routing

Usage Examples

from lmcache.v1.storage_backend.connector.valkey_connector import ValkeyConnector

# Standalone Valkey
connector = ValkeyConnector(
    url="localhost:6379",
    loop=asyncio.get_event_loop(),
    local_cpu_backend=local_cpu_backend,
    username="",
    password="",
    database_id=0,
)

# Store KV cache using batch operations
await connector.put(key, memory_obj)

# Retrieve KV cache using mget (metadata + data in one call)
result = await connector.get(key)

# Close connection
await connector.close()