feat(memory): event metadata state identification, message batching, and redundant sync elimination

[jariy17]

Summary

• Replaces prefixed actorId approach with event metadata for identifying session and agent state events
• Adds automatic migration for backwards compatibility with existing sessions
• Implements true message batching with configurable batch_size, and fixes events_to_messages() ordering for batched events
• Skips redundant sync_agent API calls via agent state hash tracking, eliminating ~6+ unnecessary API calls per conversation turn (code credit: @kevmyung)

Fixes #220
Fixes #196

Changes

Event Metadata for State Identification

Session and agent state events are now identified using event metadata instead of encoding state type into the actorId, enabling cleaner actor identification.

Before:

# Session state used a prefixed actorId
create_event(actorId="session_my-session-id", ...)

# Agent state used a prefixed actorId
create_event(actorId="agent_my-agent-id", ...)

After:

# Session state uses shared actorId + metadata
create_event(
    actorId="shared-actor-id",
    metadata={"stateType": {"stringValue": "SESSION"}},
    ...
)

# Agent state uses shared actorId + metadata
create_event(
    actorId="shared-actor-id",
    metadata={
        "stateType": {"stringValue": "AGENT"},
        "agentId": {"stringValue": "my-agent-id"},
    },
    ...
)

• Added StateType enum (SESSION, AGENT) and metadata constants
• Session and agent events use EventMetadataFilter queries instead of prefixed actorIds

Backwards Compatibility

Existing sessions created with the old prefixed actorId format continue to work without any code changes.

• Auto-migration detects legacy events on read, creates new events with metadata, and deletes old prefixed events

Message Batching

Multiple messages can now be grouped into single API calls, reducing the number of requests.

• Add batch_size configuration option (1-100, default 1)
• Group conversational messages by session_id into batched API calls
• Send blob messages (>9KB) individually via separate API path
• Clear buffer only after all API calls succeed to prevent data loss
• Fix events_to_messages() ordering for batched events by iterating in reverse instead of reversing the flat message list
• Add 6 unit tests for multi-event and batched payload ordering

Redundant Sync Elimination

The strands framework's register_hooks fires sync_agent on both MessageAddedEvent and AfterInvocationEvent, causing 2 API calls (read_agent + create_agent) per sync — ~6+ redundant calls per turn when agent state hasn't changed.

• Compute a hash of the serialized agent state (excluding created_at/updated_at timestamps) after each sync
• Compare against the last synced hash before each sync_agent call; skip entirely when unchanged
• Seed the hash during initialize() so the first hook-triggered sync correctly detects unchanged state
• Hash is NOT updated if the parent sync raises, ensuring the next call retries

Test plan

• All 129 tests pass (pytest tests/bedrock_agentcore/memory/integrations/strands/ -v)
• End-to-end demo with real API completed successfully
• Legacy migration tested with existing sessions
• Batching tests pass: pytest tests/bedrock_agentcore/memory/integrations/strands/test_agentcore_memory_session_manager.py -k "Batching" -v
• Converter ordering tests pass: pytest tests/bedrock_agentcore/memory/integrations/strands/test_bedrock_converter.py -v (24 tests)
• State hash tracking tests pass: 7 tests covering hash computation, skip/call behavior, failure resilience, and initialization

Future Work

• Branching support: Add support for conversation branching to enable forking sessions (related: AgentCoreMemorySessionManager doesn't support Branches, multi-agent, or metadata features #149)

[akshseh]

This is to say that we support multiple agents per session ? Does Strands support that for session managers ? And also, this means we're using metadata to store and retrieve events from one agent_ID and not branches.

[jariy17]

_created_agent_ids is a fallback for when list_events_by_filter fails to find an agent due to eventual consistency. Newly created events aren't immediately visible when filtering by metadata - there's a short propagation delay. If the metadata query returns nothing but the agent_id is in _created_agent_ids, we know the agent was created and proceed accordingly rather than failing in update_agent

[jariy17]

Strands supports multiple agents per session. However, we strongly advise against this to the customer by a log message in 582.

[akshseh]

Should we do retries for functions like read_agent ? It's causing unnecessary costs, maybe it's just a new agent that's empty.

[jariy17]

Retries are needed because newly created events aren't immediately visible when filtering by event_metadata. Without retries, we may miss agent state updates.