Skip to content
Strands Harness
PYPython SDKTSTypeScript SDK
Strands
EVEvalsSHShell
Organizations
strands-agentsstrands-labs

strands.storage.local_file_storage

Local filesystem storage implementation.

LocalFileStorage

Section titled “LocalFileStorage”
class LocalFileStorage()

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

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__

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

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

Initialize local file storage.

Arguments:

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

base_dir

Section titled “base_dir”
@property
def base_dir() -> str

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

The root directory under which all keys are stored.

for_sandbox

Section titled “for_sandbox”
def for_sandbox(sandbox: Sandbox) -> LocalFileStorage

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

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

Section titled “write”
async def write(key: str, data: bytes) -> None

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

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 string key identifying the value.
  • data - Raw bytes to persist.

Raises:

  • StorageError - If the write fails.

read

Section titled “read”
async def read(key: str) -> bytes | None

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

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

Section titled “delete”
async def delete(key: str) -> None

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

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

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

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

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.
Section titled “search”
async def search(query: str) -> builtins.list[StorageSearchResult]

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

Search stored content by keyword token-overlap scoring.

Arguments:

  • query - Natural-language search query.

Returns:

All matches with relevance scores, ranked best-first.

namespace

Section titled “namespace”
def namespace(prefix: str) -> LocalFileStorage

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

Return a new LocalFileStorage scoped to a subdirectory.

Unlike a generic _NamespacedStorage wrapper, this returns a real LocalFileStorage whose base_dir incorporates the prefix. This preserves access to base_dir for strategies that need the filesystem path (e.g. index-based search), and for_sandbox continues to work.

Arguments:

  • prefix - Prefix to prepend to all keys.

Returns:

A new LocalFileStorage rooted at the sub-path.