feat: add streamDeliveryResources schema, CLI flags, and validation for memory record streaming

Author: Hweinstock

docs/memory.md

@@ -198,6 +198,66 @@ Memory events expire after a configurable duration (7-365 days, default 30):
 }
 ```
 
+## Memory Record Streaming
+
+Memory record streaming delivers real-time events when memory records are created, updated, or deleted. Events are
+pushed to a delivery target in your account, enabling event-driven architectures without polling.
+
+### Enabling Streaming
+
+Via CLI flags:
+
+```bash
+agentcore add memory \
+  --name MyMemory \
+  --strategies SEMANTIC \
+  --data-stream-arn arn:aws:kinesis:us-west-2:123456789012:stream/my-stream \
+  --stream-content-level FULL_CONTENT
+```
+
+For advanced configurations (e.g. multiple delivery targets), pass the full JSON:
+
+```bash
+agentcore add memory \
+  --name MyMemory \
+  --strategies SEMANTIC \
+  --stream-delivery-resources '{"resources":[{"kinesis":{"dataStreamArn":"arn:aws:kinesis:us-west-2:123456789012:stream/my-stream","contentConfigurations":[{"type":"MEMORY_RECORDS","level":"FULL_CONTENT"}]}}]}'
+```
+
+### Configuration
+
+```json
+{
+  "type": "AgentCoreMemory",
+  "name": "MyMemory",
+  "eventExpiryDuration": 30,
+  "strategies": [{ "type": "SEMANTIC" }],
+  "streamDeliveryResources": {
+    "resources": [
+      {
+        "kinesis": {
+          "dataStreamArn": "arn:aws:kinesis:us-west-2:123456789012:stream/my-stream",
+          "contentConfigurations": [{ "type": "MEMORY_RECORDS", "level": "FULL_CONTENT" }]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Content Level
+
+| Level           | Description                                                |
+| --------------- | ---------------------------------------------------------- |
+| `FULL_CONTENT`  | Events include memory record text and all metadata         |
+| `METADATA_ONLY` | Events include only metadata (IDs, timestamps, namespaces) |
+
+The CDK construct automatically grants the memory execution role permission to publish to the configured delivery
+target.
+
+For more details, see the
+[Memory Record Streaming documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory-record-streaming.html).
+
 ## Using Memory in Code
 
 The memory ID is available via environment variable:

src/cli/commands/add/__tests__/validate.test.ts

@@ -738,6 +738,71 @@ describe('validate', () => {
         valid: true,
       });
     });
+
+    // Streaming validation
+    it('accepts valid streaming options', () => {
+      expect(
+        validateAddMemoryOptions({
+          ...validMemoryOptions,
+          dataStreamArn: 'arn:aws:kinesis:us-west-2:123456789012:stream/test',
+          contentLevel: 'FULL_CONTENT',
+        })
+      ).toEqual({ valid: true });
+    });
+
+    it('accepts dataStreamArn without contentLevel (defaults to FULL_CONTENT)', () => {
+      expect(
+        validateAddMemoryOptions({
+          ...validMemoryOptions,
+          dataStreamArn: 'arn:aws:kinesis:us-west-2:123456789012:stream/test',
+        })
+      ).toEqual({ valid: true });
+    });
+
+    it('rejects contentLevel without dataStreamArn', () => {
+      const result = validateAddMemoryOptions({ ...validMemoryOptions, contentLevel: 'FULL_CONTENT' });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('--data-stream-arn is required');
+    });
+
+    it('rejects invalid contentLevel', () => {
+      const result = validateAddMemoryOptions({
+        ...validMemoryOptions,
+        dataStreamArn: 'arn:aws:kinesis:us-west-2:123456789012:stream/test',
+        contentLevel: 'INVALID',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('Invalid content level');
+    });
+
+    it('rejects invalid deliveryType', () => {
+      const result = validateAddMemoryOptions({ ...validMemoryOptions, deliveryType: 'sqs' });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('Invalid delivery type');
+    });
+
+    it('accepts valid deliveryType', () => {
+      expect(validateAddMemoryOptions({ ...validMemoryOptions, deliveryType: 'kinesis' })).toEqual({ valid: true });
+    });
+
+    it('rejects dataStreamArn not starting with arn:', () => {
+      const result = validateAddMemoryOptions({
+        ...validMemoryOptions,
+        dataStreamArn: 'not-an-arn',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('valid ARN');
+    });
+
+    it('rejects combining streamDeliveryResources with flat flags', () => {
+      const result = validateAddMemoryOptions({
+        ...validMemoryOptions,
+        dataStreamArn: 'arn:aws:kinesis:us-west-2:123456789012:stream/test',
+        streamDeliveryResources: '{"resources":[]}',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('cannot be combined');
+    });
   });
 
   describe('validateAddIdentityOptions', () => {

src/cli/commands/add/types.ts

@@ -80,6 +80,10 @@ export interface AddMemoryOptions {
   name?: string;
   strategies?: string;
   expiry?: number;
+  deliveryType?: string;
+  dataStreamArn?: string;
+  contentLevel?: string;
+  streamDeliveryResources?: string;
   json?: boolean;
 }
 

src/cli/commands/add/validate.ts

@@ -28,6 +28,8 @@ export interface ValidationResult {
 const MEMORY_OPTIONS = ['none', 'shortTerm', 'longAndShortTerm'] as const;
 const OIDC_WELL_KNOWN_SUFFIX = '/.well-known/openid-configuration';
 const VALID_STRATEGIES = ['SEMANTIC', 'SUMMARIZATION', 'USER_PREFERENCE'];
+const VALID_STREAM_CONTENT_LEVELS = ['FULL_CONTENT', 'METADATA_ONLY'];
+const VALID_DELIVERY_TYPES = ['kinesis'];
 
 /**
  * Validate that a credential name exists in the project spec.
@@ -447,6 +449,35 @@ export function validateAddMemoryOptions(options: AddMemoryOptions): ValidationR
     }
   }
 
+  if (options.streamDeliveryResources && (options.dataStreamArn || options.contentLevel)) {
+    return {
+      valid: false,
+      error: '--stream-delivery-resources cannot be combined with --data-stream-arn or --stream-content-level',
+    };
+  }
+
+  if (options.contentLevel && !options.dataStreamArn) {
+    return { valid: false, error: '--data-stream-arn is required when --stream-content-level is set' };
+  }
+
+  if (options.dataStreamArn && !options.dataStreamArn.startsWith('arn:')) {
+    return { valid: false, error: '--data-stream-arn must be a valid ARN (starts with arn:)' };
+  }
+
+  if (options.deliveryType && !VALID_DELIVERY_TYPES.includes(options.deliveryType)) {
+    return {
+      valid: false,
+      error: `Invalid delivery type. Must be one of: ${VALID_DELIVERY_TYPES.join(', ')}`,
+    };
+  }
+
+  if (options.contentLevel && !VALID_STREAM_CONTENT_LEVELS.includes(options.contentLevel)) {
+    return {
+      valid: false,
+      error: `Invalid content level. Must be one of: ${VALID_STREAM_CONTENT_LEVELS.join(', ')}`,
+    };
+  }
+
   return { valid: true };
 }