POST /v1/memories/retrieve

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,
  "as_of": null,
  "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
`as_of`	`string \| null`	No	Historical validity boundary; ISO 8601 timestamp with timezone
`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,
  "clarification": 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
`clarification`	`MemoryClarification \| null`	Structured id, question, expiry, and backend-approved answer options for the same clarification
`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

Resolve a clarification in your existing chat

When clarification is present, show clarification.question in the same assistant conversation. Send the user’s selected answer back to MemoryOS; do not build a separate MemoryOS clarification screen and do not let the model rewrite the option into an authority decision.

POST /v1/memories/clarifications/{clarification_id}/answer
Authorization: ApiKey mem_live_xxx
Content-Type: application/json

{
  "external_user_id": "customer-123",
  "answer": "B",
  "free_text": "The Scale plan is current."
}

Allowed answers are A, B, both, and neither. MemoryOS verifies the authenticated tenant, resolves external_user_id inside that tenant, checks the clarification’s owner, expiry and current status, locks the resolution records, and applies the governed conflict transition. A repeated or expired answer returns 409; a clarification belonging to another user or tenant is returned as 404.

{
  "data": {
    "resolved": true,
    "clarification_id": "f04669c2-99f9-49a3-83ab-ad37b05e67d5",
    "conflict_id": "0c2d96aa-e5bb-4cbe-b750-23e8c06849ce",
    "resolution": "B"
  },
  "request_id": "b0eb46a4-8794-44c8-b2a9-8f2dfbb4176c",
  "timestamp": "2026-04-17T09:46:03Z"
}

`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.

Memory APIs

Domain APIs

Reference

POST /v1/memories/retrieve

Endpoint

Authentication

Request body

Fields

Response

Response schema

Top-level fields

Resolve a clarification in your existing chat

`MemorySearchResult`

Send retrieval feedback

Successful use

User correction

`format` examples

`bullets`

`json`

`xml`

Context token limit

Domain-aware retrieval

​Endpoint

​Authentication

​Request body

​Fields

​Response

​Response schema

​Top-level fields

​Resolve a clarification in your existing chat

​MemorySearchResult

​Send retrieval feedback

​Successful use

​User correction

​format examples

​bullets

​json

​xml

​Context token limit

​Domain-aware retrieval

​Related pages

Endpoint

Authentication

Request body

Fields

Response

Response schema

Top-level fields

Resolve a clarification in your existing chat

`MemorySearchResult`

Send retrieval feedback

Successful use

User correction

`format` examples

`bullets`

`json`

`xml`

Context token limit

Domain-aware retrieval

Related pages