Skip to main content
Call this at the start of every conversation — before the user says anything. MemLayer returns the most important and recently accessed memories for this user so your agent already knows who they are and what they care about. Pass the user’s opening message via current_message and the retrieval switches to semantic mode, returning memories most relevant to what was just said.

​
Request

​
Headers

NameRequiredDescription
X-API-KeyYesYour MemLayer API key (ml_live_xxx)

​
Query Parameters

​
user_id
string
required
Load memories belonging to this user. Must exactly match the value used when storing.
​
agent_id
string
required
Load memories associated with this agent. Must exactly match the value used when storing.
​
top_k
integer
default:"10"
Maximum number of memories to return. Range: 1–50. Unlike search, this endpoint can return up to 50 results — useful for building a rich system prompt.
​
current_message
string
Optional. The user’s first message in this session. When provided, MemLayer runs a semantic search using this text and returns memories most relevant to the opening message. When omitted, memories are ranked by importance and recency instead.
# Without current_message — sorted by importance + recency
curl "https://memlayer.online/memories/context?\
user_id=user_123&agent_id=support_bot&top_k=10" \
  -H "X-API-Key: ml_live_xxx"

# With current_message — semantic retrieval
curl "https://memlayer.online/memories/context?\
user_id=user_123&agent_id=support_bot&\
current_message=I+need+help+with+my+order" \
  -H "X-API-Key: ml_live_xxx"

​
Response

​
Success — 200

​
memories
MemoryOut[]
Array of memory objects, ordered by relevance (semantic mode) or by importance + recency (default mode). See Search Memories for the full MemoryOut field reference. Note that score and score_detail are only populated when current_message is provided.
​
total
integer
Number of memories returned in this response.
​
limit
integer
The top_k value applied to this request.
​
offset
integer
Always 0 for the context endpoint — pagination is not supported here.
{
  "memories": [
    {
      "id":          "775263ee-73af-4416-9804-1f274048ae08",
      "content":     "User prefers concise bullet points over long paragraphs",
      "user_id":     "user_123",
      "agent_id":    "support_bot",
      "memory_type": "semantic",
      "importance":  0.8,
      "metadata":    {},
      "score":       null,
      "score_detail": null,
      "created_at":    "2026-06-01T10:00:00Z",
      "last_accessed": "2026-06-07T09:00:00Z",
      "expires_at":    null
    }
  ],
  "total":  1,
  "limit":  10,
  "offset": 0
}

​
Errors

CodeMeaning
401Invalid or missing X-API-Key
403Account suspended
422Validation error — check parameter types

​
Notes

These two endpoints serve different moments in a conversation:
GET /memories/contextGET /memories/search
WhenSession startMid-conversation
What you haveNothing yet, or first messageA specific user query
ReturnsBroad background contextTargeted, query-specific results
Default rankingImportance + recencyHybrid semantic score
The recommended pattern is to call context() once at session start to build the system prompt, then call recall() on each user turn to fetch memories relevant to that specific message.
If the user has no memories yet, context() returns an empty memories array and total: 0. Your agent should handle this gracefully rather than injecting an empty block into the system prompt:
context = client.context(user_id=user_id, agent_id=agent_id)

if context.memories:
    memory_block = "\n".join(f"- {m.content}" for m in context.memories)
    system_suffix = f"\n\nWhat you remember about this user:\n{memory_block}"
else:
    system_suffix = ""
Context windows are finite. A top_k of 10–15 memories is usually enough to give your agent useful background without padding the prompt unnecessarily. If you’re building a memory browser or audit UI, use GET /memories instead — it supports pagination and returns all memories, not just the most relevant ones.