View a markdown version of this page

Best practices for Amazon OpenSearch Memory - Amazon OpenSearch Service

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.

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.