twilio-customer-memory

What this skill does

## 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`.

---

## Prerequisites

- Twilio account with Conversation Memory access (requires enablement)
  — New to Twilio? See `twilio-account-setup`
- `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` — see `twilio-iam-auth-setup`
- **Memory Store must be created before creating a Conversations Service in Conversation Orchestrator/Orchestrator** — the store SID is required in the conversation config
- For conversation orchestration: `twilio-conversation-orchestrator`

---

## Quickstart

### Step 1 — Create a Memory Store

Do this before setting up Conversation Orchestrator/Orchestrator. The Memory Store SID goes into your conversation service config.

**Python**
```python
import os, requests

account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]

store = requests.post(
    "https://memory.twilio.com/v1/Services",
    auth=(account_sid, auth_token),
    json={
        "uniqueName": "my-app-memory",
        "friendlyName": "My App Memory Store"
    }
).json()

memory_store_sid = store["sid"]
print(memory_store_sid)
```

**Node.js**
```javascript
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;

const store = await fetch("https://memory.twilio.com/v1/Services", {
    method: "POST",
    headers: {
        "Authorization": "Basic " + btoa(`${accountSid}:${authToken}`),
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        uniqueName: "my-app-memory",
        friendlyName: "My App Memory Store",
    }),
}).then(r => r.json());

const memoryStoreSid = store.sid;
```

Use `memory_store_sid` when creating your Conversations Service in Conversation Orchestrator/Orchestrator. The two must be linked for automatic observation and summary extraction to work.

### Step 2 — Profiles

Profiles are **created automatically** when conversations flow through Conversation Orchestrator/Orchestrator — the conversation config determines how participants are resolved into profiles. You can also create or enrich profiles manually using traits.

**Create a profile manually with traits:**

**Python**
```python
profile = requests.post(
    f"https://memory.twilio.com/v1/Services/{memory_store_sid}/Profiles",
    auth=(account_sid, auth_token),
    json={
        "traits": {
            "Contact": {
                "phone": "+15558675310",
                "firstName": "Alyssa",
                "lastName": "Mock",
                "email": "[email protected]"
            }
        }
    }
).json()

profile_id = profile["id"]
```

**Node.js**
```javascript
const profile = await fetch(
    `https://memory.twilio.com/v1/Services/${memoryStoreSid}/Profiles`,
    {
        method: "POST",
        headers: {
            "Authorization": "Basic " + btoa(`${accountSid}:${authToken}`),
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            traits: {
                Contact: {
                    phone: "+15558675310",
                    firstName: "Alyssa",
                    lastName: "Mock",
                    email: "[email protected]",
                }
            }
        }),
    }
).then(r => r.json());

const profileId = profile.id;
```

**Look up a profile by phone number** (for inbound calls where you only have the caller's number):

**Python**
```python
lookup = requests.post(
    f"https://memory.twilio.com/v1/Services/{memory_store_sid}/Profiles/Lookup",
    auth=(account_sid, auth_token),
    json={"idType": "phone", "value": "+15558675310"}
).json()

profile_id = lookup["profiles"][0]["id"] if lookup.get("profiles") else None
```

### Step 3 — Observations

Observations are **extracted automatically** from conversations when a conversation becomes inactive or is closed, based on your conversation config. You don't need to write them manually for Conversation Orchestrator-managed conversations.

**If you run your own extraction** (custom pipeline outside Conversation Orchestrator), post results directly:

**Python**
```python
requests.post(
    f"https://memory.twilio.com/v1/Services/{memory_store_sid}/Profiles/{profile_id}/Observations",
    auth=(account_sid, auth_token),
    json={
        "observations": [
            {
                "content": "Customer asked about order #4521. Wants expedited shipping. Prefers SMS updates.",
                "source": "custom_extraction",
                "occurredAt": "2026-04-20T14:30:00Z",
                "conversationIds": [conversation_sid]
            }
        ]
    }
)
```

**Node.js**
```javascript
await fetch(
    `https://memory.twilio.com/v1/Services/${memoryStoreSid}/Profiles/${profileId}/Observations`,
    {
        method: "POST",
        headers: {
            "Authorization": "Basic " + btoa(`${accountSid}:${authToken}`),
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            observations: [{
                content: "Customer asked about order #4521. Wants expedited shipping. Prefers SMS updates.",
                source: "custom_extraction",
                occurredAt: new Date().toISOString(),
                conversationIds: [conversationSid],
            }]
        }),
    }
);
```

Batch up to 10 observations in one request.

### Step 4 — Recall Context Before Responding

Recall runs hybrid lexical + semantic search and returns the most relevant observations and summaries for an LLM prompt.

**Recommended: pass a `conversationId` from Conversation Orchestrator/Orchestrator.** Recall builds a contextually relevant query from the active conversation automatically — no need to craft one yourself.

**Python**
```python
recall = requests.post(
    f"https://memory.twilio.com/v1/Services/{memory_store_sid}/Profiles/{profile_id}/Recall",
    auth=(account_sid, auth_token),
    json={
        "conversationId": orchestrator_conversation_sid,
        "observationsLimit": 10,
        "summariesLimit": 3,
    }
).json()

observations = "\n".join(o["content"] for o in recall.get("observations", []))
summaries = "\n".join(s["content"] for s in recall.get("summaries", []))

system_prompt = f"""You are a helpful support agent.

Customer history:
{observations}

Recent summaries:
{summaries}"""
```

**Node.js**
```javascript
const recall = await fetch(
    `https://memory.twilio.com/v1/Services/${memoryStoreSid}/Profiles/${profileId}/Recall`,
    {
        method: "POST",
        headers: {
            "Authorization": "Basic " + btoa(`${accountSid}:${authToken}`),
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            conversationId: orchestratorConversationSid,
            observationsLimit: 10,
            summariesLimit: 3,
        }),
    }
).then(r => r.json());

const context = [
    ...recall.observations.map(o => o.content),
    ...recall.summaries.map(s => s.content),
].join("\n");
```

**Other Recall modes:**

| Mode | How | When to use |
|------|-----|-------------|
| Conversation ID (recommended) | `"conversationId": orchestrator_sid` | Active Conversation Orchestrator/Orchestrator conversation — query is generated from conversation context |
| Custom query | `"query": "your question"` | Custom pipelines outside Conversation Orchestrato