POST /v1/memories/retrieve

Retrieve relevant memories for an end user and build prompt-ready context.

Endpoint

POST /v1/memories/retrieve

Authentication

Authorization: ApiKey mem_live_xxx
Content-Type: application/json

Request body

{
  "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

{
  "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

POST /v1/memories/retrieval-feedback
Authorization: ApiKey mem_live_xxx
Content-Type: application/json

Successful use

{
  "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

{
  "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:

{
  "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

{
  "format": "bullets"
}

What you know about this user:
- User prefers concise technical explanations and Python examples.

json

{
  "format": "json"
}

{
  "memories": {
    "preference": [
      "User prefers concise technical explanations and Python examples."
    ]
  }
}

xml

{
  "format": "xml"
}

What you know about this user:
<memory_context>
  <memory category="preference">
    User prefers concise technical explanations and Python examples.
  </memory>
</memory_context>

Context token limit

Use context_max_tokens to limit the size of system_prompt_addition.

{
  "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:

{
  "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
• Memory Provenance
• Memory Lifecycle