chore: update namespace design for data plane

[nborges-aws]

Description

Adds support for the new namespacePath data-plane field introduced by the memory namespace redesign. namespacePath is a hierarchical path-prefix filter that sits alongside the existing namespace field on ListMemoryRecords and RetrieveMemoryRecords. The existing namespace field will migrate to function as exact-match.

Replaced required namespace with unions for the option types. Forcing callers to supply exactly one of namespace / namespacePath at compile-time. Defensive runtime validation is kept for paths that bypass the type system (JSON body from web UI requests).

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe): New field added to DP methods, existing method logic changed

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published -- SDK DP PR must be merged first

---

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

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	43.37%	9077 / 20927
🔵	Statements	42.63%	9632 / 22594
🔵	Functions	39.92%	1553 / 3890
🔵	Branches	40.09%	5840 / 14565

Generated in workflow #2394 for commit 3f47058 by the Vitest Coverage Report Action

[agentcore-cli-automation]

Blocker: generated Python agent code will fail at runtime — bedrock-agentcore Python SDK does not accept namespace_path=.

In src/cli/operations/agent/import/langgraph-translator.ts and src/cli/operations/agent/import/strands-translator.ts, the emitted code calls:

memory_client.retrieve_memories(memory_id=memory_id, namespace_path=f'/users/{user_id}/facts', ...)

But the memory_client.retrieve_memories method in the high‑level Python bedrock-agentcore package (which is what's pinned via bedrock-agentcore[memory] >= 1.0.3 in pyproject-generator.ts) only accepts a namespace keyword — I checked every published release up to and including the current latest (1.8.0) and none define a namespace_path parameter:

# bedrock_agentcore/memory/client.py @ 1.8.0
def retrieve_memories(
    self, memory_id: str, namespace: str, query: str, actor_id: Optional[str] = None, top_k: int = 3
):

So every agent generated with memoryOption: 'longAndShortTerm' will raise TypeError: retrieve_memories() got an unexpected keyword argument 'namespace_path' on the first retrieval call. The two new translator tests pass because they only assert the string contents of the generated file — they never exercise the Python.

This is distinct from the raw data‑plane SDK (@aws-sdk/client-bedrock-agentcore), which does take namespacePath at the wire level — that part of the PR looks fine. The issue is specifically the high‑level Python helper the generated agents import.

Options:

1. Hold this PR's translator changes until the Python bedrock-agentcore SDK ships namespace_path support on retrieve_memories, then bump the minimum pinned version in pyproject-generator.ts (MEMORY_DEPS / BASE_DEPS) to that release.
2. Split the PR: land the data‑plane (listMemoryRecords / retrieveMemoryRecords / web‑ui handler) changes now, and revert the translator changes in langgraph-translator.ts + strands-translator.ts until the Python SDK supports it.
3. If the intent is for generated agents to call the low-level boto3 bedrock-agentcore client directly (which does support namespacePath), rewrite the emitted retrieval code to use boto3 instead of memory_client.retrieve_memories.

[agentcore-cli-automation]

Public web-UI API types are not updated — frontend can't send namespacePath.

The server handler in src/cli/operations/dev/web-ui/handlers/memory.ts now accepts and validates namespacePath, but the request types exported to the frontend in src/cli/operations/dev/web-ui/api-types.ts still declare namespace as required and have no namespacePath field:

// api-types.ts (unchanged by this PR)
// GET /api/memory?memoryName=xxx&namespace=yyy[&strategyId=zzz]   <-- comment still documents old shape
...
/** Request body for POST /api/memory/search */
export interface RetrieveMemoryRecordsRequest {
  memoryName: string;
  namespace: string;        // <-- still required, no `namespacePath` option
  searchQuery: string;
  strategyId?: string;
}

These types are exported from the package specifically so the frontend (@aws/agent-inspector) can consume them — see src/cli/operations/dev/web-ui/README.md ("Types are defined in api-types.ts and exported from the package so the frontend can import them"). As-is:

• A TS‑consuming frontend cannot put namespacePath on the request body without a cast, and the new server‑side mutual‑exclusion branch is effectively unreachable from typed callers.
• The README block for GET /api/memory and POST /api/memory/search (lines ~212–230) still documents only namespace.

Please also update api-types.ts (convert RetrieveMemoryRecordsRequest to the same discriminated‑union shape you used in web-server.ts, and fix the leading comment above the GET /api/memory section) and the README documentation for both endpoints to reflect the new namespacePath option.

[nborges-aws]

Blocker: generated Python agent code will fail at runtime — bedrock-agentcore Python SDK does not accept namespace_path=.

In src/cli/operations/agent/import/langgraph-translator.ts and src/cli/operations/agent/import/strands-translator.ts, the emitted code calls:

memory_client.retrieve_memories(memory_id=memory_id, namespace_path=f'/users/{user_id}/facts', ...)

But the memory_client.retrieve_memories method in the high‑level Python bedrock-agentcore package (which is what's pinned via bedrock-agentcore[memory] >= 1.0.3 in pyproject-generator.ts) only accepts a namespace keyword — I checked every published release up to and including the current latest (1.8.0) and none define a namespace_path parameter:

# bedrock_agentcore/memory/client.py @ 1.8.0
def retrieve_memories(
    self, memory_id: str, namespace: str, query: str, actor_id: Optional[str] = None, top_k: int = 3
):

So every agent generated with memoryOption: 'longAndShortTerm' will raise TypeError: retrieve_memories() got an unexpected keyword argument 'namespace_path' on the first retrieval call. The two new translator tests pass because they only assert the string contents of the generated file — they never exercise the Python.

This is distinct from the raw data‑plane SDK (@aws-sdk/client-bedrock-agentcore), which does take namespacePath at the wire level — that part of the PR looks fine. The issue is specifically the high‑level Python helper the generated agents import.

Options:

1. Hold this PR's translator changes until the Python bedrock-agentcore SDK ships namespace_path support on retrieve_memories, then bump the minimum pinned version in pyproject-generator.ts (MEMORY_DEPS / BASE_DEPS) to that release.
2. Split the PR: land the data‑plane (listMemoryRecords / retrieveMemoryRecords / web‑ui handler) changes now, and revert the translator changes in langgraph-translator.ts + strands-translator.ts until the Python SDK supports it.
3. If the intent is for generated agents to call the low-level boto3 bedrock-agentcore client directly (which does support namespacePath), rewrite the emitted retrieval code to use boto3 instead of memory_client.retrieve_memories.

This is expected. The following PR adds the missing field in the SDK: aws/bedrock-agentcore-sdk-python#449