@mnemix-ai/livekit-kit

Mnemix integration kit for LiveKit Agents — direction-safe SIP caller-identity resolution, a single Northsun context-fetch call for voice.Agent({ instructions }), and session-end memory write-back via ctx.addShutdownCallback().

Package scope note: published as @mnemix-ai/livekit-kit for now, same provisional scope as its siblings (vapi-kit, bland-kit, elevenlabs-kit, twilio-kit, retell-kit). @northsun-ai/core is the ratified target scope but is currently a phantom — declared as a dependency elsewhere in this repo, published by nothing. The scope string is isolated to this file's install line, package.json's name field, and the @mnemix-ai/client peerDependency only.

Why this kit looks different from its siblings

Every sibling kit (Vapi, Bland, ElevenLabs, Twilio, Retell) is built around a webhook: the vendor's platform POSTs to an HTTP endpoint you control, and the kit answers that request. LiveKit Agents has no such thing. A LiveKit Agent is a worker process that connects outward to the LiveKit server (ctx.connect()), authenticated at the SDK/transport level by LIVEKIT_URL/LIVEKIT_API_KEY/LIVEKIT_API_SECRET — there is no vendor-signed inbound request for this kit to receive or verify.

Two consequences follow directly:

1. No signature.ts. Every sibling kit ships an HMAC/shared-secret verifier for its webhook. This kit has nothing to verify — the LiveKit SDK's own connection already authenticates your worker to LiveKit. Adding a signature-verification module with nothing that would ever call it would be exactly the kind of cosmetic stub this repo's build discipline forbids.
2. One context-fetch path, not two. Every sibling kit splits into a webhook-driven "Path A" (inbound, vendor-initiated) and an inline "Path B" (outbound, initiated by your own code). LiveKit never initiates anything toward you — your own worker code is always the one that calls Mnemix, for both inbound and outbound telephony. fetchNorthsunContext() is the single entry point for both.

The direction-safety design (why this exists, not just what it does)

Twilio's TwiML webhook shipped a real HIGH-severity bug in twilio-kit (AGE-1021): reading the From field unconditionally enriched the tenant's own number on every outbound call, because From/To swap which one is the customer depending on Direction.

LiveKit's SIP participant attributes are built differently. Per LiveKit's own docs (docs.livekit.io/sip/sip-participant/, verified quotes in src/types.ts's file header):

| Attribute | Inbound | Outbound | |---|---|---| | sip.phoneNumber | the caller (customer) | the number dialed by the SIP participant (customer) | | sip.trunkPhoneNumber | the DID dialed into (tenant's own) | the trunk's own originating number (tenant's own) |

sip.phoneNumber names the customer in both directions — no direction branch is needed to pick the right field, unlike Twilio's From/To. resolveLiveKitCallerIdentity() (src/identity.ts) still computes and returns direction explicitly (via sip.ruleID, empty only for outbound), because the point of designing against this bug class is verifying what a field means for the direction you're in, not memorizing one vendor's specific quirk. test/identity.test.ts carries a direct regression test asserting phoneNumber is never the trunk's own number, in either direction.

Failure posture

fetchNorthsunContext() and handleLiveKitSessionEnd() never throw. fetchNorthsunContext()'s result carries mnemix.resolution, one of:

• "ok" — recall was attempted and Mnemix answered. known: false here is usually the ordinary "new caller" case — but this kit does not currently distinguish that from a server-side degraded read: /v1/recall_and_enrich can answer 200 with known: false, degraded: true, caller.total_calls: null when the contact lookup itself threw. Consumers who must tell those apart should read degraded off the raw response — this kit does not read it. (Known gap; the resolution enum is not four-valued today.)
• "identity_unresolved" — this kit could not determine an E.164 phone number for the participant at all (missing/malformed SIP attributes, or a non-SIP session with no phone_number override). Mnemix was never called. This is a LiveKit-side configuration problem, not a statement about the caller — it is logged at error level and is distinguishable from known: false precisely so it doesn't get silently read as "new caller."
• "recall_failed" — an E.164 number was resolved, but the recall_and_enrich call itself errored or timed out.

handleLiveKitSessionEnd() refuses ({ ok: false }, Mnemix never called) rather than writing an unattributable call when either the phone number or the session_id cannot be resolved — logged loudly, not silently defaulted.

Install

npm install @mnemix-ai/livekit-kit @mnemix-ai/client @livekit/agents

Quickstart

See examples/agent.ts for a full worker entry function, and QUICKSTART.md for the step-by-step.

import { fetchNorthsunContext, handleLiveKitSessionEnd, mapChatHistoryToTranscript } from "@mnemix-ai/livekit-kit";

// Inside your agent's entry function, after ctx.connect() + ctx.waitForParticipant():
const northsun = await fetchNorthsunContext(
  { mnemix },
  { attributes: participant.attributes, session_id: ctx.room.name },
);

const session = new voice.AgentSession({ /* stt/llm/tts */ });
await session.start({ agent: new voice.Agent({ instructions: northsun.instructions }), room: ctx.room });

ctx.addShutdownCallback(async () => {
  await handleLiveKitSessionEnd(
    { mnemix },
    {
      attributes: participant.attributes,
      session_id: ctx.room.name,
      transcript: mapChatHistoryToTranscript(session.history.items),
      contextAuditId: northsun.mnemix.context_audit_id ?? undefined,
    },
  );
});

What you get back

• fetchNorthsunContext() → LiveKitPreCallContext: .variables (the same 12-field shape as every sibling kit), .instructions (ready to pass directly as new Agent({ instructions }) — named to match the vendor's own field, not the sibling kits' system_prompt), and .mnemix (trace id, resolution state, direction, timing).
• handleLiveKitSessionEnd() → { ok: boolean; error?: string }.
• resolveLiveKitCallerIdentity(attributes) → the raw identity-resolution result, if you want to make your own routing decisions before calling Mnemix.
• mapChatHistoryToTranscript(session.history.items) → converts LiveKit's ChatContext items into the transcript shape handleLiveKitSessionEnd expects.

This kit does not build a voice.Agent for you, does not choose your STT/LLM/TTS providers, and does not decide your call outcome — same scope boundary twilio-kit draws around raw telephony: it hands you enriched context and writes back what you tell it, nothing more.

No vendor SDK at runtime

@livekit/agents / @livekit/rtc-node are devDependencies only — used in test/sdk-cross-check.test.ts to verify this kit's hardcoded assumptions (ParticipantKind.SIP === 3, ChatMessage's role/textContent/createdAt shape) against the real, installed packages, and in examples/. The kit's runtime code takes plain Record<string, string> attributes and duck-typed chat items — it never imports @livekit/agents itself, so it has no exposure to that SDK's own churn.

What's proven, and what's still owed

Verified from LiveKit's own current published docs and shipped package sources (fetched 2026-08-19 — see src/types.ts's file header for exact quotes and citations):

• The SIP participant attribute reference table (sip.phoneNumber, sip.trunkPhoneNumber, sip.ruleID, sip.callID, sip.trunkID, sip.callStatus).
• ParticipantKind.SIP = 3 and Participant.attributes: Record<string, string>, read from @livekit/rtc-node's own shipped protobuf types, cross-checked in test/sdk-cross-check.test.ts.
• JobContext.addShutdownCallback()'s signature and the fact that shutdown callbacks run after room.disconnect() and are awaited before the worker considers the job done, read from @livekit/agents' own shipped job.d.ts / ipc/job_proc_lazy_main.ts.
• AgentSession.history: ChatContext and ChatMessage's role/textContent/createdAt shape, same method, cross-checked with a real constructed ChatMessage in test/sdk-cross-check.test.ts.

Still owed — none of the below can be proven without a real LiveKit project, a deployed worker, and a real phone call (see test/live-account.test.ts for the individually-armed falsifiers, all it.skip until genuinely run):

• That a real inbound SIP call actually produces a participant whose .attributes contains the documented sip.* keys.
• That sip.phoneNumber really is direction-consistent on a real outbound call, not just per the docs' prose — the load-bearing claim this kit is designed around.
• That .instructions passed to voice.Agent actually shapes the model's spoken behavior in a live session.
• That the shutdown callback's write actually lands in Mnemix before the worker process exits, under real conditions.
• Real end-to-end latency from ctx.connect() to fetchNorthsunContext() resolving, against a LiveKit worker's actual network path (which may differ from the Cloudflare-Worker-to-Mnemix path the other kits measure against).

This kit is not yet named on any public claim surface (scripts/aeo-audit.ts's forbidden-names list, web/src/app/integrations/page.tsx, tests/web-ai-discovery.test.ts) until those falsifiers close — same posture elevenlabs-kit and retell-kit shipped with.

License

MIT