GET /memories/search — Run a Semantic Memory Search

Use this endpoint to retrieve memories that are relevant to a specific query during an active conversation. You do not need to match exact words — Remem understands meaning, so asking “where does this user live?” will surface “User is based in Lagos, Nigeria” even without overlapping terms. Results are ranked by a hybrid score: 70% semantic relevance + 20% recency + 10% importance, and every result includes a score_detail breakdown so you can see exactly how each memory ranked.

Endpoint: GET https://api.remem.online/memories/search

Request Headers

Header	Required	Value
`X-API-Key`	Yes	Your Remem API key (`rm_live_xxx`)

Query Parameters

string

required

Natural language search query. Remem uses semantic similarity, so plain conversational phrasing works well.

string

required

Search within memories belonging to this user.

string

required

Search within memories belonging to this agent.

integer

default:"5"

Number of results to return. Minimum 1, maximum 20.

float

default:"0.70"

Minimum hybrid score threshold. Only memories scoring at or above this value are returned. Set to 0.0 to return all memories regardless of relevance.

string

Filter results to a single memory category: episodic, semantic, or summary. Omit this parameter to search across all types.

Code Examples

curl "https://api.remem.online/memories/search?\
query=where+does+this+user+live&\
user_id=user_123&\
agent_id=support_bot&\
top_k=5&\
min_score=0.0" \
  -H "X-API-Key: rm_live_xxx"

from remem import RememClient

client = RememClient(api_key="rm_live_xxx")

memories = client.recall(
    "where does this user live?",
    user_id="user_123",
    agent_id="support_bot",
    top_k=5,
    min_score=0.0,
)

for m in memories:
    print(f"[{m.score:.3f}] {m.content}")
    print(m.score_detail)

import httpx

resp = httpx.get(
    "https://api.remem.online/memories/search",
    headers={"X-API-Key": "rm_live_xxx"},
    params={
        "query":     "where does this user live?",
        "user_id":   "user_123",
        "agent_id":  "support_bot",
        "top_k":     5,
        "min_score": 0.0,
    }
)
print(resp.json())

const params = new URLSearchParams({
  query:     "where does this user live?",
  user_id:   "user_123",
  agent_id:  "support_bot",
  top_k:     5,
  min_score: 0.0,
});

const response = await fetch(
  `https://api.remem.online/memories/search?${params}`,
  { headers: { "X-API-Key": "rm_live_xxx" } }
);
const data = await response.json();

Response

200 — Success

{
  "memories": [
    {
      "id":          "775263ee-73af-4416-9804-1f274048ae08",
      "content":     "User is based in Lagos, Nigeria",
      "user_id":     "user_123",
      "agent_id":    "support_bot",
      "memory_type": "semantic",
      "importance":  0.9,
      "score":       0.8912,
      "score_detail": {
        "cosine":     0.8900,
        "recency":    0.9800,
        "importance": 0.9000,
        "final":      0.8912
      },
      "metadata":      {},
      "created_at":    "2026-06-01T10:00:00Z",
      "last_accessed": "2026-06-07T09:00:00Z",
      "expires_at":    null
    }
  ],
  "query": "where does this user live?",
  "total": 1
}

Memory Object Fields

Field	Type	Description
`id`	string	Memory UUID
`content`	string	The stored memory text
`user_id`	string	User this memory belongs to
`agent_id`	string	Agent that stored this memory
`memory_type`	string	`episodic`, `semantic`, or `summary`
`importance`	float	Importance score from `0.0` to `1.0`
`score`	float	Final hybrid score for this query
`score_detail`	object	Breakdown of how the score was computed
`score_detail.cosine`	float	Semantic similarity component (70% weight)
`score_detail.recency`	float	Recency component (20% weight)
`score_detail.importance`	float	Importance component (10% weight)
`score_detail.final`	float	Weighted final score — identical to `score`
`metadata`	object	Any extra data stored with the memory
`created_at`	string	ISO 8601 timestamp when memory was stored
`last_accessed`	string	ISO 8601 timestamp of last retrieval
`expires_at`	string \| null	ISO 8601 expiry timestamp, or `null` if permanent

Error Responses

Code	Meaning	Fix
`401`	Invalid or missing API key	Verify your key is passed in the `X-API-Key` header
`422`	Missing required parameter	Include `query`, `user_id`, and `agent_id` in every request

Notes

Understanding score_detail

Use score_detail to debug why a memory ranked where it did:

for m in memories:
    print(f"Content:    {m.content}")
    print(f"Cosine:     {m.score_detail['cosine']:.3f}")
    print(f"Recency:    {m.score_detail['recency']:.3f}")
    print(f"Importance: {m.score_detail['importance']:.3f}")
    print(f"Final:      {m.score_detail['final']:.3f}")
    print()

If the wrong memory ranks first, check which signal is pulling it up. High recency but low cosine means the memory is recent but not semantically relevant to your query. High cosine but low recency means the memory is relevant but has not been accessed in a while.

Tuning min_score

The default threshold of 0.70 works well for most production use cases. Adjust it based on how strict you need results to be:

0.85+ — strict; only highly relevant memories surface
0.70 — balanced default
0.50 — loose; returns anything remotely related
0.0 — no filtering; useful during debugging

Start at 0.0 when diagnosing issues. If you see results at that threshold but not at your production threshold, the memories exist and you simply need to lower min_score.

Getting empty results

If the endpoint returns zero memories, check in this order:

Set min_score=0.0 — if results appear, your threshold is too high
Confirm user_id and agent_id match exactly what you used during storage (they are case-sensitive)
Call GET /memories to list all stored memories and confirm they were saved
Check expires_at — memories past their expiry date are excluded from results

​Request Headers

​Query Parameters

​Code Examples

​Response

​200 — Success

​Memory Object Fields

​Error Responses

​Notes

Request Headers

Query Parameters

Code Examples

Response

200 — Success

Memory Object Fields

Error Responses

Notes