Amazon OpenSearch Memory

2026/11/16 - Amazon OpenSearch Memory - 20 new api methods

Changes  Initial release of Amazon OpenSearch Memory, which gives AI agents persistent memory. Store conversation and document events in a Space, have memories extracted from them automatically, and retrieve them with semantic, lexical, or hybrid search.

SearchEvents (new) Link ¶

Searches a space's events by relevance. It works like SearchMemories without the memory type and strategy selector. The query is a subset of the OpenSearch Query DSL. The service validates it, limits the search to the actor in actorId and the sessions in sessionIds, and returns ranked results. Each result is the matching chunk of an event, not the whole event. You can page through only a limited number of results. A request past that limit fails with ValidationException (reason invalidNextToken), and the message gives the limit.

If the results are larger than 5 MiB, the request fails with ValidationException (reason queryBodyTooLarge). Lower maxResults.

If the request would exceed the service's rate for embedding requests, it fails with ThrottlingException. Retry with exponential backoff.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.search_events(
    spaceId='string',
    actorId='string',
    sessionIds=[
        'string',
    ],
    query={...}|[...]|123|123.4|'string'|True|None,
    sort={...}|[...]|123|123.4|'string'|True|None,
    maxResults=123,
    nextToken='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The space whose events to search. Use actorId and sessionIds to narrow the search within it.

type actorId:

string

param actorId:

[REQUIRED]

The actor whose events to search (exact match). Required: every search covers exactly one actor, and an event stored without an actor is never returned. Narrow the search further with sessionIds, combined by AND. This is the only way to filter by actor: a query that references system_metadata.actor_id fails with ValidationException (reason nonFilterableField).

type sessionIds:

list

param sessionIds:

Returns only events from one of these sessions (exact match). Combined with actorId by AND. Omit for no session filter. An empty list fails validation. An event stored without a session never matches a session filter. This is the only way to filter by session: a query that references system_metadata.session_id fails with ValidationException (reason nonFilterableField).

  • (string) --

    The ID of a session, which groups an actor's events.

type query:

:ref:`document<document>`

param query:

[REQUIRED]

The query: a subset of the OpenSearch Query DSL (see SearchQuery), validated by the same rules as on SearchMemories. Query event text as text and embeddings as vector. A search covers both conversation turns and chunks of documents submitted as a blob. You can't use actor and session fields here. Use the top-level actorId and sessionIds.

To search only the content of particular events, filter on event_ids with term or terms, for example with the sourceEventIds that a SearchMemories result returns. A terms clause on event_ids can list up to 10 event IDs. More IDs fail with ValidationException (reason queryBodyTooLarge). You can use event_ids only in term, terms, and exists queries.

type sort:

:ref:`document<document>`

param sort:

The sort order (see SearchSort). Omit to return the most relevant events first.

type maxResults:

integer

param maxResults:

The maximum number of events to return, from 1 to 100. The default is 20.

type nextToken:

string

param nextToken:

The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

rtype:

dict

returns:

Response Syntax

{
    'events': [
        {
            'eventId': 'string',
            'score': 123.0,
            'systemMetadata': {
                'actorId': 'string',
                'sessionId': 'string',
                'createdAt': datetime(2015, 1, 1),
                'updatedAt': datetime(2015, 1, 1)
            },
            'metadata': {
                'string': 'string'
            },
            'matchedContent': 'string'
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • events (list) --

      The matching event chunks, in the order sort requests, or most relevant first when it has none. Empty when nothing matches. Each result is the matching chunk of an event. Call GetEvent for the whole event.

      • (dict) --

        A SearchEvents result: the matching chunk of an event and its provenance. Unlike EventSummary from ListEvents, it has a relevance score and the matched content, but not the full payload.

        • eventId (string) --

          The ID of the event that the chunk belongs to. Use it with GetEvent or DeleteEvent.

        • score (float) --

          The relevance score of the result. A higher score is more relevant. Scores aren't normalized to a fixed range and can be greater than 1, so use them only to order results.

        • systemMetadata (dict) --

          Provenance for the chunk: the owning actor and session, and when it was created and last updated. It is the same block that ListMemories and SearchMemories return. Event chunks are never modified, so updatedAt always equals createdAt.

          Absent when the service has no provenance for the chunk.

          • actorId (string) --

            The owning actor. Absent when none was recorded.

          • sessionId (string) --

            The owning session. Absent when none was recorded.

          • createdAt (datetime) --

            When the record was created. Always present on ListMemories and GetMemory. It can be absent from search results.

          • updatedAt (datetime) --

            When the record was last updated. Equals createdAt for a record that has never been updated, and always for a SearchEvents result.

        • metadata (dict) --

          The event's metadata tags. All values are strings. In a query, filter on a tag as metadata.<key>.

          • (string) --

            A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

            • (string) --

              The value of a metadata entry.

        • matchedContent (string) --

          The text of the matching chunk.

    • nextToken (string) --

      The token for the next set of results. Absent when there are no more results.

UpdateMemory (new) Link ¶

Updates a memory in place. Supply only the fields to change. Omitted fields keep their stored values. A request must supply content or metadata, or it fails with ValidationException. Supplying content re-embeds the memory. A change to metadata alone doesn't.

The memory keeps its memoryId across updates. Shortly after an update, searches stop returning the previous content.

memoryType can't be changed. To change it, delete the memory and create a new one.

A memory past its expiry (set from the space's memoryExpiryDays when the memory is written) reads as not found: the operation fails with ResourceNotFoundException and changes nothing. An update does not move the expiry.

Concurrent updates to one memory are last-writer-wins. There is no version check. To avoid lost updates, serialize your updates to a memory.

If you supply content and the request would exceed the service's rate for embedding requests, it fails with ThrottlingException. Retry with exponential backoff.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.update_memory(
    spaceId='string',
    memoryId='string',
    content='string',
    metadata={
        'string': 'string'
    },
    metadataMode='REPLACE'|'MERGE',
    actorId='string',
    strategyName='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space that owns the memory, for example sp-02864597b164.

type memoryId:

string

param memoryId:

[REQUIRED]

The ID of the memory to update.

type content:

string

param content:

Replacement memory text. Supplying it re-embeds the memory. Omit to leave the text unchanged.

type metadata:

dict

param metadata:

The metadata tags to apply. By default this map replaces the stored metadata, and any key not present is removed. Set metadataMode to MERGE to keep the keys you don't supply. Limits apply to the resulting metadata, not to the request. Keys that begin with x-amz- and the key documentS3Source are reserved: a request that sets one fails with ValidationException.

A space can use at most 50 distinct metadata keys across all of its events and memories. A request that would add a key beyond that fails with ValidationException. Reuse an existing key instead.

  • (string) --

    A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

    • (string) --

      The value of a metadata entry.

type metadataMode:

string

param metadataMode:

How metadata combines with what is stored. The default is REPLACE.

type actorId:

string

param actorId:

The ID of the actor that the memory must belong to. Omit it to skip this check. If it doesn't match the stored memory, the call fails with ResourceNotFoundException, as if the memory did not exist.

type strategyName:

string

param strategyName:

The name of the strategy that the memory must belong to. Omit it to skip this check. If it doesn't match the stored memory, the call fails with ResourceNotFoundException, as if the memory did not exist.

rtype:

dict

returns:

Response Syntax

{
    'memory': {
        'memoryId': 'string',
        'memoryType': 'SEMANTIC'|'SUMMARY'|'CUSTOM',
        'strategyName': 'string',
        'content': 'string',
        'systemMetadata': {
            'actorId': 'string',
            'sessionId': 'string',
            'createdAt': datetime(2015, 1, 1),
            'updatedAt': datetime(2015, 1, 1)
        },
        'metadata': {
            'string': 'string'
        }
    }
}

Response Structure

  • (dict) --

    • memory (dict) --

      The updated memory, in the same shape that GetMemory returns.

      • memoryId (string) --

        The memory's ID, assigned by the service.

      • memoryType (string) --

        The memory type.

      • strategyName (string) --

        The name of the strategy the memory belongs to, for example user-facts. A space can hold several strategies of the same type, so this tells them apart. Absent when the memory's strategy is no longer declared on the space, for example right after the strategy is deleted.

      • content (string) --

        The memory text.

      • systemMetadata (dict) --

        Provenance for the memory: the owning actor and session, and when it was created and last updated. Always present. updatedAt equals createdAt for a memory that has never been updated.

        • actorId (string) --

          The owning actor. Absent when none was recorded.

        • sessionId (string) --

          The owning session. Absent when none was recorded.

        • createdAt (datetime) --

          When the record was created. Always present on ListMemories and GetMemory. It can be absent from search results.

        • updatedAt (datetime) --

          When the record was last updated. Equals createdAt for a record that has never been updated, and always for a SearchEvents result.

      • metadata (dict) --

        The memory's metadata tags. All values are strings. May be empty.

        • (string) --

          A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

          • (string) --

            The value of a metadata entry.

ListMemories (new) Link ¶

Lists a space's memories without a query, for example the most recent memories or the memories of one strategy. Filter by strategy and optionally by owning actor or session, sort by creation or update time, and page through the results. Results have no relevance score. To query or filter by metadata, use SearchMemories.

If memories are written or deleted while you page, the results can skip a memory or return it twice. You can page through only a limited number of results. A request past that limit fails with ValidationException (reason invalidNextToken), and the message gives the limit.

Memories past their expiry (set from the space's memoryExpiryDays when each memory is written) are left out. Unlike SearchMemories, this operation also returns memories that consolidation has superseded.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.list_memories(
    spaceId='string',
    memoryStrategies=[
        {
            'memoryType': 'SEMANTIC'|'SUMMARY'|'CUSTOM',
            'memoryStrategyNames': [
                'string',
            ]
        },
    ],
    actorIds=[
        'string',
    ],
    sessionIds=[
        'string',
    ],
    sortBy='CREATED_AT'|'UPDATED_AT',
    sortOrder='ASC'|'DESC',
    maxResults=123,
    nextToken='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The space whose memories to list.

type memoryStrategies:

list

param memoryStrategies:

The strategies to list, as selectors. A selector without memoryStrategyNames lists every strategy of its type, and omitting memoryStrategies lists every strategy in the space. A name that is not a declared strategy of that type fails with ValidationException.

  • (dict) --

    A memory type and, optionally, specific strategy names of that type. A space can hold several strategies of the same type, so the type and its names are given together.

    • memoryType (string) -- [REQUIRED]

      The memory type to search or list.

    • memoryStrategyNames (list) --

      Specific strategy names of memoryType. Omit it to include every strategy of that type.

      • (string) --

        The name of a strategy declared on a space, for example user-facts. Names are case-sensitive and must match the declared name exactly.

type actorIds:

list

param actorIds:

Lists only memories owned by one of these actors. Combined with sessionIds by AND: a memory must match both filters when both are given. Omit for no actor filter. An empty list fails validation. A memory stored without an actor never matches an actor filter.

  • (string) --

    The ID of an actor: the end user or agent that events and memories belong to.

type sessionIds:

list

param sessionIds:

Lists only memories from one of these sessions. Combined with actorIds by AND. Omit for no session filter. An empty list fails validation. A memory stored without a session never matches a session filter.

  • (string) --

    The ID of a session, which groups an actor's events.

type sortBy:

string

param sortBy:

The timestamp to sort by, as returned in systemMetadata: CREATED_AT (the default) or UPDATED_AT.

type sortOrder:

string

param sortOrder:

The sort order: ASC or DESC. The default is DESC, most recent first.

type maxResults:

integer

param maxResults:

The maximum number of memories to return, from 1 to 100. The default is 20.

type nextToken:

string

param nextToken:

The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

rtype:

dict

returns:

Response Syntax

{
    'memories': [
        {
            'memoryId': 'string',
            'memoryType': 'SEMANTIC'|'SUMMARY'|'CUSTOM',
            'strategyName': 'string',
            'systemMetadata': {
                'actorId': 'string',
                'sessionId': 'string',
                'createdAt': datetime(2015, 1, 1),
                'updatedAt': datetime(2015, 1, 1)
            },
            'metadata': {
                'string': 'string'
            }
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • memories (list) --

      The memories, in the requested order. Empty when there are none.

      • (dict) --

        A summary of a memory, as returned by ListMemories: its ID, type, provenance, and tags. It doesn't include content. Call GetMemory for the full memory.

        • memoryId (string) --

          The memory's ID, assigned by the service. IDs are opaque, can contain hyphens and underscores, and can be up to 512 characters long.

        • memoryType (string) --

          The memory type.

        • strategyName (string) --

          The name of the strategy the memory belongs to, for example user-facts: the strategy memoryStrategies selects on in ListMemories. Absent when the memory's strategy is no longer declared on the space, for example right after the strategy is deleted.

        • systemMetadata (dict) --

          Provenance for the memory: the owning actor and session, and when it was created and last updated. Always present, with both timestamps.

          • actorId (string) --

            The owning actor. Absent when none was recorded.

          • sessionId (string) --

            The owning session. Absent when none was recorded.

          • createdAt (datetime) --

            When the record was created. Always present on ListMemories and GetMemory. It can be absent from search results.

          • updatedAt (datetime) --

            When the record was last updated. Equals createdAt for a record that has never been updated, and always for a SearchEvents result.

        • metadata (dict) --

          The memory's metadata tags. All values are strings.

          • (string) --

            A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

            • (string) --

              The value of a metadata entry.

    • nextToken (string) --

      The token for the next set of results. Absent when there are no more results.

CreateSpace (new) Link ¶

Creates a space. A space is an AWS resource that stores the events you send and the memories extracted from them, and defines the memory strategies that extract those memories.

The operation returns before provisioning finishes, with status CREATING. Call GetSpace until the status is ACTIVE, and then use the space. If provisioning fails, the status becomes FAILED and statusReason says why.

See also: AWS API Documentation

Request Syntax

client.create_space(
    name='string',
    memoryStrategies=[
        {
            'type': 'SEMANTIC'|'SUMMARY'|'CUSTOM',
            'name': 'string',
            'description': 'string',
            'configuration': {
                'extractionPrompt': 'string',
                'extractEveryNMessages': 123,
                'extractEveryNTokens': 123,
                'idleTimeoutSeconds': 123,
                'extractionSeedTopK': 123,
                'extractionSeedRecentN': 123,
                'consolidationEnabled': True|False
            }
        },
    ],
    eventExpiryDays=123,
    memoryExpiryDays=123,
    extractionModelId='string',
    encryptionConfiguration={
        'kmsKeyArn': 'string'
    },
    tags=[
        {
            'key': 'string',
            'value': 'string'
        },
    ],
    clientToken='string'
)
type name:

string

param name:

[REQUIRED]

A name for the space, unique within your account in the Region. If another space already has the name, the request fails with ConflictException.

type memoryStrategies:

list

param memoryStrategies:

The memory strategies that extract memories from the space's events: up to 10 strategies, each with a name that is unique within the space.

Optional. Omit it, or send an empty list, to create a space with no memory strategies. Such a space stores the conversation events you send it and returns them through SearchEvents and ListEvents, but extracts no memories and has none to search. You can add strategies later with UpdateSpace.

The serialized list can be at most 384 KiB.

  • (dict) --

    A memory strategy: how a space extracts one kind of memory from its events.

    • type (string) -- [REQUIRED]

      The type of memory the strategy extracts.

    • name (string) --

      A name for the strategy, unique within the space. Omit it to have the service generate one from the type, for example semantic_1. The name must be 1 to 64 characters: letters, digits, periods, hyphens, and underscores, starting with a letter or digit. A strategy's name can't be changed, and the strategy's memories are stored under it: a strategy added under a new name starts with no memories.

    • description (string) --

      A description of the strategy.

    • configuration (dict) --

      Settings for the strategy. When you create a strategy, omit it to use the defaults for the strategy's type.

      A CUSTOM strategy must set extractionPrompt.

      • extractionPrompt (string) --

        Instructions that define what a CUSTOM strategy extracts, up to 30,720 characters. Required for a CUSTOM strategy: CreateSpace and UpdateSpace fail with ValidationException if a CUSTOM strategy has none.

        Only CUSTOM strategies use it. SEMANTIC and SUMMARY strategies always extract with the service's built-in instructions: the service accepts and stores a prompt on them, and GetSpace returns it, but extraction doesn't use it.

      • extractEveryNMessages (integer) --

        Extract once this many messages have accumulated, from 1 to 1000. Lower values extract more often, in smaller batches. The default is 12.

        Messages accumulate until the first of extractEveryNMessages, extractEveryNTokens, and idleTimeoutSeconds is reached. The service then extracts them together in one pass.

      • extractEveryNTokens (integer) --

        Extract once this many tokens of conversation have accumulated, from 1 to 80,000, however few messages that takes. Use it to bound how much text one extraction call carries when message sizes vary widely. Omit it to bound a batch only by extractEveryNMessages, idleTimeoutSeconds, and the service's maximum batch size.

      • idleTimeoutSeconds (integer) --

        Extract what has accumulated once the conversation has been idle for this many seconds, from 1 to 86,400. The default is 60. This is what extracts the end of a conversation that stops. Raise it when the pauses in your conversations are longer than that, so that one exchange isn't split across several extraction passes.

      • extractionSeedTopK (integer) --

        How many of the strategy's stored memories that are most relevant to the conversation to include in the extraction prompt, from 0 to 20, to improve extraction and reduce duplicates. If you omit this or set it to 0, the service uses its default (see extractionSeedRecentN). When this and extractionSeedRecentN are both set, the two sets of memories are combined without duplicates.

      • extractionSeedRecentN (integer) --

        How many of the strategy's most recent stored memories to include in the extraction prompt, from 0 to 20. If you omit this or set it to 0, the service uses its default: no seeding for most strategy types, and the 10 most recent memories for a SUMMARY strategy when neither seed setting is given. When this and extractionSeedTopK are both set, the two sets of memories are combined without duplicates.

      • consolidationEnabled (boolean) --

        Specifies whether the strategy consolidates memories. With consolidation, each new memory is compared with similar stored memories, and the service adds it, updates a stored memory, or skips it, so duplicate or contradicting facts don't accumulate. Without it, every extracted memory is stored as a new memory, which costs less and keeps a full history.

        When omitted, the default depends on the strategy's type: on for SEMANTIC and SUMMARY, off for CUSTOM.

type eventExpiryDays:

integer

param eventExpiryDays:

How many days the space keeps each event, from 1 to 365. The default is 90.

type memoryExpiryDays:

integer

param memoryExpiryDays:

How many days the space keeps each memory, from 0 to 3650, counted from when the service writes the memory. Updating a memory with UpdateMemory doesn't restart the count. 0 means memories never expire. If you omit it, memories never expire.

Searches and lists leave out a memory past its expiry, and reading, updating, or deleting it returns ResourceNotFoundException.

type extractionModelId:

string

param extractionModelId:

The model that extracts and consolidates memories for every strategy in the space, as an Amazon Bedrock model ID without an inference-profile prefix: anthropic.claude-opus-5-5 or anthropic.claude-haiku-5-5. Another value fails with ValidationException, and the message lists the supported IDs. Omit it to use the service default, which can change over time and isn't returned by GetSpace. Setting a value pins the model.

type encryptionConfiguration:

dict

param encryptionConfiguration:

The AWS KMS key that encrypts the space's data. Omit it, or omit its kmsKeyArn, to use an AWS owned key. You can't change the key after you create the space.

  • kmsKeyArn (string) --

    The ARN of a customer managed AWS KMS key that encrypts the space's data. The key must be an enabled symmetric encryption key in the space's Region, and you need permission to create grants on it ( kms:CreateGrant). Otherwise, the request fails with ValidationException or AccessDeniedException.

type tags:

list

param tags:

The tags to add to the space.

  • (dict) --

    A tag: a key-value pair that you attach to a space.

    • key (string) -- [REQUIRED]

      The key of the tag.

    • value (string) -- [REQUIRED]

      The value of the tag.

type clientToken:

string

param clientToken:

A unique, case-sensitive identifier that makes the request idempotent. A retry with the same token and the same parameters within 2 hours returns the space that the first request created, instead of creating another. Reusing the token with different parameters, or while the first request is still in progress, fails with ConflictException.

This field is autopopulated if not provided.

rtype:

dict

returns:

Response Syntax

{
    'spaceId': 'string',
    'arn': 'string',
    'name': 'string',
    'status': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING'|'DELETED'|'FAILED',
    'createdAt': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • spaceId (string) --

      The ID of the space.

    • arn (string) --

      The Amazon Resource Name (ARN) of the space.

    • name (string) --

      The name of the space.

    • status (string) --

      The status of the space: CREATING.

    • createdAt (datetime) --

      When the space was created.

ListTagsForResource (new) Link ¶

Lists the tags for the specified space.

See also: AWS API Documentation

Request Syntax

client.list_tags_for_resource(
    resourceArn='string'
)
type resourceArn:

string

param resourceArn:

[REQUIRED]

The Amazon Resource Name (ARN) of the space.

rtype:

dict

returns:

Response Syntax

{
    'tags': [
        {
            'key': 'string',
            'value': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • tags (list) --

      The tags for the space.

      • (dict) --

        A tag: a key-value pair that you attach to a space.

        • key (string) --

          The key of the tag.

        • value (string) --

          The value of the tag.

UntagResource (new) Link ¶

Removes the specified tags from the specified space.

See also: AWS API Documentation

Request Syntax

client.untag_resource(
    resourceArn='string',
    tagKeys=[
        'string',
    ]
)
type resourceArn:

string

param resourceArn:

[REQUIRED]

The Amazon Resource Name (ARN) of the space.

type tagKeys:

list

param tagKeys:

[REQUIRED]

The keys of the tags to remove from the space.

  • (string) --

rtype:

dict

returns:

Response Syntax

{}

Response Structure

  • (dict) --

GetSpace (new) Link ¶

Returns a space's configuration and status.

See also: AWS API Documentation

Request Syntax

client.get_space(
    spaceId='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space.

rtype:

dict

returns:

Response Syntax

{
    'spaceId': 'string',
    'arn': 'string',
    'name': 'string',
    'status': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING'|'DELETED'|'FAILED',
    'statusReason': 'string',
    'createdAt': datetime(2015, 1, 1),
    'memoryStrategies': [
        {
            'type': 'SEMANTIC'|'SUMMARY'|'CUSTOM',
            'name': 'string',
            'description': 'string',
            'configuration': {
                'extractionPrompt': 'string',
                'extractEveryNMessages': 123,
                'extractEveryNTokens': 123,
                'idleTimeoutSeconds': 123,
                'extractionSeedTopK': 123,
                'extractionSeedRecentN': 123,
                'consolidationEnabled': True|False
            }
        },
    ],
    'eventExpiryDays': 123,
    'memoryExpiryDays': 123,
    'extractionModelId': 'string',
    'encryptionConfiguration': {
        'kmsKeyArn': 'string'
    }
}

Response Structure

  • (dict) --

    • spaceId (string) --

      The ID of the space.

    • arn (string) --

      The Amazon Resource Name (ARN) of the space.

    • name (string) --

      The name of the space.

    • status (string) --

      The status of the space.

    • statusReason (string) --

      Details about why the space is FAILED. Read it only when status is FAILED: it can still hold the reason for an earlier failure.

    • createdAt (datetime) --

      When the space was created.

    • memoryStrategies (list) --

      The space's memory strategies, including the names the service generated for strategies created without one. Empty for a space that has no memory strategies.

      • (dict) --

        A memory strategy: how a space extracts one kind of memory from its events.

        • type (string) --

          The type of memory the strategy extracts.

        • name (string) --

          A name for the strategy, unique within the space. Omit it to have the service generate one from the type, for example semantic_1. The name must be 1 to 64 characters: letters, digits, periods, hyphens, and underscores, starting with a letter or digit. A strategy's name can't be changed, and the strategy's memories are stored under it: a strategy added under a new name starts with no memories.

        • description (string) --

          A description of the strategy.

        • configuration (dict) --

          Settings for the strategy. When you create a strategy, omit it to use the defaults for the strategy's type.

          A CUSTOM strategy must set extractionPrompt.

          • extractionPrompt (string) --

            Instructions that define what a CUSTOM strategy extracts, up to 30,720 characters. Required for a CUSTOM strategy: CreateSpace and UpdateSpace fail with ValidationException if a CUSTOM strategy has none.

            Only CUSTOM strategies use it. SEMANTIC and SUMMARY strategies always extract with the service's built-in instructions: the service accepts and stores a prompt on them, and GetSpace returns it, but extraction doesn't use it.

          • extractEveryNMessages (integer) --

            Extract once this many messages have accumulated, from 1 to 1000. Lower values extract more often, in smaller batches. The default is 12.

            Messages accumulate until the first of extractEveryNMessages, extractEveryNTokens, and idleTimeoutSeconds is reached. The service then extracts them together in one pass.

          • extractEveryNTokens (integer) --

            Extract once this many tokens of conversation have accumulated, from 1 to 80,000, however few messages that takes. Use it to bound how much text one extraction call carries when message sizes vary widely. Omit it to bound a batch only by extractEveryNMessages, idleTimeoutSeconds, and the service's maximum batch size.

          • idleTimeoutSeconds (integer) --

            Extract what has accumulated once the conversation has been idle for this many seconds, from 1 to 86,400. The default is 60. This is what extracts the end of a conversation that stops. Raise it when the pauses in your conversations are longer than that, so that one exchange isn't split across several extraction passes.

          • extractionSeedTopK (integer) --

            How many of the strategy's stored memories that are most relevant to the conversation to include in the extraction prompt, from 0 to 20, to improve extraction and reduce duplicates. If you omit this or set it to 0, the service uses its default (see extractionSeedRecentN). When this and extractionSeedRecentN are both set, the two sets of memories are combined without duplicates.

          • extractionSeedRecentN (integer) --

            How many of the strategy's most recent stored memories to include in the extraction prompt, from 0 to 20. If you omit this or set it to 0, the service uses its default: no seeding for most strategy types, and the 10 most recent memories for a SUMMARY strategy when neither seed setting is given. When this and extractionSeedTopK are both set, the two sets of memories are combined without duplicates.

          • consolidationEnabled (boolean) --

            Specifies whether the strategy consolidates memories. With consolidation, each new memory is compared with similar stored memories, and the service adds it, updates a stored memory, or skips it, so duplicate or contradicting facts don't accumulate. Without it, every extracted memory is stored as a new memory, which costs less and keeps a full history.

            When omitted, the default depends on the strategy's type: on for SEMANTIC and SUMMARY, off for CUSTOM.

    • eventExpiryDays (integer) --

      How many days the space keeps each event. Absent when it was never set, in which case the default of 90 days applies.

    • memoryExpiryDays (integer) --

      How many days the space keeps each memory. 0 means memories never expire. Absent when it was never set, in which case memories never expire.

    • extractionModelId (string) --

      The model that extracts and consolidates memories for the space. Absent when it was never set, in which case the service default applies.

    • encryptionConfiguration (dict) --

      The AWS KMS key the space was created with. Absent when the space uses an AWS owned key.

      • kmsKeyArn (string) --

        The ARN of a customer managed AWS KMS key that encrypts the space's data. The key must be an enabled symmetric encryption key in the space's Region, and you need permission to create grants on it ( kms:CreateGrant). Otherwise, the request fails with ValidationException or AccessDeniedException.

GetEvent (new) Link ¶

Gets an event by ID, including its payload.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.get_event(
    spaceId='string',
    eventId='string',
    actorId='string',
    sessionId='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space.

type eventId:

string

param eventId:

[REQUIRED]

The event's ID, as returned by CreateEvent, ListEvents, or SearchEvents.

type actorId:

string

param actorId:

The actor the event must belong to. Omit it to skip this check. If it doesn't match the stored event, the call fails with ResourceNotFoundException, as if the event did not exist.

type sessionId:

string

param sessionId:

The session the event must belong to. Omit it to skip this check. If it doesn't match the stored event, the call fails with ResourceNotFoundException, as if the event did not exist.

rtype:

dict

returns:

Response Syntax

{
    'event': {
        'eventId': 'string',
        'spaceId': 'string',
        'actorId': 'string',
        'sessionId': 'string',
        'payload': {
            'conversational': {
                'unified': {
                    'source': {
                        'object': {
                            'messages': [
                                {
                                    'role': 'USER'|'ASSISTANT'|'SYSTEM',
                                    'content': {
                                        'text': 'string'
                                    }
                                },
                            ]
                        }
                    }
                }
            },
            'structuredData': {
                'source': {
                    'json': {...}|[...]|123|123.4|'string'|True|None
                }
            },
            'blob': {
                'contentType': 'application/pdf'|'image/png'|'image/jpeg',
                'source': {
                    's3Location': {
                        'uri': 'string'
                    }
                }
            }
        },
        'metadata': {
            'string': 'string'
        },
        'eventTimestamp': datetime(2015, 1, 1)
    }
}

Response Structure

  • (dict) --

    • event (dict) --

      The event, including its payload.

      • eventId (string) --

        The event's ID.

      • spaceId (string) --

        The ID of the space.

      • actorId (string) --

        The ID of the actor the event belongs to.

      • sessionId (string) --

        The ID of the session the event belongs to.

      • payload (dict) --

        The event's content, as submitted to CreateEvent.

        • conversational (dict) --

          Conversation turns.

          • unified (dict) --

            Conversation turns in the service's own format.

            • source (dict) --

              The conversation.

              • object (dict) --

                The conversation turns.

                • messages (list) --

                  The conversation turns, in order. The order matters for extraction.

                  • (dict) --

                    A conversation turn.

                    • role (string) --

                      The author of the turn.

                    • content (dict) --

                      The content of the turn.

                      • text (string) --

                        The text of the turn.

        • structuredData (dict) --

          Structured (non-conversational) content, for example a deployment result that an agent should remember.

          • source (dict) --

            The structured content.

            • json (:ref:`document<document>`) --

              The structured content, as a JSON object of at most 1 MiB when serialized as UTF-8, nested at most 10 levels deep.

        • blob (dict) --

          A document stored in Amazon S3, such as a PDF.

          • contentType (string) --

            The document's media type. Only application/pdf is supported. Any other value fails with ValidationException.

          • source (dict) --

            The location of the document.

            • s3Location (dict) --

              The S3 object holding the document.

              • uri (string) --

                The object's S3 URI, for example s3://bucket/key. The bucket must be in the space's Region. You need s3:GetObject on the object, and kms:Decrypt on its key if the object uses SSE-KMS. The event doesn't store the object itself.

      • metadata (dict) --

        The event's metadata tags, as supplied to CreateEvent. May be empty.

        • (string) --

          A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

          • (string) --

            The value of a metadata entry.

      • eventTimestamp (datetime) --

        The time the event occurred.

ListSpaces (new) Link ¶

Lists the spaces in your account in the current Region.

See also: AWS API Documentation

Request Syntax

client.list_spaces(
    maxResults=123,
    nextToken='string'
)
type maxResults:

integer

param maxResults:

The maximum number of spaces to return, from 1 to 100. The default is 100.

type nextToken:

string

param nextToken:

The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

rtype:

dict

returns:

Response Syntax

{
    'spaces': [
        {
            'spaceId': 'string',
            'arn': 'string',
            'name': 'string',
            'status': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING'|'DELETED'|'FAILED',
            'createdAt': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • spaces (list) --

      The spaces.

      • (dict) --

        A summary of a space, as returned by ListSpaces.

        • spaceId (string) --

          The ID of the space.

        • arn (string) --

          The Amazon Resource Name (ARN) of the space.

        • name (string) --

          The name of the space.

        • status (string) --

          The status of the space.

        • createdAt (datetime) --

          When the space was created.

    • nextToken (string) --

      The token for the next set of results. Absent when there are no more results.

SearchMemories (new) Link ¶

Searches a space's memories by relevance. The query is a subset of the OpenSearch Query DSL. The service validates it, limits the search to the requested strategies and to the actor in actorId, and returns one ranked list of memories. You can page through only a limited number of results. A request past that limit fails with ValidationException (reason invalidNextToken), and the message gives the limit.

Memories past their expiry (set from the space's memoryExpiryDays when each memory is written) are left out of the results. Only current memories are returned: a memory that consolidation has superseded (an older version of a fact that a newer memory replaced) is left out.

If the results are larger than 5 MiB, the request fails with ValidationException (reason queryBodyTooLarge). Lower maxResults.

If the request would exceed the service's rate for embedding requests, it fails with ThrottlingException. Retry with exponential backoff.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.search_memories(
    spaceId='string',
    memoryStrategies=[
        {
            'memoryType': 'SEMANTIC'|'SUMMARY'|'CUSTOM',
            'memoryStrategyNames': [
                'string',
            ]
        },
    ],
    actorId='string',
    query={...}|[...]|123|123.4|'string'|True|None,
    sort={...}|[...]|123|123.4|'string'|True|None,
    maxResults=123,
    nextToken='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The space to search. Use actorId to narrow the search within it.

type memoryStrategies:

list

param memoryStrategies:

The strategies to search, as a list of selectors. Each selector names a memory type and, optionally, specific strategy names of that type. A space can hold several strategies of the same type. A selector without memoryStrategyNames searches every strategy of its type, and omitting memoryStrategies searches every strategy in the space. A name that is not a declared strategy of that type fails with ValidationException.

  • (dict) --

    A memory type and, optionally, specific strategy names of that type. A space can hold several strategies of the same type, so the type and its names are given together.

    • memoryType (string) -- [REQUIRED]

      The memory type to search or list.

    • memoryStrategyNames (list) --

      Specific strategy names of memoryType. Omit it to include every strategy of that type.

      • (string) --

        The name of a strategy declared on a space, for example user-facts. Names are case-sensitive and must match the declared name exactly.

type actorId:

string

param actorId:

[REQUIRED]

The actor whose memories to search (exact match). Required: every search covers exactly one actor, and a memory stored without an actor is never returned. This is the only way to filter by actor: a query that references system_metadata.actor_id fails with ValidationException (reason nonFilterableField).

type query:

:ref:`document<document>`

param query:

[REQUIRED]

The query: a subset of the OpenSearch Query DSL (see SearchQuery). You can't use the actor and session fields system_metadata.actor_id and system_metadata.session_id here. Use the top-level actorId to filter by actor. Searching memories doesn't filter by session.

type sort:

:ref:`document<document>`

param sort:

The sort order (see SearchSort). Omit to return the most relevant memories first.

type maxResults:

integer

param maxResults:

The maximum number of memories to return, from 1 to 100. The default is 20.

type nextToken:

string

param nextToken:

The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

rtype:

dict

returns:

Response Syntax

{
    'memories': [
        {
            'memoryId': 'string',
            'memoryType': 'SEMANTIC'|'SUMMARY'|'CUSTOM',
            'strategyName': 'string',
            'content': 'string',
            'score': 123.0,
            'systemMetadata': {
                'actorId': 'string',
                'sessionId': 'string',
                'createdAt': datetime(2015, 1, 1),
                'updatedAt': datetime(2015, 1, 1)
            },
            'metadata': {
                'string': 'string'
            },
            'sourceEventIds': [
                'string',
            ]
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • memories (list) --

      The matching memories, in the order sort requests, or most relevant first when it has none. Empty when nothing matches.

      • (dict) --

        A SearchMemories result: a matching memory and its relevance score.

        • memoryId (string) --

          The memory's ID, assigned by the service. Always present.

        • memoryType (string) --

          The memory type of the result.

        • strategyName (string) --

          The name of the strategy the memory belongs to, for example user-facts: the strategy memoryStrategies selects on in SearchMemories. Absent when the memory's strategy is no longer declared on the space, for example right after the strategy is deleted.

        • content (string) --

          The memory text.

        • score (float) --

          The relevance score of the result. A higher score is more relevant. Scores aren't normalized to a fixed range and can be greater than 1, so use them only to order results.

        • systemMetadata (dict) --

          Provenance for the memory: the actor and session that own it, and when it was created and last updated. It is the same block that ListMemories, GetMemory, and SearchEvents return.

          In a query, filter or sort on the timestamps as system_metadata.created_at and system_metadata.updated_at. Scope by owner with the top-level actorId, not in the query. Searching memories doesn't filter by session.

          Absent when the service has no provenance for the memory.

          • actorId (string) --

            The owning actor. Absent when none was recorded.

          • sessionId (string) --

            The owning session. Absent when none was recorded.

          • createdAt (datetime) --

            When the record was created. Always present on ListMemories and GetMemory. It can be absent from search results.

          • updatedAt (datetime) --

            When the record was last updated. Equals createdAt for a record that has never been updated, and always for a SearchEvents result.

        • metadata (dict) --

          The memory's metadata tags. All values are strings. In a query, filter on a tag as metadata.<key>.

          • (string) --

            A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

            • (string) --

              The value of a metadata entry.

        • sourceEventIds (list) --

          The IDs of the events the memory was derived from, without duplicates. Use them with GetEvent or BatchGetEvent, or to search those events' content with SearchEvents by filtering on event_ids in the query. Absent for a memory created directly with CreateMemory. A memory can be derived from several events. The service sets this value.

          • (string) --

            An event ID, assigned by the service.

    • nextToken (string) --

      The token for the next set of results. Absent when there are no more results.

DeleteMemory (new) Link ¶

Deletes a memory, including its content and embedding. Deletion can't be undone. Searches stop returning the memory shortly after you delete it.

Deleting a memory that no longer exists returns ResourceNotFoundException, so the operation is not idempotent. If you retry deletes, treat that error as success.

A memory past its expiry (set from the space's memoryExpiryDays when the memory is written) reads as not found: the operation returns ResourceNotFoundException, as for a memory that was already deleted.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.delete_memory(
    spaceId='string',
    memoryId='string',
    actorId='string',
    strategyName='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space that owns the memory.

type memoryId:

string

param memoryId:

[REQUIRED]

The ID of the memory to delete.

type actorId:

string

param actorId:

The ID of the actor that the memory must belong to. Omit it to skip this check. If it doesn't match the stored memory, the call fails with ResourceNotFoundException, as if the memory did not exist.

type strategyName:

string

param strategyName:

The name of the strategy that the memory must belong to. Omit it to skip this check. If it doesn't match the stored memory, the call fails with ResourceNotFoundException, as if the memory did not exist.

rtype:

dict

returns:

Response Syntax

{
    'memoryId': 'string'
}

Response Structure

  • (dict) --

    • memoryId (string) --

      The ID of the deleted memory.

CreateEvent (new) Link ¶

Submits an event (conversation turns, structured data, or a PDF document stored in Amazon S3) to a session in a space.

The operation returns as soon as the event is saved. GetEvent and ListEvents return it immediately. SearchEvents returns it after it's indexed. SearchMemories returns memories extracted from it only after a strategy's extraction trigger fires and the memories are indexed.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.create_event(
    spaceId='string',
    actorId='string',
    sessionId='string',
    eventTimestamp=datetime(2015, 1, 1),
    payload={
        'conversational': {
            'unified': {
                'source': {
                    'object': {
                        'messages': [
                            {
                                'role': 'USER'|'ASSISTANT'|'SYSTEM',
                                'content': {
                                    'text': 'string'
                                }
                            },
                        ]
                    }
                }
            }
        },
        'structuredData': {
            'source': {
                'json': {...}|[...]|123|123.4|'string'|True|None
            }
        },
        'blob': {
            'contentType': 'application/pdf'|'image/png'|'image/jpeg',
            'source': {
                's3Location': {
                    'uri': 'string'
                }
            }
        }
    },
    metadata={
        'string': 'string'
    },
    clientToken='string',
    infer=True|False
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space that owns the event, for example sp-02864597b164.

type actorId:

string

param actorId:

[REQUIRED]

The ID of the actor (end user or agent) that the event belongs to.

type sessionId:

string

param sessionId:

The session the event belongs to. Send every event of one conversation with the same session ID, so that SUMMARY strategies summarize the conversation as one session. If you omit it, the service generates a session ID and returns it.

type eventTimestamp:

datetime

param eventTimestamp:

When the event occurred. The default is the time that the service receives the request.

type payload:

dict

param payload:

[REQUIRED]

The event content. Set exactly one union member.

  • conversational (dict) --

    Conversation turns.

    • unified (dict) --

      Conversation turns in the service's own format.

      • source (dict) -- [REQUIRED]

        The conversation.

        • object (dict) --

          The conversation turns.

          • messages (list) -- [REQUIRED]

            The conversation turns, in order. The order matters for extraction.

            • (dict) --

              A conversation turn.

              • role (string) -- [REQUIRED]

                The author of the turn.

              • content (dict) -- [REQUIRED]

                The content of the turn.

                • text (string) -- [REQUIRED]

                  The text of the turn.

  • structuredData (dict) --

    Structured (non-conversational) content, for example a deployment result that an agent should remember.

    • source (dict) -- [REQUIRED]

      The structured content.

      • json (:ref:`document<document>`) --

        The structured content, as a JSON object of at most 1 MiB when serialized as UTF-8, nested at most 10 levels deep.

  • blob (dict) --

    A document stored in Amazon S3, such as a PDF.

    • contentType (string) -- [REQUIRED]

      The document's media type. Only application/pdf is supported. Any other value fails with ValidationException.

    • source (dict) -- [REQUIRED]

      The location of the document.

      • s3Location (dict) --

        The S3 object holding the document.

        • uri (string) -- [REQUIRED]

          The object's S3 URI, for example s3://bucket/key. The bucket must be in the space's Region. You need s3:GetObject on the object, and kms:Decrypt on its key if the object uses SSE-KMS. The event doesn't store the object itself.

type metadata:

dict

param metadata:

Metadata tags to store with the event. Memories derived from the event carry the same tags. Keys that begin with x-amz-, the keys documentS3Source and documentS3Url, and other keys that the service uses internally are reserved: a request that sets one fails with ValidationException, and the message names the key.

A space can use at most 50 distinct metadata keys across all of its events and memories. A request that would add a key beyond that fails with ValidationException. Reuse an existing key instead.

  • (string) --

    A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

    • (string) --

      The value of a metadata entry.

type clientToken:

string

param clientToken:

A unique, case-sensitive identifier that makes the request idempotent. Within 2 hours of the first request, a retry with the same token and the same request, including the same sessionId, returns the same event. If you omit sessionId, the service generates a new one on each attempt, so a retry fails with ConflictException. Reusing the token with different request content also fails with ConflictException. eventTimestamp isn't compared. After 2 hours, the token starts a new event.

This field is autopopulated if not provided.

type infer:

boolean

param infer:

Specifies whether to extract memories from this event. The default is true. Set it to false to store the event without extraction: the service skips strategies that infer memories, and still indexes the event's turns for SearchEvents. A document submitted as a blob is still extracted.

rtype:

dict

returns:

Response Syntax

{
    'event': {
        'eventId': 'string',
        'spaceId': 'string',
        'actorId': 'string',
        'sessionId': 'string',
        'eventTimestamp': datetime(2015, 1, 1)
    }
}

Response Structure

  • (dict) --

    • event (dict) --

      The stored event's identifiers: its ID, session, and timestamp.

      • eventId (string) --

        The event's ID, assigned by the service. Use it with GetEvent and DeleteEvent.

      • spaceId (string) --

        The ID of the space.

      • actorId (string) --

        The ID of the actor the event belongs to.

      • sessionId (string) --

        The ID of the session the event belongs to, including one the service generated.

      • eventTimestamp (datetime) --

        When the event occurred: the value supplied, or the time the request was received.

BatchGetEvent (new) Link ¶

Gets up to 10 events by ID, each as GetEvent returns it, including its payload.

If you supply actorId or sessionId, every requested event must match it. Each event has its own outcome. The operation reports an event that it can't return in errors instead of failing, with an error code named for the exception that GetEvent would return for it. The operation reports both an event that doesn't exist and an event outside the supplied scope as RESOURCE_NOT_FOUND.

The exception is the space's customer managed AWS KMS key: if it is disabled, pending deletion, can't be used for decryption, or was deleted, the whole call fails with ValidationException, as GetEvent does.

See also: AWS API Documentation

Request Syntax

client.batch_get_event(
    spaceId='string',
    actorId='string',
    sessionId='string',
    eventIds=[
        'string',
    ]
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space.

type actorId:

string

param actorId:

The actor that every requested event must belong to. Omit it to skip this check. The operation reports an event that doesn't match in errors as RESOURCE_NOT_FOUND.

type sessionId:

string

param sessionId:

The session that every requested event must belong to. Omit it to skip this check. The operation reports an event that doesn't match in errors as RESOURCE_NOT_FOUND.

type eventIds:

list

param eventIds:

[REQUIRED]

The IDs of the events to get: 1 to 10, without duplicates.

  • (string) --

    An event ID, assigned by the service.

rtype:

dict

returns:

Response Syntax

{
    'events': [
        {
            'eventId': 'string',
            'spaceId': 'string',
            'actorId': 'string',
            'sessionId': 'string',
            'payload': {
                'conversational': {
                    'unified': {
                        'source': {
                            'object': {
                                'messages': [
                                    {
                                        'role': 'USER'|'ASSISTANT'|'SYSTEM',
                                        'content': {
                                            'text': 'string'
                                        }
                                    },
                                ]
                            }
                        }
                    }
                },
                'structuredData': {
                    'source': {
                        'json': {...}|[...]|123|123.4|'string'|True|None
                    }
                },
                'blob': {
                    'contentType': 'application/pdf'|'image/png'|'image/jpeg',
                    'source': {
                        's3Location': {
                            'uri': 'string'
                        }
                    }
                }
            },
            'metadata': {
                'string': 'string'
            },
            'eventTimestamp': datetime(2015, 1, 1)
        },
    ],
    'errors': [
        {
            'eventId': 'string',
            'errorCode': 'RESOURCE_NOT_FOUND'|'THROTTLING'|'ACCESS_DENIED'|'INTERNAL_SERVER',
            'message': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • events (list) --

      The events found, in the order that you requested their IDs.

      • (dict) --

        An event, including its payload.

        • eventId (string) --

          The event's ID.

        • spaceId (string) --

          The ID of the space.

        • actorId (string) --

          The ID of the actor the event belongs to.

        • sessionId (string) --

          The ID of the session the event belongs to.

        • payload (dict) --

          The event's content, as submitted to CreateEvent.

          • conversational (dict) --

            Conversation turns.

            • unified (dict) --

              Conversation turns in the service's own format.

              • source (dict) --

                The conversation.

                • object (dict) --

                  The conversation turns.

                  • messages (list) --

                    The conversation turns, in order. The order matters for extraction.

                    • (dict) --

                      A conversation turn.

                      • role (string) --

                        The author of the turn.

                      • content (dict) --

                        The content of the turn.

                        • text (string) --

                          The text of the turn.

          • structuredData (dict) --

            Structured (non-conversational) content, for example a deployment result that an agent should remember.

            • source (dict) --

              The structured content.

              • json (:ref:`document<document>`) --

                The structured content, as a JSON object of at most 1 MiB when serialized as UTF-8, nested at most 10 levels deep.

          • blob (dict) --

            A document stored in Amazon S3, such as a PDF.

            • contentType (string) --

              The document's media type. Only application/pdf is supported. Any other value fails with ValidationException.

            • source (dict) --

              The location of the document.

              • s3Location (dict) --

                The S3 object holding the document.

                • uri (string) --

                  The object's S3 URI, for example s3://bucket/key. The bucket must be in the space's Region. You need s3:GetObject on the object, and kms:Decrypt on its key if the object uses SSE-KMS. The event doesn't store the object itself.

        • metadata (dict) --

          The event's metadata tags, as supplied to CreateEvent. May be empty.

          • (string) --

            A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

            • (string) --

              The value of a metadata entry.

        • eventTimestamp (datetime) --

          The time the event occurred.

    • errors (list) --

      An entry for each requested event that the call didn't return. Empty when the call returned every event.

      • (dict) --

        A requested event that the call didn't return, and the reason.

        • eventId (string) --

          The ID of the requested event.

        • errorCode (string) --

          The reason that the call didn't return the event.

        • message (string) --

          A human-readable description.

DeleteSpace (new) Link ¶

Deletes a space and its memories. Deletion can't be undone. After you delete the space, you can't retrieve its events, and the service removes them when they reach their expiry.

The operation returns with status DELETING. When deletion finishes, GetSpace returns ResourceNotFoundException. If deletion fails, the status becomes FAILED. A space that is CREATING or UPDATING can't be deleted until that finishes: the request fails with ConflictException. Deleting a space that is already DELETING returns DELETING again.

See also: AWS API Documentation

Request Syntax

client.delete_space(
    spaceId='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space to delete.

rtype:

dict

returns:

Response Syntax

{
    'spaceId': 'string',
    'status': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING'|'DELETED'|'FAILED'
}

Response Structure

  • (dict) --

    • spaceId (string) --

      The ID of the space.

    • status (string) --

      The status of the space: DELETING.

DeleteEvent (new) Link ¶

Deletes an event. Deletion can't be undone. The event stops appearing in SearchEvents results shortly after you delete it. Deleting an event that doesn't exist returns ResourceNotFoundException.

Deleting an event doesn't delete the memories derived from it, because a memory can combine content from several events. To remove them, use DeleteMemory.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.delete_event(
    spaceId='string',
    eventId='string',
    actorId='string',
    sessionId='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space.

type eventId:

string

param eventId:

[REQUIRED]

The ID of the event to delete.

type actorId:

string

param actorId:

The actor that the event must belong to. Omit it to skip this check. If it doesn't match the stored event, the call fails with ResourceNotFoundException, as if the event did not exist.

type sessionId:

string

param sessionId:

The session that the event must belong to. Omit it to skip this check. If it doesn't match the stored event, the call fails with ResourceNotFoundException, as if the event did not exist.

rtype:

dict

returns:

Response Syntax

{
    'eventId': 'string'
}

Response Structure

  • (dict) --

    • eventId (string) --

      The ID of the deleted event.

TagResource (new) Link ¶

Adds the specified tags to the specified space.

See also: AWS API Documentation

Request Syntax

client.tag_resource(
    resourceArn='string',
    tags=[
        {
            'key': 'string',
            'value': 'string'
        },
    ]
)
type resourceArn:

string

param resourceArn:

[REQUIRED]

The Amazon Resource Name (ARN) of the space.

type tags:

list

param tags:

[REQUIRED]

The tags to add to the space.

  • (dict) --

    A tag: a key-value pair that you attach to a space.

    • key (string) -- [REQUIRED]

      The key of the tag.

    • value (string) -- [REQUIRED]

      The value of the tag.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

  • (dict) --

UpdateSpace (new) Link ¶

Updates a space's memory strategies, retention settings, or extraction model. Supply only the fields to change. Omitted fields keep their current values.

If the request changes the set of strategies, a strategy's configuration, a retention setting, or the extraction model, the space moves to UPDATING. When the change is complete, the space returns to ACTIVE, or moves to FAILED if the change can't be applied. While the space is UPDATING, GetSpace returns the previous configuration. A request that only changes strategy descriptions or repeats the values the space has stored is applied immediately and doesn't change the status. Sending a retention value that the space never set also moves the space to UPDATING, even one that matches the behavior without it, such as 90 for eventExpiryDays or 0 for memoryExpiryDays. A space that is CREATING, UPDATING, or DELETING can't be updated: the request fails with ConflictException.

See also: AWS API Documentation

Request Syntax

client.update_space(
    spaceId='string',
    memoryStrategies=[
        {
            'type': 'SEMANTIC'|'SUMMARY'|'CUSTOM',
            'name': 'string',
            'description': 'string',
            'configuration': {
                'extractionPrompt': 'string',
                'extractEveryNMessages': 123,
                'extractEveryNTokens': 123,
                'idleTimeoutSeconds': 123,
                'extractionSeedTopK': 123,
                'extractionSeedRecentN': 123,
                'consolidationEnabled': True|False
            }
        },
    ],
    eventExpiryDays=123,
    memoryExpiryDays=123,
    extractionModelId='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space to update.

type memoryStrategies:

list

param memoryStrategies:

The complete new list of memory strategies. The service removes strategies that aren't in the list from the space. Removing a strategy stops extraction for it but doesn't delete its memories: they're kept, until they expire if the space sets memoryExpiryDays, and they're available again if you later add a strategy with the same type and name. To delete them, use DeleteMemory before you remove the strategy, or delete the space.

To keep a strategy, include it with the same type and name that GetSpace returns. For a kept strategy, any configuration member you omit keeps its current value. It doesn't return to the default, and you can't clear a member once it's set. Omit this field to leave the strategies unchanged. The list must name at least one strategy. You can't remove every strategy from a space with UpdateSpace.

The serialized list can be at most 384 KiB.

  • (dict) --

    A memory strategy: how a space extracts one kind of memory from its events.

    • type (string) -- [REQUIRED]

      The type of memory the strategy extracts.

    • name (string) --

      A name for the strategy, unique within the space. Omit it to have the service generate one from the type, for example semantic_1. The name must be 1 to 64 characters: letters, digits, periods, hyphens, and underscores, starting with a letter or digit. A strategy's name can't be changed, and the strategy's memories are stored under it: a strategy added under a new name starts with no memories.

    • description (string) --

      A description of the strategy.

    • configuration (dict) --

      Settings for the strategy. When you create a strategy, omit it to use the defaults for the strategy's type.

      A CUSTOM strategy must set extractionPrompt.

      • extractionPrompt (string) --

        Instructions that define what a CUSTOM strategy extracts, up to 30,720 characters. Required for a CUSTOM strategy: CreateSpace and UpdateSpace fail with ValidationException if a CUSTOM strategy has none.

        Only CUSTOM strategies use it. SEMANTIC and SUMMARY strategies always extract with the service's built-in instructions: the service accepts and stores a prompt on them, and GetSpace returns it, but extraction doesn't use it.

      • extractEveryNMessages (integer) --

        Extract once this many messages have accumulated, from 1 to 1000. Lower values extract more often, in smaller batches. The default is 12.

        Messages accumulate until the first of extractEveryNMessages, extractEveryNTokens, and idleTimeoutSeconds is reached. The service then extracts them together in one pass.

      • extractEveryNTokens (integer) --

        Extract once this many tokens of conversation have accumulated, from 1 to 80,000, however few messages that takes. Use it to bound how much text one extraction call carries when message sizes vary widely. Omit it to bound a batch only by extractEveryNMessages, idleTimeoutSeconds, and the service's maximum batch size.

      • idleTimeoutSeconds (integer) --

        Extract what has accumulated once the conversation has been idle for this many seconds, from 1 to 86,400. The default is 60. This is what extracts the end of a conversation that stops. Raise it when the pauses in your conversations are longer than that, so that one exchange isn't split across several extraction passes.

      • extractionSeedTopK (integer) --

        How many of the strategy's stored memories that are most relevant to the conversation to include in the extraction prompt, from 0 to 20, to improve extraction and reduce duplicates. If you omit this or set it to 0, the service uses its default (see extractionSeedRecentN). When this and extractionSeedRecentN are both set, the two sets of memories are combined without duplicates.

      • extractionSeedRecentN (integer) --

        How many of the strategy's most recent stored memories to include in the extraction prompt, from 0 to 20. If you omit this or set it to 0, the service uses its default: no seeding for most strategy types, and the 10 most recent memories for a SUMMARY strategy when neither seed setting is given. When this and extractionSeedTopK are both set, the two sets of memories are combined without duplicates.

      • consolidationEnabled (boolean) --

        Specifies whether the strategy consolidates memories. With consolidation, each new memory is compared with similar stored memories, and the service adds it, updates a stored memory, or skips it, so duplicate or contradicting facts don't accumulate. Without it, every extracted memory is stored as a new memory, which costs less and keeps a full history.

        When omitted, the default depends on the strategy's type: on for SEMANTIC and SUMMARY, off for CUSTOM.

type eventExpiryDays:

integer

param eventExpiryDays:

How many days the space keeps each event, from 1 to 365. Omit it to leave the current value unchanged. Events already stored keep the expiry they were written with.

type memoryExpiryDays:

integer

param memoryExpiryDays:

How many days the space keeps each memory, from 0 to 3650. 0 means memories never expire. Omit it to leave the current value unchanged. You can't clear the setting. To make memories written from then on never expire, send 0. GetSpace then returns 0.

A change applies to memories written after it. Memories already stored keep the expiry they were written with. A memory the service rewrites later, such as a summary it keeps up to date, takes the setting in force at that rewrite. A change moves the space to UPDATING. Sending the value that the space has stored doesn't.

type extractionModelId:

string

param extractionModelId:

The model that extracts and consolidates memories for every strategy in the space: anthropic.claude-opus-5-5 or anthropic.claude-haiku-5-5. Omit it to leave the current value unchanged. Once set, it can't be cleared back to the service default.

rtype:

dict

returns:

Response Syntax

{
    'spaceId': 'string',
    'status': 'CREATING'|'ACTIVE'|'UPDATING'|'DELETING'|'DELETED'|'FAILED'
}

Response Structure

  • (dict) --

    • spaceId (string) --

      The ID of the space.

    • status (string) --

      The status of the space: UPDATING when the change has to be applied to the space's strategies, retention, or extraction model. Otherwise, the space's current status.

CreateMemory (new) Link ¶

Writes a memory that you have already formed, without extracting it from events. The service embeds the text as given and stores it as a memory of the named strategy. To have the service extract memories from conversation turns, use CreateEvent instead.

The operation returns before the memory is searchable. The returned memoryId is final, but until the memory is indexed, GetMemory, UpdateMemory, and DeleteMemory return ResourceNotFoundException for it.

If the request would exceed the service's rate for embedding requests, it fails with ThrottlingException. Retry with exponential backoff.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.create_memory(
    spaceId='string',
    name='string',
    content='string',
    actorId='string',
    sessionId='string',
    metadata={
        'string': 'string'
    },
    clientToken='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space that owns the memory, for example sp-02864597b164.

type name:

string

param name:

[REQUIRED]

The name of the strategy that the memory belongs to. The space must already declare the strategy, and the memory's type comes from that strategy. The name must be 1 to 64 characters: letters, digits, periods, hyphens, and underscores, starting with a letter or digit.

type content:

string

param content:

[REQUIRED]

The memory text, stored and embedded as provided.

type actorId:

string

param actorId:

[REQUIRED]

The actor (end user or agent) that owns the memory.

type sessionId:

string

param sessionId:

The session that the memory belongs to. If you omit it, the service generates a session ID and returns it.

type metadata:

dict

param metadata:

Metadata tags to store with the memory. Keys that begin with x-amz-, the key documentS3Source, and other keys that the service uses internally are reserved: a request that sets one fails with ValidationException, and the message names the key.

A space can use at most 50 distinct metadata keys across all of its events and memories. A request that would add a key beyond that fails with ValidationException. Reuse an existing key instead.

  • (string) --

    A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

    • (string) --

      The value of a metadata entry.

type clientToken:

string

param clientToken:

A unique, case-sensitive identifier that makes the request idempotent. Within 2 hours of the first request, a retry with the same token returns the same memoryId instead of creating a second memory. Reusing the token with a different name, content, metadata, actorId, or sessionId fails with ConflictException. If you omit sessionId, a retry with the same token gets the same session. If you omit the token, each call creates a new memory.

This field is autopopulated if not provided.

rtype:

dict

returns:

Response Syntax

{
    'memory': {
        'memoryId': 'string',
        'spaceId': 'string',
        'name': 'string',
        'actorId': 'string',
        'sessionId': 'string'
    }
}

Response Structure

  • (dict) --

    The acknowledged memory. It isn't searchable yet when the call returns.

    • memory (dict) --

      The memory, identified but not yet indexed.

      • memoryId (string) --

        The final ID of the memory. Until the memory is indexed, GetMemory, UpdateMemory, and DeleteMemory return ResourceNotFoundException for it.

      • spaceId (string) --

        The ID of the space.

      • name (string) --

        The name of the strategy the memory belongs to.

      • actorId (string) --

        The ID of the actor the memory belongs to.

      • sessionId (string) --

        The ID of the session the memory belongs to, including one the service generated.

GetMemory (new) Link ¶

Gets a memory by ID, as returned by SearchMemories or ListMemories. A memory that doesn't exist returns ResourceNotFoundException. Unlike SearchMemories, this operation also returns memories that consolidation has superseded.

A memory past its expiry (set from the space's memoryExpiryDays when the memory is written) reads as not found: ResourceNotFoundException, the same answer as for an ID that does not exist.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.get_memory(
    spaceId='string',
    memoryId='string',
    actorId='string',
    strategyName='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space that holds the memory.

type memoryId:

string

param memoryId:

[REQUIRED]

The memory's ID, as returned by SearchMemories or ListMemories.

type actorId:

string

param actorId:

The ID of the actor the memory must belong to. Omit it to skip this check. If it doesn't match the stored memory, the call fails with ResourceNotFoundException, as if the memory did not exist.

type strategyName:

string

param strategyName:

The name of the strategy the memory must belong to. Omit it to skip this check. If it doesn't match the stored memory, the call fails with ResourceNotFoundException, as if the memory did not exist.

rtype:

dict

returns:

Response Syntax

{
    'memory': {
        'memoryId': 'string',
        'memoryType': 'SEMANTIC'|'SUMMARY'|'CUSTOM',
        'strategyName': 'string',
        'content': 'string',
        'systemMetadata': {
            'actorId': 'string',
            'sessionId': 'string',
            'createdAt': datetime(2015, 1, 1),
            'updatedAt': datetime(2015, 1, 1)
        },
        'metadata': {
            'string': 'string'
        }
    }
}

Response Structure

  • (dict) --

    • memory (dict) --

      The memory. Always present: a memory that doesn't exist returns ResourceNotFoundException.

      • memoryId (string) --

        The memory's ID, assigned by the service.

      • memoryType (string) --

        The memory type.

      • strategyName (string) --

        The name of the strategy the memory belongs to, for example user-facts. A space can hold several strategies of the same type, so this tells them apart. Absent when the memory's strategy is no longer declared on the space, for example right after the strategy is deleted.

      • content (string) --

        The memory text.

      • systemMetadata (dict) --

        Provenance for the memory: the owning actor and session, and when it was created and last updated. Always present. updatedAt equals createdAt for a memory that has never been updated.

        • actorId (string) --

          The owning actor. Absent when none was recorded.

        • sessionId (string) --

          The owning session. Absent when none was recorded.

        • createdAt (datetime) --

          When the record was created. Always present on ListMemories and GetMemory. It can be absent from search results.

        • updatedAt (datetime) --

          When the record was last updated. Equals createdAt for a record that has never been updated, and always for a SearchEvents result.

      • metadata (dict) --

        The memory's metadata tags. All values are strings. May be empty.

        • (string) --

          A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

          • (string) --

            The value of a metadata entry.

ListEvents (new) Link ¶

Lists the events in a session, sorted by time. Optionally limit the results to events whose eventTimestamp falls between eventTimestampAfter and eventTimestampBefore. Returns event metadata only. Call GetEvent for the payload. For full-text or relevance search, use SearchEvents.

If the space uses a customer managed AWS KMS key, the call can also fail because of the key. It fails with AccessDeniedException if you aren't allowed to use the key, and with ThrottlingException if AWS KMS throttles the request. It fails with ValidationException if the key is disabled, pending deletion, or deleted.

See also: AWS API Documentation

Request Syntax

client.list_events(
    spaceId='string',
    actorId='string',
    sessionId='string',
    eventTimestampBefore=datetime(2015, 1, 1),
    eventTimestampAfter=datetime(2015, 1, 1),
    sortOrder='ASC'|'DESC',
    metadataFilters={
        'string': 'string'
    },
    maxResults=123,
    nextToken='string'
)
type spaceId:

string

param spaceId:

[REQUIRED]

The ID of the space.

type actorId:

string

param actorId:

[REQUIRED]

The actor whose events to list.

type sessionId:

string

param sessionId:

[REQUIRED]

The session whose events to list. To find events across sessions, use SearchEvents.

type eventTimestampBefore:

datetime

param eventTimestampBefore:

Inclusive upper bound on eventTimestamp: only events at or before this time are returned. Omit for no upper bound.

type eventTimestampAfter:

datetime

param eventTimestampAfter:

Inclusive lower bound on eventTimestamp: only events at or after this time are returned. Omit for no lower bound.

If it's later than eventTimestampBefore, the request fails with ValidationException.

type sortOrder:

string

param sortOrder:

The order of the results by eventTimestamp: ASC or DESC. The default is DESC, most recent first.

type metadataFilters:

dict

param metadataFilters:

Returns only events whose metadata contains every one of these key-value pairs. Omit, or leave empty, for no metadata filter. The service applies the filter after it reads events, so a page can hold fewer than maxResults events, or none, and still return a nextToken. Keep paging until nextToken is absent.

  • (string) --

    A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

    • (string) --

      The value of a metadata entry.

type maxResults:

integer

param maxResults:

The maximum number of events to return, from 1 to 100. The default is 20.

type nextToken:

string

param nextToken:

The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

rtype:

dict

returns:

Response Syntax

{
    'events': [
        {
            'eventId': 'string',
            'metadata': {
                'string': 'string'
            },
            'eventTimestamp': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • events (list) --

      The events, without their payloads. Call GetEvent for an event's payload.

      • (dict) --

        A summary of an event, as returned by ListEvents. It doesn't include the payload.

        • eventId (string) --

          The event's ID.

        • metadata (dict) --

          The event's metadata tags, as supplied to CreateEvent. May be empty.

          • (string) --

            A metadata key: letters, digits, hyphens ( -), and underscores ( _). Dots are not allowed, because a query uses dots to separate nested field names.

            • (string) --

              The value of a metadata entry.

        • eventTimestamp (datetime) --

          The time the event occurred.

    • nextToken (string) --

      The token for the next set of results. Absent when there are no more results.