feat: integrate metadata support for short-term-memory (STM)

[glsukki]

Summary

BedrockAgent Memory now integrates SDK support for metadata in Short-Term Memory (STM).

Event metadata lets you attach additional contextual information to your short-term memory events as key-value pairs.
When creating events, you can include metadata that isn't part of the core event content but provides valuable context for retrieval.

For example, a travel booking agent can attach location metadata to events, making it easy to find all conversations that mentioned specific destinations.

You can then use the ListEvents operation with metadata filters to efficiently retrieve events based on these attached properties, enabling your agent to quickly locate relevant conversation history without scanning through entire sessions.

Usage

Example:

from bedrock_agentcore.memory.models import StringValue, LeftExpression, OperatorType, RightExpression, EventMetadataFilter

session_manager = MemorySessionManager(
      memory_id='test-memory-id', 
      region_name='us-east-1'
)

session = session_manager.create_memory_session(
    actor_id='user-123',
    session_id='test-session'
)

...
...

# Defining custom key-value pairs for metadata when creating an event with CreateEvent API
metadata = {}
metadataKey = "location"
metadataValue = "NYC"

metadata[metadataKey] = StringValue.build(value=metadataValue)
session.add_turns(messages=messages, metadata=metadata)


# Retrieving events with event metadata filter expression with ListEvents API
left_operand = LeftExpression.build(key=metadataKey)
operator = OperatorType.EQUALS_TO
right_operand = RightExpression.build(value=metadataValue)

filter_expression_1 = EventMetadataFilter.build_expression(left_operand, operator, right_operand)

params = {
    'actor_id': 'user-123',
    'session_id': 'test-session',
    'eventMetadata': [filter_expression_1]
}

filtered_events = session_manager.list_events(**params)

[bergjaak]

would it be possible to have the syntax like

LeftExpression(key='location')

and then we infer the type of from inspecting the type? Like we use the stringValue by checking that the key argument` is a string?

[glsukki]

As this is a TypedDict - we cannot - as it's supposed to be a type hint for dicts with specific structures - it doesn't provide runtime type conversion or inference.

For inferring the type - if needed, we can create a class method - which then invokes the respective methods.

Example:

class RightExpression(TypedDict):
    metadataValue: MetadataValue

    @classmethod
    def create(cls, value: Union[str, float, bool]) -> 'RightExpression':

        if isinstance(value, str):
            return cls(metadataValue=StringValue.create(value))
        elif isinstance(value, (int, float)):
            return cls(metadataValue=NumberValue.create(float(value)))
        else:
            raise ValueError(f"Unsupported value type: {type(value)}")

(Where we'd have other new TypedDict classes when we introduce new types (e.g: NumberValue))

If at any point, we'd want to support other functionalities for each of these types or for LeftExpression or RightExpression as an overall feature - the customer would still have to invoke the respective methods manually without any inference - where those methods would still end up being @staticmethod.

I think having it as above is more intuitive and allows the customer to understand what key type needs to be built.

[jona62]

LGTM!