strands.memory.types

Core types for the Strands memory module.

MemoryEntry

@dataclass
class MemoryEntry()

Defined in: src/strands/memory/types.py:25

A single memory entry retrieved from or stored to a memory store.

Attributes:

store_name - Name of the store this entry came from, set by MemoryManager.search. Stores need not set this themselves.

SearchOptions

class SearchOptions(TypedDict)

Defined in: src/strands/memory/types.py:38

Options passed to :meth:MemoryStore.search.

Store implementations may extend this with backend-specific fields; note that MemoryManager.search forwards only these base fields across its stores.

AddMessagesContext

@dataclass
class AddMessagesContext()

Defined in: src/strands/memory/types.py:49

Context the manager supplies to :meth:MemoryStore.add_messages.

Intentionally empty for now so fields can be added later without a breaking signature change.

MemorySearchOptions

class MemorySearchOptions(SearchOptions)

Defined in: src/strands/memory/types.py:57

Options for MemoryManager.search.

Attributes:

stores - Filter to specific stores by name. Omit to search all. A programmatic search with an empty list searches no stores, whereas the search_memory tool treats an empty list as “search all in-scope stores”.

MemoryAddOptions

class MemoryAddOptions(TypedDict)

Defined in: src/strands/memory/types.py:70

Options for MemoryManager.add.

Attributes:

stores - Filter to specific writable stores by name. Omit to write to all. A programmatic add with an empty list matches no store (raises), whereas the add_memory tool treats an empty list as “write to all in-scope stores”.

MemoryToolConfig

class MemoryToolConfig(TypedDict)

Defined in: src/strands/memory/types.py:84

Configuration for customizing a memory tool’s name or description.

MemoryAddToolConfig

class MemoryAddToolConfig(MemoryToolConfig)

Defined in: src/strands/memory/types.py:91

Configuration for the add_memory tool.

Attributes:

stores - The writable stores the tool may write to, as store names or :class:MemoryStore instances. Omit to allow all writable stores.
wait_for_writes - When True (default), wait for writes and return
```{“stored”` - …}(or surface a failure to the model). WhenFalse, fire-and-forget: return {“accepted”: …}“ once writes are dispatched; per-store failures are logged.

InjectionQueryContext

@dataclass
class InjectionQueryContext()

Defined in: src/strands/memory/types.py:108

Context passed to :attr:MemoryInjectionConfig.query.

Attributes:

messages - The current conversation, as data.

InjectionFormatContext

@dataclass
class InjectionFormatContext()

Defined in: src/strands/memory/types.py:119

Context passed to :attr:MemoryInjectionConfig.format.

Attributes:

entries - The retrieved memory entries to render.

InjectionQueryCallback

class InjectionQueryCallback(Protocol)

Defined in: src/strands/memory/types.py:129

Derives the injection search query from the current conversation.

Implemented by a plain function as well — the **kwargs tail lets the calling convention grow new keyword arguments without breaking existing callbacks.

call

def __call__(context: InjectionQueryContext, **kwargs: Any) -> str | None

Defined in: src/strands/memory/types.py:136

Return the search query, or None/"" to skip injection this call.

InjectionFormatCallback

class InjectionFormatCallback(Protocol)

Defined in: src/strands/memory/types.py:141

Renders retrieved memory entries into the injected text.

Implemented by a plain function as well — the **kwargs tail lets the calling convention grow new keyword arguments without breaking existing callbacks.

call

def __call__(context: InjectionFormatContext, **kwargs: Any) -> str

Defined in: src/strands/memory/types.py:148

Return the text to inject for the given entries.

MemoryInjectionConfig

class MemoryInjectionConfig(InjectionConfig)

Defined in: src/strands/memory/types.py:160

Configuration for memory context injection.

Extends the generic :class:~strands.injection.InjectionConfig (which carries trigger) with the memory-owned knobs: how many entries to retrieve, how to derive the query, and how to render the results.

Attributes:

max_entries - Maximum number of entries to retrieve and inject per model call. A store ranks by semantic similarity, which is not the same as contextual usefulness, so the default injects a small candidate set rather than betting on the top hit. Raising it improves recall at the cost of a larger prepend (context bloat); lower it for a tighter injection. With multiple stores, results are concatenated in store-registration order with no cross-store ranking, so this cap can favor entries from earlier-registered stores. Defaults to 5.
query - Derives the search query from the current conversation. Return None or an empty string to skip injection for this call. A callback that raises fails open (injection is skipped). Defaults to an adaptive query: the latest user message’s text on a user turn, otherwise the most recent assistant message’s text (the previous step on an autonomous turn).
format - Renders retrieved entries into the injected text. A callback that raises fails open (injection is skipped). Defaults to a <memory> XML block with one <entry> per result, carrying a source attribute naming the originating store (when known) so the model can attribute and weigh each memory. The default escapes entry content and source, so a custom format that emits markup is responsible for its own escaping.

MemoryManagerConfig

class MemoryManagerConfig(TypedDict)

Defined in: src/strands/memory/types.py:193

Configuration for the MemoryManager, mirroring the constructor kwargs.

Attributes:

stores - One or more memory stores to manage.
search_tool_config - Search tool configuration. Defaults to True.
add_tool_config - Add tool configuration. Defaults to False (opt-in); True allows all writable stores, or pass a :class:MemoryAddToolConfig to restrict it.
injection - Memory context injection. Defaults to True. True uses the default injection settings; pass a :class:MemoryInjectionConfig to customize retrieval, timing, and formatting; False disables it.

MemoryStoreConfig

class MemoryStoreConfig(TypedDict)

Defined in: src/strands/memory/types.py:213

Declarative identity and behavior fields a store is configured with.

Attributes:

name - Unique identifier for this store, used to target it in tools.
description - Human-readable description; included in tool descriptions.
max_search_results - Default maximum results per search, used when a caller does not pass a per-call value.
writable - Whether this store accepts writes. A writable store requires at least one write sink (:meth:MemoryStore.add or :meth:MemoryStore.add_messages).
extraction - Automatic-extraction configuration for this writable store, as a bool | config shorthand. True enables it with defaults; an :class:ExtractionConfig defaults any unset field; False/None is off. The defaults run every 5 turns, and the extraction method depends on the store’s write methods: a store implementing only add uses a :class:~strands.memory.extraction.model_extractor.ModelExtractor for client-side extraction (a model call to distill facts, stored via add), while a store implementing add_messages uses server-side extraction (the backend extracts the raw messages, no model call).

MemoryStore

class MemoryStore(Protocol)

Defined in: src/strands/memory/types.py:241

Runtime contract for a memory store backend.

A store exposes the :class:MemoryStoreConfig fields as attributes and implements :meth:search, plus optionally :meth:add, :meth:add_messages, and :meth:get_tools. The fields are re-declared here because a Protocol cannot extend a TypedDict.

Attributes:

name - Unique identifier for this store, used to target it in tools.
description - Human-readable description; included in tool descriptions.
max_search_results - Default maximum results per search.
writable - Whether this store accepts writes.
extraction - Resolved automatic-extraction configuration, or None/False when off.

search

async def search(query: str,
                 options: SearchOptions | None = None) -> list[MemoryEntry]

Defined in: src/strands/memory/types.py:262

Search the store for entries matching the query, ordered by relevance.

add

async def add(content: str, metadata: Metadata | None = None) -> Any

Defined in: src/strands/memory/types.py:268

Add a single piece of content to the store.

Extraction writes are at-least-once, so implementations used with extraction should tolerate duplicate writes. The resolved value is store-specific and not consumed by the manager.

add_messages

async def add_messages(messages: list[Message],
                       context: AddMessagesContext | None = None) -> Any

Defined in: src/strands/memory/types.py:277

Ingest a batch of conversation messages, preserving role structure.

The sink for extraction without a client-side extractor: the manager hands the filtered batch straight here. The resolved value is store-specific.

get_tools

def get_tools() -> list[AgentTool]

Defined in: src/strands/memory/types.py:286

Return store-specific tools to register alongside the manager’s tools.