Storage

To persist agent state between restarts, pass a Storage backend to the plugins that need it. You pick the backend once; plugins like Context Offloader, Session Management, and Memory handle the rest.

The SDK ships three backends. Pick one based on where you need your data to live:

Backend	Where data lives	Best for
InMemoryStorage	Process memory	Tests, short-lived agents
LocalFileStorage	Local filesystem	Development, single-machine
S3Storage	Amazon S3	Production, multi-instance

Usage

Pass a storage instance to whichever plugin needs persistence:

Python

storage = LocalFileStorage()

agent = Agent(plugins=[
    ContextOffloader(storage=storage)
])

TypeScript

import { LocalFileStorage } from '@strands-agents/sdk/storage'
import { Agent } from '@strands-agents/sdk'
import { ContextOffloader } from '@strands-agents/sdk/vended-plugins/context-offloader'

const storage = new LocalFileStorage()

const agent = new Agent({
  plugins: [new ContextOffloader({ storage })],
})

Built-in backends

InMemoryStorage

Data lives in process memory. No constructor arguments. Fast, zero-config, gone when the process exits.

Python

storage = InMemoryStorage()

TypeScript

import { InMemoryStorage } from '@strands-agents/sdk/storage'

const storage = new InMemoryStorage()

LocalFileStorage

Each key becomes a file under a base directory. Writes are atomic (temp file + rename).

Parameter	Default	Description
base_dirbaseDir	"./.strands/"	Root directory
sandboxsandbox	None/undefined	Optional Sandbox

Python

storage = LocalFileStorage("./my-data/")

TypeScript

import { LocalFileStorage } from '@strands-agents/sdk/storage'

const storage = new LocalFileStorage('./my-data/')

You can also bind a sandbox after construction with for_sandbox(sandbox)forSandbox(sandbox), which returns a new instance routed through the sandbox.

S3Storage

Stores data as objects in an S3 bucket. The AWS SDK loads lazily, so applications that never construct an S3Storage pay nothing.

Parameter	Default	Description
bucket	(required)	S3 bucket name
prefix	""	Key prefix (namespace within the bucket)
region_nameregion	None/undefined	AWS region override
boto_sessions3Client	None/undefined	Pre-configured client

Python

storage = S3Storage("my-bucket", prefix="agents/prod/")

TypeScript

import { S3Storage } from '@strands-agents/sdk/storage'

const storage = new S3Storage('my-bucket', {
  prefix: 'agents/prod/',
})

You cannot pass both a region and a pre-configured client; pick one or the other.

Custom backends

Implement four async methods (write, read, delete, listwrite, read, delete, list) and pass your class anywhere a Storage is accepted. In Python, Storage is a protocol; in TypeScript, implement the interface.

Community backends can add methods beyond the core four (e.g. search for vector similarity, or structured queries for databases like DynamoDB). Plugins that only need basic persistence use the four standard methods; plugins that need richer access can check for and use the extra surface your backend provides.

Plugins scope their own keys automatically, so you don’t need to worry about collisions between session data and offloaded content.

Next steps

• Context Offloader: offload large tool results
• Session Management: persist conversations across restarts
• Sandbox: route Storage I/O through a sandboxed environment

Tags

session-management4