Long-running agents accumulate memories. Some stay relevant. Most decay into noise. Without lifecycle policies, you get context bloat, compliance violations, and agents that hallucinate from stale facts.
AWS published a design guide and CDK stack for AgentCore memory lifecycle management. The pattern: nightly Step Functions workflows that score memories, consolidate duplicates, and prune low-value entries. This is not a feature announcement. It is operational plumbing for agent memory hygiene.
The Problem: Memory Accumulation as Technical Debt
Agents store memories to maintain context across sessions. A customer service agent remembers past interactions. A financial advisor tracks portfolio changes. A code assistant recalls project structure.
Without pruning, three failure modes emerge:
- Quality degradation: Outdated facts poison retrieval. The agent cites last quarter's pricing or deprecated APIs.
- Compliance risk: Retention policies require deletion after 90 days. Memories persist indefinitely by default.
- Cost creep: Vector stores charge per embedding. Unused memories consume storage and slow retrieval.
Manual cleanup does not scale. You need automated lifecycle policies.
Architecture: Step Functions as the Orchestration Layer
AWS uses Step Functions to coordinate three nightly operations: scoring, consolidation, and pruning. Each runs as a separate Lambda function invoked in sequence.
Workflow Stages
- Scoring: Lambda queries the memory store, applies a scoring function to each memory, and writes scores back to DynamoDB.
- Consolidation: Lambda identifies duplicate or overlapping memories, merges them into a single entry, and updates embeddings.
- Pruning: Lambda deletes memories below a score threshold or past a retention deadline.
The Step Functions state machine handles retries, error logging, and partial failure recovery. If consolidation fails, pruning does not run. If scoring times out, the workflow retries with exponential backoff.
Deployment Shape
The CDK stack provisions:
- One Step Functions state machine
- Three Lambda functions (Python 3.11 runtime)
- One DynamoDB table for memory metadata
- One S3 bucket for archived memories
- CloudWatch Logs for observability
- EventBridge rule for nightly triggers at 2 AM UTC
The state machine runs in a VPC with private subnets. Lambda functions access Amazon Bedrock via VPC endpoints to avoid internet egress.
Scoring Function: What Makes a Memory Valuable
The scoring function decides which memories survive. AWS provides a reference implementation with four signals:
| Signal | Weight | Rationale |
|---|---|---|
| Recency | 0.3 | Memories accessed in the last 7 days score higher |
| Frequency | 0.25 | Memories retrieved multiple times indicate relevance |
| Semantic density | 0.25 | Memories with high embedding similarity to recent queries score higher |
| Compliance flag | 0.2 | Memories tagged for retention policies score lower |
The function returns a score between 0 and 1. Memories below 0.4 are pruned. Memories above 0.7 are preserved. Memories between 0.4 and 0.7 are candidates for consolidation.
You can override the scoring logic by replacing the Lambda function. The CDK stack accepts a custom scoring module as a parameter.
Example Scoring Code
import boto3
from datetime import datetime, timedelta
def score_memory(memory_id, metadata, embeddings):
now = datetime.utcnow()
last_accessed = metadata.get("last_accessed")
access_count = metadata.get("access_count", 0)
compliance_flag = metadata.get("compliance_flag", False)
# Recency: exponential decay over 30 days
days_since_access = (now - last_accessed).days
recency_score = max(0, 1 - (days_since_access / 30))
# Frequency: logarithmic scale
frequency_score = min(1, access_count / 10)
# Semantic density: cosine similarity to recent queries
recent_queries = get_recent_queries(limit=50)
similarity_scores = [cosine_similarity(embeddings, q) for q in recent_queries]
density_score = max(similarity_scores) if similarity_scores else 0
# Compliance penalty
compliance_score = 0 if compliance_flag else 1
# Weighted sum
final_score = (
0.3 * recency_score +
0.25 * frequency_score +
0.25 * density_score +
0.2 * compliance_score
)
return final_score
Consolidation: Merging Duplicate Memories
Consolidation reduces redundancy. If an agent stores "Customer prefers email" and "Customer contact method: email," the consolidation step merges them into a single memory with a unified embedding.
The reference implementation uses semantic similarity. Lambda queries the vector store for memories with cosine similarity above 0.85. It groups similar memories, generates a new summary via Bedrock, and replaces the group with a single consolidated entry.
Consolidation preserves provenance. The new memory includes a consolidated_from field listing the original memory IDs. This supports audit trails and rollback.
Consolidation Trade-offs
Consolidation reduces storage cost but increases processing time. The Lambda function must:
- Query the vector store for all memories
- Compute pairwise similarity for high-scoring candidates
- Call Bedrock to generate consolidated summaries
- Update embeddings and metadata
For agents with 10,000+ memories, this takes 5-10 minutes. The Step Functions workflow sets a 15-minute timeout for the consolidation step.
Pruning: Deletion Versus Archival
Pruning removes low-value memories. The reference implementation supports two modes:
- Hard delete: Memory is removed from DynamoDB and the vector store.
- Archive: Memory is written to S3 with a Glacier transition policy, then removed from active storage.
Archival satisfies compliance requirements. If a regulator requests historical data, you can restore from S3. Hard delete is faster and cheaper for non-regulated use cases.
The pruning Lambda checks the retention_policy field in memory metadata. If the policy is archive, the memory is written to S3 before deletion. If the policy is delete, the memory is removed immediately.
Handling Partial Failures
Pruning can fail mid-batch. The Lambda function processes memories in batches of 100. If a batch fails, the function logs the error and continues with the next batch. Failed memory IDs are written to a DLQ for manual review.
The Step Functions workflow does not retry pruning. Retrying risks double-deletion or inconsistent state. Instead, the workflow sends an SNS notification to the operations team.
Real-Time Query Consistency During Nightly Runs
Agents query memories in real time. The nightly workflow modifies the memory store. This creates a consistency window.
AWS recommends two strategies:
- Read-only mode: During the workflow, the agent switches to a read-only replica of the memory store. Writes are queued and applied after the workflow completes.
- Optimistic locking: The agent uses DynamoDB conditional writes. If a memory is deleted during a query, the agent retries with the updated state.
The CDK stack does not enforce a strategy. You must implement consistency logic in the agent's memory client.
Observability: What to Monitor
The Step Functions workflow emits CloudWatch metrics for each stage:
-
ScoringDuration: Time to score all memories -
ConsolidationCount: Number of memories consolidated -
PruningCount: Number of memories pruned -
FailedBatches: Number of batches that failed during pruning
Set alarms for:
-
ScoringDuration > 10 minutes: Indicates memory store growth or slow queries -
FailedBatches > 0: Requires manual intervention -
PruningCount = 0: Suggests scoring thresholds are too lenient
The workflow also logs memory IDs and scores to CloudWatch Logs. This supports debugging and compliance audits.
Security Boundaries
The workflow runs in a private VPC. Lambda functions assume an IAM role with least-privilege permissions:
- Read/write access to the memory DynamoDB table
- Read/write access to the S3 archive bucket
- Invoke permissions for Bedrock models
- Write permissions for CloudWatch Logs
The role does not have access to the agent's execution environment or user data. Memory metadata includes a user_id field, but the workflow does not decrypt or inspect user-specific content.
Deployment Checklist
Before deploying the CDK stack:
- Choose a scoring function or implement a custom one
- Define retention policies for each memory type
- Set pruning thresholds (default: 0.4)
- Configure archival versus hard delete
- Set up CloudWatch alarms
- Test the workflow in a staging environment with synthetic memories
The CDK stack includes a --dry-run flag that simulates the workflow without modifying the memory store.
Technical Verdict
Use this pattern when:
- Your agent runs for weeks or months and accumulates thousands of memories
- You have compliance requirements for data retention or deletion
- Memory quality degrades over time and affects agent performance
- You need audit trails for memory lifecycle events
Avoid this pattern when:
- Your agent is stateless or short-lived
- Memory count stays below 1,000 entries
- You need real-time pruning triggered by user actions (this is batch-only)
- Your memory store does not support bulk operations (the workflow assumes DynamoDB or similar)
The Step Functions approach works for batch hygiene. It does not replace real-time memory management. If your agent needs to forget a fact immediately (for example, after a user deletes their account), implement a separate synchronous deletion path.
Top comments (0)