strands.storage.storage

Unified storage interface and key-normalization helpers.

Storage

@runtime_checkable
class Storage(Protocol[ListQuery])

Defined in: src/strands/storage/storage.py:74

A backend for storing and retrieving raw bytes under string keys.

The interface is deliberately minimal — four operations over opaque bytes values. Keys are opaque strings — implementations must round-trip the bytes they are given unchanged. The shipped backends interpret ’/’ as a logical separator (collapsing runs, rejecting ’..’), but custom backends may apply their own key scheme.

The ListQuery type parameter controls what list accepts. It defaults to str (a key prefix), which every backend supports. Implementations may widen it to accept a richer query object while still accepting a plain string for SDK-internal callers.

Implement this to add a custom backend; the SDK ships :class:InMemoryStorage, :class:LocalFileStorage, and :class:S3Storage.

write

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

Defined in: src/strands/storage/storage.py:92

Store data under key, overwriting any existing value.

Arguments:

• key - Opaque string 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/storage.py:104

Retrieve the bytes previously stored under key.

Arguments:

• key - The key to read.

Returns:

The stored bytes, or None if no value exists for key.

Raises:

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

delete

async def delete(key: str) -> None

Defined in: src/strands/storage/storage.py:118

Delete the value stored under key. A no-op if the key does not exist.

Arguments:

• key - The key to delete.

Raises:

• StorageError - If the delete fails.

list

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

Defined in: src/strands/storage/storage.py:129

List keys matching the given prefix query.

Returns full keys (not the suffix after the prefix), sorted lexicographically. An empty string lists every key.

Arguments:

• query - A string prefix to match.

Returns:

The matching keys, sorted ascending.

Raises:

• StorageError - If the listing fails.

_NamespacedStorage

class _NamespacedStorage()

Defined in: src/strands/storage/storage.py:147

A storage view that prepends a prefix to all keys.

Composable — calling .namespace() on the result nests prefixes. Uses :func:_normalize_prefix to sanitize the prefix, so it assumes a ’/‘-separated key scheme. Backends with a different key scheme should implement their own namespacing.

write

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

Defined in: src/strands/storage/storage.py:163

Store data under the prefixed key.

read

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

Defined in: src/strands/storage/storage.py:167

Read from the prefixed key.

delete

async def delete(key: str) -> None

Defined in: src/strands/storage/storage.py:171

Delete the prefixed key.

list

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

Defined in: src/strands/storage/storage.py:175

List keys under the prefix, stripping it from results.

namespace

def namespace(prefix: str) -> _NamespacedStorage

Defined in: src/strands/storage/storage.py:180

Return a further-scoped view by nesting prefixes.

for_sandbox

def for_sandbox(sandbox: object) -> _NamespacedStorage

Defined in: src/strands/storage/storage.py:184

Delegate sandbox binding to the underlying storage and re-wrap.