Three caller-memory endpoints, on purpose

Northsun is the memory and enrichment layer for AI agents. For the caller-memory lifecycle, its frozen public REST contract contains three endpoints:

• POST /v1/recall_and_enrich — recall same-number history and return available caller enrichment before the agent's first turn.
• POST /v1/calls/end — submit the completed interaction after hangup for durable write-back.
• GET /v1/caller/{phone_number} — read an existing caller profile without creating one or triggering enrichment.

That trio is intentionally small. It is not, however, the whole Northsun product surface. The hosted MCP server exposes an independently evolving tool contract for voice, chat, coding, and workflow agents. REST integrations can pin the three caller endpoints; MCP integrations should inspect tools/list and pin the tool schemas they depend on.

The contract follows the caller lifecycle

A returning-caller workflow has three distinct jobs:

1. Prepare: resolve the caller, retrieve prior-call memory, and add enrichment when available.
2. Record: submit what happened; the request writes the interaction durably, and downstream processing continues asynchronously.
3. Inspect: fetch the stored caller profile for support, verification, or dashboard use.

The REST surface maps those jobs directly. Your application still owns the agent, call control, prompts, and business actions. Northsun owns the memory-and-enrichment request boundary.

A small contract reduces integration drift

Every public endpoint becomes a compatibility obligation: request validation, authentication, SDK behavior, documentation, error handling, and versioning all have to agree. A focused caller API gives builders fewer paths to reconcile.

It also keeps internal implementation choices behind the boundary. Builders do not need to manage enrichment-provider requests, storage tiers, or background interaction processing to complete the caller loop. They do need to handle the behavior the contract actually promises:

• Enrichment is nullable and must not block the interaction.
• calls/end commits the interaction durably before returning 204 No Content. That statement covers the interaction record only; enrichment and other background work follow their own timing.
• caller/{phone_number} returns 404 for an unknown caller and has no creation side effect.
• Authentication, validation, rate-limit, and service errors remain explicit non-2xx responses.

Those details are more important than the endpoint count. A small API is useful only when its lifecycle and failure semantics are clear.

REST stability and MCP reach solve different needs

Use the frozen REST trio when you want a narrow server-to-server caller integration with a stable route boundary. Use hosted MCP when an MCP-compatible agent client needs Northsun tools directly.

The distinction prevents two common mistakes:

• Treating every MCP tool as a new frozen public REST endpoint.
• Assuming the three REST routes limit Northsun to voice agents.

Voice is a primary use case because context has to arrive before the conversation stalls. The same memory-and-context problem also appears in chat, coding, and workflow agents; MCP is the current surface for evaluating those broader agent workflows.

Prove one loop before expanding it

A useful integration test is concrete:

1. Call recall_and_enrich with a controlled test number and session ID.
2. Confirm the response remains useful when enrichment fields are null.
3. Submit a short synthetic transcript to calls/end, with a unique phrase in its first user turn, and expect an empty 204 response.
4. Verify the phrase shows up as the summary of the newest memory.recent_calls entry on the next read, and read once more briefly before treating a miss as a failure: a recall already in flight, or a failed refresh of the recall cache, can lag until that cached view is refreshed.
5. Read the caller profile and retain trace information for any mismatch.

That proves the boundary your agent will rely on without turning an architecture claim into a runtime claim.

Next steps

• Follow the exact request and response shapes in the API reference.
• Build the lifecycle with the quickstart.
• Connect an agent client through the independently evolving MCP server.
• Review authentication and tenant scope before using production data.

Choose Northsun as your agent memory layer.