Skip to main content

strands-dynamodb-storage (Python)

Python implementation of the Amazon DynamoDB Storage backend for the Strands Agents SDK — at parity with ../typescript/. Implements the SDK's strands.storage.Storage protocol (write/read/delete/list, plus namespace) so one DynamoDB-backed instance serves Session Manager, Memory Manager, and any subsystem that persists bytes.

Install

pip install strands-dynamodb-storage

Usage

from strands import Agent
from strands.session import SnapshotSessionManager
from strands_dynamodb_storage import DynamoDBStorage

storage = DynamoDBStorage("agent-data", region_name="us-east-1")
agent = Agent(session_manager=SnapshotSessionManager(storage=storage))

The same instance backs any subsystem that accepts a Storage, for example the context manager's stash (strands-agents 1.56.0 or later):

from strands import Agent

agent = Agent(storage=storage, context_manager="auto")

The stash writes each message's content under context/<session_id>/ in the agent's storage and registers a retrieve_context tool to read originals back. A session manager deletes it with the session; without one, each run gets a new session ID, so set ttl_seconds to expire old stashes.

Direct byte usage (async):

store = DynamoDBStorage("agent-data", region_name="us-east-1")
await store.write("sessions/s1/snapshot.json", b'{"turn": 1}')
data = await store.read("sessions/s1/snapshot.json")           # bytes | None
keys = await store.list("sessions/s1/")                         # native Query
# Note: prefixes must cover at least a full scope and identifier ("scope/id/").
# list("") and single-segment prefixes are rejected as too broad -- they would
# require a cross-partition Scan. This deliberately narrows the SDK Storage
# contract (whose in-memory backends list everything on ""); SDK subsystems
# always pass namespaced prefixes and are unaffected.
scoped = await store.list(DynamoDBListQuery(pk="sessions/s1", sk_prefix="scopes/"))
await store.delete("sessions/s1/snapshot.json")

Features (parity with the TypeScript package)

  • Single-table design (pk/sk), with a structured DynamoDBListQuery extension point.
  • Optional Amazon S3 offload for values above the item-size limit (s3_bucket=...).
  • Optional gzip compression="gzip" (applied before the offload check).
  • Optional per-item TTL (ttl_seconds=...) with read/list/search expiry filtering.
  • Native vector search() via Amazon DynamoDB vector indexes (SearchVectors, requires boto3 >= 1.43.64); a vector_search adapter can override the call.
  • DynamoDBMemoryStore, a Strands MemoryStore for the Memory Manager, with BedrockEmbedder (Amazon Titan Text Embeddings V2, Cohere Embed v3 and v4).
  • DynamoDBVectorSearchStrategy, a Strands SearchStrategy over the same vector index, for text search through DynamoDBStorage (such as the SDK's FileMemoryStore).

Long-term memory

DynamoDBMemoryStore gives the Strands Memory Manager a long-term memory on the same table. It embeds each memory through Amazon Bedrock, stores the text with its embedding, and finds memories by meaning with one SearchVectors call. The table needs the vector index from the repository README's Provisioning and permissions, with Dimensions 1024 for the default embedder (Amazon Titan Text Embeddings V2).

from strands import Agent
from strands.memory import MemoryManager
from strands_dynamodb_storage import DynamoDBMemoryStore, DynamoDBStorage

storage = DynamoDBStorage("agent-storage", region_name="us-east-1").namespace("user/u1")
memory = DynamoDBMemoryStore(storage)
agent = Agent(memory_manager=MemoryManager(stores=[memory], add_tool_config=True))

# The store also works on its own.
key = await memory.add("Prefers a window seat", {"source": "chat"})
entries = await memory.search("Where does the user like to sit?")
entries[0].content   # "Prefers a window seat"
entries[0].metadata  # {"source": "chat", "_key": "memory/dynamodb/8b29884b...", "_score": 0.59}

How it behaves:

  • One item per memory. A memory is stored at memory/<name>/<id> inside the storage namespace, where <name> is the store name (default dynamodb) and <id> is a hash of the text. Adding the same text again overwrites that item, replacing its metadata, so retried writes do not create duplicates. await storage.delete((entry.metadata or {})["_key"]) removes a memory.
  • Two calls per operation. add() makes one Bedrock call and one PutItem; search() makes one Bedrock call and one SearchVectors, pinned to the partition that holds the namespace. With the index projection ALL, memories come back from the index, so a search reads no base-table items; a memory large enough to be offloaded to S3 costs one GetItem and one S3 read. Results come closest first; _score is the raw index score (lower is closer for COSINE).
  • One memory store per partition. The partition is the first two segments of the full key: namespace("user/u1") gives the store partition user/u1, but user/u1/agent-a and user/u1/agent-b share partition user/u1. Every item with a vector in the partition competes for the same search results, and the store drops matches that are not its own memories before reading them, so a second memory store (or the application's own vector items) in the partition costs no extra reads but can leave results short of max_search_results. Give each memory store a two-segment namespace of its own, such as user/<id>.
  • Only memories are embedded. Session snapshots and other values written through the same storage never call Bedrock.
  • TTL applies. With ttl_seconds on the storage, memories expire like any other item, and search drops expired matches.
  • Metadata values that are strings, booleans, or numbers that are zero or from 1e-130 to 2**53 - 1 in magnitude are kept, the same set the TypeScript package accepts. Other values (lists, nested dicts, None, numbers outside that range), keys or strings containing a lone surrogate (which DynamoDB stores as ?), empty keys, the keys __proto__ and constructor (which the AWS SDK for JavaScript cannot write), and the reserved keys _key and _score are dropped with a logged warning, so a memory whose metadata came from a model's extraction is still stored.

The default embedder runs in the storage's Region with its boto_session and boto_client_config, and needs bedrock:InvokeModel on the model. When the storage was given a client, the embedder takes that client's Region but resolves its own credentials through the standard chain; pass BedrockEmbedder(client=...) to control them. To use another model, pass an embedder. dimensions must match the index's Dimensions; a mismatch fails the write or search with a StorageError whose cause names the expected and actual sizes:

from strands_dynamodb_storage import BedrockEmbedder

# Cohere Embed v4 through a cross-Region inference profile; Cohere embeds memories and
# queries with separate input types.
memory = DynamoDBMemoryStore(storage, embedder=BedrockEmbedder("us.cohere.embed-v4:0", dimensions=1024))

# Any other model: a function from text to a list of floats (sync or async), an object with an
# `embed(self, text, purpose)` method (sync or async) where purpose is "document" or "query", or
# a Strands SDK `strands.storage.search.Embedder` (strands-agents 1.64.0 or later), whose
# `embed(text)` takes only the text.
memory = DynamoDBMemoryStore(storage, embedder=lambda text: my_model.encode(text).tolist())

BedrockEmbedder supports Titan Text Embeddings V2 (256, 512, or 1024 dimensions), Cohere Embed v3 English and multilingual (1024), and Cohere Embed v4 (256, 512, 1024, or 1536), by model ID, cross-Region inference profile ID, or ARN. An application inference profile or provisioned model ARN does not name the model, so pass its request format as well: BedrockEmbedder(profile_arn, model_family="amazon.titan-embed-text-v2"). Bedrock limits the input size. Titan Text Embeddings V2 rejects a text over 8,192 tokens or 50,000 characters, and Cohere Embed v3 a text over 2,048 characters; either fails with a StorageError that carries Bedrock's message. Cohere Embed v3 also embeds only the first 512 tokens of a text, without an error, so a long memory is found by its beginning. Cohere Embed v4 accepts up to about 128,000 tokens per text.

search() is the lower-level API under the memory store: write each item with its embedding, then query by vector. Scoring runs in the database against a DynamoDB vector index (no second vector store, no ETL), and because the index is partitioned on pk, every search is scoped to the caller's key space -- one tenant's memories can never surface in another's results. Creating the table with a vector index (and the IAM permissions needed) is covered in the repository README's Provisioning and permissions.

Two behaviours to know: pk is required whenever the index's SearchSchema declares a HASH element (the provisioning guide's setup does) and must be omitted when it doesn't. And with TTL enabled, search() drops matches whose expiry has passed, reading the TTL attribute from the vector index at no extra read cost. That needs the index to project it (ALL, or INCLUDE listing the TTL attribute); with a narrower projection matches are returned unfiltered. A vector_search adapter opts in by returning expire_at (epoch seconds) on each match. Expired matches are not back-filled, so a search can return fewer than top_k results, and an item whose TTL was just renewed can be briefly hidden until the index catches up with the write.

from strands_dynamodb_storage import DynamoDBStorage, SearchQuery

store = DynamoDBStorage("agent-memory", region_name="us-east-1", prefix="user/u1")

# store a memory with its embedding (kept inline even when the payload offloads to S3)
await store.write(
    "memories/m1",
    b"likes window seats",
    vector=embed("likes window seats"),   # your embedding model, e.g. 1024 floats
    metadata={"kind": "preference"},
)

# recall by meaning, scoped to this store's partition
results = await store.search(SearchQuery(
    vector=embed("seating preferences?"),
    top_k=5,
    pk=store.partition_key("memories/m1"),  # the partition holding these keys ("user/u1")
    filter={"kind": "preference"},        # optional metadata equality filter
    include_values=True,                  # hydrate each match's stored bytes
))
for r in results:
    print(r.key, r.score, r.data)
# ordered most-similar-first; score direction follows the index's distance function
# (COSINE/EUCLIDEAN: lower = nearer; DOT_PRODUCT: higher = more similar)

A plain-string search() does not embed the text. It goes to the search_strategy passed to the constructor, which also indexes every write and is shared with namespace() views. Without one, it uses the SDK's KeywordSearchStrategy (strands-agents 1.54.0 or later), which lists every key and so works on a namespace at least two segments deep, such as store.namespace("user/u1"); on a broader storage the listing is rejected as too broad. Keyword scores rank higher as more relevant, unlike vector scores.

from strands.storage.search import KeywordSearchStrategy

store = DynamoDBStorage("agent-data", search_strategy=KeywordSearchStrategy())

Vector search strategy

DynamoDBVectorSearchStrategy is the DynamoDB counterpart of the SDK's S3VectorSearchStrategy: search by meaning over the table's vector index, for anything that searches through a Storage. Each write embeds the value and stores its vector on the same item, in the same request; a plain-string search embeds the query and returns results best first, with higher scores closer. Its embedder is any SDK Embedder (strands-agents 1.64.0 or later), BedrockEmbedder (the default, which is itself an SDK Embedder), or a function from text to vector. The strategy needs strands-agents 1.54.0 or later.

from strands.vended_memory_stores.file_memory_store import FileMemoryStore
from strands_dynamodb_storage import DynamoDBStorage, DynamoDBVectorSearchStrategy

storage = DynamoDBStorage("agent-memory", search_strategy=DynamoDBVectorSearchStrategy())
knowledge = FileMemoryStore(name="facts", storage=storage)

Every write through the storage is embedded, so give the strategy a storage of its own rather than the agent's. Searches are pinned to one partition, so use it on a storage namespaced at least two segments deep, as FileMemoryStore's memory/<name> is. Each value is embedded whole and must fit the embedding model's input; if embedding fails, write raises and stores nothing. Values written before the strategy was configured have no vector until rewritten, or passed to index(). Pass distance_function when the index doesn't use COSINE.

Like a global secondary index, the vector index is eventually consistent, and a freshly created index backfills before it is searchable. Requires boto3 >= 1.43.64; a vector_search adapter, when configured, overrides the native call (testing, custom routing).

Examples

Runnable, live-verified examples for every capability, from session resume to a customer-support capstone, live in the examples library.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q            # unit tests (moto, offline)
.venv/bin/ruff check src tests && .venv/bin/mypy src
RUN_INTEG=1 AWS_REGION=us-east-1 .venv/bin/python -m pytest tests/integ -q   # real DynamoDB + S3

Metadata

Release files for strands-dynamodb-storage 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for strands-dynamodb-storage 0.3.0
File Size Uploaded Provenance Actions
strands_dynamodb_storage-0.3.0.tar.gz 64.9 kB With provenance Details for strands_dynamodb_storage-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for strands-dynamodb-storage 0.3.0
File Interpreter ABI Platform Actions
strands_dynamodb_storage-0.3.0-py3-none-any.whl Python 3 none any Details for strands_dynamodb_storage-0.3.0-py3-none-any.whl

Total release size: 104.3 kB

Release files / strands_dynamodb_storage-0.3.0.tar.gz

Download URL strands_dynamodb_storage-0.3.0.tar.gz
Size 64.9 kB
Tags Source
SHA-256 checksum
How to use checksums
bf79dd90d8c0e13fdf343e5c8b10caa9393688bee80b7fcbc043803216e1812d
BLAKE2b-256 checksum
How to use checksums
e349c636fecc1d7e716819ae682e92084050f1924dfed7e85fe60604921de271
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / strands_dynamodb_storage-0.3.0-py3-none-any.whl

Download URL strands_dynamodb_storage-0.3.0-py3-none-any.whl
Size 39.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
974fbece4e86306f9fd00c3ab2cb5441993a55e324e415530211d46fac3317d9
BLAKE2b-256 checksum
How to use checksums
9658bbf984db20257611467c3bc24c475f4cee447764c3aec8cbb1af123de769
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for strands-dynamodb-storage 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for strands_dynamodb_storage-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page