Designing lifecycle policies for AgentCore memory

extract

Artificial Intelligence Designing lifecycle policies for AgentCore memory Memory lifecycle policies help long-running agents on Amazon Bedrock AgentCore stay effective by systematically managing what they remember and forget. Your agent generates memories from every conversation it conducts. If you don’t actively manage these memories, your agents will accumulate outdated context, which can degrade response quality and create compliance risks for your deployment. After months of production use, problems emerge. We observed a customer support agent reference a billing dispute resolved four months earlier, treating it as active. Another agent repeated outdated deployment advice because its memory still contained a superseded runbook. In this post, we introduce memory lifecycle management for AI agents: the practice of systematically scoring, consolidating, and pruning agent memories over time. We walk through a deployable architecture using AgentCore memory (a capability of Amazon Bedrock AgentCore), AWS Step Functions, and Amazon Bedrock to run a nightly lifecycle workflow. By the end, you will have an AWS Cloud Development Kit (AWS CDK) stack and a framework for managing agent memory as a managed resource. The complete code is available in the GitHub repository. This solution targets agents that accumulate high volumes of interaction data over weeks or months, such as customer support agents, sales advisors, and IT helpdesk bots. For lower-volume agents like personal assistants, you might start with time-to-live (TTL) expiration and General Data Protection Regulation (GDPR) compliance alone. All thresholds are configurable to match your agent’s needs. Solution overview This solution combines a shared memory taxonomy with three lifecycle policies that run as a nightly workflow. We begin with the memory types that shape those policies. Memory types Before designing lifecycle policies, we need a shared vocabulary for what agents remember. We categorize agent memory into three types, each with different retention requirements. - Episodic memory: Episodic memories capture what happened, it’s the record of past conversations. These are timestamped, session-bound, and high-volume. Agentcore memory stores this information in two strategies, Summary and Episodic. Both strategies store memories as individual entries tied to specific agent-user sessions. Episodes and Summary provide short-term continuity but individually they become less relevant as time progresses. When designing your lifecycle policies, prioritize these memories for expiration first. - Semantic memory: Semantic memories are distilled facts and preferences extracted from interactions but decoupled from any single conversation. “The user prefers the US East (N. Virginia) AWS Region (us-east-1) for deployments.” These are durable, high value, and compact. In your lifecycle policies, retain semantic memories longer than episodic memories. These are prime candidates for consolidation, where you merge multiple episodic observations into a single, authoritative fact. - Procedural memory: Procedural memories encode learned workflows and tool-use patterns. “When the user asks about costs, query the AWS Cost Explorer API first, then summarize.” These represent the agent’s operational expertise. Procedural memories are lower volume but the most valuable type for certain use cases. They have the longest retention and the highest bar for pruning. AgentCore memory stores procedural knowledge as reflections tied to episodic memory. Read more about it in Episodic memory deep dive blog. You should check these for validity as your procedures evolve. Lifecycle policies With our taxonomy in place, we can design three complementary lifecycle policies. Each targets a different failure mode of unbounded memory. Policy 1: TTL-based expiration The first policy automatically deletes memories older than a configured TTL. We default to 90 days for episodic memories. TTL does not consider whether a memory is still useful, but it provides a hard ceiling on accumulation and is essential for compliance. In production, differentiate TTL by memory type. Configure your summary memories to expire after 30–60 days, semantic memories after 6–12 months, and consider setting no TTL for procedural memories. This post delivers a single configurable memoryTtlDays parameter as a starting point. TTL expiration runs first, before scoring or consolidation, which helps avoid wasting compute on memories that should already be gone. AgentCore memory doesn’t provide a built-in auto-delete TTL. However, it exposes system-generated timestamp fields that support BEFORE and AFTER filter operators on ListMemoryRecords. Our pruner uses x-amz-agentcore-memory-createdAt with a BEFORE filter to retrieve only records older than the configured TTL, then deletes them. Policy 2: Relevance decay scoring Not all memories age at the same rate. A memory accessed yesterday is more relevant than one untouched for weeks. We score each memory using a three-term weighted formula that combines creation recency, last-access recency, and access frequency: Rather than exposing a raw decay constant, we provide one intuitive parameter: pruneDays, the approximate number of days after which an unaccessed memory’s score drops below the relevance threshold: With the defaults (pruneDays = 45, threshold = 0.3), this gives decay_rate ≈ 0.02676. The formula produces a score between 0.0–1.0. When memories score below your configured threshold, the system flags them for consolidation or pruning based on your policy settings. The formula balances three intuitions: recent memories matter, recently used memories matter even more, and frequently retrieved memories carry additional signal. The exponential decay means scores drop sharply in the first few weeks, then level off. A memory that is old but accessed recently and frequently can still score well. The three weights are configurable, letting operators emphasize different signals depending on their agent’s workload: - W_RECENCY (default 0.4): Weight for creation recency. Higher values favor newer memories. - W_ACCESS (default 0.35): Weight for last-access recency. Higher values favor recently retrieved memories. - W_FREQUENCY (default 0.25): Weight for access frequency. Higher values favor memories that are retrieved often. - MAX_ACCESS_BASELINE (default 50): The access count at which the frequency term saturates at 1.0. Set this to the approximate number of accesses a “heavily used” memory accumulates in your lookback window. When the three weights sum to 1.0, the score will fall in [0.0, 1.0]. Operators can adjust weights to match their agent’s needs. For example, increase W_FREQUENCY for agents where frequently accessed memories are most valuable (for example, a support bot that repeatedly references the same troubleshooting runbook), or increase W_RECENCY for agents where freshness matters most (for example, a real-time trading assistant). The right pruneDays value depends on your agent’s use case. The following table provides recommended starting points for common agent archetypes: The following scoring function comes from our Memory Scorer AWS Lambda function (code/lambdas/memory_scorer/handler.py): AWS CloudTrail-based access tracking The AgentCore memory API does not include a lastAccessedAt field in its MemoryRecordSummary. To get real access data, we use AWS CloudTrail. The CDK stack configures a trail with advanced event selectors that capture GetMemoryRecord data events. Your CloudTrail configuration logs every memory retrieval with its memoryRecordId and timestamp, then delivers the logs to your Amazon Simple Storage Service (Amazon S3) bucket. At the start of each scoring invocation, the Memory Scorer lists CloudTrail log files from the past 25 hours, decompresses them, and aggregates GetMemoryRecord events into a per-record lookup of last-access timestamps and access counts. To maintain cumulative access history across invocations, the scorer persists an access ledger in Amazon S3. Each run merges fresh CloudTrail counts with historical counts, giving the frequency term a true lifetime signal rather than a narrow daily snapshot. Policy 3: LLM-based consolidation Before pruning low-scoring memories, we give them one last chance. Consolidation uses Amazon Bedrock to merge related memories into a single, compact semantic entry. Five episodic memories about deployment preferences become one authoritative fact. In this step, a large language model (LLM) summarizes its own memories. The consolidation prompt instructs the model to preserve essential facts, remove redundancy, and output a confidence score: The system stores the consolidated memory back in AgentCore memory, then deletes the originals. If Amazon Bedrock fails, the system retains the originals unchanged. The system logs failed deletions for your manual review. Consolidation is lossy by nature. An LLM summarizing five memories into one can drop some nuance. The confidence score returned by the model helps flag low-quality consolidations for human review. For high-stakes domains, consider archiving originals to cold storage instead of deleting them. For production deployments, configure Amazon Bedrock Guardrails to filter harmful content and use grounding checks to verify consolidated memories remain faithful to the source material. These controls are production requirements, not optional additions. Architecture diagram The following diagram shows the nightly lifecycle workflow architecture. Amazon EventBridge triggers an AWS Step Functions state machine that orchestrates five Lambda functions in sequence. Text description for accessibility: An Amazon EventBridge rule triggers a Step Functions state machine nightly. The state machine invokes Lambda functions in sequence: Memory Pruner (TTL expiration), Memory Scorer (relevance scoring using CloudTrail access data), Memory Consolidator (LLM-based merging through Amazon Bedrock), Metrics Emitter (Amazon CloudWatch metrics), and Run Output Writer (S3 persistence). Failures route to an Amazon Simple Notification Service (Amazon SNS) topic for alerts. The workflow proceeds as follows: - TTL Expiration: The Memory Pruner queries AgentCore memory for records older than the configured TTL (default: 90 days) and deletes them. - Score Memories: The Memory Scorer builds a per-record access lookup from CloudTrail logs, merges it with a persistent S3 ledger, computes relevance scores, and returns memories below the threshold. - Consolidate: The workflow batches low-scoring memories (default size: 10) and sends them to the Memory Consolidator, which invokes Amazon Bedrock to merge them into compact semantic entries and deletes the originals. - Emit Metrics: The Metrics Emitter publishes workflow metrics (memories processed, consolidated, pruned) to CloudWatch. - Write Run Output: The Run Output Writer persists workflow results to S3 for auditability. If any step fails, a Catch block routes to a failure handler that publishes error details to an Amazon SNS topic. Prerequisites Before deploying the solution, confirm you have the following: - An AWS account with permissions to create Lambda functions, Step Functions state machines, Amazon EventBridge rules, SNS topics, CloudWatch dashboards, CloudTrail trails, and S3 buckets. - AWS CDK v2 installed (npm install -g aws-cdk ). - Node.js 18+ and npm. - Python 3.12 with pip. - Amazon Bedrock model access enabled for Claude Sonnet 4.5 (anthropic.claude-sonnet-4-5-20250929-v1:0 ) in your target Region. See Supported models by AWS Region in Amazon Bedrock to verify availability. - Amazon Bedrock AgentCore with at least one agent configured with memory enabled. - AWS Command Line Interface (AWS CLI) configured with appropriate credentials. Clone the repository and install dependencies: Solution walkthrough We orchestrate the entire lifecycle as a nightly AWS Step Functions workflow triggered by Amazon EventBridge. The workflow runs five stages in sequence: TTL expiration, scoring, consolidation, metrics emission, and run output writing. CDK stack walkthrough A single CDK stack (code/lib/memory-lifecycle-stack.ts) defines the entire infrastructure. Here are the key sections. Lambda function definitions: Each handler uses Python 3.12 with least-privilege IAM permissions. The stack deploys shared code as a Lambda Layer and passes configurable parameters as environment variables: AWS Identity and Access Management (IAM) least-privilege: The Memory Scorer can only list memories. The Consolidator can read, create, delete memories and invoke Amazon Bedrock. The Pruner can list and delete: Step Functions workflow: The state machine chains TTL expiration, scoring, a Choice state for low-score memories, batch consolidation (Map state), metrics emission, and run output writing: Nightly trigger: An Amazon EventBridge rule fires the workflow at 2 AM UTC every day: All configurable parameters (memoryTtlDays, relevanceThreshold, consolidationBatchSize, pruneDays, bedrockModelId, and the scoring weights) are read from CDK context, so you can tune them at deploy time without changing code: Cost considerations The primary cost driver is Amazon Bedrock invocations during consolidation. For an agent with 1,000 memories where 20 percent score below the threshold, expect roughly 20 Bedrock invocations per nightly run (about $0.01–$0.02). At 100,000 memories, this could reach $50–$100 per month. Start with a higher relevance threshold to limit consolidation volume, and review Amazon Bedrock pricing for your specific workload. Testing memory quality Pruning and consolidation are only useful if the agent still answers correctly afterward. We measure whether lifecycle operations degrade response quality using a regression test suite. Memory regression test suite We define test cases as question-and-criteria pairs (code/test/test_regression_suite.py). Each test case specifies a question, the criteria the agent’s response should satisfy, and a minimum quality score: The regression suite follows a before-and-after pattern: - Baseline: Query the agent with each test question before the lifecycle run. Record the quality score using AgentCore Evaluations, a capability of Amazon Bedrock AgentCore. - Run lifecycle: Execute the nightly workflow (scoring, consolidation, pruning). - Post-lifecycle: Query the agent again with the same questions. Record new quality scores. - Evaluate: A test case passes if the post-lifecycle score meets or exceeds the configured minimum. We also compute the quality delta (post_lifecycle_score - baseline_score ) for reporting. AgentCore Evaluations integration The regression suite integrates with Amazon Bedrock AgentCore Evaluations to compute quality scores programmatically. AgentCore Evaluations works as an LLM-as-judge system: you provide the agent’s response and human-defined criteria, and the service returns a normalized quality score between 0.0 and 1.0. This makes the suite fully automated and suitable for continuous integration and continuous delivery (CI/CD) pipelines. Running the suite produces a per-test-case report that pairs the baseline and post-lifecycle scores so you can see the quality delta at a glance: In this sample run, both test cases stay above their configured minimums. A test case fails only when the post-lifecycle score drops below its min_quality_score, signaling that pruning or consolidation went too far. Privacy and compliance Memory lifecycle management is not only about performance. It’s a compliance requirement. When your agent stores personal data in memory, you inherit obligations under regulations like GDPR. GDPR right-to-be-forgotten A dedicated GDPR Deletion Handler (code/lambdas/gdpr_deletion/handler.py) deletes all memories for a specific user. It lists every memory for that user in AgentCore memory and deletes them individually: The handler returns a confirmation with the count of deleted memories and any failed IDs. On partial failure, the response includes the failed memory identifiers so operators can investigate and retry. Audit logging with CloudTrail Every memory mutation (scoring, consolidation, pruning, GDPR deletion) produces structured JSON logs in Amazon CloudWatch Logs with action type, memory ID, and ISO 8601 timestamp. The CDK stack also configures AWS CloudTrail to log AgentCore memory API calls, providing an immutable audit trail for compliance demonstrations: The stack creates an Amazon CloudWatch dashboard displaying memories processed, consolidated, pruned, and workflow execution status for real-time operational visibility. Clean up To remove all resources created by this solution, run: This removes all resources created by the stack. You might need to delete CloudWatch log groups created by Lambda executions separately. Conclusion We showed how to build memory lifecycle policies for Amazon Bedrock AgentCore agents using AWS Step Functions and Amazon Bedrock. The solution applies three complementary policies: TTL expiration for hard time limits, relevance decay scoring for intelligent prioritization, and LLM-based consolidation for preserving knowledge. With the pruneDays parameter, you can tune decay aggressiveness. We also covered testing to confirm pruning doesn’t degrade quality, and GDPR compliance at the memory layer. The full code is available in the GitHub repository. Deploy it with npx cdk deploy -c pruneDays=45 and start running nightly memory lifecycle management for your agents. To learn more, see the Amazon Bedrock AgentCore documentation, the Amazon Bedrock AgentCore detail page, the AWS Step Functions Developer Guide, and the Amazon Bedrock User Guide.