Labsco
openai logo

twilio-customer-memory

✓ Official★ 4,081

by openai · part of openai/plugins

Store and retrieve customer context using Twilio Conversation Memory. Covers Memory Store provisioning, profile management, traits, observations, conversation summaries, and semantic Recall. Use this skill to give AI agents or human agents persistent memory of customer interactions across sessions and channels.

🧩 One of 7 skills in the openai/plugins package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

Overview

Conversation Memory gives your application persistent customer memory. Observations (what happened) and traits (who the customer is) are written automatically from conversations flowing through Conversation Orchestrator/Orchestrator — or posted directly if you run your own extraction. Retrieve relevant context via Recall before responding.

Conversation Orchestrator/Orchestrator conversation → auto-extracted observations & summaries → Memory Store
Your App → Recall → relevant context injected into LLM prompt

All Conversation Memory APIs are on memory.twilio.com. Observations, traits, profiles, summaries — everything is on the same host.

Auth: Basic Auth — TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN.

Key Patterns

Trait Groups

Traits are organized into named groups. The Contact group is the standard identity anchor — its fields are promoted to profile identifiers for lookup.

GroupFieldsUse
Contactphone, email, firstName, lastNameIdentity anchor — always include
AccountaccountNumber, tier, regionBusiness account data
Supportdisposition, caseId, lastIssueTypeSupport history

Define your own groups for domain-specific data.

Summaries

Summaries are written automatically at conversation close or when a conversation goes inactive, based on your conversation config — the same trigger as observations. You can also write them manually:

Python

requests.post(
    f"https://memory.twilio.com/v1/Services/{memory_store_sid}/Profiles/{profile_id}/ConversationSummaries",
    auth=(account_sid, auth_token),
    json={
        "conversationId": conversation_sid,
        "content": "Customer called about order #4521. Resolved: approved expedited upgrade.",
        "source": "manual"
    }
)

Summaries are returned in the summaries array of Recall results.

Voice Agent Integration

Retrieve memory at call start, store observations at call end. For voice AI agents on ConversationRelay.

Python (WebSocket handler)

async def handle_call(websocket):
    setup = json.loads(await websocket.recv())
    caller = setup.get("from", "unknown")

    # Look up profile by caller phone
    lookup = requests.post(
        f"https://memory.twilio.com/v1/Services/{MEMORY_STORE_SID}/Profiles/Lookup",
        auth=(ACCOUNT_SID, AUTH_TOKEN),
        json={"idType": "phone", "value": caller}
    ).json()
    profiles = lookup.get("profiles", [])
    profile_id = profiles[0]["id"] if profiles else None

    context = ""
    if profile_id:
        recall = requests.post(
            f"https://memory.twilio.com/v1/Services/{MEMORY_STORE_SID}/Profiles/{profile_id}/Recall",
            auth=(ACCOUNT_SID, AUTH_TOKEN),
            json={"observationsLimit": 5, "summariesLimit": 2}
        ).json()
        context = "\n".join(o["content"] for o in recall.get("observations", []))

    system_prompt = f"You are a helpful agent.\n\nCustomer history:\n{context}" if context else "You are a helpful agent."

    # ... handle conversation ...

    # Store observation at end if running custom extraction
    if profile_id:
        requests.post(
            f"https://memory.twilio.com/v1/Services/{MEMORY_STORE_SID}/Profiles/{profile_id}/Observations",
            auth=(ACCOUNT_SID, AUTH_TOKEN),
            json={"observations": [{"content": call_summary, "source": "voice_agent", "conversationIds": [orchestrator_conversation_sid]}]}
        )

Multi-Tenant (ISV) Pattern

Use one Memory Store per client. The uniqueName doubles as a namespace.

# At client onboarding
store = requests.post(
    "https://memory.twilio.com/v1/Services",
    auth=(account_sid, auth_token),
    json={"uniqueName": f"client-{client_id}", "friendlyName": client_name}
).json()
# Store store["sid"] in your tenant config — pass it to Conversation Orchestrator conversation service setup

CANNOT

  • Cannot create Conversation Orchestrator before Memory Store — Create Memory Store first. Its SID is required when creating the Conversations Service. Reversing this order breaks the linkage.
  • Cannot extract observations mid-conversation — Automatic extraction happens on conversation close or inactive. For real-time writing, post directly to the Observations endpoint.
  • Cannot read observations immediately after write — Eventual consistency. Allow ~2 seconds after write before querying Recall.
  • Cannot exceed 15 Memory Stores per account — ISVs with more than 15 tenants should use sub-accounts
  • Cannot detect misconfigured linkages — If Memory Store is not correctly linked in Conversation Orchestrator config, observations are silently not extracted. See twilio-debugging-observability.
  • Cannot recover deleted profiles — Profile deletion is irreversible, permanent
  • Cannot exceed 20 observations per Recall query — observationsLimit max 20, default 5. summariesLimit and communicationsLimit similar.
  • Cannot batch more than 10 observations per request — Hard limit on batch writes

Next Steps

  • Set up Conversation Orchestrator conversations: twilio-conversation-orchestrator
  • Add real-time intelligence: twilio-conversation-intelligence
  • Enterprise knowledge retrieval (scripts, offers, policies): twilio-enterprise-knowledge
  • Voice agent setup: twilio-voice-conversation-relay
  • Debug integration issues: twilio-debugging-observability