Skip to content

feat: add EPISODIC memory strategy support#651

Merged
tejaskash merged 15 commits intomainfrom
episodic-memory-strategy
Mar 26, 2026
Merged

feat: add EPISODIC memory strategy support#651
tejaskash merged 15 commits intomainfrom
episodic-memory-strategy

Conversation

@tejaskash
Copy link
Copy Markdown
Contributor

@tejaskash tejaskash commented Mar 25, 2026

Summary

  • Adds EPISODIC as a new memory strategy type across the CLI: schema, primitives, TUI, templates, and docs
  • EPISODIC strategy requires reflectionNamespaces (service requirement); enforced via Zod schema refinement
  • Default namespaces and reflectionNamespaces are auto-populated for EPISODIC when creating memories via TUI or CLI flags
  • longAndShortTerm memory preset now includes all 4 strategies (SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC)

Depends on CDK PR: https://github.com/aws/agentcore-l3-cdk-constructs/pull/108

TUI Walkthrough

1. Select "Add" from the main menu

Help Screen

2. Choose "Memory" resource

Add Resource

3. Enter memory name

Memory Name

4. Strategy picker now shows EPISODIC

Strategies Picker

5. All 4 strategies selected including EPISODIC

All Strategies Selected

6. Review screen confirms EPISODIC

Confirm Screen

7. Memory created successfully

Success Screen

8. Resulting agentcore.json

EPISODIC strategy is persisted with both namespaces and reflectionNamespaces:

{
  "type": "EPISODIC",
  "namespaces": ["/episodes/{actorId}/{sessionId}"],
  "reflectionNamespaces": ["/reflections/{actorId}"]
}

Test plan

  • Unit tests: Zod refinement tests (accepts/rejects EPISODIC with/without reflectionNamespaces)
  • Unit tests: create command verifies EPISODIC in longAndShortTerm preset
  • Integration tests: add memory --strategies EPISODIC verifies reflectionNamespaces in config
  • Integration tests: create-memory longAndShortTerm verifies all 4 strategies
  • TUI integration test: full Add Memory wizard flow selecting EPISODIC
  • E2E test: strands-bedrock-memory deploys with longAndShortTerm (includes EPISODIC)
  • TUI screenshots captured showing the full EPISODIC selection flow

@tejaskash tejaskash requested a review from a team March 25, 2026 19:34
@github-actions github-actions bot added size/m PR size: M size/l PR size: L and removed size/m PR size: M labels Mar 25, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 25, 2026

Coverage Report

Status Category Percentage Covered / Total
🔵 Lines 45.69% 6445 / 14105
🔵 Statements 45.25% 6840 / 15113
🔵 Functions 44.54% 1159 / 2602
🔵 Branches 45.63% 4208 / 9220
Generated in workflow #1387 for commit cc45775 by the Vitest Coverage Report Action

Hweinstock and others added 10 commits March 26, 2026 14:41
Add EPISODIC as a new memory strategy type across the CLI:
- Schema enum with default episode namespace (/strategy/{memoryStrategyId}/actor/{actorId}/)
- Default reflection namespaces for episodic (required by the service)
- reflectionNamespaces field on MemoryStrategy schema
- CLI validation, help text, and TUI descriptions
- longAndShortTerm preset now includes EPISODIC
- LLM-compacted schema and AGENTS.md docs
- Unit and integration tests
Add Zod refinement to MemoryStrategySchema that requires
reflectionNamespaces when strategy type is EPISODIC, matching the
AWS service requirement. Update docs/commands.md and docs/memory.md
to document the EPISODIC strategy and reflectionNamespaces field.
- Add strands-bedrock-memory E2E test that deploys with longAndShortTerm
  memory (includes all 4 strategies including EPISODIC)
- Extend e2e-helper to support configurable memory option
- Strengthen integ create-memory test to verify EPISODIC strategy is
  present with reflectionNamespaces in longAndShortTerm preset
- create.test.ts: verify EPISODIC with namespaces and reflectionNamespaces
  in longAndShortTerm preset
- add-remove-resources integ: verify `add memory --strategies EPISODIC`
  persists reflectionNamespaces in agentcore.json
- TUI test: drive Add Memory wizard through strategy multi-select,
  verify EPISODIC is persisted with correct config in agentcore.json
@github-actions github-actions bot added size/l PR size: L and removed size/l PR size: L labels Mar 26, 2026
@jesseturner21
Copy link
Copy Markdown
Contributor

lol i like the screenshots but we should remove them from docs/

Copy link
Copy Markdown
Contributor

@notgitika notgitika left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. docs/memory.md says reflectionNamespaces "must be a prefix of namespaces" but the code doesn't enforce this and the defaults don't satisfy it — Blocking. Users will follow the doc and get confused, or the service will reject configs that follow the doc's defaults.
  2. Schema validation mismatch between CLI and CDK — CLI requires reflectionNamespaces for EPISODIC via Zod refinement; CDK allows EPISODIC without it and even has a test asserting that path works. Non-blocking but worth a comment — if someone bypasses the CLI, CDK will happily synth invalid CloudFormation.
  3. Unrelated commits in PR #651 (evaluator tests, OIDC constant removal, readProjectConfig retype) — Non-blocking, but repo convention says keep PRs focused.

LGTM otherwise

@github-actions github-actions bot removed the size/l PR size: L label Mar 26, 2026
@github-actions github-actions bot added the size/l PR size: L label Mar 26, 2026
@tejaskash
Copy link
Copy Markdown
Contributor Author

Thanks for the review! Addressing each point:

  1. reflectionNamespaces prefix claim (blocking) — Fixed in 777e402. The doc incorrectly stated reflectionNamespaces "must be a prefix of namespaces." That's not a service requirement — removed that claim. The defaults (/episodes/{actorId}/{sessionId} and /reflections/{actorId}) are correct per the service docs.

  2. CLI/CDK schema mismatch — Good catch. The CDK is intentionally more permissive since it's a lower-level construct — users bypassing the CLI take on responsibility for valid configs. But agree it's worth noting. Will add a comment in the CDK code.

  3. Unrelated commits — The evaluator test and OIDC constant changes came from rebase conflict resolution against main. The evaluator test was an add/add conflict (accepted theirs), and the OIDC constant was introduced by main then flagged as unused by the code quality bot. Happy to squash these on merge if preferred.

@github-actions github-actions bot added size/l PR size: L and removed size/l PR size: L labels Mar 26, 2026
@github-actions github-actions bot added size/m PR size: M and removed size/l PR size: L labels Mar 26, 2026
@tejaskash
Copy link
Copy Markdown
Contributor Author

Done — removed the episodic-memory screenshots from docs/ in 3ad72ed (kept the existing advanced-gate ones).

- Default reflectionNamespaces changed from /reflections/{actorId} to
  /episodes/{actorId} so it's a proper prefix of the episode namespace
- Added Zod refinement to validate that each reflectionNamespace is a
  prefix of at least one namespace
- Restored doc claim that reflectionNamespaces must be a prefix of namespaces
- Added tests for prefix validation (accept valid, reject invalid)
@tejaskash
Copy link
Copy Markdown
Contributor Author

Correction on point 1 — the prefix requirement IS correct per the AWS docs. Fixed properly in cc45775:

  • Changed default reflectionNamespaces from /reflections/{actorId} to /episodes/{actorId} (a proper prefix of /episodes/{actorId}/{sessionId})
  • Added a Zod refinement that validates each reflectionNamespace is a prefix of at least one namespace
  • Restored the doc claim
  • Added tests for the prefix validation (accepts valid prefixes, rejects non-prefixes)

@github-actions github-actions bot added size/l PR size: L and removed size/m PR size: M labels Mar 26, 2026
Copy link
Copy Markdown
Contributor

@jesseturner21 jesseturner21 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@notgitika notgitika self-requested a review March 26, 2026 21:24
Copy link
Copy Markdown
Contributor

@notgitika notgitika left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@tejaskash tejaskash merged commit 247de18 into main Mar 26, 2026
19 of 21 checks passed
@tejaskash tejaskash deleted the episodic-memory-strategy branch March 26, 2026 21:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/l PR size: L

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants