Writing Memories

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. Neither is readable until that operation completes.

Ingest a Session

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."}
    ]
  }'

{
  "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.

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 filters on.

Remember a Fact

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"}'

{
  "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.

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.

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 is the verb that fits mid-conversation: one distilled fact, stored as written, safe to retry.

Track a Write

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

curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/operations/op_01H…" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

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

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.

A profile does not appear in the profile listing until its first memory is extracted, so a still-running ingest is not there yet.

Recalling memories — asking questions, and reading a profile whole
Agent Memory — namespaces, profiles, and how they are created

Agent Memory

Features

API Reference

For AI Agents

Writing Memories

Ingest a Session

Remember a Fact

Track a Write

​Ingest a Session

​Remember a Fact

​Track a Write

​Related

Ingest a Session

Remember a Fact

Track a Write

Related