View a markdown version of this page

Working with memories in Amazon OpenSearch Memory - Amazon OpenSearch Service

Working with memories in Amazon OpenSearch Memory

In Amazon OpenSearch Memory, a memory is a piece of text that a memory strategy extracted from events, or that you wrote directly. Each memory belongs to one actor, one session, and one strategy, and carries the IDs of the events it was derived from.

OpenSearch Memory provides the following memory operations. Every one of them takes the ID of the space.

The memory record

GetMemory returns a memory with the following members. SearchMemories and ListMemories return subsets of them.

Member Description
memoryId The memory's ID, assigned by OpenSearch Memory.
memoryType SEMANTIC, SUMMARY, or CUSTOM. The type of the strategy that produced the memory.
strategyName The name of the strategy the memory belongs to.
content The memory text.
systemMetadata The owning actorId and sessionId, and the createdAt and updatedAt timestamps.
metadata The memory's metadata tags.
sourceEventIds The IDs of the events the memory was extracted from. Returned by SearchMemories.

Writing a memory directly

When your application already knows something worth remembering, you can write it as a memory with CreateMemory instead of sending it as an event and waiting for extraction. OpenSearch Memory stores the text as you supply it under the strategy you name. It doesn't extract or consolidate it.

The request requires the space ID, the name of a strategy that the space already declares, the memory content (1 to 16,000 characters), and an actorId. You can also supply a sessionId, metadata, and a clientToken.

aws opensearchmemory create-memory \ --space-id sp-02864597b164 \ --name user-facts \ --actor-id user-123 \ --content "The user prefers vegetarian recipes."

The response returns the new memory's ID.

{ "memory": { "memoryId": "mem-3b9f1c2e-7d4a-4e8b-9c1f-2a6d8e0b4f17", "spaceId": "sp-02864597b164", "name": "user-facts", "actorId": "user-123", "sessionId": "a4c1e0f2-9b3d-4c5e-8f6a-7b8c9d0e1f2a" } }

The memory takes its type from the strategy. It becomes searchable shortly after the call returns. Until it is indexed, GetMemory, UpdateMemory, and DeleteMemory return ResourceNotFoundException for the new ID. If your application needs the memory right away, poll GetMemory with backoff.

The AWS CLI and SDKs add a clientToken to the request. A retry with the same token within 2 hours returns the same memoryId instead of creating a second memory. For more information, see Idempotent requests.

Reading memories

Getting a memory by ID

To read one memory, call GetMemory with the space ID and the memory ID that SearchMemories or ListMemories returned.

aws opensearchmemory get-memory \ --space-id sp-02864597b164 \ --memory-id mem-3b9f1c2e-7d4a-4e8b-9c1f-2a6d8e0b4f17

GetMemory, UpdateMemory, and DeleteMemory accept optional actorId and strategyName parameters. If you supply them, OpenSearch Memory checks that the memory belongs to that actor and strategy and returns ResourceNotFoundException if it doesn't, as if the memory didn't exist. Use these parameters when your application acts on behalf of one end user. You can require them in IAM with the osm:actorId and osm:strategyName condition keys. For more information, see Policy condition keys for OpenSearch Memory.

Listing memories

To list memories without a query, call ListMemories. The results include each memory's ID, type, strategy name, system metadata, and metadata tags, but not its content. Use GetMemory to read the content of the memories you need.

You can narrow the list with the following parameters:

  • memoryStrategies – One to five selectors, each naming a memoryType and optionally memoryStrategyNames of that type. Omit it to list every strategy.

  • actorIds and sessionIds – Up to 10 of each. A memory must match both filters if you supply both.

  • sortBy – CREATED_AT (the default) or UPDATED_AT.

  • sortOrder – ASC or DESC (the default).

The following example lists the most recently updated user-facts memories of one actor.

aws opensearchmemory list-memories \ --space-id sp-02864597b164 \ --memory-strategies '[{"memoryType":"SEMANTIC","memoryStrategyNames":["user-facts"]}]' \ --actor-ids user-123 \ --sort-by UPDATED_AT \ --max-results 20

ListMemories returns up to maxResults memories per page (1 to 100, default 20) and a nextToken when there are more. If memories are written or deleted while you page through results, a memory can be skipped or returned twice.

To find memories by what they say, call SearchMemories with the space ID, an actorId, and a query. Each search covers one actor. The results are ranked by relevance and include each memory's content, score, and source events.

aws opensearchmemory search-memories \ --space-id sp-02864597b164 \ --actor-id user-123 \ --query '{"neural": {"memory_vector": {"query_text": "what does the user like to eat", "k": 10}}}'

To search only some strategies, add memoryStrategies selectors. To filter by metadata, add a metadata.key filter to the query. For the query language, see Searching memories and events in Amazon OpenSearch Memory.

Updating a memory

To change a memory's text or metadata, call UpdateMemory with the space ID, the memory ID, and the fields to change. Supply content, metadata, or both.

  • content – Replaces the memory text. The memory becomes searchable by its new text shortly after the call returns, and the old text is no longer searchable.

  • metadata and metadataMode – With REPLACE, the default, the supplied tags replace the memory's tags, and any tag you don't supply is removed. With MERGE, tags you don't supply are kept, and a tag whose value is the empty string is removed.

The following example adds one tag and keeps the others.

aws opensearchmemory update-memory \ --space-id sp-02864597b164 \ --memory-id mem-3b9f1c2e-7d4a-4e8b-9c1f-2a6d8e0b4f17 \ --metadata-mode MERGE \ --metadata verified=true

The response returns the updated memory in the same shape as GetMemory.

Note the following about updates:

  • The memory keeps its memoryId. You can't change its type. To change the type, delete the memory and create a new one under a different strategy.

  • An update doesn't extend the memory's lifetime. The expiry is counted from when the memory was first written.

  • If two requests update the same memory at the same time, the last one wins. OpenSearch Memory doesn't check versions. If your application needs ordered updates to a memory, serialize them.

  • UpdateMemory doesn't take a clientToken. A retried request is applied again, with the same result.

Deleting a memory

Warning

You can't undo deleting a memory.

To delete a memory, call DeleteMemory with the space ID and memory ID. You can supply actorId and strategyName to check the memory's owner first.

aws opensearchmemory delete-memory \ --space-id sp-02864597b164 \ --memory-id mem-3b9f1c2e-7d4a-4e8b-9c1f-2a6d8e0b4f17 \ --actor-id user-123

The memory stops appearing in search results shortly after the call returns. Deleting a memory that doesn't exist returns ResourceNotFoundException. If your application retries deletes, treat that error as success.