fix(memory): use namespacePath for hierarchical memory retrieval

[XinyuQu]

The orchestrator's loadMemoryContext was retrieving episodic records via namespace: '/{repo}/episodes/', which used to do prefix-match on the AgentCore Memory API. AWS changed namespace to exact-match and introduced a new namespacePath field for hierarchical (prefix) retrieval. Per-task episodes live one level below at /{repo}/episodes/{sessionId}/, so the previous call was about to silently return 0 records once the grace window for legacy behavior closes. Switching both reads in loadMemoryContext to namespacePath preserves the intended retrieval semantics.

Area

• cdk — infrastructure, handlers, constructs
• agent — Python runtime / Docker image
• cli — bgagent client
• docs — guides or design sources (docs/guides/, docs/design/)
• tooling — root mise.toml, scripts, CI workflows

Related

• AWS API reference for RetrieveMemoryRecords: https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_RetrieveMemoryRecords.html — documents both namespace (exact match) and namespacePath (hierarchical).
• AWS API reference for ListMemoryRecords: https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ListMemoryRecords.html — same shape change.
• AWS ML blog (May 2026), namespace design patterns under the new semantics: https://aws.amazon.com/blogs/machine-learning/organizing-agents-memory-at-scale-namespace-design-patterns-in-agentcore-memory/

Changes

cdk/src/handlers/shared/memory.ts — switched both RetrieveMemoryRecordsCommand calls in loadMemoryContext from namespace to namespacePath. Renamed the locals (semanticNamespacePath, episodicNamespacePath) and the audit log key (namespace → namespace_path) for accuracy.

cdk/test/handlers/shared/memory.test.ts — call-shape assertion now requires namespacePath and explicitly asserts namespace is not sent. Two hash-mismatch audit log assertions updated to match the renamed log key. Live API verification against bedrock-agentcore confirmed sending both fields raises ValidationException: API Request contains both 'namespace' and 'namespacePath' field for memory records retrieval, only one of the fields is allowed. — so single-field correctness matters.

cdk/package.json + yarn.lock — bumped @aws-sdk/client-bedrock-agentcore from ^3.1021.0 to ^3.1046.0 (resolved to 3.1047.0). The earlier pin was installing a build that predates the namespacePath request field.

docs/design/MEMORY.md (and regenerated Starlight mirror under docs/src/content/docs/architecture/Memory.md) — added a one-sentence note that hierarchical reads use namespacePath, with a link to the AWS API reference.

No CDK construct changes were needed. The @aws-cdk/aws-bedrock-agentcore-alpha construct still uses the legacy namespaces field on its strategy props; the AgentCore Control API accepts both namespaces (deprecated) and namespaceTemplates (current) and dual-emits them on read. Existing memory resources keep working unchanged.

Test plan

• CDK mise //cdk:build — compile, lint, 1243/1243 tests, synth, all clean
• Agent mise //agent:quality — 527/527 pytest pass
• Docs mise //docs:build — Astro/Starlight site build clean; mirrors regenerated and committed
• Full monorepo mise run build (matching CI's build.yml env) — exit 0, 0 self-mutations (CI's most common gate)
• mise run security:secrets (gitleaks) — no leaks
• mise run security:sast (semgrep) — clean
• mise run security:deps (osv-scanner) — only the pre-existing high-sev devalue@5.6.4 finding from main; Dependabot PR chore(deps): bump devalue from 5.6.4 to 5.8.1 #94 already in flight to fix it
• Live API verification against AgentCore Memory in dev account us-east-1:
  • RetrieveMemoryRecords with namespacePath only → HTTP 200
  • RetrieveMemoryRecords with namespace only → HTTP 200 (account is on the existing-customer grace allow-list)
  • RetrieveMemoryRecords with both fields → ValidationException (matches docs; confirms the migrated single-field call is correctly shaped)
  • ListMemoryRecords with namespacePath → HTTP 200
  • Test events written during verification were cleaned up afterward

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[scottschreckengaust]

LGTM