AgentCoreMemorySessionManager: allow excluding binary content from persisted messages

[surecloud-jleite]

Summary

When a tool result carries a Bedrock document or image block, AgentCoreMemorySessionManager persists the raw bytes to AgentCore Memory.

For a large document, CreateEvent rejects the request with HTTP 413 and the agent's turn is destroyed. There is currently no way to persist the message without its binary payload.

Reproduction

Agent configured with AgentCoreMemorySessionManager (defaults: persistence_mode=FULL, batch_size=1, async_mode=False). A tool returns a document block containing a ~16.5 MB PDF. Strands appends the tool-result message, the MessageAddedEvent hook persists it, and CreateEvent returns 413:

File ".../bedrock_agentcore/memory/integrations/strands/session_manager.py", line 631, in create_message
    event = self.memory_client.gmdp_client.create_event(**create_event_kwargs)
botocore.exceptions.ClientError: An error occurred (413) when calling the CreateEvent operation:

The above exception was the direct cause of the following exception:

File ".../strands/event_loop/event_loop.py", line 832, in _handle_tool_execution
    await agent._append_messages(tool_result_message)
File ".../strands/session/session_manager.py", line 46, in <lambda>
    registry.add_callback(MessageAddedEvent, lambda event: self.append_message(...))
File ".../bedrock_agentcore/memory/integrations/strands/session_manager.py", line 840, in append_message
File ".../bedrock_agentcore/memory/integrations/strands/session_manager.py", line 636, in create_message
    raise SessionException(f"Failed to create message: {e}") from e

strands.types.exceptions.SessionException: Failed to create message: An error occurred (413) ...
strands.types.exceptions.EventLoopException: Failed to create message: An error occurred (413) ...

The tool call itself succeeded. The failure is in persistence, and it aborts the whole invocation, losing every prior step of the turn.

Observed with bedrock-agentcore 1.21.0. A 612 KB document persists fine, so the threshold sits somewhere between that and 16.5 MB. It does not appear to be documented, and 413 is not among the modelled CreateEvent errors in the API reference.

Why the existing configuration does not cover this

Option	Limitation
persistence_mode=NONE	All or nothing. Disables session history entirely, which is the reason for using the session manager.
filter_restored_tool_context	Applies on the read side when restoring messages. The failure is on write.
batch_size, flush_interval_seconds	Batching happens downstream of the oversized payload.

Why binary content is not worth persisting

Beyond the size failure, storing the bytes has little upside:

1. Long-term memory extraction cannot use base64 document or image payloads.
2. On restore, replaying the bytes into every subsequent model request is usually undesirable.
3. It writes megabytes per turn for content the caller can re-fetch from its own source of truth.

Proposed change

A hook applied to each message before create_event, so callers can substitute or drop content they do
not want persisted:

AgentCoreMemoryConfig(
    memory_id=...,
    session_id=...,
    actor_id=...,
    message_transform=lambda message: ...,  # Callable[[Message], Message] | None
)

A narrower declarative option would also solve the reported case, and may be easier to land:

AgentCoreMemoryConfig(..., persist_binary_content=False)

replacing document and image blocks (including blocks nested inside a toolResult) with a short text placeholder, so the restored history stays structurally valid for a subsequent model request.

Either shape would let callers keep session durability without the SDK deciding what belongs in memory.