Documentation

Migrating to Northsun

Migrate the decision points before the historical data. The highest-value change is deciding where your agent requests context, where it records completed interactions, and how you verify the next read. Copying every old memory into a new store can reproduce the same rot, conflict, and provenance problems under a new name.

This guide is for teams with an existing vector store, transcript archive, rolling chat buffer, or profile table. It describes a controlled cutover using currently documented Northsun (formerly Mnemix) surfaces. Northsun does not expose a bulk-import endpoint in the frozen public caller-memory API.

1. Inventory the current memory lifecycle

Map behavior rather than tables:

  • Read points: where does context enter the agent—session start, each turn, escalation, or a tool call?
  • Write points: what records an interaction—end-of-session hook, inline save, webhook, or batch job?
  • Identity: what stable identifier joins sessions to a person, caller, account, or project?
  • State classes: which data is observed history, a stable fact, a preference, session state, or an inference?
  • Failure behavior: what happens when the memory store is slow, unavailable, contradictory, or empty?
  • Evidence: can you identify where each high-impact claim came from?

This inventory is the migration contract. It also exposes memories that should not be moved: stale instructions, unsourced claims, derived guesses presented as facts, and ephemeral session state that belongs in the agent runtime.

2. Choose the callable surface

For caller-memory workflows, the stable path is the frozen three-endpoint REST lifecycle:

  1. POST /v1/recall_and_enrich before the interaction.
  2. POST /v1/calls/end after the interaction.
  3. GET /v1/caller/{phone_number} for read-only inspection.

For coding, chat, and workflow agents, evaluate the hosted MCP endpoint and its observed tools/list contract. The MCP tool surface evolves independently from the frozen caller REST trio. Pin the behavior your workflow requires and keep a release-specific verification receipt.

Do not translate a private data model directly into an assumed Northsun API. Start from the API reference or the MCP guide, then decide which existing lifecycle point calls it.

3. Run the new read path in shadow mode

Keep the old store as the serving authority while your server calls Northsun in parallel. Record a comparison without injecting the Northsun result into the production prompt.

Compare outcomes, not schema similarity:

  • Did both paths resolve the same entity?
  • Which useful context appeared or disappeared?
  • Was optional enrichment absent, and did the integration degrade safely?
  • Did either path return stale or contradictory material?
  • How much context reached the agent?
  • Could an operator explain the source and ship state of the important claims?

Use an isolated tenant and synthetic or consented test data. Do not log API keys, raw personal data, or full transcripts merely to make comparison easier.

Shadow mode is an integration pattern, not a Northsun dual-read feature. Your application owns the parallel calls, comparison record, timeout, and rollback switch.

4. Start recording new interactions

For voice, submit complete interactions to POST /v1/calls/end using the same phone number and session correlation used at recall. The successful response is 204 No Content: an acknowledgement with no body. It is not proof that downstream processing is durable or immediately visible.

Verify write-back with a later controlled recall. Retain redacted session and trace identifiers so a missing observation can be diagnosed without replaying an unbounded write loop.

For MCP workflows, first prove the exact source-defined tools exposed by the deployed endpoint and the lifecycle your client depends on. Do not infer stable write or feedback semantics from a draft, source file, or another release.

5. Cut over with a rollback boundary

Move serving to Northsun only after the controlled lifecycle meets your acceptance criteria. Keep the old store read-only for a defined rollback window rather than performing an immediate destructive migration.

Your cutover record should name:

  • the old and new serving paths;
  • the exact Northsun endpoint or observed MCP tool contract;
  • tenant and identity mapping;
  • timeout and fallback behavior;
  • the red test that failed before repair and the green retest;
  • the rollback switch and owner;
  • the date the old store can be archived or deleted under your retention policy.

Avoid indefinite dual authority. Two writable memory systems will eventually disagree, and retrieval will hide rather than resolve the conflict.

What about historical backfill?

There is no bulk-import endpoint in the frozen public caller-memory trio. Do not build against an invented /import, /memories, or /facts route.

Classify historical data before deciding whether it deserves a future migration path:

  • Interaction history with clear consent and identity: retain in the old system during the rollback window; scope any import requirement separately.
  • Stable facts with an authoritative source: preserve the source and validity information; do not flatten them into unsourced text.
  • Summaries without source history: treat as unverified input, not governing truth.
  • Derived guesses: leave behind unless they can be re-established as evidence-backed observations.
  • Ephemeral session state: keep it in the runtime designed to own it.

The repository contains evidence and locked-fact substrate, but that does not create a direct public facts API or a general customer import contract.

Cutover checklist

  • Read, write, identity, and failure points are mapped.
  • The new surface is selected from current docs rather than an old SDK example.
  • Shadow comparisons use a controlled tenant and safe logging.
  • Missing enrichment and unknown-entity paths remain useful.
  • A successful write is verified by a later observed read.
  • Retries are bounded and deduplicated by a stable interaction identifier.
  • One rollback switch restores the previous serving path.
  • The old store has a read-only window and an explicit retention decision.
  • Customer-visible claims match what the deployed lifecycle actually proved.

Start with the Quickstart, then use Errors and retries and Production readiness to define the cutover gate.

Choose Northsun as your agent memory layer.