> ## 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/context — Load a User's Session Context

> Load the most important and recent memories for a user at conversation start. Pass current_message to switch to semantic retrieval based on the user's first message.

Call this endpoint at the beginning of every conversation — before your agent generates its first response. Remem returns the most important and recent memories for the user so your agent already knows who they are and what they care about. If you supply `current_message`, the retrieval switches to semantic mode and returns memories most relevant to what the user just said, rather than a general importance-and-recency sort.

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

## Request Headers

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

## Query Parameters

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

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

<ParamField query="top_k" type="integer" default="10">
  Maximum number of memories to return. Minimum `1`, maximum `50`.
</ParamField>

<ParamField query="current_message" type="string">
  The first message sent by the user in this session. When provided, Remem uses semantic retrieval to return memories most relevant to this message. When omitted, memories are sorted by importance and recency.
</ParamField>

## Code Examples

<CodeGroup>
  ```bash curl theme={null}
  # Without current_message — sorted by importance + recency
  curl "https://api.remem.online/memories/context?\
  user_id=user_123&agent_id=support_bot&top_k=10" \
    -H "X-API-Key: rm_live_xxx"

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

  ```python Python SDK theme={null}
  from remem import RememClient

  client = RememClient(api_key="rm_live_xxx")

  # At session start — no message yet
  context = client.context(
      user_id="user_123",
      agent_id="support_bot",
      top_k=10,
  )

  # When the user sends their first message
  context = client.context(
      user_id="user_123",
      agent_id="support_bot",
      current_message="I need help with my order",
  )

  # Inject into system prompt
  memory_lines = "\n".join(f"- {m.content}" for m in context.memories)
  system_prompt = f"What you know about this user:\n{memory_lines}"
  ```
</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,
      "metadata":    {},
      "created_at":  "2026-06-01T10:00:00Z",
      "last_accessed": "2026-06-07T09:00:00Z",
      "expires_at":  null
    }
  ],
  "total":  4,
  "limit":  10,
  "offset": 0
}
```

The response uses the same Memory object shape as the [Search Memories](/api-reference/search) endpoint. Refer to the [Memory Object Fields](/api-reference/search#memory-object-fields) table there for a full field-by-field description. Key fields at a glance:

| Field         | Type           | Description                                         |
| ------------- | -------------- | --------------------------------------------------- |
| `id`          | string         | Memory UUID                                         |
| `content`     | string         | The stored memory text                              |
| `memory_type` | string         | `episodic`, `semantic`, or `summary`                |
| `importance`  | float          | Priority score from `0.0` to `1.0`                  |
| `created_at`  | string         | ISO 8601 creation timestamp                         |
| `expires_at`  | string \| null | ISO 8601 expiry timestamp, or `null` if permanent   |
| `total`       | integer        | Total memories available for this user + agent pair |
| `limit`       | integer        | The `top_k` value applied to this response          |
| `offset`      | integer        | Pagination offset (always `0` for context requests) |

## 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 | Both `user_id` and `agent_id` are required          |

## Notes

<AccordionGroup>
  <Accordion title="context() vs recall() — when to use each">
    Use **`context()`** at **session start**, before you have a specific query. It surfaces the memories that are most important and recent for this user overall, giving your agent a baseline understanding before the conversation begins.

    Use **`recall()`** (the [Search Memories](/api-reference/search) endpoint) **during a session**, when the user says something specific and you want memories relevant to that particular message.

    You can combine both: call `context()` once at the start to pre-populate your system prompt, then call `recall()` on each user turn to retrieve memories relevant to what they just said.
  </Accordion>

  <Accordion title="New users — handling empty memory lists">
    If the user has no stored memories yet, `context()` returns an empty `memories` array. Make sure your agent handles this gracefully rather than treating it as an error:

    ```python theme={null}
    context = client.context(user_id=user_id, agent_id=agent_id)

    if context.memories:
        memory_text = "\n".join(f"- {m.content}" for m in context.memories)
    else:
        memory_text = "This is a new user — no previous context available."

    system_prompt = f"What you know about this user:\n{memory_text}"
    ```

    A `total` of `0` in the response is the reliable signal that no memories exist yet for this user + agent pair.
  </Accordion>
</AccordionGroup>