> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remem.online/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /memories/search — Run a Semantic Memory Search

> Natural language semantic search returning memories ranked by hybrid scoring (70% semantic, 20% recency, 10% importance). Returns a score_detail breakdown on every result.

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.

<Note>
  **Endpoint:** `GET https://api.remem.online/memories/search`
</Note>

## Request Headers

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

## Query Parameters

<ParamField query="query" type="string" required>
  Natural language search query. Remem uses semantic similarity, so plain conversational phrasing works well.
</ParamField>

<ParamField query="user_id" type="string" required>
  Search within memories belonging to this user.
</ParamField>

<ParamField query="agent_id" type="string" required>
  Search within memories belonging to this agent.
</ParamField>

<ParamField query="top_k" type="integer" default="5">
  Number of results to return. Minimum `1`, maximum `20`.
</ParamField>

<ParamField query="min_score" type="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.
</ParamField>

<ParamField query="memory_type" type="string">
  Filter results to a single memory category: `episodic`, `semantic`, or `summary`. Omit this parameter to search across all types.
</ParamField>

## Code Examples

<CodeGroup>
  ```bash curl theme={null}
  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"
  ```

  ```python Python SDK theme={null}
  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)
  ```

  ```python Python (httpx) theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

## Response

### 200 — Success

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Understanding score_detail">
    Use `score_detail` to debug why a memory ranked where it did:

    ```python theme={null}
    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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="Getting empty results">
    If the endpoint returns zero memories, check in this order:

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