MemoryConfig
Configuration for searching, injecting and storing semantic memories during generation.
Memory integration is configured in the mem0 block of a thread's defaultGenerationConfig
(set at thread creation or via update-default-generation-config) or per turn via
overrideGenerationConfig.
Enabled memory integration provides retrieval and asynchronous extraction. Despite the legacy injectAsSystemContext name, the current injection path adds retrieved context to the latest user message. addMemoriesAsync is ignored: extraction runs after the run, with no send-response option to wait for it.
Reranking and graph relationships require deployment support; setting their flags does not establish that support or a complete relationship-removal procedure. exposeAsMcpTool has no effect.
exposeAsMcpTool currently has no effect. Use search-memories from your application or enable automatic retrieval with mem0.enabled; setting this flag alone does not give the model a new tool.
Usage profiles
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
| In webhook payloads | View fields |
In requests
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
enabled | boolean | Optional | Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. |
searchTopK | integer (int32) | Optional | Number of memories to retrieve during search. Higher values provide more context but increase token usage. Range: 1-50 (validated only when enabled = true) Default: 5 Minimum: -2147483648. Maximum: 2147483647. |
searchThreshold | 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) Default: 0.3 |
injectAsSystemContext | boolean | Optional | When true, inject found memories into the system prompt context. Memories are formatted as a bullet list under a "[Relevant memories:]" header. Default: true |
searchQueryOverride | 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. |
enableRerank | boolean | Optional | Enable reranking for improved search relevance. Reranking provides better results but adds latency. Default: false |
addMemoriesAsync | boolean | Optional | When true, memory extraction happens asynchronously after generation completes. This prevents extraction latency from affecting response time. Default: true |
customExtractionPrompt | 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. |
enableGraph | boolean | Optional | Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. |
agentIdOverride | 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. |
exposeAsMcpTool | boolean | Optional | Expose memory search as an MCP tool during generation. When true, the LLM can explicitly search memories via tool calls. Rate limited to 3 searches per generation turn. Default: false |
includeAssistantMessages | 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 |
injectMemoryTimestamps | 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 |
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 | mem0_config_valid_when_enabled | search_top_k and search_threshold must be valid when enabled is true |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
enabled | boolean | Optional | Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. |
searchTopK | integer (int32) | Optional | Number of memories to retrieve during search. Higher values provide more context but increase token usage. Range: 1-50 (validated only when enabled = true) Default: 5 Minimum: -2147483648. Maximum: 2147483647. |
searchThreshold | 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) Default: 0.3 |
injectAsSystemContext | boolean | Optional | When true, inject found memories into the system prompt context. Memories are formatted as a bullet list under a "[Relevant memories:]" header. Default: true |
searchQueryOverride | 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. |
enableRerank | boolean | Optional | Enable reranking for improved search relevance. Reranking provides better results but adds latency. Default: false |
addMemoriesAsync | boolean | Optional | When true, memory extraction happens asynchronously after generation completes. This prevents extraction latency from affecting response time. Default: true |
customExtractionPrompt | 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. |
enableGraph | boolean | Optional | Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. |
agentIdOverride | 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. |
exposeAsMcpTool | boolean | Optional | Expose memory search as an MCP tool during generation. When true, the LLM can explicitly search memories via tool calls. Rate limited to 3 searches per generation turn. Default: false |
includeAssistantMessages | 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 |
injectMemoryTimestamps | 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 |
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 | mem0_config_valid_when_enabled | search_top_k and search_threshold must be valid when enabled is true |
In webhook payloads
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
enabled | boolean | Optional | Enable searching for relevant memories, adding them to generation context and extracting new memories after generation. Default: false. |
search_top_k | integer (int32) | Optional | Number of memories to retrieve during search. Higher values provide more context but increase token usage. Range: 1-50 (validated only when enabled = true) Default: 5 Minimum: -2147483648. Maximum: 2147483647. |
search_threshold | 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) Default: 0.3 |
inject_as_system_context | boolean | Optional | When true, inject found memories into the system prompt context. Memories are formatted as a bullet list under a "[Relevant memories:]" header. Default: true |
search_query_override | 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. |
enable_rerank | boolean | Optional | Enable reranking for improved search relevance. Reranking provides better results but adds latency. Default: false |
add_memories_async | boolean | Optional | When true, memory extraction happens asynchronously after generation completes. This prevents extraction latency from affecting response time. Default: true |
custom_extraction_prompt | 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. |
enable_graph | boolean | Optional | Enable relationship extraction and graph-based memory search when graph memory is configured. Default: false. |
agent_id_override | 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. |
expose_as_mcp_tool | boolean | Optional | Expose memory search as an MCP tool during generation. When true, the LLM can explicitly search memories via tool calls. Rate limited to 3 searches per generation turn. Default: false |
include_assistant_messages | 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 |
inject_memory_timestamps | 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 |
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 | mem0_config_valid_when_enabled | search_top_k and search_threshold must be valid when enabled is true |
Where used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| Import a prompt library | POST /api/v1/agent-profiles/import |
| Update an agent profile | POST /api/v1/agent-profiles/update |
| 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 |
| Send a message and wait for the result | POST /api/v1/llm/send-message-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 |
| Update the caller's default generation config | POST /api/v1/enduser/update-generation-config |
| Get an agent profile | POST /api/v1/agent-profiles/get |
| List agent profiles | POST /api/v1/agent-profiles/list |
| 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 |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-sync |
| Get the caller's end-user profile | POST /api/v1/enduser/get |
| Generation configuration | API JSON uses JSON field names (camelCase). |
| llm.generation_started | Webhook JSON uses protobuf field names (snake_case). |
| llm.message_published | Webhook JSON uses protobuf field names (snake_case). |
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
Download the public reference contract.
Document: DOC-API-MODEL-memory-config.