Implementation:LMCache LMCache FS Connector

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

Overview

FSConnector is a file-system-based remote connector that stores KV cache data as individual files on local or network-attached storage with support for multiple base paths, O_DIRECT, and read-ahead optimization.

Description

The FSConnector stores each cache key as a separate file under one or more configurable base directories. When multiple base paths are provided (comma-separated), keys are distributed across them using a hash-based modulo scheme on the chunk hash. Each file contains optional metadata (a serialized RemoteMetadata header) followed by the raw KV cache byte data. The connector supports several performance optimizations: O_DIRECT for bypassing the OS page cache (when block-size alignment is satisfied and chunk metadata saving is disabled), configurable read-ahead sizes for triggering filesystem prefetch, and temporary file directories for atomic writes via rename. Write operations use a temp-file-then-rename pattern to ensure atomicity. Async file I/O is provided via aiofiles.

Usage

Use FSConnector when you want to persist KV cache data to a local filesystem, shared filesystem (NFS, Lustre), or any mounted volume. It is suitable for scenarios where a dedicated caching service (Redis, Valkey) is not available or when local disk persistence is preferred. The remote URL should specify a filesystem path.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/storage_backend/connector/fs_connector.py
• Lines: 1-378

Signature

class FSConnector(RemoteConnector):
    def __init__(
        self,
        base_paths_str: str,
        loop: asyncio.AbstractEventLoop,
        local_cpu_backend: LocalCPUBackend,
        config: Optional[LMCacheEngineConfig],
    ): ...
    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): ...
    def remove_sync(self, key: CacheEngineKey) -> bool: ...
    async def list(self) -> List[str]: ...
    async def close(self): ...

Import

from lmcache.v1.storage_backend.connector.fs_connector import FSConnector

I/O Contract

Inputs

Name	Type	Required	Description
base_paths_str	str	Yes	Comma-separated list of directory paths for storing cache files
loop	asyncio.AbstractEventLoop	Yes	Asyncio event loop for async operations
local_cpu_backend	LocalCPUBackend	Yes	CPU backend for memory allocation and providing config/metadata
config	Optional[LMCacheEngineConfig]	No	Optional engine config for extra settings (fs_connector_relative_tmp_dir, fs_connector_read_ahead_size, fs_connector_use_odirect)

Outputs

Name	Type	Description
FSConnector	RemoteConnector	A file-system connector that stores each key as a separate .data file with optional metadata header

Usage Examples

from lmcache.v1.storage_backend.connector.fs_connector import FSConnector

# Initialize with a single base path
connector = FSConnector(
    base_paths_str="/mnt/cache/lmcache",
    loop=asyncio.get_event_loop(),
    local_cpu_backend=local_cpu_backend,
    config=lmcache_config,
)

# Initialize with multiple paths for distribution
connector = FSConnector(
    base_paths_str="/mnt/ssd1/cache,/mnt/ssd2/cache",
    loop=asyncio.get_event_loop(),
    local_cpu_backend=local_cpu_backend,
    config=lmcache_config,
)

# Store and retrieve
await connector.put(key, memory_obj)
result = await connector.get(key)

# Check existence
exists = await connector.exists(key)

# Remove a cached entry
connector.remove_sync(key)