> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact memory

> Let agents remember facts and preferences about each contact across conversations, and manage those memories in the app or through the API.

Contact memory lets your agents remember what they learned about a person. After each conversation, Callers saves short facts such as preferences, objections, scheduling details, and things the contact asked you to avoid. The next time any of your agents talks to that contact, it starts with that context instead of from scratch.

For example, if a contact said "I only take calls after 6 pm" or "We already use another provider", the next call can open with that in mind. Memories are shared across channels, so a Text agent benefits from what a Voice agent learned (see [Multichannel agents](https://docs.callers.ai/documentation/get-started/multichannel.md#contact-memory-across-channels)).

## How it works

**1. The conversation ends**

During post-call analysis, Callers reviews the transcript together with the contact's existing memories.

**2. Memories are added, updated, or removed**

New facts are saved, outdated facts are replaced, and facts that are no longer true are removed. Each memory is a short note, by default up to 200 characters.

**3. The next conversation starts with context**

When the contact is called or messaged again, the agent receives their memories as part of its instructions: up to 30 memories plus up to 10 **boundaries** (things the contact asked you to avoid). Memories from the same agent come first, then profile facts, then the newest of the rest.

### What gets remembered

Memories are grouped by type so the agent can use them appropriately:

* **Boundaries:** things the contact asked you not to do, such as "don't call my work number". These are always given priority.
* **Notes:** preferences, objections, scheduling details, profile facts, and contact details.

Some notes are lasting facts (for example, a job title). Others are about a moment in time (for example, "on vacation until next week"); those expire automatically after at most 90 days.

No memories are saved from a conversation that contained sensitive data when your account restricts sensitive content. See [Security and privacy](https://docs.callers.ai/documentation/account/security-and-privacy.md).

### Memories shared between agents

Each memory records the agent it came from. By default, every agent both reads and adds to a shared, account-wide pool of memories for each phone number. You can change that per agent with the settings below.

## Agent settings

Open the agent, click **Edit**, open **Technical Settings**, and find **Contact Memory**. These settings are available on voice agents (inbound and outbound). All are off by default, which means memory is fully on.

| Setting | What it does |
| :- | :- |
| **Turn Off Contact Memories** | The agent neither reads nor saves memories. The other options are hidden. |
| **Turn Off Contact Memory Contribution** | The agent still reads the shared memories but doesn't add or update memories from its own calls. |
| **Turn Off Global Contact Memories** | The agent only reads memories created by its own calls and ignores the shared pool. It still contributes its memories for other agents. |
| **Use Custom Contact Memory Prompt** | Shows a **Contact Memory Prompt** field (up to 2,000 characters) where you tell the agent which details to remember and prioritize. Standard safety and evidence rules still apply. |

The maximum length of each memory (default 200 characters, range 50–1,000) can be set through the API with `contactMemoryTextLimit`.

The same settings are available on the agent through the API: `turnOffContactMemories`, `turnOffContactMemoryContribution`, `turnOffGlobalContactMemories`, `useCustomContactMemoryPrompt`, and `contactMemoryPrompt`.

> [!TIP]
>
> Use a custom prompt to focus memory on what matters for your use case. For a renewal agent, for example: "Remember the contact's current plan, renewal date, and any competitor they mention. Ignore small talk."

> [!TIP]
>
> Turn off contribution on test or experimental agents so their conversations don't add memories that your production agents will use.

## View and edit memories in the app

Open a contact from an agent's list and go to the **Summary** tab. The **AI Context** section ("Let AI save and use info from conversations") lists what Callers remembers about the contact.

* **Add:** click **+**, type the memory, and click **Save**.
* **Edit:** change the text and click **Save**.
* **Delete:** click delete and confirm with **Yes, Delete**.

When a conversation changes a contact's memories, the transcript shows an **AI Context Updated** block. Click **Manage** to open the editor.

![Three rows under a call transcript: AI Call finished with the call duration, AI Context Updated with a Manage link, and Post-Conversation Actions](https://mintcdn.com/voxiaai/UGuY0UNIphM-6pUX/images/documentation/contacts/ai-context-updated.png?fit=max\&auto=format\&n=UGuY0UNIphM-6pUX\&q=85\&s=e1edc8824f06cb27bbe49f3de4d5d603)

The AI Context Updated block under a call transcript, with the Manage link.

> [!NOTE]
>
> If you don't see **AI Context** on the Summary tab, contact [support@callers.ai](mailto:support@callers.ai) to turn it on for your account.

## Manage memories with the API

The [Contact memory API guide](https://docs.callers.ai/api-reference/guides/contact-memory.md) has the full endpoint reference with examples.

Use the API to load what you already know about a contact from your CRM before the first call, or to read memories back into your systems.

| Method | Path | What it does |
| :- | :- | :- |
| `POST` | `/contacts/{contactId}/memories` | Add a memory to a contact. |
| `POST` | `/agents/{agentId}/contacts/{phoneNumber}/memories` | Add a memory to the agent's contact with that phone number. |
| `GET` | `/contacts/{contactId}/memories` | List a contact's memories. |
| `GET` | `/agents/{agentId}/contacts/{phoneNumber}/memories` | List memories by agent and phone number. |
| `PATCH` | `/memories/{memoryId}` | Update a memory's text. |
| `DELETE` | `/memories/{memoryId}` | Delete one memory. |
| `DELETE` | `/contacts/{contactId}/memories` | Delete all of a contact's memories. |

The `/campaigns/{campaignId}/…` paths still work as aliases of the `/agents/{agentId}/…` paths.

### Add a memory

**name** `string` *required*

Short label for the memory, 1–200 characters.

**text** `string` *required*

The memory itself, 1–5,000 characters.

```bash cURL theme={"dark"}
curl -X POST "https://api.callers.ai/contacts/CONTACT_ID/memories" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Preferred contact time",
    "text": "Prefers calls after 6 pm on weekdays."
  }'
```

```javascript Node.js theme={"dark"}
const response = await fetch(
  `https://api.callers.ai/contacts/${contactId}/memories`,
  {
    method: "POST",
    headers: {
      Authorization: process.env.CALLERS_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Preferred contact time",
      text: "Prefers calls after 6 pm on weekdays.",
    }),
  }
);
const { data: memory } = await response.json();
console.log(memory.id);
```

```python Python theme={"dark"}
import os
import requests

response = requests.post(
    f"https://api.callers.ai/contacts/{contact_id}/memories",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={
        "name": "Preferred contact time",
        "text": "Prefers calls after 6 pm on weekdays.",
    },
)
memory = response.json()["data"]
print(memory["id"])
```

When you add by phone number, use the number with or without `+` (5–15 digits). A badly formatted number returns `400`.

```json Response (201) theme={"dark"}
{
  "status": "success",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Preferred contact time",
    "text": "Prefers calls after 6 pm on weekdays.",
    "status": "ACTUAL",
    "phoneNumber": "14155552671",
    "agentId": "507f1f77bcf86cd799439012",
    "campaignId": "507f1f77bcf86cd799439012",
    "contactId": "507f1f77bcf86cd799439013",
    "createdAt": "2026-10-26T14:03:00.000Z"
  }
}
```

### List memories

`GET /contacts/{contactId}/memories` returns all of a contact's memories. Add `?status=ACTUAL` to get only current ones.

| Status | Meaning |
| :- | :- |
| `ACTUAL` | Current memory, used in conversations. |
| `OUTDATED` | Replaced by a newer version, or expired. |
| `DELETED` | Deleted. |

```bash cURL theme={"dark"}
curl "https://api.callers.ai/contacts/CONTACT_ID/memories?status=ACTUAL" \
  -H "Authorization: YOUR_API_KEY"
```

```javascript Node.js theme={"dark"}
const response = await fetch(
  `https://api.callers.ai/contacts/${contactId}/memories?status=ACTUAL`,
  { headers: { Authorization: process.env.CALLERS_API_KEY } }
);
const { data: memories } = await response.json();
```

```python Python theme={"dark"}
response = requests.get(
    f"https://api.callers.ai/contacts/{contact_id}/memories",
    params={"status": "ACTUAL"},
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
)
memories = response.json()["data"]
```

### Update or delete a memory

`PATCH /memories/{memoryId}` with a new `text` creates a new version of the memory. The old version becomes `OUTDATED`, and its ID is kept in the new memory's `previousMemoryId`. Only `ACTUAL` memories can be updated.

`DELETE /memories/{memoryId}` marks a memory as `DELETED` and returns it. `DELETE /contacts/{contactId}/memories` deletes all of the contact's memories and returns the `count` deleted.

```bash cURL theme={"dark"}
curl -X PATCH "https://api.callers.ai/memories/MEMORY_ID" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Prefers calls after 7 pm on weekdays." }'
```

```javascript Node.js theme={"dark"}
await fetch(`https://api.callers.ai/memories/${memoryId}`, {
  method: "PATCH",
  headers: {
    Authorization: process.env.CALLERS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Prefers calls after 7 pm on weekdays." }),
});
```

```python Python theme={"dark"}
requests.patch(
    f"https://api.callers.ai/memories/{memory_id}",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={"text": "Prefers calls after 7 pm on weekdays."},
)
```

## FAQ

> **Do memories carry over between agents?**
>
> Yes, by default. Memories are shared across your account by phone number. Use **Turn Off Global Contact Memories** to keep an agent to its own memories only.

> **Can a contact ask to be forgotten?**
>
> Delete their memories from the **AI Context** section or with `DELETE /contacts/{contactId}/memories`.

> **Why did a memory disappear?**
>
> Memories about a moment in time expire after at most 90 days, and later conversations can update or remove memories that are no longer true. Fetch all statuses through the API to see the history.

## Related

> **[Post-call analysis](https://docs.callers.ai/documentation/using-callers/key-questions.md)**
>
> What else Callers extracts after each conversation.

> **[Variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md)**
>
> Pass structured contact data into the script.

> **[API reference](https://docs.callers.ai/api-reference/introduction.md)**
>
> Authentication and response format.

> **[Agent settings](https://docs.callers.ai/documentation/build-your-agent/agent-setup.md)**
>
> Other technical settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.