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

# Recalling Memories

> Ask a profile a question and get ranked facts back, or read everything one profile holds.

Reading comes in two shapes. **Ask a question** and get the facts that answer it, ranked. Or **read a profile whole**, unranked, when you want to see everything it holds.

## Ask a Question

```bash theme={null}
curl -X POST "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/recall" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where do invoices go?", "top_k": 5}'
```

| Field   | Required | Description                         |
| ------- | -------- | ----------------------------------- |
| `query` | yes      | The question, 1-4096 characters.    |
| `top_k` | no       | How many memories to return, 1-100. |

<Note>
  **URL-encode the profile id in the path.** A `profile_id` is free-form and often carries reserved characters — `caller:+13128675309` has both `:` and `+` — so percent-encode it when you interpolate it into a request path (`caller%3A%2B13128675309`), or the route can be changed or truncated.
</Note>

Results come back in rank order, most relevant first. **Rank is the signal to build on** — read the list in the order it arrives rather than filtering on the `score` field:

```json theme={null}
{
  "data": [
    {
      "id": "mem_01H…",
      "text": "Invoices go to 220 W Chicago Ave.",
      "recorded_at": "2026-08-26T21:14:11Z",
      "score": 0.82
    }
  ]
}
```

<Note>
  **There is no model in the recall path.** Recall ranks and returns facts; it does not compose an answer. Putting those facts in front of your own agent is the last step, and it stays yours.
</Note>

## Prime a Session Before the First Turn

`recall` answers questions, which means your agent has to have one. At the start of a session it does not: nobody has said anything yet, and "what do we know about this person?" is a weak query that returns ranked fragments rather than a picture.

That is the job `summary` does — the whole profile as one card, precomputed, no query and no retrieval at request time:

```bash theme={null}
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/$PROFILE_ID/summary" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

```json theme={null}
{
  "data": {
    "profile_id": "user-42",
    "text": "## Profile Summary\n\n- Prefers Slack over email.\n- Timezone: US Central.",
    "generated_at": "2026-09-18T18:32:17Z",
    "is_stale": false
  }
}
```

A card is generated in the background. `is_stale` means newer memories have landed since the card was written — ordinary, and the card is still usable.

<Note>
  **On the first read, a card may not exist yet.** For a profile whose summary has not been generated, `text` and `generated_at` come back `null` — the first read schedules one, so read again shortly. Guard for a non-null `text` before templating it into a prompt; if it is `null`, open the session without a card rather than injecting `null`.
</Note>

Three things follow from a precomputed card:

* **It is fast enough for turn zero.** A voice agent cannot spend a retrieval round-trip before greeting someone.
* **It has a stable shape.** A card is a predictable block to template into a system prompt. Ranked facts vary in length and content with every query, which is awkward to budget context for.
* **It costs less.** Opening every session with "tell me about this person" pays for full multi-strategy retrieval to answer a question whose result barely moves between sessions.

So the two reads divide by moment rather than by preference:

|           | When                                                                                    |
| --------- | --------------------------------------------------------------------------------------- |
| `summary` | Session start, before the first turn. Fetched by your application and placed in context |
| `recall`  | Mid-conversation, when the agent needs something specific                               |

You can steer how these cards read with [summary instructions](/docs/agent-memory/namespace-settings#summary-instructions), set once per namespace.

## Read a Profile Whole

Everything one profile holds, most recent first:

```bash theme={null}
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/memories" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

```json theme={null}
{
  "data": [
    { "id": "mem_01H…", "text": "Invoices go to 220 W Chicago Ave.", "recorded_at": "2026-08-26T21:14:11Z" }
  ],
  "meta": { "page_number": 1, "page_size": 20, "total_pages": 22, "total_results": 431 }
}
```

| Parameter      | Default | Description                                                |
| -------------- | ------- | ---------------------------------------------------------- |
| `session_id`   | --      | Narrow to what one session put in. Maximum 128 characters. |
| `page[number]` | `1`     | Which page to return, 1-based.                             |
| `page[size]`   | `20`    | Entries per page, up to 100.                               |

Listing depth is bounded: `page[number]` × `page[size]` cannot exceed 10,000. To reach older memories, narrow with `session_id` rather than paging deeper.

<Warning>
  **Don't stop on a short page.** A page can hold fewer than `page[size]` entries while more results remain, so a client that stops when `data.length < page[size]` silently drops the rest. Advance `page[number]` until it passes `meta.total_pages` (or you have read `meta.total_results`). Both listings behave this way.

  A page is also a snapshot: counts and order shift as writes land, so paging through a namespace that is being written to can repeat or miss an entry at a boundary. If that matters, page when writes are quiet, or de-duplicate on `id` as you go.
</Warning>

<Warning>
  `session_id` narrows to memories that came from that one session. **Some memories draw on several sessions and belong to none of them**, so they appear only in the unfiltered listing. A filtered read is not a subset you can page through to see everything.
</Warning>

## Who Is in a Namespace

Which profiles hold memories, and how many each:

```bash theme={null}
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

```json theme={null}
{
  "data": [
    { "profile_id": "caller:+13128675309", "memory_count": 12 }
  ],
  "meta": { "page_number": 1, "page_size": 20, "total_pages": 1, "total_results": 1 }
}
```

Takes the same `page[number]` and `page[size]`. A profile appears once its first memory is extracted, so one whose [ingest is still running](/docs/agent-memory/writing#track-a-write) is not listed yet.

## Related

* [Writing memories](/docs/agent-memory/writing) -- `ingest`, `remember`, and tracking the operation
* [Sources](/docs/agent-memory/sources) -- what a profile stored, and tracing a memory back to it
* [Agent Memory](/docs/agent-memory) -- namespaces, profiles, and how they are created