Merge pull request #88 from awslabs/feature/add-long-term-memory

feature/add long term memory

Author: brianz

frontend/.prettierrc .prettierrcfrontend/.prettierrc renamed to .prettierrc

@@ -16,6 +16,7 @@ A basic conversational agent using the Strands framework with AgentCore Memory i
 
 - Multi-turn conversational chat
 - Maintains conversation history with short-term memory
+- **Optional long-term memory**: When `use_long_term_memory: true` is set in `config.yaml`, the agent uses a `SemanticMemoryStrategy` to extract and recall facts across sessions (keyed by Cognito user ID). See [Memory Integration Guide](MEMORY_INTEGRATION.md#enabling-long-term-memory) for details.
 - Streams responses for better UX
 - Authenticated via Cognito (user identity tracked in memory)
 

docs/AGENT_CONFIGURATION.md

@@ -6,6 +6,46 @@ AgentCore provides two types of memory: **short-term memory** stores raw convers
 
 ---
 
+## Enabling Long-Term Memory
+
+Long-term memory (LTM) is supported on the **`strands-single-agent`** pattern. It uses a `SemanticMemoryStrategy` to automatically extract and store facts from conversations, enabling the agent to recall information across sessions. Facts are keyed by the Cognito `userId`, so each user gets their own persistent memory.
+
+### How It Works
+
+1. **Infrastructure**: The CDK stack always creates the `SemanticMemoryStrategy` on the memory resource (there is no cost to simply define the strategy). A `USE_LONG_TERM_MEMORY` environment variable is passed to the agent runtime.
+2. **Agent behavior**: When `USE_LONG_TERM_MEMORY` is `"true"`, the Strands agent's `AgentCoreMemorySessionManager` is configured with a `retrieval_config` that reads from the `/facts/{actorId}` namespace on each turn. When `"false"` (the default), only short-term conversation history is active.
+3. **Fact extraction**: AgentCore processes conversation events asynchronously and extracts factual information (e.g., "the user lives in Seattle", "the user prefers Python"). These facts are stored under `/facts/{actorId}` and retrieved on subsequent turns to personalize responses.
+
+### Configuration
+
+Toggle LTM in `infra-cdk/config.yaml`:
+
+```yaml
+backend:
+  use_long_term_memory: true   # Enable long-term semantic memory retrieval
+```
+
+Then redeploy:
+
+```bash
+cd infra-cdk && cdk deploy --all
+```
+
+### Cost Considerations
+
+LTM incurs additional charges beyond short-term memory:
+
+- **Storage**: $0.75 per 1,000 memory records stored
+- **Retrieval**: $0.50 per 1,000 retrieval calls
+
+When `use_long_term_memory` is `false`, neither cost applies — short-term memory (conversation history) is the only active feature.
+
+### Other Patterns
+
+The **`langgraph-single-agent`** pattern does not currently use long-term memory. It uses `AgentCoreMemorySaver` as a LangGraph checkpointer for short-term conversation persistence only. See the LangGraph section below for details on adding long-term memory via `AgentCoreMemoryStore`.
+
+---
+
 ## Step 1: Configure Memory with CDK
 
 Memory resources are created using [CloudFormation L1 constructs](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrockagentcore-memory.html). **L2 constructs will be available in future releases.**
@@ -157,6 +197,32 @@ config = AgentCoreMemoryConfig(
 )
 ```
 
+**With long-term memory enabled** (see [Enabling Long-Term Memory](#enabling-long-term-memory) above):
+
+The `strands-single-agent` pattern conditionally enables LTM retrieval based on the `USE_LONG_TERM_MEMORY` environment variable. When enabled, the agent retrieves facts from the `/facts/{actorId}` namespace on each turn:
+
+```python
+use_ltm = os.environ.get("USE_LONG_TERM_MEMORY", "false").lower() == "true"
+
+retrieval_config = (
+    {
+        "/facts/{actorId}": RetrievalConfig(
+            top_k=10,
+            relevance_score=0.3,
+        )
+    }
+    if use_ltm
+    else None
+)
+
+config = AgentCoreMemoryConfig(
+    memory_id=memory_id,
+    session_id=session_id,
+    actor_id=user_id,
+    retrieval_config=retrieval_config,
+)
+```
+
 **💡 Example:** See this approach implemented in `patterns/strands-single-agent/basic_agent.py`
 
 **📚 Official AWS Guide:** [Strands SDK Memory Integration](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/strands-sdk-memory.html)

docs/MEMORY_INTEGRATION.md

@@ -15,6 +15,14 @@ backend:
   deployment_type: docker # Available deployment types: docker (default), zip (not supported for claude-agent-sdk)
   network_mode: PUBLIC # Available network modes: PUBLIC (default), VPC
 
+  # Long-term memory uses a SemanticMemoryStrategy to extract and store facts across sessions.
+  # This incurs additional costs: $0.75/1,000 records stored + $0.50/1,000 retrieval calls.
+  # Set to true when you want to try persistent cross-session memory, which is keyed off of the
+  # Cognito userId.
+  use_long_term_memory: false
+  ltm_top_k: 10             # Number of facts to retrieve per turn (default: 10)
+  ltm_relevance_score: 0.3  # Minimum similarity threshold for retrieval (default: 0.3)
+
   # VPC configuration - required when network_mode is VPC
   # Your VPC must have the necessary VPC endpoints for AWS services.
   # See docs/DEPLOYMENT.md for the full list of required VPC endpoints.

infra-cdk/.prettierrc

@@ -113,10 +113,13 @@ export class BackendStack extends cdk.NestedStack {
     let agentRuntimeArtifact: agentcore.AgentRuntimeArtifact
     let zipPackagerResource: cdk.CustomResource | undefined
 
-    if (deploymentType === "zip" && (pattern === "claude-agent-sdk-single-agent" || pattern === "claude-agent-sdk-multi-agent")) {
+    if (
+      deploymentType === "zip" &&
+      (pattern === "claude-agent-sdk-single-agent" || pattern === "claude-agent-sdk-multi-agent")
+    ) {
       throw new Error(
         "claude-agent-sdk patterns require Docker deployment (deployment_type: docker) " +
-        "because they need Node.js and the claude-code CLI installed at build time."
+          "because they need Node.js and the claude-code CLI installed at build time."
       )
     }
 
@@ -147,7 +150,7 @@ export class BackendStack extends cdk.NestedStack {
 
       // Read agent code files and encode as base64
       const agentCode: Record<string, string> = {}
-      
+
       // Read pattern .py files
       for (const file of fs.readdirSync(patternDir)) {
         if (file.endsWith(".py")) {
@@ -166,7 +169,8 @@ export class BackendStack extends cdk.NestedStack {
 
       // Read requirements
       const requirementsPath = path.join(patternDir, "requirements.txt") // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
-      const requirements = fs.readFileSync(requirementsPath, "utf-8")
+      const requirements = fs
+        .readFileSync(requirementsPath, "utf-8")
         .split("\n")
         .map(line => line.trim())
         .filter(line => line && !line.startsWith("#"))
@@ -241,7 +245,16 @@ export class BackendStack extends cdk.NestedStack {
         Name: cdk.Names.uniqueResourceName(this, { maxLength: 48 }),
         EventExpiryDuration: 30,
         Description: `Short-term memory for ${config.stack_name_base} agent`,
-        MemoryStrategies: [], // Empty array = short-term only (conversation history)
+        MemoryStrategies: [
+          {
+            // Extracts and stores factual information shared by the user across sessions.
+            // Stored under /facts/{actorId} — retrieved on each turn to personalise responses.
+            SemanticMemoryStrategy: {
+              Name: "FactExtractor",
+              Namespaces: ["/facts/{actorId}"],
+            },
+          },
+        ],
         MemoryExecutionRoleArn: agentRole.roleArn,
         Tags: {
           Name: `${config.stack_name_base}_Memory`,
@@ -339,6 +352,14 @@ export class BackendStack extends cdk.NestedStack {
       MEMORY_ID: memoryId,
       STACK_NAME: config.stack_name_base,
       GATEWAY_CREDENTIAL_PROVIDER_NAME: `${config.stack_name_base}-runtime-gateway-auth`, // Used by @requires_access_token decorator to look up the correct provider
+      // Controls whether the agent activates long-term semantic memory retrieval.
+      // The memory resource always includes the SemanticMemoryStrategy (no cost to define it),
+      // but retrieval is only performed when this is "true". See config.yaml: use_long_term_memory.
+      USE_LONG_TERM_MEMORY: config.backend.use_long_term_memory ? "true" : "false",
+      // Retrieval tuning for long-term memory. Only used when USE_LONG_TERM_MEMORY is "true".
+      // See config.yaml: ltm_top_k and ltm_relevance_score.
+      LTM_TOP_K: String(config.backend.ltm_top_k),
+      LTM_RELEVANCE_SCORE: String(config.backend.ltm_relevance_score),
     }
 
     // Add claude-agent-sdk specific environment variable
@@ -767,8 +788,6 @@ export class BackendStack extends cdk.NestedStack {
       },
     })
 
-
-
     // Store for use in createAgentCoreRuntime()
     this.runtimeCredentialProvider = runtimeCredentialProvider
 
@@ -935,8 +954,6 @@ export class BackendStack extends cdk.NestedStack {
       ),
       description: "Machine Client Secret for M2M authentication",
     })
-
-
   }
 
   /**
@@ -964,18 +981,16 @@ export class BackendStack extends cdk.NestedStack {
 
       // Import the user-specified subnets by their IDs.
       // These subnets must exist within the VPC specified above.
-      const subnets: ec2.ISubnet[] = vpcConfig.subnet_ids.map(
-        (subnetId: string, index: number) =>
-          ec2.Subnet.fromSubnetId(this, `ImportedSubnet${index}`, subnetId)
+      const subnets: ec2.ISubnet[] = vpcConfig.subnet_ids.map((subnetId: string, index: number) =>
+        ec2.Subnet.fromSubnetId(this, `ImportedSubnet${index}`, subnetId)
       )
 
       // Build the VPC config props for the AgentCore L2 construct.
       // Security groups are optional — if not provided, the construct creates a default one.
       const securityGroups =
         vpcConfig.security_group_ids && vpcConfig.security_group_ids.length > 0
-          ? vpcConfig.security_group_ids.map(
-              (sgId: string, index: number) =>
-                ec2.SecurityGroup.fromSecurityGroupId(this, `ImportedSG${index}`, sgId)
+          ? vpcConfig.security_group_ids.map((sgId: string, index: number) =>
+              ec2.SecurityGroup.fromSecurityGroupId(this, `ImportedSG${index}`, sgId)
             )
           : undefined
 
@@ -1028,4 +1043,4 @@ export class BackendStack extends cdk.NestedStack {
     const crypto = require("crypto")
     return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16)
   }
-}
+}

infra-cdk/config.yaml

@@ -36,6 +36,23 @@ export interface AppConfig {
     network_mode: NetworkMode
     /** VPC configuration. Required when network_mode is "VPC". */
     vpc?: VpcConfig
+    /**
+     * Enable long-term memory (SemanticMemoryStrategy) for the agent.
+     * When true, the agent extracts and retrieves facts across sessions.
+     * This incurs additional costs: $0.75/1,000 records stored + $0.50/1,000 retrievals.
+     * Defaults to false.
+     */
+    use_long_term_memory: boolean
+    /**
+     * Number of facts to retrieve per turn when long-term memory is enabled.
+     * Maps to the top_k parameter of RetrievalConfig. Defaults to 10.
+     */
+    ltm_top_k: number
+    /**
+     * Minimum similarity threshold for long-term memory retrieval.
+     * Maps to the relevance_score parameter of RetrievalConfig. Defaults to 0.3.
+     */
+    ltm_relevance_score: number
   }
 }
 
@@ -63,7 +80,9 @@ export class ConfigManager {
       configPath = defaultConfigPath
     }
     if (!fs.existsSync(configPath)) {
-      throw new Error(`Configuration file ${configPath} does not exist. Please create config.yaml file.`)
+      throw new Error(
+        `Configuration file ${configPath} does not exist. Please create config.yaml file.`
+      )
     }
 
     try {
@@ -72,7 +91,9 @@ export class ConfigManager {
 
       const deploymentType = parsedConfig.backend?.deployment_type || "docker"
       if (deploymentType !== "docker" && deploymentType !== "zip") {
-        throw new Error(`Invalid deployment_type '${deploymentType}' in ${configPath}. Must be 'docker' or 'zip'.`)
+        throw new Error(
+          `Invalid deployment_type '${deploymentType}' in ${configPath}. Must be 'docker' or 'zip'.`
+        )
       }
 
       const stackNameBase = parsedConfig.stack_name_base
@@ -89,20 +110,28 @@ export class ConfigManager {
       // Validate network_mode if provided
       const networkMode = parsedConfig.backend?.network_mode || "PUBLIC"
       if (networkMode !== "PUBLIC" && networkMode !== "VPC") {
-        throw new Error(`Invalid network_mode '${networkMode}' in ${configPath}. Must be 'PUBLIC' or 'VPC'.`)
+        throw new Error(
+          `Invalid network_mode '${networkMode}' in ${configPath}. Must be 'PUBLIC' or 'VPC'.`
+        )
       }
 
       // Validate VPC configuration when network_mode is VPC
       const vpcConfig = parsedConfig.backend?.vpc
       if (networkMode === "VPC") {
         if (!vpcConfig) {
-          throw new Error(`backend.vpc configuration is required in ${configPath} when network_mode is 'VPC'.`)
+          throw new Error(
+            `backend.vpc configuration is required in ${configPath} when network_mode is 'VPC'.`
+          )
         }
         if (!vpcConfig.vpc_id) {
-          throw new Error(`backend.vpc.vpc_id is required in ${configPath} when network_mode is 'VPC'.`)
+          throw new Error(
+            `backend.vpc.vpc_id is required in ${configPath} when network_mode is 'VPC'.`
+          )
         }
         if (!vpcConfig.subnet_ids || vpcConfig.subnet_ids.length === 0) {
-          throw new Error(`backend.vpc.subnet_ids must contain at least one subnet ID in ${configPath} when network_mode is 'VPC'.`)
+          throw new Error(
+            `backend.vpc.subnet_ids must contain at least one subnet ID in ${configPath} when network_mode is 'VPC'.`
+          )
         }
       }
 
@@ -114,6 +143,9 @@ export class ConfigManager {
           deployment_type: deploymentType,
           network_mode: networkMode,
           vpc: vpcConfig,
+          use_long_term_memory: parsedConfig.backend?.use_long_term_memory === true,
+          ltm_top_k: parsedConfig.backend?.ltm_top_k ?? 10,
+          ltm_relevance_score: parsedConfig.backend?.ltm_relevance_score ?? 0.3,
         },
       }
     } catch (error) {