Documentation

Voice integration patterns

Every Northsun (formerly Mnemix) voice integration follows the same lifecycle: recall context before the first useful turn, let the voice platform run the conversation, submit the completed interaction after hangup, and verify the write-back with a later read. The voice platform owns the call; Northsun is the memory and enrichment layer the surrounding application calls.

The platform-neutral architecture

platform call-start event
  -> verify the platform request
  -> normalize phone number and stable call ID
  -> POST /v1/recall_and_enrich
  -> select safe, relevant context
  -> continue with a useful fallback if context is unavailable

platform call-end event
  -> verify and deduplicate the event
  -> normalize transcript and outcome
  -> POST /v1/calls/end
  -> retain the acknowledgement and redacted correlation data
  -> later verify the expected history with recall or caller lookup

The frozen public caller-memory surface has exactly three endpoints:

  • POST /v1/recall_and_enrich
  • POST /v1/calls/end
  • GET /v1/caller/{phone_number}

Platform-specific guides translate vendor events into this lifecycle. They document custom integrations; they do not imply native, certified, or vendor-endorsed partnerships.

Recall before the agent needs context

Call recall_and_enrich from your server when the platform provides a verified call-start event. Supply the caller number and a stable session or call identifier when available:

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

The response distinguishes caller profile, prior-call memory, and nullable person, company, and phone enrichment blocks. Handle each branch independently. An unknown caller, missing enrichment, or degraded memory read must still reach a useful first-contact conversation.

The trigger field records whether your integration fired at ringing or answered. Do not assume it changes server behavior beyond the documented contract.

Northsun is designed for sub-300ms voice recall. That exact phrase describes design intent, not a measured percentile or an end-to-end guarantee. Your platform hook, server, network, mapping logic, and model all contribute to the caller’s perceived delay. Choose a timeout from your own measurements.

Select context; do not dump the response

Treat the recall response as input to an application policy:

  • Use prior interaction history only when it is relevant to the current line or workflow.
  • Keep an enriched name or company as contextual evidence, not identity verification.
  • Do not reveal sensitive history before the caller is appropriately identified.
  • Preserve an unknown-caller greeting that works without optional context.
  • Log correlation and timing information without storing secrets or raw personal data unnecessarily.

The current REST response does not prove that every item carries provenance, policy, or bi-temporal state. Governed-context substrate and future serving direction are documented separately.

Write back after every completed termination path

Map the platform’s final event to calls/end. Normalize the transcript into {role, text, ts_ms} entries and use one of the documented outcomes:

curl -i -sS -X POST https://mcp.mnemix.ai/v1/calls/end \
  -H "Authorization: Bearer $MNEMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "platform_call_123",
    "phone_number": "+15551234567",
    "transcript": [
      {"role":"agent","text":"How can I help?","ts_ms":0},
      {"role":"user","text":"Please call Tuesday.","ts_ms":2100}
    ],
    "duration_s": 18,
    "outcome": "callback_requested"
  }'

The success response is 204 No Content. Do not parse a body. See Hangup, and what happens next for exactly what's guaranteed by the time that response returns.

Voice platforms often retry webhooks. Deduplicate with the platform’s stable call ID in your own integration. Avoid automatic repeated write-back when the state of an earlier attempt is unknown.

Inspect and troubleshoot outside the live call

Use GET /v1/caller/{phone_number} for a read-only profile check. It does not create a caller or trigger enrichment, and an unknown number returns 404.

A useful support receipt contains:

  • UTC timestamps;
  • endpoint and HTTP status;
  • redacted platform call/session ID;
  • recall trace_id when returned;
  • whether enrichment was partial or memory was degraded;
  • the later read used to verify write-back.

Do not include bearer tokens or unnecessary transcript/PII content.

Platform guides

Before production, run the Quickstart, Errors and retries, and Production readiness gates with a controlled caller and the exact deployed platform configuration.