Implementation:LMCache LMCache Mooncake Lookup Client

Knowledge Sources	LMCache
Domains	KV Cache, Distributed Storage
Last Updated	2026-02-09 00:00 GMT

Overview

MooncakeLookupClient is a lookup client that queries the Mooncake distributed store to determine which KV cache chunks are available remotely.

Description

This client implements LookupClientInterface and uses the Mooncake distributed store backend for cache existence checks. During initialization, it sets up a MooncakeDistributedStore connection using peer-to-peer handshake over TCP and creates a ChunkedTokenDatabase for processing tokens into cache engine keys. The lookup method converts token IDs to CacheEngineKey strings, performs a batch existence check via batch_is_exist, and returns the end position of the longest contiguous prefix of found chunks. Blending mode is not currently supported.

Usage

Use this client when LMCache is configured to use the Mooncake distributed store as a remote KV cache backend. It is suitable for multi-node deployments where cache data is shared across machines via the Mooncake transfer engine.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/lookup_client/mooncake_lookup_client.py
• Lines: 1-87

Signature

class MooncakeLookupClient(LookupClientInterface):
    def __init__(
        self,
        config: LMCacheEngineConfig,
        metadata: LMCacheMetadata,
        master_addr: str,
    ): ...

    def lookup(
        self,
        token_ids: Union[torch.Tensor, list[int]],
        lookup_id: Optional[str] = None,
        request_configs: Optional[dict] = None,
    ) -> Optional[int]: ...

    def supports_producer_reuse(self) -> bool: ...

    def close(self): ...

Import

from lmcache.v1.lookup_client.mooncake_lookup_client import MooncakeLookupClient

I/O Contract

Inputs

Name	Type	Required	Description
config	LMCacheEngineConfig	Yes	The LMCache engine configuration
metadata	LMCacheMetadata	Yes	Metadata extracted from the serving engine
master_addr	str	Yes	Address of the Mooncake master node for distributed store setup
token_ids	Union[torch.Tensor, list[int]]	Yes	Token IDs to look up in the distributed store
lookup_id	Optional[str]	No	Unique identifier for this lookup request
request_configs	Optional[dict]	No	Additional per-request configuration options

Outputs

Name	Type	Description
lookup result	Optional[int]	End position of the longest prefix of contiguous found chunks, or 0 if none found
supports_producer_reuse	bool	Always returns True

Usage Examples

from lmcache.v1.lookup_client.mooncake_lookup_client import MooncakeLookupClient

# Initialize with Mooncake master address
client = MooncakeLookupClient(config, metadata, master_addr="192.168.1.100:12345")

# Perform a lookup against the distributed store
matched_tokens = client.lookup(token_ids=[10, 20, 30, 40, 50])

# Clean up
client.close()