Amazon OpenSearch Memory 2026-08-24
- 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:
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
errorsasRESOURCE_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
errorsasRESOURCE_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, andfieldListmembers 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 omitsessionId, the service generates a new one on each attempt, so a retry fails withConflictException. Reusing the token with different request content also fails withConflictException.eventTimestampisn'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 tofalseto store the event without extraction: the service skips strategies that infer memories, and still indexes the event's turns forSearchEvents. A document submitted as ablobis 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 keysdocumentS3SourceanddocumentS3Url, and other keys that the service uses internally are reserved: a request that sets one fails withValidationException, 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
SUMMARYstrategies 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, andfieldListmembers 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
memoryIdinstead of creating a second memory. Reusing the token with a differentname,content,metadata,actorId, orsessionIdfails withConflictException. If you omitsessionId, 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 keydocumentS3Source, and other keys that the service uses internally are reserved: a request that sets one fails withValidationException, 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, andfieldListmembers 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-5oranthropic.claude-haiku-5-5. Another value fails withValidationException, and the message lists the supported IDs. Omit it to use the service default, which can change over time and isn't returned byGetSpace. 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
UpdateMemorydoesn'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
SearchEventsandListEvents, but extracts no memories and has none to search. You can add strategies later withUpdateSpace.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, andfieldListmembers 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, andfieldListmembers 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, andfieldListmembers 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, andfieldListmembers 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, orSearchEvents. - 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, andfieldListmembers 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
SearchMemoriesorListMemories. - 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, andfieldListmembers 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 whenstatusisFAILED: 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, andfieldListmembers 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 withValidationException. - 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
maxResultsevents, or none, and still return anextToken. Keep paging untilnextTokenis 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:ASCorDESC. The default isDESC, 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
GetEventfor 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, andfieldListmembers 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
sessionIdsby 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
memoryStrategyNameslists every strategy of its type, and omittingmemoryStrategieslists every strategy in the space. A name that is not a declared strategy of that type fails withValidationException. - 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
actorIdsby 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) orUPDATED_AT. - sortOrder
-
- Type: string
The sort order:
ASCorDESC. The default isDESC, 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, andfieldListmembers 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, andfieldListmembers 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, andfieldListmembers 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 referencessystem_metadata.actor_idfails withValidationException(reasonnonFilterableField). - 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 onSearchMemories. Query event text astextand embeddings asvector. A search covers both conversation turns and chunks of documents submitted as ablob. You can't use actor and session fields here. Use the top-levelactorIdandsessionIds.To search only the content of particular events, filter on
event_idswithtermorterms, for example with thesourceEventIdsthat aSearchMemoriesresult returns. Atermsclause onevent_idscan list up to 10 event IDs. More IDs fail withValidationException(reasonqueryBodyTooLarge). You can useevent_idsonly interm,terms, andexistsqueries. - sessionIds
-
- Type: Array of strings
Returns only events from one of these sessions (exact match). Combined with
actorIdby 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 referencessystem_metadata.session_idfails withValidationException(reasonnonFilterableField). - 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
actorIdandsessionIdsto 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
sortrequests, or most relevant first when it has none. Empty when nothing matches. Each result is the matching chunk of an event. CallGetEventfor 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, andfieldListmembers 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_idfails withValidationException(reasonnonFilterableField). - 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
memoryStrategyNamessearches every strategy of its type, and omittingmemoryStrategiessearches every strategy in the space. A name that is not a declared strategy of that type fails withValidationException. - 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 fieldssystem_metadata.actor_idandsystem_metadata.session_idhere. Use the top-levelactorIdto 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
actorIdto 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
sortrequests, 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, andfieldListmembers 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
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, andfieldListmembers 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
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, andfieldListmembers 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
metadataModetoMERGEto keep the keys you don't supply. Limits apply to the resulting metadata, not to the request. Keys that begin withx-amz-and the keydocumentS3Sourceare reserved: a request that sets one fails withValidationException.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
metadatacombines with what is stored. The default isREPLACE. - 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
GetMemoryreturns.
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, andfieldListmembers 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-5oranthropic.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.
GetSpacethen 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 sametypeandname. To delete them, useDeleteMemorybefore you remove the strategy, or delete the space.To keep a strategy, include it with the same
typeandnamethatGetSpacereturns. For a kept strategy, anyconfigurationmember 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 withUpdateSpace.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:
UPDATINGwhen 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, andfieldListmembers 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/pdfis supported. Any other value fails withValidationException. - 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, andDeleteMemoryreturnResourceNotFoundExceptionfor 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 withValidationExceptionorAccessDeniedException.
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
GetEventandDeleteEvent. - 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
GetEventorDeleteEvent. - 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
ListMemoriesandSearchMemoriesreturn. Event chunks are never modified, soupdatedAtalways equalscreatedAt.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.
updatedAtequalscreatedAtfor 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 strategymemoryStrategiesselects on inListMemories. 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
GetEventorBatchGetEvent, or to search those events' content withSearchEventsby filtering onevent_idsin the query. Absent for a memory created directly withCreateMemory. 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 strategymemoryStrategiesselects on inSearchMemories. 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, andSearchEventsreturn.In a query, filter or sort on the timestamps as
system_metadata.created_atandsystem_metadata.updated_at. Scope by owner with the top-levelactorId, 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
CUSTOMstrategy must setextractionPrompt. - 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
SEMANTICandSUMMARY, off forCUSTOM. - 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, andidleTimeoutSecondsis 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
CUSTOMstrategy extracts, up to 30,720 characters. Required for aCUSTOMstrategy:CreateSpaceandUpdateSpacefail withValidationExceptionif aCUSTOMstrategy has none.Only
CUSTOMstrategies use it.SEMANTICandSUMMARYstrategies always extract with the service's built-in instructions: the service accepts and stores a prompt on them, andGetSpacereturns 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
SUMMARYstrategy when neither seed setting is given. When this andextractionSeedTopKare 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 andextractionSeedRecentNare 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 needs3:GetObjecton the object, andkms:Decrypton 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
ListMemoriesandGetMemory. 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
createdAtfor a record that has never been updated, and always for aSearchEventsresult.
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.