Skip to main content
Microsoft Foundry
Start building
View as Markdown
View as Markdown
Memory Stores

Search memories

POST
/memory_stores/{name}:search_memories

Searches the specified memory store for memories relevant to the provided conversation context.

Path Parameters
namestringrequired
The name of the memory store to search.
Query Parameters
api-versionstringrequired
The API version to use for this operation.
Header Parameters
Foundry-Featuresstringrequired
A feature flag opt-in required when using preview operations or modifying persisted preview resources.
MemoryStores=V1Preview
Request BodyContent-Type: application/json
scopestringrequired
The namespace that logically groups and isolates memories, such as a user ID.
items(message | item_reference | output_message | file_search_call | computer_call | computer_call_output | web_search_call | function_call | function_call_output | tool_search_call | tool_search_output | additional_tools | reasoning | compaction | image_generation_call | code_interpreter_call | local_shell_call | local_shell_call_output | shell_call | shell_call_output | apply_patch_call | apply_patch_call_output | mcp_list_tools | mcp_approval_request | mcp_approval_response | mcp_call | custom_tool_call_output | custom_tool_call)[]
Items for which to search for relevant memories.
One of the following:
messageOpenAI.EasyInputMessage
A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.
item_referenceOpenAI.ItemReferenceParam
An internal identifier for an item to reference.
output_messageOpenAI.InputItemOutputMessage
An output message from the model.
file_search_callOpenAI.InputItemFileSearchToolCall
The results of a file search tool call. See the file search guide for more information.
computer_callOpenAI.InputItemComputerToolCall
A tool call to a computer use tool. See the computer use guide for more information.
computer_call_outputOpenAI.InputItemComputerCallOutputItemParam
The output of a computer tool call.
web_search_callOpenAI.InputItemWebSearchToolCall
The results of a web search tool call. See the web search guide for more information.
function_callOpenAI.InputItemFunctionToolCall
A tool call to run a function. See the function calling guide for more information.
function_call_outputOpenAI.InputItemFunctionCallOutputItemParam
The output of a function tool call.
tool_search_callOpenAI.InputItemToolSearchCallItemParam
An item representing part of the context for the response to be generated by the model. Can contain text, images, and audio inputs, as well as previous assistant responses and tool call outputs.
tool_search_outputOpenAI.InputItemToolSearchOutputItemParam
An item representing part of the context for the response to be generated by the model. Can contain text, images, and audio inputs, as well as previous assistant responses and tool call outputs.
additional_toolsOpenAI.InputItemAdditionalToolsItemParam
An item representing part of the context for the response to be generated by the model. Can contain text, images, and audio inputs, as well as previous assistant responses and tool call outputs.
reasoningOpenAI.InputItemReasoningItem
A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.
compactionOpenAI.InputItemCompactionSummaryItemParam
A compaction item generated by the v1/responses/compact API.
image_generation_callOpenAI.InputItemImageGenToolCall
An image generation request made by the model.
code_interpreter_callOpenAI.InputItemCodeInterpreterToolCall
A tool call to run code.
local_shell_callOpenAI.InputItemLocalShellToolCall
A tool call to run a command on the local shell.
local_shell_call_outputOpenAI.InputItemLocalShellToolCallOutput
The output of a local shell tool call.
shell_callOpenAI.InputItemFunctionShellCallItemParam
A tool representing a request to execute one or more shell commands.
shell_call_outputOpenAI.InputItemFunctionShellCallOutputItemParam
The streamed output items emitted by a shell tool call.
apply_patch_callOpenAI.InputItemApplyPatchToolCallItemParam
A tool call representing a request to create, delete, or update files using diff patches.
apply_patch_call_outputOpenAI.InputItemApplyPatchToolCallOutputItemParam
The streamed output emitted by an apply patch tool call.
mcp_list_toolsOpenAI.InputItemMcpListTools
A list of tools available on an MCP server.
mcp_approval_requestOpenAI.InputItemMcpApprovalRequest
A request for human approval of a tool invocation.
mcp_approval_responseOpenAI.InputItemMcpApprovalResponse
A response to an MCP approval request.
mcp_callOpenAI.InputItemMcpToolCall
An invocation of a tool on an MCP server.
custom_tool_call_outputOpenAI.InputItemCustomToolCallOutput
The output of a custom tool call from your code, being sent back to the model.
custom_tool_callOpenAI.InputItemCustomToolCall
A call to a custom tool created by the model.
previous_search_idstring
The unique ID of the previous search request, enabling incremental memory search from where the last operation left off.
optionsMemorySearchOptions
Memory search options.
max_memoriesinteger
Maximum number of memory items to return.
Responses
search_idstringrequired
The unique ID of this search request. Use this value as previous_search_id in subsequent requests to perform incremental searches.
memoriesMemorySearchItem[]required
Related memory items found during the search operation.
memory_itemuser_profile | chat_summary | proceduralrequired
Retrieved memory item.
usageMemoryStoreOperationUsagerequired
Usage statistics associated with the memory search operation.
embedding_tokensintegerrequired
The number of embedding tokens.
input_tokensintegerrequired
The number of input tokens.
input_tokens_detailsOpenAI.ResponseUsageInputTokensDetailsrequired
A detailed breakdown of the input tokens.
output_tokensintegerrequired
The number of output tokens.
output_tokens_detailsOpenAI.ResponseUsageOutputTokensDetailsrequired
A detailed breakdown of the output tokens.
total_tokensintegerrequired
The total number of tokens used.