Contact memory

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

string

Memory ID.

string

Short label, for example Communication preference.

string

The remembered fact.

string

ACTUAL, OUTDATED, or DELETED.

string

Contact phone number (digits only).

string

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

string

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

string

The version this memory replaced, if any.

string

ISO 8601 timestamp.

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.

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."}'

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

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:

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

curl "https://api.callers.ai/contacts/$CONTACT_ID/memories?status=ACTUAL" \
  -H "Authorization: $CALLERS_API_KEY"

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();

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.

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."}'

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();

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

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

Contact memory in the dashboard

How agents use memory and how to review it per contact.

Manage contacts

Add and update the contacts memories belong to.

Get started

Guides

Webhooks

Endpoints

How memories work

Memory object

Endpoints

Seed memories before the first call

Read memories

Update a memory

Delete memories

Agent settings that affect memory

Best practices

Contact memory in the dashboard

Manage contacts

​How memories work

​Memory object

​Endpoints

​Seed memories before the first call

​Read memories

​Update a memory

​Delete memories

​Agent settings that affect memory

​Best practices

​Related

Contact memory in the dashboard

Manage contacts

How memories work

Memory object

Endpoints

Seed memories before the first call

Read memories

Update a memory

Delete memories

Agent settings that affect memory

Best practices

Related