View a markdown version of this page

Working with events in Amazon OpenSearch Memory - Amazon OpenSearch Service

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.

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 is true. Set it to false to 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:

  • eventTimestampAfter and eventTimestampBefore – Return only events in a time range. Both bounds are inclusive.

  • sortOrder – ASC for oldest first or DESC for most recent first. The default is DESC.

  • 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.

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

Warning

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 with ValidationException.

  • 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.