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.
-
CreateMemory – Write a memory directly, without extraction.
-
GetMemory – Read a memory by ID.
-
ListMemories – List memories without a query, for example the most recent memories of one actor.
-
SearchMemories – Find memories by relevance to a query.
-
UpdateMemory – Change a memory's text or metadata.
-
DeleteMemory – Delete a memory.
Topics
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 amemoryTypeand optionallymemoryStrategyNamesof that type. Omit it to list every strategy. -
actorIdsandsessionIds– Up to 10 of each. A memory must match both filters if you supply both. -
sortBy–CREATED_AT(the default) orUPDATED_AT. -
sortOrder–ASCorDESC(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.
Searching memories
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. -
metadataandmetadataMode– WithREPLACE, the default, the supplied tags replace the memory's tags, and any tag you don't supply is removed. WithMERGE, 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.
-
UpdateMemorydoesn't take aclientToken. A retried request is applied again, with the same result.
Deleting a memory
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.