> ## Documentation Index > Fetch the complete documentation index at: https://docs.memoryo.dev/llms.txt > Use this file to discover all available pages before exploring further. # POST /v1/memories/retrieve > Retrieve relevant memories for an end user and build prompt-ready context. ## Endpoint ```http theme={null} POST /v1/memories/retrieve ``` ## Authentication ```http theme={null} Authorization: ApiKey mem_live_xxx Content-Type: application/json ``` ## Request body ```json theme={null} { "external_user_id": "customer-123", "query": "How should I respond to this user?", "limit": 5, "categories": ["preference", "goal"], "agent_id": "support-bot", "time_filter_days": 30, "format": "bullets", "context_max_tokens": 500 } ``` ### Fields | Field | Type | Required | Notes | | -------------------- | ------------------------------ | -------- | -------------------------------------------------------------- | | `external_user_id` | `string` | Yes | End-user identifier inside your tenant | | `query` | `string` | Yes | Natural-language retrieval query | | `limit` | `integer` | No | Default `10`, max `50` | | `categories` | `MemoryCategory[]` | No | Optional category filters | | `agent_id` | `string \| null` | No | Optional agent filter | | `time_filter_days` | `integer \| null` | No | Return only memories created in the last N days | | `format` | `"bullets" \| "json" \| "xml"` | No | Default `bullets` | | `context_max_tokens` | `integer` | No | Default `500`; max context budget for `system_prompt_addition` | ## Response ```json theme={null} { "retrieval_id": "68716fef-731c-4496-bff0-78ccc8ce8bb3", "data": [ { "id": "2b8f5f87-bbd4-4f84-9f5f-0cba5033f058", "content": "User prefers concise technical explanations and Python examples.", "category": "preference", "importance_score": 8.5, "last_accessed": "2026-04-17T09:45:00Z", "relevance_score": 0.962341, "context_snippet": "- User prefers concise technical explanations and Python examples.", "source_event_id": "f9a61e94-67c5-4a9a-9e72-61b8b15df4cc", "provenance": { "service": "support-service", "event_id": "support-chat-8841", "observed_at": "2026-04-17T09:40:00Z", "writer_id": "b7b5b2a8-2a66-4ce3-9b37-2a1d8cf78d4d" } } ], "cached": false, "system_prompt_addition": "What you know about this user:\n- User prefers concise technical explanations and Python examples.", "context_token_count": 18, "memories_from_hot_tier": 0, "clarification_question": null, "quota_mode": "FULL", "is_degraded": false, "is_passthrough": false, "request_id": "b0eb46a4-8794-44c8-b2a9-8f2dfbb4176c", "timestamp": "2026-04-17T09:45:03Z" } ``` ## Response schema ### Top-level fields | Field | Type | Meaning | | ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `retrieval_id` | `string \| null` | Stable id used when sending retrieval feedback | | `data` | `MemorySearchResult[]` | Ranked memory results | | `cached` | `boolean` | Whether retrieval came from the hot cache | | `system_prompt_addition` | `string` | Prompt-ready memory context | | `context_token_count` | `integer \| null` | Token count of the built context when available | | `memories_from_hot_tier` | `integer` | Number of returned memories served from Redis hot tier | | `clarification_question` | `string \| null` | Optional user-facing question for resolving a pending conflict | | `quota_mode` | `"FULL" \| "PASSTHROUGH" \| "DEGRADED_RETRIEVE" \| "BLOCKED"` | Current quota behavior | | `is_degraded` | `boolean` | `true` when retrieval is degraded | | `is_passthrough` | `boolean` | `true` when memory context should be skipped | | `request_id` | `string` | Trace id | | `timestamp` | `datetime` | Response timestamp | ### `MemorySearchResult` | Field | Type | Meaning | | ------------------ | ------------------ | ---------------------------------------------------- | | `id` | `string` | Memory id | | `content` | `string` | Memory text | | `category` | `string` | Memory category | | `importance_score` | `float` | Current importance score after lifecycle adjustments | | `last_accessed` | `datetime \| null` | Last access timestamp | | `relevance_score` | `float` | Final retrieval score | | `context_snippet` | `string` | Single-memory rendering in the selected format | | `source_event_id` | `string \| null` | Provenance event id when available | | `provenance` | `object \| null` | Source, writer, evidence, and processing metadata | ## Send retrieval feedback Feedback is optional but recommended. It closes the quality loop after your agent uses retrieved memory. Use it when: * the retrieved context helped the agent answer correctly * the agent ignored a memory because it was not useful * the user corrected the agent * the agent had to ask for clarification because context was missing ```http theme={null} POST /v1/memories/retrieval-feedback Authorization: ApiKey mem_live_xxx Content-Type: application/json ``` ### Successful use ```json theme={null} { "retrieval_id": "68716fef-731c-4496-bff0-78ccc8ce8bb3", "outcome": "used_successfully", "used_memory_ids": ["2b8f5f87-bbd4-4f84-9f5f-0cba5033f058"], "agent_confidence": 0.86, "metadata": { "agent_id": "support-bot", "conversation_id": "chat_8841" } } ``` ### User correction ```json theme={null} { "retrieval_id": "68716fef-731c-4496-bff0-78ccc8ce8bb3", "outcome": "user_corrected", "used_memory_ids": ["2b8f5f87-bbd4-4f84-9f5f-0cba5033f058"], "correction": "Actually I prefer Hindi explanations for billing questions, not English.", "agent_confidence": 0.2, "metadata": { "agent_id": "support-bot", "conversation_id": "chat_8841" } } ``` Example response: ```json theme={null} { "data": { "feedback_id": "0e6aa7b1-6678-4c76-b675-12f63fbf54c2", "retrieval_id": "68716fef-731c-4496-bff0-78ccc8ce8bb3", "outcome": "user_corrected", "correction_job_id": "d2bb7542-aea1-4090-a70a-0ff2dfd86175" }, "request_id": "c772f4e2-1e8f-4852-aa92-9c6548d26a1e", "timestamp": "2026-06-30T10:00:00Z" } ``` `correction_job_id` means MemoryOS queued an async retrospective extraction pass. It does not block the user response. ## `format` examples The `format` value controls how MemoryOS renders both `context_snippet` and `system_prompt_addition`. ### `bullets` ```json theme={null} { "format": "bullets" } ``` ```text theme={null} What you know about this user: - User prefers concise technical explanations and Python examples. ``` ### `json` ```json theme={null} { "format": "json" } ``` ```json theme={null} { "memories": { "preference": [ "User prefers concise technical explanations and Python examples." ] } } ``` ### `xml` ```json theme={null} { "format": "xml" } ``` ```xml theme={null} What you know about this user: User prefers concise technical explanations and Python examples. ``` ## Context token limit Use `context_max_tokens` to limit the size of `system_prompt_addition`. ```json theme={null} { "external_user_id": "customer-123", "query": "How should I answer this user?", "limit": 10, "format": "bullets", "context_max_tokens": 300 } ``` MemoryOS drops lower-importance memories first when the context is too large. It does not truncate mid-sentence. ## Domain-aware retrieval If a tenant has a domain schema enabled, the same retrieve endpoint returns domain-aware context in `system_prompt_addition`. For example, an EdTech tenant may receive tutoring context about exam goals, weak topics, learning style, or forgetting-stage review urgency. The request shape does not change: ```json theme={null} { "external_user_id": "student_123", "query": "teach this student trigonometry identities", "limit": 8, "context_max_tokens": 600 } ``` Use optional domain profile endpoints only when you need structured UI data, not for normal model calls. ## Related pages * [Extraction Quality Loop](/concepts/extraction-quality) * [Memory Provenance](/concepts/provenance) * [Memory Lifecycle](/concepts/memory-lifecycle)