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:
- Ingests a support transcript — a list of
role/contentmessages — into a memory profile. - Polls the async ingestion operation until it reaches a terminal status.
- Recalls facts by asking a natural-language question against the profile's memory.
- 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
completedstatus. session_idmust be 128 characters or fewer, or ingest raises aValueError.401 Unauthorizedalmost always meansTELNYX_API_KEYis missing or invalid — check your.env.404 Not Foundusually means a wrong namespace or an unencoded profile ID.- Long-running operations: if a large transcript sits in
pendinglonger 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
- persistent-ai-agent-memory on GitHub
- Telnyx developer docs
llms-full.txtfor agent-facing API discovery