@aws-cdk/aws-bedrock-agentcore-alpha 2.221.1-alpha.0 → 2.222.0-alpha.0

package/agentcore/memory/memory.d.ts

@@ -0,0 +1,538 @@
+/**
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+ *  with the License. A copy of the License is located at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+ *  OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+ *  and limitations under the License.
+ */
+import { Duration, IResource, Resource } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { DimensionsMap, Metric, MetricOptions } from 'aws-cdk-lib/aws-cloudwatch';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as kms from 'aws-cdk-lib/aws-kms';
+import { IMemoryStrategy } from './memory-strategy';
+/******************************************************************************
+ *                                Interface
+ *****************************************************************************/
+/**
+ * Interface for Memory resources
+ */
+export interface IMemory extends IResource, iam.IGrantable {
+    /**
+     * The ARN of the memory resource
+     * @attribute
+     */
+    readonly memoryArn: string;
+    /**
+     * The id of the memory
+     * @attribute
+     */
+    readonly memoryId: string;
+    /**
+     * The IAM role that provides permissions for the memory to access AWS services.
+     */
+    readonly executionRole?: iam.IRole;
+    /**
+     * Custom KMS key for encryption (if provided)
+     */
+    readonly kmsKey?: kms.IKey;
+    /**
+     * The status of the memory
+     * @attribute
+     */
+    readonly status?: string;
+    /**
+     * Timestamp when the memory was last updated
+     * @attribute
+     */
+    readonly updatedAt?: string;
+    /**
+     * Timestamp when the memory was created
+     * @attribute
+     */
+    readonly createdAt?: string;
+    /**
+     * Grant the given principal identity permissions to perform actions on this memory.
+     */
+    grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to write content to this memory.
+     */
+    grantWrite(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to read the contents of this memory.
+     * Both Short-Term Memory (STM) and Long-Term Memory (LTM).
+     */
+    grantRead(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to read the Short-Term Memory (STM) contents of this memory.
+     */
+    grantReadShortTermMemory(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to read the Long-Term Memory (LTM) contents of this memory.
+     */
+    grantReadLongTermMemory(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to delete content on this memory.
+     */
+    grantDelete(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to delete Short-Term Memory (STM) content on this memory.
+     */
+    grantDeleteShortTermMemory(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to delete Long-Term Memory (LTM) content on this memory.
+     */
+    grantDeleteLongTermMemory(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to manage the control plane of this memory.
+     */
+    grantAdmin(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to do every action on this memory.
+     */
+    grantFullAccess(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Return the given named metric for this memory.
+     */
+    metric(metricName: string, dimensions: DimensionsMap, props?: MetricOptions): Metric;
+    /**
+     * Return the given named metric related to the API operation performed on this memory.
+     */
+    metricForApiOperation(metricName: string, operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric measuring the latency of a specific API operation performed on this memory.
+     */
+    metricLatencyForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the total number of API requests made for a specific memory operation.
+     */
+    metricInvocationsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the number of errors for a specific API operation performed on this memory.
+     */
+    metricErrorsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Returns the metric containing the number of created memory events and memory records.
+     */
+    metricEventCreationCount(props?: MetricOptions): Metric;
+}
+/******************************************************************************
+ *                        ABSTRACT BASE CLASS
+ *****************************************************************************/
+/**
+ * Abstract base class for a Memory.
+ * Contains methods and attributes valid for Memories either created with CDK or imported.
+ */
+export declare abstract class MemoryBase extends Resource implements IMemory {
+    abstract readonly memoryArn: string;
+    abstract readonly memoryId: string;
+    abstract readonly status?: string;
+    abstract readonly updatedAt?: string;
+    abstract readonly createdAt?: string;
+    abstract readonly executionRole?: iam.IRole;
+    abstract readonly kmsKey?: kms.IKey;
+    /**
+     * The principal to grant permissions to
+     */
+    abstract readonly grantPrincipal: iam.IPrincipal;
+    constructor(scope: Construct, id: string);
+    /**
+     * Grants IAM actions to the IAM Principal
+     * @param grantee - The IAM principal to grant permissions to
+     * @param actions - The actions to grant
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to write content to short-term memory.
+     *
+     * @param grantee - The IAM principal to grant read permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:CreateEvent'] on this.memoryArn
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantWrite(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to read the contents of this memory.
+     * Both Short-Term Memory (STM) and Long-Term Memory (LTM).
+     *
+     * @param grantee - The IAM principal to grant read permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:GetMemoryRecord',
+        'bedrock-agentcore:RetrieveMemoryRecords',
+        'bedrock-agentcore:ListMemoryRecords',
+        'bedrock-agentcore:ListActors',
+        'bedrock-agentcore:ListSessions] on this.memoryArn
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantRead(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to read the Short-Term Memory (STM) contents of this memory.
+     *
+     * @param grantee - The IAM principal to grant read permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:GetEvent',
+        'bedrock-agentcore:ListEvents',
+        'bedrock-agentcore:ListActors',
+        'bedrock-agentcore:ListSessions',] on this.memoryArn
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantReadShortTermMemory(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to read the Long-Term Memory (LTM) contents of this memory.
+     *
+     * @param grantee - The IAM principal to grant read permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:GetMemoryRecord',
+        'bedrock-agentcore:RetrieveMemoryRecords',
+        'bedrock-agentcore:ListMemoryRecords',
+        'bedrock-agentcore:ListActors',
+        'bedrock-agentcore:ListSessions',] on this.memoryArn
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantReadLongTermMemory(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to delete content on this memory.
+     *
+     * Both Short-Term Memory (STM) and Long-Term Memory (LTM).
+     *
+     * @param grantee - The IAM principal to grant delete permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:DeleteEvent',
+        'bedrock-agentcore:DeleteMemoryRecord'] on this.memoryArn
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantDelete(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to delete Short-Term Memory (STM) content on this memory.
+     *
+     * @param grantee - The IAM principal to grant delete permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:DeleteEvent'] on this.memoryArn
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantDeleteShortTermMemory(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to delete Long-Term Memory (LTM) content on this memory.
+     *
+     * @param grantee - The IAM principal to grant delete permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:DeleteMemoryRecord'] on this.memoryArn
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantDeleteLongTermMemory(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to manage the control plane of this memory.
+     *
+     * @param grantee - The IAM principal to grant admin permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:CreateMemory',
+        'bedrock-agentcore:GetMemory',
+        'bedrock-agentcore:DeleteMemory',
+        'bedrock-agentcore:UpdateMemory'] on this.memoryArn
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantAdmin(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Grant the given principal identity permissions to do every action on this memory.
+     *
+     * @param grantee - The IAM principal to grant full access permissions to
+     * @default - Default grant configuration:
+     * - actions: ['bedrock-agentcore:CreateEvent',
+        'bedrock-agentcore:GetEvent',
+        'bedrock-agentcore:DeleteEvent',
+        'bedrock-agentcore:GetMemoryRecord',
+        'bedrock-agentcore:RetrieveMemoryRecords',
+        'bedrock-agentcore:ListMemoryRecords',
+        'bedrock-agentcore:ListActors',
+        'bedrock-agentcore:ListSessions',
+        'bedrock-agentcore:CreateMemory',
+        'bedrock-agentcore:GetMemory',
+        'bedrock-agentcore:DeleteMemory',
+        'bedrock-agentcore:UpdateMemory'] on this.memoryArn
+     * @returns An IAM Grant object representing the granted permissions
+     */
+    grantFullAccess(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Return the given named metric for this memory.
+     *
+     * By default, the metric will be calculated as a sum over a period of 5 minutes.
+     * You can customize this by using the `statistic` and `period` properties.
+     */
+    metric(metricName: string, dimensions: DimensionsMap, props?: MetricOptions): Metric;
+    /**
+     * Return the given named metric related to the API operation performed on this memory.
+     */
+    metricForApiOperation(metricName: string, operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric measuring the latency of a specific API operation performed on this memory.
+     *
+     * The latency metric represents the total time elapsed between receiving the request and sending
+     * the final response token, measuring complete end-to-end processing time.
+     *
+     * For memory creation events specifically, this measures the time from the last CreateEvent
+     * that met strategy criteria until memory storage is completed.
+     *
+     */
+    metricLatencyForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the total number of API requests made for a specific memory operation like
+     * `CreateEvent`, `ListEvents`, `RetrieveMemoryRecords` ...
+     */
+    metricInvocationsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Return a metric containing the number of errors for a specific API operation performed on this memory.
+     */
+    metricErrorsForApiOperation(operation: string, props?: MetricOptions): Metric;
+    /**
+     * Returns the metric containing the number of short-term memory events.
+     */
+    metricEventCreationCount(props?: MetricOptions): Metric;
+    /**
+     * Returns the metric containing the number of long-term memory records
+     * created by the long-term extraction strategies.
+     */
+    metricMemoryRecordCreationCount(props?: MetricOptions): Metric;
+    /**
+     * Internal method to create a metric.
+     */
+    private configureMetric;
+}
+/******************************************************************************
+ *                        PROPS FOR NEW CONSTRUCT
+ *****************************************************************************/
+/**
+ * Properties for creating a Memory resource
+ */
+export interface MemoryProps {
+    /**
+     * The name of the memory
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore)
+     * The name must start with a letter and can be up to 48 characters long
+     * Pattern: [a-zA-Z][a-zA-Z0-9_]{0,47}
+     * @required - No
+     */
+    readonly memoryName: string;
+    /**
+     * Short-term memory expiration in days (between 7 and 365).
+     * Sets the short-term (raw event) memory retention.
+     * Events older than the specified duration will expire and no longer be stored.
+     * @default 90
+     * @required - No
+     */
+    readonly expirationDuration?: Duration;
+    /**
+     * Optional description for the memory
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and spaces
+     * The description can have up to 200 characters
+     * @default No description
+     * @required - No
+     */
+    readonly description?: string;
+    /**
+     * Custom KMS key to use for encryption.
+     * @default Your data is encrypted with a key that AWS owns and manages for you
+     * @required - No
+     */
+    readonly kmsKey?: kms.IKey;
+    /**
+     * If you need long-term memory for context recall across sessions,
+     * you can setup memory extraction strategies to extract the relevant memory from the raw events.
+     * @default No extraction strategies (short term memory only)
+     * @required - No
+     */
+    readonly memoryStrategies?: IMemoryStrategy[];
+    /**
+     * The IAM role that provides permissions for the memory to access AWS services
+     * when using custom strategies.
+     *
+     * @default A new role will be created.
+     * @required - No
+     */
+    readonly executionRole?: iam.IRole;
+    /**
+     * Tags (optional)
+     * A list of key:value pairs of tags to apply to this memory resource
+     *
+     * @default {} no tags
+     * @required - No
+     */
+    readonly tags?: {
+        [key: string]: string;
+    };
+}
+/******************************************************************************
+ *                      ATTRS FOR IMPORTED CONSTRUCT
+ *****************************************************************************/
+/**
+ * Attributes for specifying an imported Memory.
+ */
+export interface MemoryAttributes {
+    /**
+     * The ARN of the memory.
+     * @attribute
+     */
+    readonly memoryArn: string;
+    /**
+     * The ARN of the IAM role associated to the memory.
+     * @attribute
+     */
+    readonly roleArn: string;
+    /**
+     * When this memory was last updated.
+     * @default undefined - No last updated timestamp is provided
+     */
+    readonly updatedAt?: string;
+    /**
+     * Optional KMS encryption key associated with this memory
+     * @default undefined - An AWS managed key is used
+     */
+    readonly kmsKeyArn?: string;
+    /**
+     * The status of the memory.
+     * @default undefined - No status is provided
+     */
+    readonly status?: string;
+    /**
+     * The created timestamp of the memory.
+     * @default undefined - No created timestamp is provided
+     */
+    readonly createdAt?: string;
+}
+/******************************************************************************
+ *                                Class
+ *****************************************************************************/
+/**
+ * Long-term memory store for extracted insights like user preferences, semantic facts and summaries.
+ * Enables knowledge retention across sessions by storing user preferences (e.g. coding style),
+ * semantic facts (e.g. learned info) and interaction summaries for context optimization.
+ *
+ * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html
+ * @resource AWS::BedrockAgentCore::Memory
+ */
+export declare class Memory extends MemoryBase {
+    /** Uniquely identifies this class. */
+    static readonly PROPERTY_INJECTION_ID: string;
+    /**
+     * Static Method for importing an existing Bedrock AgentCore Memory.
+     */
+    /**
+     * Creates an Memory reference from an existing memory's attributes.
+     *
+     * @param scope - The construct scope
+     * @param id - Identifier of the construct
+     * @param attrs - Attributes of the existing browser custom
+     * @returns An IBrowserCustom reference to the existing browser
+     */
+    static fromMemoryAttributes(scope: Construct, id: string, attrs: MemoryAttributes): IMemory;
+    /**
+     * The ARN of the memory resource.
+     * @attribute
+     */
+    readonly memoryArn: string;
+    /**
+     * The name of the memory.
+     * @attribute
+     */
+    readonly memoryName: string;
+    /**
+     * The id of the memory.
+     * @attribute
+     */
+    readonly memoryId: string;
+    /**
+     * The expiration days of the memory.
+     */
+    readonly expirationDuration?: Duration;
+    /**
+     * The failure reason of the browser
+     * @attribute
+     */
+    readonly failureReason?: string;
+    /**
+     * The description of the memory.
+     */
+    readonly description?: string;
+    /**
+     * The execution role of the memory.
+     */
+    readonly executionRole?: iam.IRole;
+    /**
+     * The status of the memory.
+     */
+    readonly status?: string;
+    /**
+     * The created timestamp of the memory.
+     */
+    readonly createdAt?: string;
+    /**
+     * The updated at timestamp of the memory.
+     */
+    readonly updatedAt?: string;
+    /**
+     * Tags applied to this browser resource
+     * A map of key-value pairs for resource tagging
+     * @default - No tags applied
+     */
+    readonly tags?: {
+        [key: string]: string;
+    };
+    /**
+     * The principal to grant permissions to
+     */
+    readonly grantPrincipal: iam.IPrincipal;
+    /**
+     * The KMS key used to encrypt the memory.
+     */
+    readonly kmsKey?: kms.IKey;
+    /**
+     * The memory strategies used by the memory.
+     * @attribute
+     */
+    readonly memoryStrategies: IMemoryStrategy[];
+    private readonly __resource;
+    constructor(scope: Construct, id: string, props: MemoryProps);
+    /**
+     * Add memory strategy to the memory.
+     * @default - No memory strategies.
+     */
+    addMemoryStrategy(memoryStrategy: IMemoryStrategy): void;
+    /**
+     * Creates execution role needed for the memory to access AWS services
+     * @returns The created role
+     * @internal This is an internal core function and should not be called directly.
+     */
+    private _createMemoryRole;
+    /**
+     * Validates the memory tags format
+     * @param tags The tags object to validate
+     * @returns Array of validation error messages, empty if valid
+     */
+    private _validateMemoryTags;
+    /**
+     * Validates the memory name format
+     * @param name The memory name to validate
+     * @returns Array of validation error messages, empty if valid
+     */
+    private _validateMemoryName;
+    /**
+     * Validates the memory expiration days
+     * @param expirationDays The memory expiration days to validate
+     * @returns Array of validation error messages, empty if valid
+     */
+    private _validateMemoryExpirationDays;
+    /**
+     * Render the memory strategies.
+     *
+     * @returns Array of MemoryStrategyProperty objects in CloudFormation format, or undefined if no strategies are defined
+     * @default - undefined if no strategies are defined or array is empty
+     * @internal This is an internal core function and should not be called directly.
+     */
+    private _renderMemoryStrategies;
+}