View a markdown version of this page

Working with spaces in Amazon OpenSearch Memory - Amazon OpenSearch Service

Working with spaces in Amazon OpenSearch Memory

In Amazon OpenSearch Memory, a space is the AWS resource that stores your events and memories. A space also defines which memory strategies extract memories, how long events and memories are kept, which model does the extraction, and which key encrypts the data. You control access to events and memories by controlling access to their space.

This topic describes how to create and manage spaces. For the event and memory operations, see Working with events in Amazon OpenSearch Memory and Working with memories in Amazon OpenSearch Memory.

Space IDs and ARNs

Each space has an ID that OpenSearch Memory assigns, for example sp-02864597b164. You pass the ID in every operation that acts on the space or its data.

Each space also has an Amazon Resource Name (ARN) in the following format. You use the ARN in IAM policies and in the tagging operations.

arn:aws:osm:region:account-id:space/space-id

Space settings

The following table describes the settings of a space.

Setting Description Changeable after creation
name A name from 1 to 128 characters that is unique among the spaces in your account and Region. It must start with a letter and can contain letters, digits, spaces, underscores, and hyphens. No
memoryStrategies Up to 10 memory strategies. A space with no strategies stores events but doesn't extract memories. For more information, see Memory strategies in Amazon OpenSearch Memory. Yes
eventExpiryDays How many days the space keeps each event, from 1 to 365. The default is 90. Yes
memoryExpiryDays How many days the space keeps each memory, from 1 to 3,650. Specify 0 to keep memories indefinitely. If you don't set this value, memories are kept indefinitely. Yes
extractionModelId The model that extracts and consolidates memories for every strategy in the space. For more information, see Choosing an extraction model. Yes
encryptionConfiguration The AWS KMS key that encrypts the space's data. By default, an AWS owned key. For more information, see Choosing an encryption key. No
tags Up to 50 key-value pairs. For more information, see Tagging a space. Yes

Configuring retention

A space keeps each event for eventExpiryDays and each memory for memoryExpiryDays. OpenSearch Memory counts a memory's lifetime from the time it writes the memory. Updating a memory doesn't restart the count.

When an event or memory expires, it is removed. An expired memory is no longer returned by searches or lists, and reading, updating, or deleting it returns ResourceNotFoundException, the same as for a memory that never existed.

When you change a retention setting, the change applies to events and memories written after the change. Items already stored keep the lifetime they were written with. A memory that OpenSearch Memory rewrites later, such as a summary that it keeps up to date, takes the setting in effect at the rewrite.

Note

GetSpace returns a retention setting only if you have set it. If eventExpiryDays or memoryExpiryDays is absent from the response, the space uses the default: 90 days for events, and no expiry for memories.

Choosing an extraction model

OpenSearch Memory uses one model to extract and consolidate memories for every strategy in a space. You can choose from the following models by specifying the model ID in extractionModelId:

  • anthropic.claude-haiku-5-5 – The default. Lower cost and latency.

  • anthropic.claude-opus-5-5 – Higher quality extraction, at higher cost.

Specify the model ID exactly as shown, without a Region or inference-profile prefix. If you omit the setting, the space uses the service default, which can change over time. To keep a space on one model, set the value explicitly. After you set a model, you can change it to the other supported model, but you can't return the space to the service default.

You don't need to request access to the model or grant any permissions for it. OpenSearch Memory calls the model on your behalf. Model calls may be processed in another AWS Region within the same geography as your space. Your spaces and the data stored in them stay in the Region where you created them. For more information, see Data location.

Choosing an encryption key

By default, OpenSearch Memory encrypts a space's data with an AWS owned key. To use a customer managed key in AWS Key Management Service (AWS KMS) instead, specify the key's ARN in encryptionConfiguration.kmsKeyArn when you create the space. You can't change the key after the space is created.

The key must be a symmetric encryption key that is enabled and in the same Region as the space. The principal that creates the space needs the kms:CreateGrant permission on the key, and principals that read and write the space's data need permission to use the key. For more information, see Key management.

Space status

A space's status tells you whether you can use or change it.

Status Meaning
CREATING OpenSearch Memory is setting up the space. You can't send events, update, or delete the space yet.
ACTIVE The space is ready to use.
UPDATING OpenSearch Memory is applying a change from UpdateSpace. GetSpace returns the previous configuration until the change is applied. You can't update or delete the space until then.
DELETING OpenSearch Memory is deleting the space and its memories.
FAILED Creating, updating, or deleting the space failed. statusReason explains why.

When deletion finishes, GetSpace returns ResourceNotFoundException.

The AWS SDKs and the AWS CLI provide two waiters: SpaceActive, which waits until a space is ACTIVE, and SpaceDeleted, which waits until a space no longer exists. Use them instead of polling GetSpace yourself.

Creating a space

To create a space, call CreateSpace with a name. All other settings are optional.

The following AWS CLI example creates a space that keeps events for 30 days, keeps memories indefinitely, uses the Opus model for extraction, and encrypts its data with a customer managed key. Replace the key ARN with the ARN of your own key.

aws opensearchmemory create-space \ --name support-agent-memory \ --event-expiry-days 30 \ --memory-expiry-days 0 \ --extraction-model-id anthropic.claude-opus-5-5 \ --encryption-configuration kmsKeyArn=arn:aws:kms:us-east-1:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \ --memory-strategies '[{"type":"SEMANTIC","name":"user-facts"},{"type":"SUMMARY","name":"session-summary"}]' \ --tags '[{"key":"team","value":"support"}]'

The call returns with the status CREATING. Wait until the status is ACTIVE before you send events.

The AWS CLI and SDKs add a clientToken to the request. If a request is retried with the same token within 2 hours, OpenSearch Memory returns the space that the first request created instead of creating a second one. For more information, see Idempotent requests.

To create a space (console)
  1. Open the Amazon OpenSearch Service console.

  2. In the navigation pane, under Memory, choose Spaces, and then choose Create Space.

  3. For Creation method, choose one of the following:

    • Easy create – Creates the space with a SEMANTIC strategy and a SUMMARY strategy and the default settings. Enter a Space name and choose Create Space.

    • Standard create – Lets you choose strategies and configure them, set event and memory expiry, choose an encryption key, and add tags. The extraction model can be set only with the API.

  4. Choose Create Space.

The space appears in the list with the status Creating. When it is ready, the status changes to Active.

Viewing spaces

To view a space's settings, status, and strategies, call GetSpace with the space ID.

aws opensearchmemory get-space --space-id sp-02864597b164

The response includes any strategy names that OpenSearch Memory generated for strategies that you created without a name.

To list the spaces in your account in the current Region, call ListSpaces. Each entry includes the space's ID, ARN, name, status, and creation time. Use --max-results to control the page size, from 1 to 100, and pass the returned nextToken to get the next page.

aws opensearchmemory list-spaces --max-results 20

Updating a space

To change a space's strategies, retention settings, or extraction model, call UpdateSpace. Supply only the settings you want to change. Settings you omit keep their current values.

The following example changes how long a space keeps events.

aws opensearchmemory update-space \ --space-id sp-02864597b164 \ --event-expiry-days 60

Note the following about updates:

  • To change the strategies, supply the complete new list in memoryStrategies. The list must contain at least one strategy. For more information, see Updating and removing strategies.

  • A change to strategies, retention, or the extraction model moves the space to UPDATING while it is applied, then back to ACTIVE. A request that changes nothing, or changes only a strategy description, is applied immediately.

  • You can't update a space that is CREATING, UPDATING, or DELETING. The request fails with ConflictException. Wait for the space to return to ACTIVE and try again.

  • Once you set memoryExpiryDays, extractionModelId, or a strategy configuration value, you can change it to another value but you can't unset it. To stop memories from expiring, set memoryExpiryDays to 0.

On the console, choose the space name on the Spaces page and then choose Edit. You can edit the strategies and the retention settings of an Active space.

Deleting a space

Warning

Deleting a space permanently deletes its memories. You can't undo the deletion or recover the memories. You can't retrieve the space's events after you delete it, and they are removed when they reach their expiry.

When you no longer need a space, call DeleteSpace with the space ID.

aws opensearchmemory delete-space --space-id sp-02864597b164

The call returns with the status DELETING, and deletion continues after the call returns. When it finishes, GetSpace returns ResourceNotFoundException. Use the SpaceDeleted waiter to wait for this.

Deleting a space deletes its memories. The space's events are removed when they reach the end of their retention period. To remove events sooner, delete them with DeleteEvent before you delete the space.

You can't delete a space that is CREATING or UPDATING. Wait for the space to become ACTIVE, then delete it. Calling DeleteSpace on a space that is already DELETING returns DELETING again, so you can safely retry the call.

To delete a space (console)
  1. Open the Amazon OpenSearch Service console.

  2. In the navigation pane, under Memory, choose Spaces.

  3. Select the space and choose Delete.

  4. Enter the space name to confirm, and then choose Delete.

Tagging a space

A tag is a key-value pair that you attach to a space to organize it, track costs, or control access. You can add tags when you create a space with the tags parameter, and manage tags on an existing space with TagResource, UntagResource, and ListTagsForResource, which take the space's ARN.

aws opensearchmemory tag-resource \ --resource-arn arn:aws:osm:us-east-1:111122223333:space/sp-02864597b164 \ --tags '[{"key":"environment","value":"production"}]'

A tag key can have up to 128 characters, and a tag value up to 256 characters. A space can have up to 50 tags. On the console, manage tags on the space's Tags tab.

Adding tags when you create a space requires the osm:TagResource permission in addition to osm:CreateSpace. You can use the aws:ResourceTag/key, aws:RequestTag/key, and aws:TagKeys condition keys to control access to spaces based on their tags. For more information, see ABAC with OpenSearch Memory.