feat: add streamDeliveryResources schema, CLI flags, and validation for memory record streaming (#531)

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

* fix: address review feedback on streaming support

- Replace unsafe `as MemoryStrategyType` casts with Zod parse
- Include deliveryType in streamDeliveryResources conflict check
- Reject deliveryType without dataStreamArn
- Validate streamDeliveryResources JSON eagerly in validator
- Include Zod error details in parseStreamDeliveryResources
- Extract DEFAULT_DELIVERY_TYPE constant
- Tighten createMemory strategies param type

* fix: update create-memory test for strict strategy validation

CUSTOM is not a valid MemoryStrategyType. The previous test relied on
an unsafe `as` cast to pass an invalid strategy through. Now that we
use Zod parse, invalid strategies are correctly rejected.

Author: Hweinstock

docs/memory.md

@@ -222,6 +222,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

@@ -994,6 +994,119 @@ 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,
+        dataStreamArn: 'arn:aws:kinesis:us-west-2:123456789012:stream/test',
+        deliveryType: 'sqs',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('Invalid delivery type');
+    });
+
+    it('accepts valid deliveryType', () => {
+      expect(
+        validateAddMemoryOptions({
+          ...validMemoryOptions,
+          dataStreamArn: 'arn:aws:kinesis:us-west-2:123456789012:stream/test',
+          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');
+    });
+
+    it('rejects combining streamDeliveryResources with deliveryType', () => {
+      const result = validateAddMemoryOptions({
+        ...validMemoryOptions,
+        deliveryType: 'kinesis',
+        streamDeliveryResources:
+          '{"resources":[{"kinesis":{"dataStreamArn":"arn:aws:kinesis:us-west-2:123456789012:stream/test","contentConfigurations":[{"type":"MEMORY_RECORDS","level":"FULL_CONTENT"}]}}]}',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('cannot be combined');
+    });
+
+    it('rejects deliveryType without dataStreamArn', () => {
+      const result = validateAddMemoryOptions({
+        ...validMemoryOptions,
+        deliveryType: 'kinesis',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('--data-stream-arn is required');
+    });
+
+    it('rejects invalid streamDeliveryResources JSON', () => {
+      const result = validateAddMemoryOptions({
+        ...validMemoryOptions,
+        streamDeliveryResources: 'not json',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('Invalid JSON');
+    });
+
+    it('rejects streamDeliveryResources that fails schema validation', () => {
+      const result = validateAddMemoryOptions({
+        ...validMemoryOptions,
+        streamDeliveryResources: '{"resources":[]}',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('does not match the expected schema');
+    });
   });
 
   describe('validateAddCredentialOptions', () => {

src/cli/commands/add/types.ts

@@ -109,6 +109,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

@@ -8,6 +8,7 @@ import {
   ProtocolModeSchema,
   RuntimeAuthorizerTypeSchema,
   SDKFrameworkSchema,
+  StreamDeliveryResourcesSchema,
   TARGET_TYPE_AUTH_CONFIG,
   TargetLanguageSchema,
   getSupportedFrameworksForProtocol,
@@ -35,6 +36,9 @@ export interface ValidationResult {
 // Constants
 const MEMORY_OPTIONS = ['none', 'shortTerm', 'longAndShortTerm'] as const;
 const VALID_STRATEGIES = ['SEMANTIC', 'SUMMARIZATION', 'USER_PREFERENCE', 'EPISODIC'];
+const VALID_STREAM_CONTENT_LEVELS = ['FULL_CONTENT', 'METADATA_ONLY'];
+const VALID_DELIVERY_TYPES = ['kinesis'] as const;
+export const DEFAULT_DELIVERY_TYPE = 'kinesis';
 
 /**
  * Validate that a credential name exists in the project spec.
@@ -677,6 +681,57 @@ export function validateAddMemoryOptions(options: AddMemoryOptions): ValidationR
     }
   }
 
+  if (options.streamDeliveryResources && (options.dataStreamArn || options.contentLevel || options.deliveryType)) {
+    return {
+      valid: false,
+      error:
+        '--stream-delivery-resources cannot be combined with --data-stream-arn, --stream-content-level, or --delivery-type',
+    };
+  }
+
+  if (options.contentLevel && !options.dataStreamArn) {
+    return { valid: false, error: '--data-stream-arn is required when --stream-content-level is set' };
+  }
+
+  if (options.deliveryType && !options.dataStreamArn) {
+    return { valid: false, error: '--data-stream-arn is required when --delivery-type 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 as (typeof VALID_DELIVERY_TYPES)[number])
+  ) {
+    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(', ')}`,
+    };
+  }
+
+  if (options.streamDeliveryResources) {
+    try {
+      StreamDeliveryResourcesSchema.parse(JSON.parse(options.streamDeliveryResources));
+    } catch (e) {
+      return {
+        valid: false,
+        error:
+          e instanceof SyntaxError
+            ? 'Invalid JSON in --stream-delivery-resources'
+            : 'Invalid --stream-delivery-resources: does not match the expected schema',
+      };
+    }
+  }
+
   return { valid: true };
 }
 

src/cli/operations/memory/__tests__/create-memory.test.ts

@@ -76,20 +76,18 @@ describe('add', () => {
     expect(addedMemory.strategies[0]!.namespaces).toEqual(['/users/{actorId}/facts']);
   });
 
-  it('creates memory with strategy without default namespaces', async () => {
+  it('rejects invalid strategy type', async () => {
     const project = makeProject([]);
     mockReadProjectSpec.mockResolvedValue(project);
-    mockWriteProjectSpec.mockResolvedValue(undefined);
 
-    await primitive.add({
+    const result = await primitive.add({
       name: 'NewMem',
       strategies: 'CUSTOM',
       expiry: 30,
     });
 
-    const writtenSpec = mockWriteProjectSpec.mock.calls[0]![0];
-    const addedMemory = writtenSpec.memories.find((m: { name: string }) => m.name === 'NewMem');
-    expect(addedMemory.strategies[0]!.namespaces).toBeUndefined();
+    expect(result).toEqual(expect.objectContaining({ success: false, error: expect.any(String) }));
+    expect(mockWriteProjectSpec).not.toHaveBeenCalled();
   });
 
   it('returns error on duplicate memory name', async () => {