strands.storage.storage

Unified storage interface and key-normalization helpers.

StorageSearchResult

@dataclass
class StorageSearchResult()

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

A single result from a storage search call.

Attributes:

• key - Storage key of the matched item.
• score - Relevance score; higher values indicate greater relevance. Backends using distance-based scoring (e.g. vector distance) must invert to similarity before returning results.
• data - Stored bytes, present only when the backend includes them.

Storage

@runtime_checkable
class Storage(Protocol[ListQuery, SearchQuery])

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

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:111

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:123

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:137

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:148

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.

search

async def search(query: SearchQuery) -> builtins.list[StorageSearchResult]

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

Search stored content by query.

The default implementation uses :class:~strands.storage.search.KeywordSearchStrategy (token-overlap scoring over all keys). Backends may override with a richer strategy (vector similarity, full-text index, etc.).

The SearchQuery type parameter controls what this method accepts. It defaults to str (a natural-language query). Implementations may widen it to accept richer query objects (e.g. a pre-computed embedding vector with metadata filters).

Arguments:

• query - A string query or backend-specific query object.

Returns:

Matched keys with relevance scores, ranked best-first.

_NamespacedStorage

class _NamespacedStorage()

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

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:203

Store data under the prefixed key.

read

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

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

Read from the prefixed key.

delete

async def delete(key: str) -> None

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

Delete the prefixed key.

list

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

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

List keys under the prefix, stripping it from results.

search

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

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

Search within this namespace, filtering results to the prefix.

namespace

def namespace(prefix: str) -> _NamespacedStorage

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

Return a further-scoped view by nesting prefixes.

for_sandbox

def for_sandbox(sandbox: object) -> _NamespacedStorage

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

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