Best practices for Amazon OpenSearch Memory
This topic provides recommendations for getting good memories out of Amazon OpenSearch Memory and for keeping your users' data separate and secure. The recommendations are general guidelines and don't represent a complete solution.
Designing spaces and strategies
Use one space per application, not per user. A space is the unit of configuration and access control. Separate users within a space by actor ID, and keep separate applications, or separate environments such as development and production, in separate spaces.
Start with SEMANTIC and
SUMMARY. These two strategies cover most agent use cases:
facts that persist across sessions and a running summary of each session. Add a
CUSTOM strategy when you need structured records that the built-in
types don't capture, and describe the record you want precisely in its prompt.
Set the idle timeout to match your conversations. The
default idle timeout of 60 seconds suits chat. If your users take minutes between turns,
raise idleTimeoutSeconds so that one exchange isn't split across several
extractions. If your agent needs memories within seconds of a turn, lower
extractEveryNMessages instead and accept more frequent, smaller
extractions.
Leave consolidation on for facts. Consolidation keeps
a SEMANTIC strategy's memories current, so a search returns "lives in
Austin" rather than both "lives in Seattle" and "lives in Austin." Turn it off only when
you want a full history of every extracted memory and your application handles
duplicates.
Choose retention deliberately. Keep events only as long as you need them for auditing or re-extraction, and set a memory retention period if your use case or regulations require memories to age out. By default, memories don't expire. For more information, see Configuring retention.
Sending events
Always send a session ID. Send every turn of one
conversation with the same sessionId. Extraction groups a session's turns
together, and SUMMARY strategies summarize a session. Letting OpenSearch Memory
generate a session ID is fine for the first event of a new conversation, as long as you
reuse the returned ID afterward.
Let the SDK supply the client token. The AWS SDKs add a clientToken to
CreateEvent and reuse it when they retry, so a retry returns the original event instead of creating a
duplicate. Without a client token, a retry stores the event again, and if you omitted
sessionId, the copy lands in a new session. Reuse the same
sessionId on every CreateEvent of a conversation so that
it stays in one session.
Send turns as they happen. Sending each exchange as its own event, rather than batching a whole conversation into one event at the end, lets the idle timeout and message-count triggers work as intended and lets your agent recall earlier parts of a long conversation.
Use infer: false for content you want to search but
not learn from. For example, store a transcript you need for auditing
without extracting memories from it.
Use metadata for your own attributes, not for content. Tag events with attributes you will filter by, such as a channel or a tenant. Don't put the content itself, or personal data, in metadata.
Searching
Prefer hybrid queries for recall. A
hybrid query combines keyword and semantic matching, so it finds both
exact phrases and paraphrases. Use a plain match query when you know the
exact words, and a neural query for natural-language questions.
Scope searches to the strategies you need. Searching
only the SEMANTIC strategy for facts, or only a CUSTOM strategy
for records, returns more relevant results than searching every strategy at once.
Don't store memory IDs long term. Consolidation replaces a memory with a new one when a fact changes, and the replacement has a new ID. Fetch current IDs from SearchMemories or ListMemories when you need them.
Treat scores as ordering only. Relevance scores aren't normalized and vary with the query type. Don't compare scores across queries or apply fixed thresholds without testing.
Security
Grant least privilege. Scope policies to specific space ARNs and to the actions each principal needs. Separate the principals that administer spaces from the principals that read and write data.
Limit each end user to their own data. Use a separate
actor ID for each end user. When end users call OpenSearch Memory with their own credentials,
use the osm:actorId condition key with a Null check to limit
each principal to one actor. For more information, see Limiting a principal to one actor's memories.
Pass the owner on reads and deletes. When your
application acts for one end user, supply actorId (and
sessionId or strategyName) on GetEvent,
GetMemory, DeleteEvent, and DeleteMemory, so
that a mistaken or forged ID can't reach another user's data.
Use a customer managed key for sensitive data. With a customer managed key you control and audit access to a space's data and can revoke it. For more information, see Key management.
Monitor API activity with CloudTrail. Turn on data events for your spaces to record every event and memory operation. For more information, see Logging Amazon OpenSearch Memory API calls with AWS CloudTrail.