SDK for PHP V3

Client: Aws\OpenSearchMemory\OpenSearchMemoryClient
Service ID: opensearchmemory
Version: 2026-08-24

This page describes the parameters and results for the operations of the Amazon OpenSearch Memory (2026-08-24), and shows how to use the Aws\OpenSearchMemory\OpenSearchMemoryClient object to call the described operations. This documentation is specific to the 2026-08-24 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

BatchGetEvent ( array $params = [] )
Gets up to 10 events by ID, each as GetEvent returns it, including its payload.
CreateEvent ( array $params = [] )
Submits an event (conversation turns, structured data, or a PDF document stored in Amazon S3) to a session in a space.
CreateMemory ( array $params = [] )
Writes a memory that you have already formed, without extracting it from events.
CreateSpace ( array $params = [] )
Creates a space.
DeleteEvent ( array $params = [] )
Deletes an event.
DeleteMemory ( array $params = [] )
Deletes a memory, including its content and embedding.
DeleteSpace ( array $params = [] )
Deletes a space and its memories.
GetEvent ( array $params = [] )
Gets an event by ID, including its payload.
GetMemory ( array $params = [] )
Gets a memory by ID, as returned by SearchMemories or ListMemories.
GetSpace ( array $params = [] )
Returns a space's configuration and status.
ListEvents ( array $params = [] )
Lists the events in a session, sorted by time.
ListMemories ( array $params = [] )
Lists a space's memories without a query, for example the most recent memories or the memories of one strategy.
ListSpaces ( array $params = [] )
Lists the spaces in your account in the current Region.
ListTagsForResource ( array $params = [] )
Lists the tags for the specified space.
SearchEvents ( array $params = [] )
Searches a space's events by relevance.
SearchMemories ( array $params = [] )
Searches a space's memories by relevance.
TagResource ( array $params = [] )
Adds the specified tags to the specified space.
UntagResource ( array $params = [] )
Removes the specified tags from the specified space.
UpdateMemory ( array $params = [] )
Updates a memory in place.
UpdateSpace ( array $params = [] )
Updates a space's memory strategies, retention settings, or extraction model.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

ListEvents
ListMemories
ListSpaces
SearchEvents
SearchMemories

Waiters

Waiters allow you to poll a resource until it enters into a desired state. A waiter has a name used to describe what it does, and is associated with an API operation. When creating a waiter, you can provide the API operation parameters associated with the corresponding operation. Waiters can be accessed using the getWaiter($waiterName, $operationParameters) method of a client object. This client supports the following waiters:

Waiter name API Operation Delay Max Attempts
SpaceActive GetSpace 10 60
SpaceDeleted GetSpace 10 60

Operations

BatchGetEvent

$result = $client->batchGetEvent([/* ... */]);
$promise = $client->batchGetEventAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->batchGetEvent([
    'actorId' => '<string>',
    'eventIds' => ['<string>', ...], // REQUIRED
    'sessionId' => '<string>',
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
actorId
Type: string

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.

eventIds
Required: Yes
Type: Array of strings

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

sessionId
Type: string

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.

spaceId
Required: Yes
Type: string

The ID of the space.

Result Syntax

[
    'errors' => [
        [
            'errorCode' => 'RESOURCE_NOT_FOUND|THROTTLING|ACCESS_DENIED|INTERNAL_SERVER',
            'eventId' => '<string>',
            'message' => '<string>',
        ],
        // ...
    ],
    'events' => [
        [
            'actorId' => '<string>',
            'eventId' => '<string>',
            'eventTimestamp' => <DateTime>,
            'metadata' => ['<string>', ...],
            'payload' => [
                'blob' => [
                    'contentType' => 'application/pdf|image/png|image/jpeg',
                    'source' => [
                        's3Location' => [
                            'uri' => '<string>',
                        ],
                    ],
                ],
                'conversational' => [
                    'unified' => [
                        'source' => [
                            'object' => [
                                'messages' => [
                                    [
                                        'content' => [
                                            'text' => '<string>',
                                        ],
                                        'role' => 'USER|ASSISTANT|SYSTEM',
                                    ],
                                    // ...
                                ],
                            ],
                        ],
                    ],
                ],
                'structuredData' => [
                    'source' => [
                        'json' => [
                        ],
                    ],
                ],
            ],
            'sessionId' => '<string>',
            'spaceId' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
errors
Required: Yes
Type: Array of BatchGetEventError structures

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

events
Required: Yes
Type: Array of Event structures

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

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

CreateEvent

$result = $client->createEvent([/* ... */]);
$promise = $client->createEventAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->createEvent([
    'actorId' => '<string>', // REQUIRED
    'clientToken' => '<string>',
    'eventTimestamp' => <integer || string || DateTime>,
    'infer' => true || false,
    'metadata' => ['<string>', ...],
    'payload' => [ // REQUIRED
        'blob' => [
            'contentType' => 'application/pdf|image/png|image/jpeg', // REQUIRED
            'source' => [ // REQUIRED
                's3Location' => [
                    'uri' => '<string>', // REQUIRED
                ],
            ],
        ],
        'conversational' => [
            'unified' => [
                'source' => [ // REQUIRED
                    'object' => [
                        'messages' => [ // REQUIRED
                            [
                                'content' => [ // REQUIRED
                                    'text' => '<string>', // REQUIRED
                                ],
                                'role' => 'USER|ASSISTANT|SYSTEM', // REQUIRED
                            ],
                            // ...
                        ],
                    ],
                ],
            ],
        ],
        'structuredData' => [
            'source' => [ // REQUIRED
                'json' => [
                ],
            ],
        ],
    ],
    'sessionId' => '<string>',
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
actorId
Required: Yes
Type: string

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

clientToken
Type: string

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.

eventTimestamp
Type: timestamp (string|DateTime or anything parsable by strtotime)

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

infer
Type: boolean

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.

metadata
Type: Associative array of custom strings keys (MetadataKey) to strings

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.

payload
Required: Yes
Type: EventPayload structure

The event content. Set exactly one union member.

sessionId
Type: string

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.

spaceId
Required: Yes
Type: string

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

Result Syntax

[
    'event' => [
        'actorId' => '<string>',
        'eventId' => '<string>',
        'eventTimestamp' => <DateTime>,
        'sessionId' => '<string>',
        'spaceId' => '<string>',
    ],
]

Result Details

Members
event
Required: Yes
Type: EventDetail structure

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

Errors

ConflictException:

The request conflicts with the current state of the resource. For example, the space is being created, updated, or deleted, a space with the same name already exists, or you reused a client token with different parameters. Wait for the space to finish being created, updated, or deleted, or use a different name or client token, and then retry.

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

CreateMemory

$result = $client->createMemory([/* ... */]);
$promise = $client->createMemoryAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->createMemory([
    'actorId' => '<string>', // REQUIRED
    'clientToken' => '<string>',
    'content' => '<string>', // REQUIRED
    'metadata' => ['<string>', ...],
    'name' => '<string>', // REQUIRED
    'sessionId' => '<string>',
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
actorId
Required: Yes
Type: string

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

clientToken
Type: string

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.

content
Required: Yes
Type: string

The memory text, stored and embedded as provided.

metadata
Type: Associative array of custom strings keys (MetadataKey) to strings

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.

name
Required: Yes
Type: string

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.

sessionId
Type: string

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

spaceId
Required: Yes
Type: string

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

Result Syntax

[
    'memory' => [
        'actorId' => '<string>',
        'memoryId' => '<string>',
        'name' => '<string>',
        'sessionId' => '<string>',
        'spaceId' => '<string>',
    ],
]

Result Details

Members
memory
Required: Yes
Type: CreateMemoryDetail structure

The memory, identified but not yet indexed.

Errors

ConflictException:

The request conflicts with the current state of the resource. For example, the space is being created, updated, or deleted, a space with the same name already exists, or you reused a client token with different parameters. Wait for the space to finish being created, updated, or deleted, or use a different name or client token, and then retry.

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

CreateSpace

$result = $client->createSpace([/* ... */]);
$promise = $client->createSpaceAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->createSpace([
    'clientToken' => '<string>',
    'encryptionConfiguration' => [
        'kmsKeyArn' => '<string>',
    ],
    'eventExpiryDays' => <integer>,
    'extractionModelId' => '<string>',
    'memoryExpiryDays' => <integer>,
    'memoryStrategies' => [
        [
            'configuration' => [
                'consolidationEnabled' => true || false,
                'extractEveryNMessages' => <integer>,
                'extractEveryNTokens' => <integer>,
                'extractionPrompt' => '<string>',
                'extractionSeedRecentN' => <integer>,
                'extractionSeedTopK' => <integer>,
                'idleTimeoutSeconds' => <integer>,
            ],
            'description' => '<string>',
            'name' => '<string>',
            'type' => 'SEMANTIC|SUMMARY|CUSTOM', // REQUIRED
        ],
        // ...
    ],
    'name' => '<string>', // REQUIRED
    'tags' => [
        [
            'key' => '<string>', // REQUIRED
            'value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members
clientToken
Type: string

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.

encryptionConfiguration
Type: EncryptionConfiguration structure

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.

eventExpiryDays
Type: int

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

extractionModelId
Type: string

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.

memoryExpiryDays
Type: int

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.

memoryStrategies
Type: Array of MemoryStrategy structures

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.

name
Required: Yes
Type: string

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

tags
Type: Array of Tag structures

The tags to add to the space.

Result Syntax

[
    'arn' => '<string>',
    'createdAt' => <DateTime>,
    'name' => '<string>',
    'spaceId' => '<string>',
    'status' => 'CREATING|ACTIVE|UPDATING|DELETING|DELETED|FAILED',
]

Result Details

Members
arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the space.

createdAt
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

When the space was created.

name
Required: Yes
Type: string

The name of the space.

spaceId
Required: Yes
Type: string

The ID of the space.

status
Required: Yes
Type: string

The status of the space: CREATING.

Errors

ConflictException:

The request conflicts with the current state of the resource. For example, the space is being created, updated, or deleted, a space with the same name already exists, or you reused a client token with different parameters. Wait for the space to finish being created, updated, or deleted, or use a different name or client token, and then retry.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

ServiceQuotaExceededException:

The request would exceed a quota, such as the number of spaces in your account or the number of strategies in a space.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

DeleteEvent

$result = $client->deleteEvent([/* ... */]);
$promise = $client->deleteEventAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->deleteEvent([
    'actorId' => '<string>',
    'eventId' => '<string>', // REQUIRED
    'sessionId' => '<string>',
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
actorId
Type: string

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.

eventId
Required: Yes
Type: string

The ID of the event to delete.

sessionId
Type: string

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.

spaceId
Required: Yes
Type: string

The ID of the space.

Result Syntax

[
    'eventId' => '<string>',
]

Result Details

Members
eventId
Required: Yes
Type: string

The ID of the deleted event.

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

DeleteMemory

$result = $client->deleteMemory([/* ... */]);
$promise = $client->deleteMemoryAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->deleteMemory([
    'actorId' => '<string>',
    'memoryId' => '<string>', // REQUIRED
    'spaceId' => '<string>', // REQUIRED
    'strategyName' => '<string>',
]);

Parameter Details

Members
actorId
Type: string

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.

memoryId
Required: Yes
Type: string

The ID of the memory to delete.

spaceId
Required: Yes
Type: string

The ID of the space that owns the memory.

strategyName
Type: string

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.

Result Syntax

[
    'memoryId' => '<string>',
]

Result Details

Members
memoryId
Required: Yes
Type: string

The ID of the deleted memory.

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

DeleteSpace

$result = $client->deleteSpace([/* ... */]);
$promise = $client->deleteSpaceAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->deleteSpace([
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
spaceId
Required: Yes
Type: string

The ID of the space to delete.

Result Syntax

[
    'spaceId' => '<string>',
    'status' => 'CREATING|ACTIVE|UPDATING|DELETING|DELETED|FAILED',
]

Result Details

Members
spaceId
Required: Yes
Type: string

The ID of the space.

status
Required: Yes
Type: string

The status of the space: DELETING.

Errors

ConflictException:

The request conflicts with the current state of the resource. For example, the space is being created, updated, or deleted, a space with the same name already exists, or you reused a client token with different parameters. Wait for the space to finish being created, updated, or deleted, or use a different name or client token, and then retry.

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

GetEvent

$result = $client->getEvent([/* ... */]);
$promise = $client->getEventAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->getEvent([
    'actorId' => '<string>',
    'eventId' => '<string>', // REQUIRED
    'sessionId' => '<string>',
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
actorId
Type: string

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.

eventId
Required: Yes
Type: string

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

sessionId
Type: string

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.

spaceId
Required: Yes
Type: string

The ID of the space.

Result Syntax

[
    'event' => [
        'actorId' => '<string>',
        'eventId' => '<string>',
        'eventTimestamp' => <DateTime>,
        'metadata' => ['<string>', ...],
        'payload' => [
            'blob' => [
                'contentType' => 'application/pdf|image/png|image/jpeg',
                'source' => [
                    's3Location' => [
                        'uri' => '<string>',
                    ],
                ],
            ],
            'conversational' => [
                'unified' => [
                    'source' => [
                        'object' => [
                            'messages' => [
                                [
                                    'content' => [
                                        'text' => '<string>',
                                    ],
                                    'role' => 'USER|ASSISTANT|SYSTEM',
                                ],
                                // ...
                            ],
                        ],
                    ],
                ],
            ],
            'structuredData' => [
                'source' => [
                    'json' => [
                    ],
                ],
            ],
        ],
        'sessionId' => '<string>',
        'spaceId' => '<string>',
    ],
]

Result Details

Members
event
Required: Yes
Type: Event structure

The event, including its payload.

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

GetMemory

$result = $client->getMemory([/* ... */]);
$promise = $client->getMemoryAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->getMemory([
    'actorId' => '<string>',
    'memoryId' => '<string>', // REQUIRED
    'spaceId' => '<string>', // REQUIRED
    'strategyName' => '<string>',
]);

Parameter Details

Members
actorId
Type: string

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.

memoryId
Required: Yes
Type: string

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

spaceId
Required: Yes
Type: string

The ID of the space that holds the memory.

strategyName
Type: string

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.

Result Syntax

[
    'memory' => [
        'content' => '<string>',
        'memoryId' => '<string>',
        'memoryType' => 'SEMANTIC|SUMMARY|CUSTOM',
        'metadata' => ['<string>', ...],
        'strategyName' => '<string>',
        'systemMetadata' => [
            'actorId' => '<string>',
            'createdAt' => <DateTime>,
            'sessionId' => '<string>',
            'updatedAt' => <DateTime>,
        ],
    ],
]

Result Details

Members
memory
Required: Yes
Type: Memory structure

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

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

GetSpace

$result = $client->getSpace([/* ... */]);
$promise = $client->getSpaceAsync([/* ... */]);

Returns a space's configuration and status.

Parameter Syntax

$result = $client->getSpace([
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
spaceId
Required: Yes
Type: string

The ID of the space.

Result Syntax

[
    'arn' => '<string>',
    'createdAt' => <DateTime>,
    'encryptionConfiguration' => [
        'kmsKeyArn' => '<string>',
    ],
    'eventExpiryDays' => <integer>,
    'extractionModelId' => '<string>',
    'memoryExpiryDays' => <integer>,
    'memoryStrategies' => [
        [
            'configuration' => [
                'consolidationEnabled' => true || false,
                'extractEveryNMessages' => <integer>,
                'extractEveryNTokens' => <integer>,
                'extractionPrompt' => '<string>',
                'extractionSeedRecentN' => <integer>,
                'extractionSeedTopK' => <integer>,
                'idleTimeoutSeconds' => <integer>,
            ],
            'description' => '<string>',
            'name' => '<string>',
            'type' => 'SEMANTIC|SUMMARY|CUSTOM',
        ],
        // ...
    ],
    'name' => '<string>',
    'spaceId' => '<string>',
    'status' => 'CREATING|ACTIVE|UPDATING|DELETING|DELETED|FAILED',
    'statusReason' => '<string>',
]

Result Details

Members
arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the space.

createdAt
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

When the space was created.

encryptionConfiguration
Type: EncryptionConfiguration structure

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

eventExpiryDays
Type: int

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

extractionModelId
Type: string

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

memoryExpiryDays
Type: int

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.

memoryStrategies
Type: Array of MemoryStrategy structures

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.

name
Required: Yes
Type: string

The name of the space.

spaceId
Required: Yes
Type: string

The ID of the space.

status
Required: Yes
Type: string

The status of the space.

statusReason
Type: 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.

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

ListEvents

$result = $client->listEvents([/* ... */]);
$promise = $client->listEventsAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->listEvents([
    'actorId' => '<string>', // REQUIRED
    'eventTimestampAfter' => <integer || string || DateTime>,
    'eventTimestampBefore' => <integer || string || DateTime>,
    'maxResults' => <integer>,
    'metadataFilters' => ['<string>', ...],
    'nextToken' => '<string>',
    'sessionId' => '<string>', // REQUIRED
    'sortOrder' => 'ASC|DESC',
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
actorId
Required: Yes
Type: string

The actor whose events to list.

eventTimestampAfter
Type: timestamp (string|DateTime or anything parsable by strtotime)

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.

eventTimestampBefore
Type: timestamp (string|DateTime or anything parsable by strtotime)

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

maxResults
Type: int

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

metadataFilters
Type: Associative array of custom strings keys (MetadataKey) to strings

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.

nextToken
Type: string

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.

sessionId
Required: Yes
Type: string

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

sortOrder
Type: string

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

spaceId
Required: Yes
Type: string

The ID of the space.

Result Syntax

[
    'events' => [
        [
            'eventId' => '<string>',
            'eventTimestamp' => <DateTime>,
            'metadata' => ['<string>', ...],
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
events
Required: Yes
Type: Array of EventSummary structures

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

nextToken
Type: string

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

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

ListMemories

$result = $client->listMemories([/* ... */]);
$promise = $client->listMemoriesAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->listMemories([
    'actorIds' => ['<string>', ...],
    'maxResults' => <integer>,
    'memoryStrategies' => [
        [
            'memoryStrategyNames' => ['<string>', ...],
            'memoryType' => 'SEMANTIC|SUMMARY|CUSTOM', // REQUIRED
        ],
        // ...
    ],
    'nextToken' => '<string>',
    'sessionIds' => ['<string>', ...],
    'sortBy' => 'CREATED_AT|UPDATED_AT',
    'sortOrder' => 'ASC|DESC',
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
actorIds
Type: Array of strings

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.

maxResults
Type: int

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

memoryStrategies
Type: Array of StrategySelector structures

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.

nextToken
Type: string

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.

sessionIds
Type: Array of strings

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.

sortBy
Type: string

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

sortOrder
Type: string

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

spaceId
Required: Yes
Type: string

The space whose memories to list.

Result Syntax

[
    'memories' => [
        [
            'memoryId' => '<string>',
            'memoryType' => 'SEMANTIC|SUMMARY|CUSTOM',
            'metadata' => ['<string>', ...],
            'strategyName' => '<string>',
            'systemMetadata' => [
                'actorId' => '<string>',
                'createdAt' => <DateTime>,
                'sessionId' => '<string>',
                'updatedAt' => <DateTime>,
            ],
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
memories
Required: Yes
Type: Array of MemoryListSummary structures

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

nextToken
Type: string

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

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

ListSpaces

$result = $client->listSpaces([/* ... */]);
$promise = $client->listSpacesAsync([/* ... */]);

Lists the spaces in your account in the current Region.

Parameter Syntax

$result = $client->listSpaces([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
maxResults
Type: int

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

nextToken
Type: string

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.

Result Syntax

[
    'nextToken' => '<string>',
    'spaces' => [
        [
            'arn' => '<string>',
            'createdAt' => <DateTime>,
            'name' => '<string>',
            'spaceId' => '<string>',
            'status' => 'CREATING|ACTIVE|UPDATING|DELETING|DELETED|FAILED',
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

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

spaces
Required: Yes
Type: Array of SpaceSummary structures

The spaces.

Errors

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

Lists the tags for the specified space.

Parameter Syntax

$result = $client->listTagsForResource([
    'resourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the space.

Result Syntax

[
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
tags
Type: Array of Tag structures

The tags for the space.

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

SearchEvents

$result = $client->searchEvents([/* ... */]);
$promise = $client->searchEventsAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->searchEvents([
    'actorId' => '<string>', // REQUIRED
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'query' => [ // REQUIRED
    ],
    'sessionIds' => ['<string>', ...],
    'sort' => [
    ],
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
actorId
Required: Yes
Type: string

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).

maxResults
Type: int

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

nextToken
Type: string

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.

query
Required: Yes
Type: document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documents

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.

sessionIds
Type: Array of strings

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).

sort
Type: document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documents

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

spaceId
Required: Yes
Type: string

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

Result Syntax

[
    'events' => [
        [
            'eventId' => '<string>',
            'matchedContent' => '<string>',
            'metadata' => ['<string>', ...],
            'score' => <float>,
            'systemMetadata' => [
                'actorId' => '<string>',
                'createdAt' => <DateTime>,
                'sessionId' => '<string>',
                'updatedAt' => <DateTime>,
            ],
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
events
Required: Yes
Type: Array of EventSearchSummary structures

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.

nextToken
Type: string

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

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

SearchMemories

$result = $client->searchMemories([/* ... */]);
$promise = $client->searchMemoriesAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->searchMemories([
    'actorId' => '<string>', // REQUIRED
    'maxResults' => <integer>,
    'memoryStrategies' => [
        [
            'memoryStrategyNames' => ['<string>', ...],
            'memoryType' => 'SEMANTIC|SUMMARY|CUSTOM', // REQUIRED
        ],
        // ...
    ],
    'nextToken' => '<string>',
    'query' => [ // REQUIRED
    ],
    'sort' => [
    ],
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
actorId
Required: Yes
Type: string

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).

maxResults
Type: int

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

memoryStrategies
Type: Array of StrategySelector structures

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.

nextToken
Type: string

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.

query
Required: Yes
Type: document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documents

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.

sort
Type: document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documents

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

spaceId
Required: Yes
Type: string

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

Result Syntax

[
    'memories' => [
        [
            'content' => '<string>',
            'memoryId' => '<string>',
            'memoryType' => 'SEMANTIC|SUMMARY|CUSTOM',
            'metadata' => ['<string>', ...],
            'score' => <float>,
            'sourceEventIds' => ['<string>', ...],
            'strategyName' => '<string>',
            'systemMetadata' => [
                'actorId' => '<string>',
                'createdAt' => <DateTime>,
                'sessionId' => '<string>',
                'updatedAt' => <DateTime>,
            ],
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
memories
Required: Yes
Type: Array of MemorySearchSummary structures

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

nextToken
Type: string

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

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Adds the specified tags to the specified space.

Parameter Syntax

$result = $client->tagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tags' => [ // REQUIRED
        [
            'key' => '<string>', // REQUIRED
            'value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the space.

tags
Required: Yes
Type: Array of Tag structures

The tags to add to the space.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes the specified tags from the specified space.

Parameter Syntax

$result = $client->untagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the space.

tagKeys
Required: Yes
Type: Array of strings

The keys of the tags to remove from the space.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

UpdateMemory

$result = $client->updateMemory([/* ... */]);
$promise = $client->updateMemoryAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->updateMemory([
    'actorId' => '<string>',
    'content' => '<string>',
    'memoryId' => '<string>', // REQUIRED
    'metadata' => ['<string>', ...],
    'metadataMode' => 'REPLACE|MERGE',
    'spaceId' => '<string>', // REQUIRED
    'strategyName' => '<string>',
]);

Parameter Details

Members
actorId
Type: string

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.

content
Type: string

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

memoryId
Required: Yes
Type: string

The ID of the memory to update.

metadata
Type: Associative array of custom strings keys (MetadataKey) to strings

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.

metadataMode
Type: string

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

spaceId
Required: Yes
Type: string

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

strategyName
Type: string

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.

Result Syntax

[
    'memory' => [
        'content' => '<string>',
        'memoryId' => '<string>',
        'memoryType' => 'SEMANTIC|SUMMARY|CUSTOM',
        'metadata' => ['<string>', ...],
        'strategyName' => '<string>',
        'systemMetadata' => [
            'actorId' => '<string>',
            'createdAt' => <DateTime>,
            'sessionId' => '<string>',
            'updatedAt' => <DateTime>,
        ],
    ],
]

Result Details

Members
memory
Required: Yes
Type: Memory structure

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

Errors

ConflictException:

The request conflicts with the current state of the resource. For example, the space is being created, updated, or deleted, a space with the same name already exists, or you reused a client token with different parameters. Wait for the space to finish being created, updated, or deleted, or use a different name or client token, and then retry.

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

UpdateSpace

$result = $client->updateSpace([/* ... */]);
$promise = $client->updateSpaceAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->updateSpace([
    'eventExpiryDays' => <integer>,
    'extractionModelId' => '<string>',
    'memoryExpiryDays' => <integer>,
    'memoryStrategies' => [
        [
            'configuration' => [
                'consolidationEnabled' => true || false,
                'extractEveryNMessages' => <integer>,
                'extractEveryNTokens' => <integer>,
                'extractionPrompt' => '<string>',
                'extractionSeedRecentN' => <integer>,
                'extractionSeedTopK' => <integer>,
                'idleTimeoutSeconds' => <integer>,
            ],
            'description' => '<string>',
            'name' => '<string>',
            'type' => 'SEMANTIC|SUMMARY|CUSTOM', // REQUIRED
        ],
        // ...
    ],
    'spaceId' => '<string>', // REQUIRED
]);

Parameter Details

Members
eventExpiryDays
Type: int

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.

extractionModelId
Type: string

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.

memoryExpiryDays
Type: int

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.

memoryStrategies
Type: Array of MemoryStrategy structures

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.

spaceId
Required: Yes
Type: string

The ID of the space to update.

Result Syntax

[
    'spaceId' => '<string>',
    'status' => 'CREATING|ACTIVE|UPDATING|DELETING|DELETED|FAILED',
]

Result Details

Members
spaceId
Required: Yes
Type: string

The ID of the space.

status
Required: Yes
Type: 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.

Errors

ConflictException:

The request conflicts with the current state of the resource. For example, the space is being created, updated, or deleted, a space with the same name already exists, or you reused a client token with different parameters. Wait for the space to finish being created, updated, or deleted, or use a different name or client token, and then retry.

ResourceNotFoundException:

The specified resource doesn't exist. Check the IDs in the request.

AccessDeniedException:

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

ThrottlingException:

The service throttled the request. Retry the request with exponential backoff.

ServiceQuotaExceededException:

The request would exceed a quota, such as the number of spaces in your account or the number of strategies in a space.

InternalServerException:

The service couldn't process the request because of an internal error. Retry the request.

ValidationException:

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

Shapes

AccessDeniedException

Description

You don't have sufficient access to perform this operation. To use this operation, you must have AWS Identity and Access Management (IAM) permissions for the operation, and on the resource it acts on. If the space uses a customer managed AWS Key Management Service (AWS KMS) key, you must also have permission to use the key.

Members
message
Required: Yes
Type: string

A message that describes which access the request is missing.

BatchGetEventError

Description

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

Members
errorCode
Required: Yes
Type: string

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

eventId
Required: Yes
Type: string

The ID of the requested event.

message
Required: Yes
Type: string

A human-readable description.

BlobPayload

Description

A document stored in Amazon S3, such as a PDF, and its media type.

Members
contentType
Required: Yes
Type: string

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

source
Required: Yes
Type: BlobSource structure

The location of the document.

BlobSource

Description

The source of a blob's content. Set exactly one member. Currently, the only member is s3Location.

Members
s3Location
Type: S3Location structure

The S3 object holding the document.

ConflictException

Description

The request conflicts with the current state of the resource. For example, the space is being created, updated, or deleted, a space with the same name already exists, or you reused a client token with different parameters. Wait for the space to finish being created, updated, or deleted, or use a different name or client token, and then retry.

Members
message
Required: Yes
Type: string

A message that describes the conflict.

resourceId
Type: string

The ID of the resource that caused the conflict.

resourceType
Type: string

The type of the resource that caused the conflict.

ConversationalPayload

Description

Conversational content. Exactly one member is set.

Members
unified
Type: UnifiedConversational structure

Conversation turns in the service's own format.

CreateMemoryDetail

Description

The memory as CreateMemory acknowledges it: its identifiers. The memory isn't searchable yet when the call returns.

Members
actorId
Required: Yes
Type: string

The ID of the actor the memory belongs to.

memoryId
Required: Yes
Type: string

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

name
Required: Yes
Type: string

The name of the strategy the memory belongs to.

sessionId
Required: Yes
Type: string

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

spaceId
Required: Yes
Type: string

The ID of the space.

Document

Members

EncryptionConfiguration

Description

Encryption settings for a space.

Members
kmsKeyArn
Type: 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.

Event

Description

An event, including its payload.

Members
actorId
Required: Yes
Type: string

The ID of the actor the event belongs to.

eventId
Required: Yes
Type: string

The event's ID.

eventTimestamp
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time the event occurred.

metadata
Type: Associative array of custom strings keys (MetadataKey) to strings

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

payload
Required: Yes
Type: EventPayload structure

The event's content, as submitted to CreateEvent.

sessionId
Required: Yes
Type: string

The ID of the session the event belongs to.

spaceId
Required: Yes
Type: string

The ID of the space.

EventDetail

Description

The stored event's identifiers. Call GetEvent for the payload.

Members
actorId
Required: Yes
Type: string

The ID of the actor the event belongs to.

eventId
Required: Yes
Type: string

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

eventTimestamp
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

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

sessionId
Required: Yes
Type: string

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

spaceId
Required: Yes
Type: string

The ID of the space.

EventPayload

Description

The event content. Exactly one member must be set.

Members
blob
Type: BlobPayload structure

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

conversational
Type: ConversationalPayload structure

Conversation turns.

structuredData
Type: StructuredDataPayload structure

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

EventSearchSummary

Description

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.

Members
eventId
Required: Yes
Type: string

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

matchedContent
Type: string

The text of the matching chunk.

metadata
Type: Associative array of custom strings keys (MetadataKey) to strings

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

score
Type: double

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
Type: SystemMetadata structure

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.

EventSummary

Description

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

Members
eventId
Required: Yes
Type: string

The event's ID.

eventTimestamp
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time the event occurred.

metadata
Type: Associative array of custom strings keys (MetadataKey) to strings

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

InternalServerException

Description

The service couldn't process the request because of an internal error. Retry the request.

Members
message
Required: Yes
Type: string

A message that describes the internal error.

Memory

Description

A memory, as returned by GetMemory and UpdateMemory. Unlike MemoryListSummary it includes content, and unlike MemorySearchSummary it has no relevance score.

Members
content
Required: Yes
Type: string

The memory text.

memoryId
Required: Yes
Type: string

The memory's ID, assigned by the service.

memoryType
Required: Yes
Type: string

The memory type.

metadata
Type: Associative array of custom strings keys (MetadataKey) to strings

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

strategyName
Type: 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.

systemMetadata
Required: Yes
Type: SystemMetadata structure

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.

MemoryListSummary

Description

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.

Members
memoryId
Required: Yes
Type: 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
Required: Yes
Type: string

The memory type.

metadata
Type: Associative array of custom strings keys (MetadataKey) to strings

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

strategyName
Type: 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
Required: Yes
Type: SystemMetadata structure

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

MemorySearchSummary

Description

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

Members
content
Type: string

The memory text.

memoryId
Required: Yes
Type: string

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

memoryType
Type: string

The memory type of the result.

metadata
Type: Associative array of custom strings keys (MetadataKey) to strings

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

score
Type: double

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.

sourceEventIds
Type: Array of strings

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.

strategyName
Type: 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.

systemMetadata
Type: SystemMetadata structure

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.

MemoryStrategy

Description

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

Members
configuration
Type: MemoryStrategyConfiguration structure

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.

description
Type: string

A description of the strategy.

name
Type: 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.

type
Required: Yes
Type: string

The type of memory the strategy extracts.

MemoryStrategyConfiguration

Description

Settings for a memory strategy. The defaults described here apply when you create a strategy. In UpdateSpace, a member you omit for a kept strategy keeps its current value.

Members
consolidationEnabled
Type: 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.

extractEveryNMessages
Type: int

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
Type: int

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.

extractionPrompt
Type: 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.

extractionSeedRecentN
Type: int

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.

extractionSeedTopK
Type: int

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.

idleTimeoutSeconds
Type: int

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.

Message

Description

A conversation turn.

Members
content
Required: Yes
Type: MessageContent structure

The content of the turn.

role
Required: Yes
Type: string

The author of the turn.

MessageContent

Description

The content of a conversation turn.

Members
text
Required: Yes
Type: string

The text of the turn.

ResourceNotFoundException

Description

The specified resource doesn't exist. Check the IDs in the request.

Members
message
Required: Yes
Type: string

A message that describes which resource wasn't found.

resourceId
Type: string

The ID of the resource that wasn't found.

resourceType
Type: string

The type of the resource that wasn't found.

S3Location

Description

An object in Amazon S3.

Members
uri
Required: Yes
Type: 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.

SearchQuery

Description

A query clause in OpenSearch Query DSL (the value of an OpenSearch query). The service accepts a subset of query types whose cost is bounded and rejects anything else with ValidationException. In SearchMemories, query memory text as memory_text and embeddings as memory_vector. In SearchEvents, use text and vector. Supported: match, match_phrase, match_all, term, terms, ids, exists, range (on system_metadata.created_at and system_metadata.updated_at only), neural, hybrid, bool, constant_score, boosting, and function_score (decay functions on the time fields only). The service doesn't support aggregations, highlight, or rescore. If query and sort together are larger than 64 KB, the request fails with ValidationException (reason queryBodyTooLarge).

A query can use at most one distinct neural query_text. Repeating the same text is allowed. A bool query can nest at most 5 levels. The whole query can contain at most 32 clauses, counting function_score functions. terms and ids take at most 100 values, and function_score takes at most 3 decay functions. A second distinct neural query_text, more than 32 clauses, too many values, or too many decay functions fails with ValidationException (reason queryBodyTooLarge). A query text longer than 2,048 characters, or a neural k over 100, fails with reason fieldValidationFailed. A bool query nested more than 5 levels fails with reason queryNestingTooDeep.

In range and decay functions, give system_metadata.created_at and system_metadata.updated_at values as ISO 8601 strings such as 2026-06-01T00:00:00Z, as epoch milliseconds, or as date math such as now-30d.

Members

SearchSort

Description

A sort clause in OpenSearch Query DSL (the value of an OpenSearch sort): a field name, {"field": "asc"|"desc"}, {"field": {"order": "asc"|"desc"}}, or an array of these. Sorting is supported on _score, system_metadata.created_at, and system_metadata.updated_at.

Members

ServiceQuotaExceededException

Description

The request would exceed a quota, such as the number of spaces in your account or the number of strategies in a space.

Members
message
Required: Yes
Type: string

A message that describes which quota the request would exceed.

quotaCode
Type: string

The Service Quotas code of the quota that the request would exceed. Not currently returned.

serviceCode
Type: string

The Service Quotas code of the service. Not currently returned.

SpaceSummary

Description

A summary of a space, as returned by ListSpaces.

Members
arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the space.

createdAt
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

When the space was created.

name
Required: Yes
Type: string

The name of the space.

spaceId
Required: Yes
Type: string

The ID of the space.

status
Required: Yes
Type: string

The status of the space.

StrategySelector

Description

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.

Members
memoryStrategyNames
Type: Array of strings

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

memoryType
Required: Yes
Type: string

The memory type to search or list.

StructuredDataPayload

Description

Structured content, as a JSON object.

Members
source
Required: Yes
Type: StructuredDataSource structure

The structured content.

StructuredDataSource

Description

The source of structured content. Set exactly one member. Currently, the only member is json.

Members
json
Type: document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documents

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

SystemMetadata

Description

System-generated provenance for a memory or event: the owning actor and session, and the creation and last-update timestamps. SearchMemories, SearchEvents, ListMemories, and GetMemory return the same block.

ListMemories and GetMemory always return createdAt and updatedAt. The search operations return what is recorded and omit the block when nothing is.

In a query, the timestamps are system_metadata.created_at and system_metadata.updated_at. Scope by owner with the top-level parameters (actorId on the search operations, actorIds on ListMemories) and sessionIds (SearchEvents and ListMemories). The search operations reject actor and session fields inside the query or sort.

Members
actorId
Type: string

The owning actor. Absent when none was recorded.

createdAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

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

sessionId
Type: string

The owning session. Absent when none was recorded.

updatedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

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

Tag

Description

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

Members
key
Required: Yes
Type: string

The key of the tag.

value
Required: Yes
Type: string

The value of the tag.

ThrottlingException

Description

The service throttled the request. Retry the request with exponential backoff.

Members
message
Required: Yes
Type: string

A message that describes the throttling.

retryAfterSeconds
Type: int

The number of seconds to wait before you retry the request.

UnifiedConversational

Description

Conversation turns in the service's own format.

Members
source
Required: Yes
Type: UnifiedConversationalSource structure

The conversation.

UnifiedConversationalObject

Description

Conversation turns.

Members
messages
Required: Yes
Type: Array of Message structures

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

UnifiedConversationalSource

Description

The source of a conversation. Set exactly one member. Currently, the only member is object.

Members
object
Type: UnifiedConversationalObject structure

The conversation turns.

ValidationException

Description

The request isn't valid. The reason, message, and fieldList members describe the problem. Fix the request, and then try again.

Members
fieldList
Type: Array of ValidationExceptionField structures

The fields that failed validation, if any.

message
Required: Yes
Type: string

A message that describes why the request failed validation, such as the field, key, or limit involved.

reason
Type: string

The reason that the request failed validation.

ValidationExceptionField

Description

Information about a request field that failed validation.

Members
message
Required: Yes
Type: string

A message that describes why the field failed validation.

name
Required: Yes
Type: string

The field name.