Voice AI

Give Your AI Agent a Memory That Outlives the Session

Every AI agent shares the same tragic flaw: total amnesia the moment a conversation ends. Tell a support bot your insurance details on Monday, and on Tuesday it asks again — politely, confidently, and with zero recollection of ever speaking to you.

For a consumer chatbot, that's annoying. For an AI triage assistant at an urgent care clinic, it's a patient-safety problem. If the assistant forgets that a patient prefers email over SMS, a critical care notification might never reach them. If it forgets an insurance carrier, staff waste time re-collecting information the patient already gave. In this context, memory isn't a nice-to-have — it's the product.

This post walks through persistent-ai-agent-memory, a compact Python CLI demo that implements the full lifecycle of long-term agent memory on Telnyx's AI Communications Infrastructure: ingest a conversation transcript, poll an asynchronous fact-extraction job to completion, and recall the extracted facts with a natural-language query. Three API calls, one API key, and no vector database to babysit.

What the App Does

The demo models a realistic scenario: an AI-powered triage assistant fielding patient inquiries about appointment scheduling, prescription refills, and billing. Across fragmented touchpoints, the assistant accumulates durable facts — "prefers email," "covered by insurance," "takes lisinopril" — and needs to recall them reliably in later sessions, even across restarts.

The CLI (app.py) runs four steps in sequence:

  1. Ingests a support transcript — a list of role/content messages — into a memory profile.
  2. Polls the async ingestion operation until it reaches a terminal status.
  3. Recalls facts by asking a natural-language question against the profile's memory.
  4. Prints the ranked results with relevance scores.

Three concepts from the Telnyx Agent Memory API carry the whole design:

  • Namespace — the isolation boundary. The demo uses default.
  • Profile — the entity whose memory you're building. Here it's user_123, a stand-in for a real patient or end user.
  • Operation — the async job tracking fact extraction from submission to completion.

Agent Memory sits alongside Telnyx's communications primitives as part of its AI Communications Infrastructure, so memory lives next to the channels your conversations actually run on — no separate retrieval stack to glue together.

The key architectural insight: writes are asynchronous by design. Fact extraction isn't instantaneous, so the ingest endpoint returns 202 Accepted with an operation_id immediately, and you poll for the result. Your request handlers stay fast, and the platform does the heavy lifting.

How It Works

The entire demo boils down to three HTTP calls:

1. POST /v2/ai/memory/namespaces/{ns}/profiles/{id}/ingest   → 202 + operation_id
2. GET  /v2/ai/memory/namespaces/{ns}/operations/{op_id}     → pending → processing → completed
3. POST /v2/ai/memory/namespaces/{ns}/profiles/{id}/recall   → ranked memory facts

Let's walk through each.

Step 1: Ingest the transcript

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.environ["TELNYX_API_KEY"]
BASE_URL = "https://api.telnyx.com/v2/ai/memory"
NAMESPACE = "default"
PROFILE_ID = "user_123"
SESSION_ID = "demo-session-001"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

transcript = [
    {"role": "user", "content": "Hi, I need to refill my lisinopril prescription."},
    {"role": "assistant", "content": "I can help with that. Would you prefer reminders by text or email?"},
    {"role": "user", "content": "Email, please — I rarely check texts. I'm also covered through my employer's plan."},
]

resp = requests.post(
    f"{BASE_URL}/namespaces/{NAMESPACE}/profiles/{PROFILE_ID}/ingest",
    params={"session_id": SESSION_ID},
    headers=headers,
    json={"messages": transcript},
)
resp.raise_for_status()

operation_id = resp.json()["data"]["operation_id"]
print(f"Ingest accepted. Operation: {operation_id}")

The response comes back as 202 Accepted:

{
  "data": {
    "operation_id": "op_abc123",
    "profile_id": "user_123",
    "session_id": "demo-session-001",
    "source_id": "src_xyz789"
  }
}

Note what you didn't have to do: chunk the transcript, pick an embedding model, stand up a vector store, or write an upsert pipeline. You hand over raw conversation messages; extraction and storage are handled for you.

Step 2: Poll the operation

Because extraction is async, the demo polls the operation endpoint until it hits a terminal status:

import time

TERMINAL_STATUSES = {"completed", "failed", "cancelled"}

while True:
    op = requests.get(
        f"{BASE_URL}/namespaces/{NAMESPACE}/operations/{operation_id}",
        headers=headers,
    ).json()["data"]

    print(f"status: {op['status']}")
    if op["status"] in TERMINAL_STATUSES:
        break
    time.sleep(2)

if op["status"] != "completed":
    raise SystemExit(f"Ingest did not complete: {op['status']}")

Statuses progress pending → processing → completed. The non-terminal states are pending and processing; completed, failed, and cancelled are terminal. Modeling those as two distinct sets — rather than checking for one magic string — is what keeps the polling loop robust.

Step 3: Recall the facts

Once the operation is completed, the memory is queryable:

resp = requests.post(
    f"{BASE_URL}/namespaces/{NAMESPACE}/profiles/{PROFILE_ID}/recall",
    headers=headers,
    json={
        "query": "What is the user's preferred contact method?",
        "top_k": 10,
    },
)

for fact in resp.json()["data"]:
    print(f"[{fact['score']:.2f}] {fact['text']}")

The response is a ranked list of extracted facts:

{
  "data": [
    {
      "id": "mem_abc123",
      "text": "The user's preferred contact method is email at user@example.com.",
      "recorded_at": "2026-10-05T12:00:05Z",
      "score": 0.92
    }
  ]
}

Run the demo end to end and you'll see the payoff: ask about contact preferences, insurance, or medications, and the assistant answers from memory it built in a previous session. That's the line between a stateless chatbot and an agent with continuity.

Gotchas worth knowing before you build

A few things the demo's troubleshooting table makes explicit:

  • Recalling before the operation completes returns an empty list. Gate your recall call on the completed status.
  • session_id must be 128 characters or fewer, or ingest raises a ValueError.
  • 401 Unauthorized almost always means TELNYX_API_KEY is missing or invalid — check your .env.
  • 404 Not Found usually means a wrong namespace or an unencoded profile ID.
  • Long-running operations: if a large transcript sits in pending longer than expected, increase the poll timeout before assuming failure.

Setup

The demo needs exactly one credential: a Telnyx API key.

# 1. Clone the repository
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/persistent-ai-agent-memory

# 2. Add your API key
echo "TELNYX_API_KEY=your_telnyx_api_key_here" > .env

# 3. Install dependencies
pip install -r requirements.txt

# 4. Run it
python app.py

Grab your key from the Telnyx Portal → API Keys. If you're wiring this into an agent workflow, the Telnyx CLI handles auth with telnyx auth login, and the full API surface is machine-readable at llms-full.txt — handy when you're pointing an agent at the docs instead of reading them yourself.

No phone numbers, messaging profiles, or other provisioned resources required — the API key is the whole setup.

Run python app.py and you should see something like:

Ingest accepted. Operation: op_abc123
status: pending
status: processing
status: completed

[0.92] The user's preferred contact method is email at user@example.com.
[0.88] The user takes lisinopril and requested a refill.
[0.85] The user is covered under their employer's insurance plan.

Wrap-Up: Memory as Infrastructure

The ingest → poll → recall pattern generalizes well beyond the clinic scenario:

  • Support desks — ingest resolved tickets so the next agent picks up where the last one left off.
  • Sales assistants — accumulate account context across calls and emails.
  • Personal assistants — remember preferences across devices and sessions, because memory lives on the platform, not in a browser tab.

And because memory is scoped per-profile inside a namespace, multi-tenant apps get isolation almost for free: namespace per customer, profile per end user.

The bigger takeaway is architectural. Agents built on Telnyx's AI Communications Infrastructure treat memory as infrastructure — durable, asynchronous, and queryable — rather than as a context window you're constantly cramming. The conversation becomes the write path; recall becomes the read path. Your agent's "brain" stops being whatever fits in the prompt and starts being everything it has ever been told.

Clone the repo, run the demo, then try asking your own questions against the profile. Once you've seen an agent answer from facts it learned in a previous session, it's hard to go back to amnesia.

Resources

Ready to build with low-latency voice AI?

Join developers building the future of real-time conversations