DOC-API-MODEL-schema-1g8iadjcu1#overview
MemoryConfig
Configuration for searching, injecting and storing semantic memories during generation. Configure memory integration in the mem0 block of the conversation defaultGenerationConfig or in a per-turn overrideGenerationConfig.
Enabled integration provides retrieval and asynchronous extraction. Retrieved context is added to the latest user message despite the injectAsSystemContext name. addMemoriesAsync is ignored: extraction runs after the run, without an option to delay the send response until extraction completes.
Reranking and graph relationships require deployment support; their flags do not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect. Use search-memories from the application or enable automatic retrieval with mem0.enabled; the flag alone does not give the model a new tool.
When memory is enabled, search_top_k selects 1–50 results; search_threshold selects a relevance score from 0.0 to 1.0. The generation retrieval limit bounds injected context; the separate user-facing memory-search operation allows up to 100 results.
custom_extraction_prompt selects a custom extraction prompt when nonempty; otherwise the default prompt is used. agent_id_override changes the conversation-based memory scope so memories can be shared across conversations. include_assistant_messages controls assistant/agent-scoped memories and defaults to false. inject_memory_timestamps defaults to true and includes remembered and, when available, updated dates.
Type-reference view: API Schema 9frhv4euve, API Schema 9ftjkkjhfa. Request and response views describe this type; they do not declare an endpoint.
Meaning and usage
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-enabledenabled | boolean | Optional | Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-searchtopksearchTopK | string (int64) | Optional | See meaning below. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-searchthresholdsearchThreshold | number (double) or string (NaN, Infinity, -Infinity) | Optional | Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-injectassystemcontextinjectAsSystemContext | boolean | Optional | When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-searchqueryoverridesearchQueryOverride | string | Optional | Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-enablererankenableRerank | boolean | Optional | Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-addmemoriesasyncaddMemoriesAsync | boolean | Optional | This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-customextractionpromptcustomExtractionPrompt | string | Optional | Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-enablegraphenableGraph | boolean | Optional | Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-agentidoverrideagentIdOverride | string | Optional | Override the agent_id used for memory scoping. By default, the conversation_id is used as the agent_id. Use this to share memories across multiple conversations. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-exposeasmcptoolexposeAsMcpTool | boolean | Optional | This flag is currently ignored. It does not expose memory search as a model tool. Default: false. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-includeassistantmessagesincludeAssistantMessages | boolean | Optional | Include assistant/agent-scoped memories in operations. When false, skips agent_id for both add and search operations, keeping only user-scoped memories. Default: false |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-field-injectmemorytimestampsinjectMemoryTimestamps | boolean | Optional | Include created_at/updated_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: <date>)" annotation and optionally "(updated: <date>)" if the memory was modified after creation. Default: true |
searchTopK
Number of memories to retrieve during search. Higher values provide more context but increase token usage.
The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results.
Range: 1–50 when memory is enabled.
Request validation
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#request-validation
These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.
| Applies to | Rule | Requirement |
|---|---|---|
| Message | native.gate.enabled | search_top_k and search_threshold must be valid when enabled is true |
In responses
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-enabledSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-enabledenabled | boolean | Optional | Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-searchtopkSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-searchtopksearchTopK | string (int64) | Optional | See meaning below. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-searchthresholdSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-searchthresholdsearchThreshold | number (double) or string (NaN, Infinity, -Infinity) | Optional | Minimum relevance score threshold for memory search results. Memories below this threshold are filtered out. Range: 0.0-1.0 (validated only when enabled = true) |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-injectassystemcontextSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-injectassystemcontextinjectAsSystemContext | boolean | Optional | When true, include retrieved memories in the per-turn volatile context attached to the current user message. Memories are formatted as a bullet list under a "[Relevant memories about this user:]" header. When false, retrieved memories are not included in the model context. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-searchqueryoverrideSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-searchqueryoverridesearchQueryOverride | string | Optional | Custom search query to use instead of the last user message. If empty, the last user message content is used as the search query. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-enablererankSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-enablererankenableRerank | boolean | Optional | Request reranking to improve search relevance. It may improve results and add latency, and requires deployment support. Default: false. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-addmemoriesasyncSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-addmemoriesasyncaddMemoriesAsync | boolean | Optional | This field is accepted but does not change extraction behavior. When memory integration is enabled, extraction runs asynchronously after generation, including when this value is false. It does not make the send response wait for extraction to complete. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-customextractionpromptSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-customextractionpromptcustomExtractionPrompt | string | Optional | Custom prompt for memory/fact extraction. If empty, the default extraction prompt is used. Use this to customize what types of facts are extracted. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-enablegraphSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-enablegraphenableGraph | boolean | Optional | Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-agentidoverrideSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-agentidoverrideagentIdOverride | string | Optional | Override the agent_id used for memory scoping. By default, the conversation_id is used as the agent_id. Use this to share memories across multiple conversations. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-exposeasmcptoolSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-exposeasmcptoolexposeAsMcpTool | boolean | Optional | This flag is currently ignored. It does not expose memory search as a model tool. Default: false. |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-includeassistantmessagesSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-includeassistantmessagesincludeAssistantMessages | boolean | Optional | Include assistant/agent-scoped memories in operations. When false, skips agent_id for both add and search operations, keeping only user-scoped memories. Default: false |
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#field-injectmemorytimestampsSection ID: DOC-API-MODEL-schema-1g8iadjcu1#response-field-injectmemorytimestampsinjectMemoryTimestamps | boolean | Optional | Include created_at/updated_at timestamps on injected memories. When true, each memory bullet includes a "(remembered: <date>)" annotation and optionally "(updated: <date>)" if the memory was modified after creation. Default: true |
searchTopK
Number of memories to retrieve during search. Higher values provide more context but increase token usage.
The generation retrieval limit is 50 because retrieved memories can be included in the volatile context attached to the current turn’s user message. This is a token-budget guard rather than a hard limit of the memory store. The separate user-facing memory-search request allows up to 100 results.
Range: 1–50 when memory is enabled.
Section ID:DOC-API-MODEL-schema-1g8iadjcu1#validation
Request validation
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#response-validation
These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.
| Applies to | Rule | Requirement |
|---|---|---|
| Message | native.gate.enabled | search_top_k and search_threshold must be valid when enabled is true |
Where used
Section ID: DOC-API-MODEL-schema-1g8iadjcu1#where-used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| Get an agent profile | POST /api/v1/agent-profiles/get |
| Import a prompt library | POST /api/v1/agent-profiles/import |
| List agent profiles | POST /api/v1/agent-profiles/list |
| Update an agent profile | POST /api/v1/agent-profiles/update |
| Withdraw your rating on a message | POST /api/v1/llm/delete-message-rating |
| Get full conversation state | POST /api/v1/llm/conversation-state |
| Rate an assistant message | POST /api/v1/llm/rate-message |
| Send a message and wait for the result | POST /api/v1/llm/send-message-sync |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-sync |
| Update context management settings | POST /api/v1/llm/update-context-management-settings |
| Update default generation config | POST /api/v1/llm/update-default-generation-config |
| Get the caller's end-user profile | POST /api/v1/enduser/get |
| Append a message without generating | POST /api/v1/llm/append-message |
| Create a new conversation thread | POST /api/v1/llm/create-thread |
| Send a message to a conversation | POST /api/v1/llm/send-message |
| Update the caller's default generation config | POST /api/v1/enduser/update-generation-config |
| ReceiveMessageRequest | API JSON uses JSON field names (camelCase). |
| ClientToolDispatch | API JSON uses JSON field names (camelCase). |
Models containing this value
| Model | Relationship |
|---|---|
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-1g8iadjcu1