Get access

Get started · 5 / 42

What is caller memory?

Caller memory uses the incoming phone number to fetch the tenant's caller record, prior-call history, and enrichment before your voice agent needs it.

Caller memory is the application pattern of using an incoming phone number to request the tenant's known caller record, prior-call history, and available enrichment before the agent needs that context. A number identifies a caller record; it does not prove which person is holding the phone.

That's the whole definition. Everything below is what it takes to actually deliver it.

Why caller memory starts earlier than chat history

A signed-in chat application often has an account identifier before it retrieves history. A phone call may begin with only an incoming number and a platform call ID. The surrounding application therefore needs a pre-conversation step that maps the number to tenant-scoped history and handles the case where no prior record exists.

Northsun supports that caller-memory lifecycle through the frozen REST surface. Broader chat, coding, and workflow context is exposed through an evolving hosted MCP surface and has a different stability and proof boundary.

What resolves, and when

A call-start request can combine two inputs:

  1. Memory lookup. Same-number tenant history: whether a caller record exists and which processed calls are available.
  2. Optional enrichment. Can include nullable person, company, and phone context from Trestle and Twilio Lookup.

Both appear in one response shape. known describes whether the caller record existed before the request; it does not verify a human identity. Any enrichment branch can be null, and a useful first-contact flow must work without it. See Enrichment for field and privacy boundaries.

Northsun is designed for sub-300ms voice recall. That is a design phrase, not a measured percentile or an end-to-end guarantee. Choose the application timeout and fallback from measurements of your complete platform path.

Where it lives in the API

Caller memory isn't a separate product — it's what POST /v1/recall_and_enrich returns. Call it once, before the agent's first turn:

curl -sS -X POST https://mcp.northsun.ai/v1/recall_and_enrich \
  -H "Authorization: Bearer $NORTHSUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551234567", "trigger": "answered" }'

The response carries caller (the tenant's current profile record), memory (processed prior-call summary and recent history), and nullable enrichment. Select only context appropriate for the current interaction, and use a neutral opening until the caller is identified through an appropriate mechanism.

Next steps