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

> Read, add, update, and delete the facts your agents remember about each contact across conversations, using the Callers API.

Contact memory lets your agents remember facts about a person between conversations, such as "prefers to be called after 5 pm" or "already renewed their contract". Callers writes memories automatically after conversations, and the API lets you read them, seed them from your CRM before the first call, correct them, and delete them.

See [Contact memory](https://docs.callers.ai/documentation/contacts/contact-memory.md) for how agents use memories and the per-agent settings.

## How memories work

* A memory has a short `name` (up to 200 characters) and a `text` (up to 5,000 characters).
* Each memory is tied to a contact and the contact's phone number in your account.
* Before a conversation, the agent loads the contact's current memories: memories for that contact, memories for the same phone number in the same agent, and, unless the agent turns off account-wide memories, memories for the same phone number from any agent in the account.
* Memories are versioned. Updating a memory creates a new version and marks the previous one `OUTDATED`. Deleting marks it `DELETED`. Only `ACTUAL` memories are used in conversations.

| Status | Meaning |
| - | - |
| `ACTUAL` | Current. Used by agents. |
| `OUTDATED` | Replaced by a newer version (see `previousMemoryId` on the new one). |
| `DELETED` | Deleted. Kept for history, never used. |

## Memory object

**id** `string`

Memory ID.

**name** `string`

Short label, for example `Communication preference`.

**text** `string`

The remembered fact.

**status** `string`

`ACTUAL`, `OUTDATED`, or `DELETED`.

**phoneNumber** `string`

Contact phone number (digits only).

**contactId** `string`

Contact ID, when the memory is linked to a contact.

**campaignId** `string`

Agent ID where the memory was created. Also returned as `agentId`.

**previousMemoryId** `string`

The version this memory replaced, if any.

**createdAt** `string`

ISO 8601 timestamp.

**updatedAt** `string`

ISO 8601 timestamp.

## Endpoints

| Method and path | What it does |
| - | - |
| `GET /contacts/{contactId}/memories` | List a contact's memories. Optional `status` filter. |
| `POST /contacts/{contactId}/memories` | Add a memory to a contact. |
| `DELETE /contacts/{contactId}/memories` | Delete all of a contact's memories. Returns `{ "count": n }`. |
| `GET /agents/{agentId}/contacts/{phoneNumber}/memories` | List memories by agent and phone number. Optional `status` filter. |
| `POST /agents/{agentId}/contacts/{phoneNumber}/memories` | Add a memory to the agent's contact with that phone number. |
| `PATCH /memories/{memoryId}` | Update a memory's text (creates a new version). |
| `DELETE /memories/{memoryId}` | Delete one memory. |

The phone-number routes are convenient when your system knows the phone number but not the Callers contact ID. Pass the number as digits with an optional leading `+` (URL-encode the `+` as `%2B`). Adding a memory by phone number requires the contact to already exist in that agent.

## Seed memories before the first call

Add what your CRM already knows so the agent doesn't ask again.

```bash cURL theme={"dark"}
curl -X POST "https://api.callers.ai/contacts/$CONTACT_ID/memories" \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Account status", "text": "Customer since March 2025; contract renewal due 30 Nov 2026."}'
```

```javascript Node.js theme={"dark"}
const res = 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: "Account status",
    text: "Customer since March 2025; contract renewal due 30 Nov 2026.",
  }),
});
const { data: memory } = await res.json(); // status 201
```

```python Python theme={"dark"}
memory = requests.post(
    f"https://api.callers.ai/contacts/{contact_id}/memories",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={
        "name": "Account status",
        "text": "Customer since March 2025; contract renewal due 30 Nov 2026.",
    },
).json()["data"]
```

Or by agent and phone number:

```bash theme={"dark"}
curl -X POST "https://api.callers.ai/agents/$AGENT_ID/contacts/%2B14155552671/memories" \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Preferred time", "text": "Prefers calls after 5 pm local time."}'
```

## Read memories

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

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

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

Omit `status` to get every version, including outdated and deleted ones.

## Update a memory

`PATCH /memories/{memoryId}` with a new `text`. The response is the new version, with a new `id` and `previousMemoryId` pointing at the old one. Use the new ID for later updates.

```bash cURL theme={"dark"}
curl -X PATCH "https://api.callers.ai/memories/$MEMORY_ID" \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Renewed on 2 Nov 2026 for 12 months."}'
```

```javascript Node.js theme={"dark"}
const res = 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: "Renewed on 2 Nov 2026 for 12 months." }),
});
const { data: newVersion } = await res.json();
```

```python Python theme={"dark"}
new_version = requests.patch(
    f"https://api.callers.ai/memories/{memory_id}",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={"text": "Renewed on 2 Nov 2026 for 12 months."},
).json()["data"]
```

If two updates to the same memory race, one of them gets `409 Memory was modified concurrently`. Re-read the contact's memories and apply your change to the current version.

## Delete memories

```bash theme={"dark"}
# One memory
curl -X DELETE "https://api.callers.ai/memories/$MEMORY_ID" \
  -H "Authorization: $CALLERS_API_KEY"

# All memories for a contact (for example, on a data deletion request)
curl -X DELETE "https://api.callers.ai/contacts/$CONTACT_ID/memories" \
  -H "Authorization: $CALLERS_API_KEY"
```

Deleted memories are marked `DELETED` and are never used again in conversations.

## Agent settings that affect memory

You can control memory per agent in the dashboard or through the agent fields in `POST`/`PUT /agents`:

| Field | Effect |
| - | - |
| `turnOffContactMemories` | The agent neither reads nor writes memories. |
| `turnOffContactMemoryContribution` | The agent reads memories but doesn't add new ones. |
| `turnOffGlobalContactMemories` | The agent ignores memories created by other agents for the same phone number. |
| `useCustomContactMemoryPrompt` + `contactMemoryPrompt` | Custom instructions for what the agent should remember (up to 2,000 characters). |
| `contactMemoryTextLimit` | Maximum length of memory text the agent writes. |

## Best practices

* Keep each memory to one fact with a clear `name`. The agent reads them as context, so short, specific facts work best.
* Don't store secrets or payment data in memories.
* Mirror memories into your CRM by reading them after `CALL_FINISHED` webhooks, if your team needs them outside Callers.

## Related

> **[Contact memory in the dashboard](https://docs.callers.ai/documentation/contacts/contact-memory.md)**
>
> How agents use memory and how to review it per contact.

> **[Manage contacts](https://docs.callers.ai/api-reference/guides/manage-contacts.md)**
>
> Add and update the contacts memories belong to.


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