Skip to main content
Find the memories most relevant to a natural-language query. You don’t need to match exact words — MemLayer understands meaning. Ask "where does this user live?" and it surfaces "User is based in Lagos, Nigeria" even though no words overlap. Use this mid-conversation when the user raises a specific topic and you need targeted context fast.

​
Request

​
Headers

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

​
Query Parameters

​
query
string
required
Natural-language search query. Max 1,000 characters. Phrase it the way you’d describe what you want to know — "user's dietary restrictions" works better than a raw keyword like "diet".
​
user_id
string
required
Return memories belonging to this user only. Must exactly match the value used when storing.
​
agent_id
string
required
Return memories associated with this agent only. Must exactly match the value used when storing.
​
top_k
integer
default:"5"
Maximum number of results to return. Range: 1–20. Only memories scoring above min_score are included, so you may receive fewer than top_k results.
​
min_score
float
default:"0.70"
Minimum hybrid score threshold. Range: 0.0–1.0. Memories scoring below this value are excluded. Lower values return more (but less relevant) results; higher values return only strong matches.
​
memory_type
string
Optional filter. One of episodic, semantic, or summary. Omit to search across all types.
curl "https://memlayer.online/memories/search?\
query=what+does+this+user+prefer&\
user_id=user_123&\
agent_id=support_bot&\
top_k=5&\
min_score=0.70" \
  -H "X-API-Key: ml_live_xxx"

​
Response

​
Success — 200

​
memories
MemoryOut[]
Array of matching memories, ordered by descending hybrid score.
​
query
string
The query string echoed back from your request.
​
total
integer
Number of memories returned in this response (after applying min_score and top_k filters).
{
  "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":       0.8912,
      "score_detail": {
        "cosine":     0.8900,
        "recency":    0.9800,
        "importance": 0.8000,
        "final":      0.8912
      },
      "created_at":    "2026-06-01T10:00:00Z",
      "last_accessed": "2026-06-07T09:00:00Z",
      "expires_at":    null
    }
  ],
  "query": "what does this user prefer?",
  "total": 1
}

​
Errors

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

​
Notes

Use score_detail to diagnose ranking behaviour:
for m in memories:
    d = m.score_detail
    print(f"Content:    {m.content}")
    print(f"Cosine:     {d['cosine']:.4f}")
    print(f"Recency:    {d['recency']:.4f}")
    print(f"Importance: {d['importance']:.4f}")
    print(f"Final:      {d['final']:.4f}")
    print()
If an unexpected memory ranks first, check whether it has a disproportionately high recency or importance score pulling it above more semantically relevant results. Adjust the memory’s importance with a PATCH /memories/ call if needed.
The default 0.70 strikes a balance between precision and recall for most use cases.
  • 0.85+ — strict. Only surfaces memories with high semantic overlap. Use when false positives are costly (e.g. injecting wrong medical context).
  • 0.70 (default) — balanced. Works well for general assistants.
  • 0.50 — loose. Good for broad topic matching.
  • 0.0 — returns everything up to top_k. Useful when debugging why nothing is returned.
Start at the default and adjust based on the quality of results you observe.
If you receive "total": 0, work through this checklist:
  1. Confirm user_id and agent_id exactly match the values used when storing.
  2. Use GET /memories to verify that memories actually exist for this pair.
  3. Temporarily set min_score=0.0 — if results appear, your threshold is too high for this query.
  4. Check that the memories haven’t expired (expires_at in the past).
  5. Ensure the memory_type filter (if set) matches what was stored.