feat(memory): add CUSTOM strategy type to agentcore-cli (#677) (#694)

* feat(memory): add CUSTOM strategy type to agentcore-cli (#677)

Enable self-managed (CUSTOM) memory strategy in the CLI, aligning
with the CDK constructs which already support customMemoryStrategy
via CloudFormation.

Changes:
- Add CUSTOM to MemoryStrategyTypeSchema enum and validation
- Add CUSTOM description to TUI wizard strategy picker
- Update CLI help text, LLM-compacted types, and AGENTS.md
- Add documentation for self-managed strategy in docs/
- Update tests: flip rejection tests to acceptance, add new cases
- Regenerate asset snapshots

Constraint: CDK already maps CUSTOM → customMemoryStrategy in CFN
Rejected: New SELF_MANAGED type | cross-layer naming inconsistency with CDK
Confidence: high
Scope-risk: narrow

* refactor(memory): derive VALID_STRATEGIES and help text from schema

Eliminates source-of-truth drift by deriving the valid strategies
array and CLI help text from MemoryStrategyTypeSchema.options
instead of maintaining hand-written duplicates.

Constraint: MemoryStrategyTypeSchema is the single source of truth
Confidence: high
Scope-risk: narrow

* fix(memory): add CUSTOM block to session.py templates

Without this, selecting CUSTOM as the only strategy would render
an empty retrieval_config dict with no guidance. Now both HTTP and
A2A Strands templates include a CUSTOM Handlebars block with a
TODO comment guiding users to add their own namespace and
retrieval config.

Constraint: CUSTOM is self-managed — no default namespaces to vend
Rejected: Auto-generating a placeholder namespace | would mislead users into thinking it works out of the box
Confidence: high
Scope-risk: narrow

* feat(memory): add CUSTOM as wizard MemoryOption and wire existing memories to new agents

Add 'custom' as a 4th MemoryOption in the create/add-agent wizards,
completing CUSTOM strategy support across all CLI flows. When adding
an agent to a project with existing memories, the template now
references all existing memories instead of always creating new ones.

- Add 'custom' to MemoryOption type, MEMORY_OPTIONS array, and all
  validation/help text across create and add-agent commands
- Add 'custom' case to mapGenerateInputToMemories (CUSTOM strategy,
  no default namespaces) and getMemoryLabel in wizard UI
- Add mapExistingMemoriesToProviders() to convert project Memory[]
  to MemoryProviderRenderConfig[] for template rendering
- Update mapGenerateConfigToRenderConfig to accept existing memories
  and merge them with new memory providers (deduped by name)
- Update writeAgentToProject to skip adding duplicate memories
- Wire existing project.memories through both add-agent paths
  (AgentPrimitive CLI + useAddAgent TUI hook)

Constraint: Strands Agent takes a single session_manager, so session.py
  references memoryProviders[0] as the primary memory
Rejected: Multi-select wizard for memory | template only supports one
  session_manager, all memory env vars already available at runtime
Confidence: high
Scope-risk: moderate

* test(memory): add CUSTOM strategy and existingMemories tests

Add 18 new tests to schema-mapper.test.ts covering:
- mapGenerateInputToMemories with 'custom' MemoryOption
- mapGenerateConfigToResources with custom memory
- mapGenerateConfigToRenderConfig with existingMemories parameter
  (dedup logic, hasMemory from existing, combining existing + new)
- mapExistingMemoriesToProviders (CUSTOM, empty strategies, multiple)

Also fix docs/configuration.md missing EPISODIC strategy row.

Constraint: CUSTOM strategy has no default namespaces or reflectionNamespaces
Constraint: Dedup operates on provider name, not strategy type
Confidence: high
Scope-risk: narrow

* style: fix prettier formatting in docs and source files

Author: aidandaly24

docs/commands.md

@@ -225,12 +225,12 @@ agentcore add memory \
   --expiry 30
 ```
 
-| Flag                   | Description                                                                 |
-| ---------------------- | --------------------------------------------------------------------------- |
-| `--name <name>`        | Memory name                                                                 |
-| `--strategies <types>` | Comma-separated: `SEMANTIC`, `SUMMARIZATION`, `USER_PREFERENCE`, `EPISODIC` |
-| `--expiry <days>`      | Event expiry duration in days (default: 30, min: 7, max: 365)               |
-| `--json`               | JSON output                                                                 |
+| Flag                   | Description                                                                           |
+| ---------------------- | ------------------------------------------------------------------------------------- |
+| `--name <name>`        | Memory name                                                                           |
+| `--strategies <types>` | Comma-separated: `SEMANTIC`, `SUMMARIZATION`, `USER_PREFERENCE`, `EPISODIC`, `CUSTOM` |
+| `--expiry <days>`      | Event expiry duration in days (default: 30, min: 7, max: 365)                         |
+| `--json`               | JSON output                                                                           |
 
 ### add gateway
 

docs/configuration.md

@@ -239,11 +239,13 @@ on the next deployment.
 
 ### Memory Strategies
 
-| Strategy          | Description                                         |
-| ----------------- | --------------------------------------------------- |
-| `SEMANTIC`        | Vector-based similarity search for relevant context |
-| `SUMMARIZATION`   | Compressed conversation history                     |
-| `USER_PREFERENCE` | Store user-specific preferences and settings        |
+| Strategy          | Description                                                 |
+| ----------------- | ----------------------------------------------------------- |
+| `SEMANTIC`        | Vector-based similarity search for relevant context         |
+| `SUMMARIZATION`   | Compressed conversation history                             |
+| `USER_PREFERENCE` | Store user-specific preferences and settings                |
+| `EPISODIC`        | Capture and reflect on meaningful interaction episodes      |
+| `CUSTOM`          | Self-managed strategy with user-controlled extraction logic |
 
 Strategy configuration:
 

docs/memory.md

@@ -168,12 +168,13 @@ conversations, enabling cross-session recall via semantic search.
 
 ## Memory Strategies
 
-| Strategy          | Description                                            |
-| ----------------- | ------------------------------------------------------ |
-| `SEMANTIC`        | Vector-based similarity search for relevant context    |
-| `SUMMARIZATION`   | Compressed conversation history                        |
-| `USER_PREFERENCE` | Store user-specific preferences and settings           |
-| `EPISODIC`        | Capture and reflect on meaningful interaction episodes |
+| Strategy          | Description                                                 |
+| ----------------- | ----------------------------------------------------------- |
+| `SEMANTIC`        | Vector-based similarity search for relevant context         |
+| `SUMMARIZATION`   | Compressed conversation history                             |
+| `USER_PREFERENCE` | Store user-specific preferences and settings                |
+| `EPISODIC`        | Capture and reflect on meaningful interaction episodes      |
+| `CUSTOM`          | Self-managed strategy with user-controlled extraction logic |
 
 You can combine multiple strategies:
 
@@ -188,6 +189,36 @@ You can combine multiple strategies:
 }
 ```
 
+### Self-Managed (Custom) Strategy
+
+The `CUSTOM` strategy lets you control memory extraction logic externally rather than relying on built-in
+implementations. This is useful when you need specialized extraction pipelines or want to integrate with your own
+processing infrastructure.
+
+**Prerequisites:** CUSTOM strategies require user-managed extraction logic and are not functional without it. You must
+implement your own extraction mechanism (e.g., via AWS Lambda).
+
+**Key characteristics:**
+
+- No default namespaces are assigned — you provide your own or omit them
+- Each memory supports at most one CUSTOM strategy
+- You are responsible for implementing the extraction logic that processes memory events
+
+```json
+{
+  "type": "AgentCoreMemory",
+  "name": "MyMemory",
+  "eventExpiryDuration": 30,
+  "strategies": [
+    {
+      "type": "CUSTOM",
+      "name": "my_custom_strategy",
+      "description": "Custom extraction logic"
+    }
+  ]
+}
+```
+
 ### Strategy Options
 
 Each strategy can have optional configuration:

src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -1702,6 +1702,11 @@ def get_memory_session_manager(session_id: str, actor_id: str) -> Optional[Agent
 {{/if}}
 {{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
         f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "CUSTOM")}}
+        # TODO: Add your custom namespace and retrieval config.
+        # Custom strategies use user-controlled extraction logic.
+        # Example: f"/custom/{actor_id}/data": RetrievalConfig(top_k=3, relevance_score=0.5),
 {{/if}}
     }
 {{/if}}
@@ -3987,6 +3992,11 @@ def get_memory_session_manager(session_id: str, actor_id: str) -> Optional[Agent
 {{/if}}
 {{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
         f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "CUSTOM")}}
+        # TODO: Add your custom namespace and retrieval config.
+        # Custom strategies use user-controlled extraction logic.
+        # Example: f"/custom/{actor_id}/data": RetrievalConfig(top_k=3, relevance_score=0.5),
 {{/if}}
     }
 {{/if}}
@@ -4331,7 +4341,7 @@ file maps to a JSON config file and includes validation constraints as comments.
 - **BuildType**: \`'CodeZip'\` | \`'Container'\`
 - **NetworkMode**: \`'PUBLIC'\`
 - **RuntimeVersion**: \`'PYTHON_3_10'\` | \`'PYTHON_3_11'\` | \`'PYTHON_3_12'\` | \`'PYTHON_3_13'\`
-- **MemoryStrategyType**: \`'SEMANTIC'\` | \`'SUMMARIZATION'\` | \`'USER_PREFERENCE'\` | \`'EPISODIC'\`
+- **MemoryStrategyType**: \`'SEMANTIC'\` | \`'SUMMARIZATION'\` | \`'USER_PREFERENCE'\` | \`'EPISODIC'\` | \`'CUSTOM'\`
 
 ### Build Types
 

src/assets/agents/AGENTS.md

@@ -63,7 +63,7 @@ file maps to a JSON config file and includes validation constraints as comments.
 - **BuildType**: `'CodeZip'` | `'Container'`
 - **NetworkMode**: `'PUBLIC'`
 - **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'`
-- **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'` | `'EPISODIC'`
+- **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'` | `'EPISODIC'` | `'CUSTOM'`
 
 ### Build Types
 

src/assets/python/a2a/strands/capabilities/memory/session.py

@@ -21,6 +21,11 @@ def get_memory_session_manager(session_id: str, actor_id: str) -> Optional[Agent
 {{/if}}
 {{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
         f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "CUSTOM")}}
+        # TODO: Add your custom namespace and retrieval config.
+        # Custom strategies use user-controlled extraction logic.
+        # Example: f"/custom/{actor_id}/data": RetrievalConfig(top_k=3, relevance_score=0.5),
 {{/if}}
     }
 {{/if}}

src/assets/python/http/strands/capabilities/memory/session.py

@@ -21,6 +21,11 @@ def get_memory_session_manager(session_id: str, actor_id: str) -> Optional[Agent
 {{/if}}
 {{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
         f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "CUSTOM")}}
+        # TODO: Add your custom namespace and retrieval config.
+        # Custom strategies use user-controlled extraction logic.
+        # Example: f"/custom/{actor_id}/data": RetrievalConfig(top_k=3, relevance_score=0.5),
 {{/if}}
     }
 {{/if}}

src/cli/commands/add/__tests__/add-memory.test.ts

@@ -51,16 +51,17 @@ describe('add memory command', () => {
       expect(json.error.includes('INVALID'), `Error: ${json.error}`).toBeTruthy();
     });
 
-    // Issue #235: CUSTOM strategy has been removed
-    it('rejects CUSTOM strategy', async () => {
+    // Issue #677: CUSTOM strategy is now supported
+    it('creates memory with CUSTOM strategy', async () => {
+      const memoryName = `memCustom${Date.now()}`;
       const result = await runCLI(
-        ['add', 'memory', '--name', 'testCustom', '--strategies', 'CUSTOM', '--json'],
+        ['add', 'memory', '--name', memoryName, '--strategies', 'CUSTOM', '--json'],
         projectDir
       );
-      expect(result.exitCode).toBe(1);
+      expect(result.exitCode, `stdout: ${result.stdout}, stderr: ${result.stderr}`).toBe(0);
       const json = JSON.parse(result.stdout);
-      expect(json.success).toBe(false);
-      expect(json.error.includes('CUSTOM'), `Error: ${json.error}`).toBeTruthy();
+      expect(json.success).toBe(true);
+      expect(json.memoryName).toBe(memoryName);
     });
   });
 

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

@@ -953,17 +953,15 @@ describe('validate', () => {
       ).toEqual({ valid: true });
     });
 
-    // AC23: CUSTOM strategy is not supported (Issue #235)
-    it('rejects CUSTOM strategy', () => {
+    // Issue #677: CUSTOM strategy is now supported
+    it('accepts CUSTOM strategy', () => {
       const result = validateAddMemoryOptions({ ...validMemoryOptions, strategies: 'CUSTOM' });
-      expect(result.valid).toBe(false);
-      expect(result.error).toContain('Invalid strategy: CUSTOM');
+      expect(result.valid).toBe(true);
     });
 
-    it('rejects CUSTOM even when mixed with valid strategies', () => {
+    it('accepts CUSTOM mixed with other strategies', () => {
       const result = validateAddMemoryOptions({ ...validMemoryOptions, strategies: 'SEMANTIC,CUSTOM' });
-      expect(result.valid).toBe(false);
-      expect(result.error).toContain('Invalid strategy: CUSTOM');
+      expect(result.valid).toBe(true);
     });
 
     // AC24: Each individual valid strategy should pass

src/cli/commands/add/validate.ts

@@ -4,6 +4,7 @@ import {
   BuildTypeSchema,
   GatewayExceptionLevelSchema,
   GatewayNameSchema,
+  MemoryStrategyTypeSchema,
   ModelProviderSchema,
   ProtocolModeSchema,
   RuntimeAuthorizerTypeSchema,
@@ -33,8 +34,8 @@ export interface ValidationResult {
 }
 
 // Constants
-const MEMORY_OPTIONS = ['none', 'shortTerm', 'longAndShortTerm'] as const;
-const VALID_STRATEGIES = ['SEMANTIC', 'SUMMARIZATION', 'USER_PREFERENCE', 'EPISODIC'];
+const MEMORY_OPTIONS = ['none', 'shortTerm', 'longAndShortTerm', 'custom'] as const;
+const VALID_STRATEGIES: readonly string[] = MemoryStrategyTypeSchema.options;
 
 /**
  * Validate that a credential name exists in the project spec.
@@ -134,7 +135,7 @@ export function validateAddAgentOptions(options: AddAgentOptions): ValidationRes
     if (!MEMORY_OPTIONS.includes(options.memory as (typeof MEMORY_OPTIONS)[number])) {
       return {
         valid: false,
-        error: `Invalid memory option: ${options.memory}. Use none, shortTerm, or longAndShortTerm`,
+        error: `Invalid memory option: ${options.memory}. Use none, shortTerm, longAndShortTerm, or custom`,
       };
     }
     // Parse and validate lifecycle configuration for import path
@@ -242,7 +243,7 @@ export function validateAddAgentOptions(options: AddAgentOptions): ValidationRes
     if (!MEMORY_OPTIONS.includes(options.memory as (typeof MEMORY_OPTIONS)[number])) {
       return {
         valid: false,
-        error: `Invalid memory option: ${options.memory}. Use none, shortTerm, or longAndShortTerm`,
+        error: `Invalid memory option: ${options.memory}. Use none, shortTerm, longAndShortTerm, or custom`,
       };
     }
   }