Documentation

Quickstart

Complete one Northsun (formerly Mnemix) caller-memory lifecycle against the frozen public REST contract: recall context before an interaction, submit the completed interaction, and verify the next recall sees it immediately.

Complete Installation first and keep MNEMIX_API_KEY in your shell or secret manager.

Host migration: the canonical platform host is moving to mcp.northsun.ai. During the transition mcp.mnemix.ai continues to serve the full surface unchanged — existing integrations keep working, no action required. When the successor host is generally available, responses from this host will carry a Deprecation header (RFC 9745) and a Link rel="successor-version" header pointing at the corresponding mcp.northsun.ai URL; a retirement date, if one is ever set, will be announced in advance with a Sunset header (RFC 8594). No cutoff is scheduled.

1. Recall before the interaction

Use a controlled test phone number. The route creates a caller record on a miss and returns caller memory plus any enrichment that completed within the request deadline.

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": "call_demo_01"
  }'

Inspect these fields:

  • known: whether the caller record existed before this request;
  • caller: profile fields and call count;
  • memory: summary and recent processed calls;
  • enrichment: nullable person, company, and phone blocks;
  • trace_id: correlation value for this recall;
  • timing_ms: measurements for this request, not a published benchmark;
  • degraded: present and true when an authenticated caller-memory read returned the safe degraded shape.

Do not block the conversation on a missing enrichment block, and do not treat enrichment as identity verification.

2. Submit the completed interaction

Reuse the session ID and send the normalized transcript after hangup:

curl -i -sS -X POST https://mcp.mnemix.ai/v1/calls/end \
  -H "Authorization: Bearer $MNEMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "session_id": "call_demo_01",
    "transcript": [
      {
        "role": "user",
        "text": "Please call me Tuesday morning.",
        "ts_ms": 0
      },
      {
        "role": "agent",
        "text": "I will record that callback request.",
        "ts_ms": 2400
      }
    ],
    "duration_s": 18,
    "outcome": "callback_requested"
  }'

A successful request returns 204 No Content. That status is more than an acknowledgement: the durable write and the cache write-through the next recall reads from are both complete before it's returned. See Hangup, and what happens next for the guarantee and what it does not cover — enrichment and the retry-net queue stay asynchronous.

3. Verify the write-back

Repeat the recall immediately, with a new session ID — no wait required:

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": "call_demo_02"
  }'

Verify the unique callback request appears in memory.summary or memory.recent_calls. If it does not, retain both trace IDs, the UTC timestamps, and the redacted session IDs. Follow Troubleshooting instead of creating an unbounded retry loop.

What this proves

When all three steps succeed and the later recall contains the controlled observation, you have proved:

  • API-key authentication and tenant scope for the test key;
  • request/response mapping for the frozen caller endpoints;
  • partial-enrichment handling;
  • the read-after-write guarantee for that controlled lifecycle — the next recall sees it immediately, not eventually.

It does not prove a vendor-platform mapping, a latency percentile, proactive Beacon behavior, or another tenant's configuration.

Next steps