strands.storage.local_file_storage

Local filesystem storage implementation.

LocalFileStorage

class LocalFileStorage()

Defined in: src/strands/storage/local_file_storage.py:20

Persists each key as a file under a base directory.

Key segments separated by ’/’ map to directory segments. Writes on the host filesystem are atomic (write to temp file, then rename).

Example:

from strands.storage import LocalFileStorage

storage = LocalFileStorage("./.strands/")
await storage.write("session/abc/state.json", data)

__init__

def __init__(base_dir: str = "./.strands/",
             *,
             sandbox: Sandbox | None = None) -> None

Defined in: src/strands/storage/local_file_storage.py:35

Initialize local file storage.

Arguments:

• base_dir - Root directory under which all keys are stored.
• sandbox - Optional sandbox to route I/O through.

for_sandbox

def for_sandbox(sandbox: Sandbox) -> LocalFileStorage

Defined in: src/strands/storage/local_file_storage.py:45

Return a copy bound to the given sandbox.

If already bound to the same sandbox, returns self.

Arguments:

• sandbox - Sandbox to bind to.

Returns:

A LocalFileStorage instance bound to the sandbox.

write

async def write(key: str, data: bytes) -> None

Defined in: src/strands/storage/local_file_storage.py:60

Store data as a file, creating parent directories as needed.

On the host filesystem, writes are atomic via write-to-temp-then-rename.

Arguments:

• key - Opaque, ’/‘-separated key identifying the value.
• data - Raw bytes to persist.

Raises:

• StorageError - If the write fails.

read

async def read(key: str) -> bytes | None

Defined in: src/strands/storage/local_file_storage.py:99

Read the file corresponding to key.

Arguments:

• key - The key to read.

Returns:

The file contents as bytes, or None if the file does not exist.

Raises:

• StorageError - If the read fails for a reason other than a missing file.

delete

async def delete(key: str) -> None

Defined in: src/strands/storage/local_file_storage.py:127

Delete the file corresponding to key. No-op if it does not exist.

Arguments:

• key - The key to delete.

Raises:

• StorageError - If the delete fails.

list

async def list(query: str = "") -> builtins.list[str]

Defined in: src/strands/storage/local_file_storage.py:156

List keys matching the given prefix by walking the directory tree.

Arguments:

• query - A prefix string to filter keys. Empty string matches all.

Returns:

Matching keys sorted ascending.

Raises:

• StorageError - If the listing fails.

namespace

def namespace(prefix: str) -> _NamespacedStorage

Defined in: src/strands/storage/local_file_storage.py:181

Return a view of this storage with all keys prefixed.

The returned view preserves for_sandbox via delegation to the underlying storage, so sandbox routing works even when storage is pre-namespaced before being passed to a plugin.

Arguments:

• prefix - Prefix to prepend to all keys.

Returns:

A namespaced storage view.