twilio-conversation-memory

Overview

Conversation Memory gives agents persistent, cross-session context about customers. A Memory Store holds profiles, observations, summaries, and traits. Data enters two ways:

1. Automatic: Link a Conversation Orchestrator config to a store. Profiles are auto-created per caller. At conversation close, observations and summaries are extracted from the transcript and saved. Conflicting data is automatically reconciled.

2. Direct API: POST observations, summaries, or traits yourself for any use case.

Data comes out via Recall — hybrid semantic + lexical search that surfaces the most relevant profile data. For voice agents where latency is critical, use GET /Observations directly instead.

Base URL: https://memory.twilio.com

Authentication: HTTP Basic — Authorization: Basic {base64(accountSid:authToken)}

Rules for agents:

• Always poll statusUrl after any 202 response — all writes are async
• Always create a trait group before writing traits of that group
• Always use E.164 format for phone numbers (+15558675310)
• Always verify store status is ACTIVE before operating on it
• Never use /v1/Services/ paths — correct paths are /v1/ControlPlane/Stores (config) and /v1/Stores/{storeId}/... (data)
• Never exceed 10 observations per batch or 4096 characters per observation
• Never assume writes are immediately readable — indexing is async
• Never send PCI or HIPAA data — not yet compliant

Prerequisites

• Twilio account with Account SID and Auth Token — A credit card must be added to the account — See twilio-account-setup for initial setup — See twilio-iam-auth-setup for credential best practices
• Environment variables:
  • TWILIO_ACCOUNT_SID
  • TWILIO_AUTH_TOKEN
• SDK: pip install twilio / npm install twilio
• For automatic extraction: a Conversation Orchestrator configuration — see twilio-conversation-orchestrator

Quickstart

Step 1 — Create a Memory Store

Python

import os, requests
from requests.auth import HTTPBasicAuth

account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
base_url = "https://memory.twilio.com"
auth = HTTPBasicAuth(account_sid, auth_token)

store = requests.post(
    f"{base_url}/v1/ControlPlane/Stores",
    auth=auth,
    json={"displayName": "my-store", "description": "Customer memory"}
).json()

print(store["id"])  # mem_store_xxx — save this
# Poll store["statusUrl"] until status is ACTIVE