> ## 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.

# Writing Memories

> Two ways to put something in a profile: ingest a whole session and let facts be extracted, or remember a single fact exactly as written.

There are two ways in, and the difference is who decides what the fact is.

**`ingest`** takes a conversation and extracts the facts from it. Use it when the agent has just finished talking to someone and you want whatever mattered to be kept, without deciding in advance what that was.

**`remember`** takes one sentence you have already distilled and stores it as written. Use it when your system already knows the fact — a CRM field, a preference the user set, something a human entered.

Both answer `202 Accepted` with an `operation_id`, and the `source_id` the write is stored as — see [Sources](/docs/agent-memory/sources). Neither is readable until that operation completes.

## Ingest a Session

```bash theme={null}
curl -X POST "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/ingest?session_id=conv_8901" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "invoices go to 220 W Chicago Ave now"},
      {"role": "assistant", "content": "Got it."}
    ]
  }'
```

```json theme={null}
{
  "data": {
    "operation_id": "op_01H…",
    "profile_id": "caller:+13128675309",
    "session_id": "conv_8901",
    "source_id": "b1e6c0a2-…"
  }
}
```

| Parameter    | In    | Required | Description                                                                                       |
| ------------ | ----- | -------- | ------------------------------------------------------------------------------------------------- |
| `session_id` | query | no       | Your identifier for the conversation. Omit it and one is opened for you -- the response names it. |
| the body     | body  | yes      | Stored whole, in whatever shape your framework produces.                                          |

**The body is not a fixed shape.** `session_id` is a query parameter, so the whole body is stored exactly as it arrives -- you can post the transcript your framework already produces, even a bare array or a plain string, rather than reshaping it to carry a key. The `messages` array above is the conventional form, not a requirement.

**Re-sending the same `session_id` re-ingests that session in place** rather than adding a second copy, so a retry after a timeout is safe.

<Note>
  `session_id` is a query parameter of at most 128 characters, validated on the way in -- a longer value is rejected with a `422`, the same bound the [memories listing](/docs/agent-memory/recall#read-a-profile-whole) filters on.
</Note>

## Remember a Fact

```bash theme={null}
curl -X POST "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/remember" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Prefers window seats and flies out of ORD"}'
```

```json theme={null}
{
  "data": {
    "operation_id": "op_01H…",
    "profile_id": "caller:+13128675309",
    "source_id": "9af23d17-…"
  }
}
```

`text` is the whole request. Sending the same text again writes the same memory rather than a second copy, so retries are safe here too.

<Note>
  `remember` keeps your wording, but it does not freeze it. The service may later restate the same fact in its own prose, so a recall can answer about it in words you never wrote.
</Note>

<Note>
  **`ingest` is not a tool for your agent to call.** A tool is something the model invokes *during* a conversation; ingestion needs the finished transcript, and a model has no useful notion of "the conversation is over" while it is still in it. Call `ingest` from your application once the session ends. [`remember`](#remember-a-fact) is the verb that fits mid-conversation: one distilled fact, stored as written, safe to retry.
</Note>

## Track a Write

Both verbs return an `operation_id`. Poll it to find out when the memory is recallable:

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

```json theme={null}
{
  "data": {
    "operation_id": "op_01H…",
    "status": "completed",
    "created_at": "2026-08-26T21:14:07Z",
    "completed_at": "2026-08-26T21:14:11Z"
  }
}
```

<Warning>
  **Three statuses end the poll, not one.** `completed` means the memory is recallable. `failed` and `cancelled` are equally terminal and mean the write did not happen -- retry or surface the failure, but stop polling. Only `pending` and `processing` are worth another request.
</Warning>

A profile does not appear in [the profile listing](/docs/agent-memory/recall#who-is-in-a-namespace) until its first memory is extracted, so a still-running ingest is not there yet.

## Related

* [Recalling memories](/docs/agent-memory/recall) -- asking questions, and reading a profile whole
* [Agent Memory](/docs/agent-memory) -- namespaces, profiles, and how they are created