Implementation:LMCache LMCache KVController Lookup

Knowledge Sources	LMCache
Domains	Cluster_Management, Monitoring
Last Updated	2026-02-09 00:00 GMT

Overview

Concrete tool for looking up KV cache entries across cluster instances, provided by the KVController class.

Description

The KVController class provides REST API handlers for cluster-level KV cache operations: lookup, move, pin, clear, and compress. The lookup method queries the registry tree to find which instances hold specific token prefixes. All mutating operations (move, pin, clear, compress) are dispatched via the LMCacheClusterExecutor which sends ZMQ messages to target workers.

Usage

Send REST API requests to the controller's endpoints. The controller REST API is automatically registered when the controller is launched.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/cache_controller/controllers/kv_controller.py
• Lines: L55-L440

Signature

class KVController:
    def __init__(
        self,
        registry: RegistryTree,
        full_sync_completion_threshold: float = 0.8,
        full_sync_timeout_s: float = 300.0,
    ):
        """
        Args:
            registry: Global registry of KV cache entries across instances
            full_sync_completion_threshold: Worker fraction needed for full sync
            full_sync_timeout_s: Timeout for full sync operations
        """

    async def lookup(self, msg: LookupMsg) -> LookupRetMsg:
        """Look up which instances hold specific cache entries."""

    async def move(self, msg: MoveMsg) -> MoveRetMsg:
        """Move cache entries between instances."""

    async def pin(self, msg: PinMsg) -> PinRetMsg:
        """Pin cache entries to prevent eviction."""

    async def clear(self, msg: ClearMsg) -> ClearRetMsg:
        """Clear cache entries from instances."""

    async def compress(self, msg: CompressMsg) -> CompressRetMsg:
        """Compress cache entries on instances."""

Import

from lmcache.v1.cache_controller.controllers.kv_controller import KVController

I/O Contract

Inputs

Name	Type	Required	Description
msg	LookupMsg/MoveMsg/PinMsg/ClearMsg/CompressMsg	Yes	Operation-specific message with instance_id and parameters

Outputs

Name	Type	Description
return	LookupRetMsg/MoveRetMsg/etc.	Operation-specific response with results

Usage Examples

Lookup via REST API

curl -X POST http://localhost:9000/lookup \
    -H "Content-Type: application/json" \
    -d '{"instance_id": "lmcache_instance_1", "tokens": [1, 2, 3, 4]}'

Clear Cache via REST API

curl -X POST http://localhost:9000/clear \
    -H "Content-Type: application/json" \
    -d '{"event_id": "clear_001", "instance_id": "lmcache_instance_1", "location": "local_cpu"}'

Related Pages

Implements Principle

• Principle:LMCache_LMCache_Cluster_Management