Working with events in Amazon OpenSearch Memory
In Amazon OpenSearch Memory, an event is content that your agent sends to a space: a set of conversation turns, a JSON object, or a document in Amazon S3. OpenSearch Memory stores the event as you sent it and extracts memories from it according to the space's strategies.
OpenSearch Memory provides the following event operations. Every one of them takes the ID of the space.
-
CreateEvent – Send an event.
-
GetEvent – Read an event, including its payload.
-
BatchGetEvent – Read up to 10 events in one call.
-
ListEvents – List the events in a session in time order.
-
SearchEvents – Find events by the relevance of their content to a query.
-
DeleteEvent – Delete an event.
Sending an event
To send an event, call CreateEvent with the space ID, an
actorId, and a payload. The following parameters are
optional:
-
sessionId– The conversation the event belongs to. Send every event of one conversation with the same session ID. If you omit it, OpenSearch Memory generates a session ID and returns it. A generated ID is useful for the first event of a new conversation, but every later event of that conversation should carry it. -
eventTimestamp– When the event occurred. The default is the time OpenSearch Memory received the request. -
metadata– Up to 15 key-value tags to store with the event. Memories extracted from the event carry the same tags. For more information, see Metadata tags. -
infer– Whether to extract memories from the event. The default istrue. Set it tofalseto store an event that you want to keep and search but don't want memories extracted from. -
clientToken– A unique token that makes retrying the request safe. The AWS CLI and SDKs supply one for you. For more information, see Idempotent requests.
The following example sends a two-turn conversation. The request is in a file named
event.json.
aws opensearchmemory create-event --cli-input-json file://event.json
{ "spaceId": "sp-02864597b164", "actorId": "user-123", "sessionId": "session-001", "metadata": { "channel": "web" }, "payload": { "conversational": { "unified": { "source": { "object": { "messages": [ { "role": "USER", "content": { "text": "What's my order status?" } }, { "role": "ASSISTANT", "content": { "text": "Order 4471 shipped yesterday and arrives Friday." } } ] } } } } } }
The response returns the event's ID, actor, session, and timestamp.
{ "event": { "eventId": "ev-8f3a2c1d9b7e", "spaceId": "sp-02864597b164", "actorId": "user-123", "sessionId": "session-001", "eventTimestamp": "2026-11-14T00:35:41Z" } }
CreateEvent returns as soon as the event is stored. Memories are
extracted afterward. For more information about when the event and its memories become
visible to each operation, see What you see, and when.
Event payloads
The payload of an event contains exactly one of the following
members.
Conversational
Conversation turns, in order. Set
payload.conversational.unified.source.object.messages to a list of
1 to 100 turns. Each turn has a role of USER,
ASSISTANT, or SYSTEM and its text in
content.text. The order of the turns matters for extraction. The
text of all turns in one event can total up to 5 MiB.
Structured data
A JSON object, for content that isn't a conversation, such as a tool result or a
record your agent produced. Set payload.structuredData.source.json to
the object. The object can be up to 1 MiB and nested up to 10 levels deep.
Structured data is always JSON, so it has no content type.
{ "spaceId": "sp-02864597b164", "actorId": "user-123", "sessionId": "release-2026-11-02", "payload": { "structuredData": { "source": { "json": { "service": "checkout", "version": "4.2.0", "result": "rolled back", "reason": "Error rate exceeded the alarm threshold." } } } } }
Blob
A document stored in Amazon S3. Set payload.blob.contentType to the
document's type and payload.blob.source.s3Location.uri to the object's
S3 URI. The following content types are supported:
-
application/pdf -
image/png -
image/jpeg
{ "spaceId": "sp-02864597b164", "actorId": "user-123", "sessionId": "release-2026-11-02", "payload": { "blob": { "contentType": "application/pdf", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/runbooks/checkout.pdf" } } } } }
OpenSearch Memory reads the object with your credentials when you call
CreateEvent, so you need s3:GetObject permission on
the object. If the object is encrypted with a customer managed key (SSE-KMS), you also need
kms:Decrypt on that key. The bucket must be in the same Region as
the space. OpenSearch Memory reads the document's content for extraction and search, but
doesn't store a copy of the object in the event. GetEvent returns the
S3 URI you supplied.
A blob event has no turns. Its content is split into passages, which are extracted
like conversation turns and can be found with SearchEvents.
OpenSearch Memory extracts memories from a blob even when infer is
false.
Reading events
Getting an event by ID
To read one event, including its payload, call GetEvent with the
space ID and event ID.
aws opensearchmemory get-event \ --space-id sp-02864597b164 \ --event-id ev-8f3a2c1d9b7e
To read up to 10 events in one call, call BatchGetEvent with a list
of event IDs. The response returns the events in the order you requested them. An
event that couldn't be returned is listed in errors with a code that
explains why, such as RESOURCE_NOT_FOUND, instead of failing the whole
call.
aws opensearchmemory batch-get-event \ --space-id sp-02864597b164 \ --event-ids ev-8f3a2c1d9b7e ev-1c2d3e4f5a6b
Checking an event's owner
GetEvent, BatchGetEvent, and DeleteEvent
accept optional actorId and sessionId parameters. If you
supply them, OpenSearch Memory checks that the event belongs to that actor and session
and returns ResourceNotFoundException if it doesn't, as if the event
didn't exist. Use these parameters when your application acts on behalf of one end
user, so that a mistaken or forged event ID can't reach another user's data. You can
require them in IAM with the osm:actorId and
osm:sessionId condition keys. For more information, see Policy condition keys for OpenSearch Memory.
Listing a session's events
To list the events of one session in time order, call ListEvents
with the space ID, actorId, and sessionId. The response
returns each event's ID, timestamp, and metadata, but not its payload. Use
GetEvent or BatchGetEvent to read the payloads you
need.
aws opensearchmemory list-events \ --space-id sp-02864597b164 \ --actor-id user-123 \ --session-id session-001 \ --sort-order ASC \ --max-results 50
You can narrow the list with the following parameters:
-
eventTimestampAfterandeventTimestampBefore– Return only events in a time range. Both bounds are inclusive. -
sortOrder–ASCfor oldest first orDESCfor most recent first. The default isDESC. -
metadataFilters– Return only events whose metadata contains every one of the given key-value pairs.
ListEvents returns up to maxResults events per page (1
to 100, default 20) and a nextToken when there are more. When you use
metadataFilters, a page can contain fewer events than
maxResults, or none, and still return a nextToken.
Keep paging until the response has no nextToken.
Searching events
To find events by what they say rather than by when they happened, call
SearchEvents with the space ID, an actorId, and a query.
The query uses the same subset of the OpenSearch Query DSL as
SearchMemories, with the fields text and
vector. Each search covers one actor. To narrow it to specific
conversations, add up to 10 sessionIds.
aws opensearchmemory search-events \ --space-id sp-02864597b164 \ --actor-id user-123 \ --session-ids session-001 \ --query '{"match": {"text": "order status"}}'
Each result is the passage of an event that matched, in
matchedContent, with the event's ID, a relevance score, and the event's
metadata. A long event can match more than once. To read the whole event, pass its ID to
GetEvent.
To search only particular events, such as the source events of a memory, filter on
event_ids with a term or terms query. For
more information, see Searching memories and events in Amazon OpenSearch Memory.
Deleting an event
You can't undo deleting an event.
To delete an event, call DeleteEvent with the space ID and event ID. You
can supply actorId and sessionId to check the event's owner
first.
aws opensearchmemory delete-event \ --space-id sp-02864597b164 \ --event-id ev-8f3a2c1d9b7e \ --actor-id user-123
The event stops appearing in SearchEvents results shortly after the call
returns. Deleting an event that doesn't exist returns
ResourceNotFoundException.
Deleting an event doesn't delete the memories extracted from it, because a memory can combine information from several events. To delete those memories, use DeleteMemory. For more information, see Deleting a memory.
Metadata tags
Metadata tags are key-value pairs that you attach to an event when you create it.
Memories extracted from the event carry the same tags. Use metadata to record attributes
of your own, such as the channel a conversation came from or the tenant it belongs to,
and then filter by them in ListEvents, SearchEvents, and
SearchMemories. Metadata tags are separate from the AWS tags that you
attach to a space.
The following rules apply to metadata:
-
An event or memory can have up to 15 tags, and a space can use up to 50 distinct keys.
-
A key has 1 to 128 characters and can contain letters, digits, hyphens, and underscores. Keys that begin with
x-amz-are reserved for AWS use. A request that uses a reserved key fails withValidationException. -
A value has up to 256 characters and can contain letters, digits, spaces, and the characters
. _ : / = + @ -.
In a query, refer to a tag as metadata.key. For example, the following
SearchMemories query finds memories about recipes that have the tag
channel set to web.
{ "bool": { "must": [ { "match": { "memory_text": "recipes" } } ], "filter": [ { "term": { "metadata.channel": "web" } } ] } }
Don't put sensitive information, such as names or email addresses, in metadata keys or values.