Fundamentals

TypeScript / JavaScript Data Placement

Use Node.js 22.18 or newer and install the official SDK:

pnpm add @neutron-ai/sdk

The SDK works from TypeScript and JavaScript. The example uses TypeScript for explicit input types; JavaScript applications use the same imports and calls without the type annotations.

Provision the three Nuclei

Run provisioning from an authenticated administration process, not from an agent or browser:

import { NeutronAIClient } from "@neutron-ai/sdk";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`${name} is required`);
  }
  return value;
}

const baseUrl = requiredEnv("NEUTRON_API_URL");
const controlClient = new NeutronAIClient({
  baseUrl,
  token: requiredEnv("NEUTRON_WORKSPACE_API_KEY")
});

await controlClient.createNucleus({
  nucleusId: "product-knowledge-global",
  name: "Global product knowledge",
  placement: {
    mode: "global",
    guarantee: "none",
    notes: ["Approved global knowledge; no jurisdictional storage guarantee."]
  }
});

await controlClient.createNucleus({
  nucleusId: "support-operations-weur",
  name: "Western Europe support operations",
  placement: {
    mode: "regional",
    regionHint: "weur",
    r2LocationHint: "weur",
    guarantee: "best_effort_regional",
    notes: ["Latency preference only; not a legal residency boundary."]
  }
});

await controlClient.createNucleus({
  nucleusId: "regulated-cases-eu",
  name: "EU regulated case memory",
  placement: {
    mode: "jurisdictional",
    jurisdiction: "eu",
    regionalServicesRequired: true,
    metadataBoundaryRequired: true,
    geoKeyManagerRequired: false,
    guarantee: "jurisdictional_storage",
    notes: [
      "Requires the EU Durable Object jurisdiction and matching EU archive binding.",
      "Processing, logs, metadata, keys, retention, and contracts require separate verification."
    ]
  }
});

Creation is a one-time control-plane operation. Treat an already-existing Nucleus as an explicit deployment state instead of blindly retrying with changed placement.

Build the memory router

Construct one client per Nucleus with a token that can access only that boundary:

const globalMemory = new NeutronAIClient({
  baseUrl,
  token: requiredEnv("NEUTRON_GLOBAL_TOKEN"),
  nucleusId: "product-knowledge-global"
});

const westernEuropeMemory = new NeutronAIClient({
  baseUrl,
  token: requiredEnv("NEUTRON_WEUR_TOKEN"),
  nucleusId: "support-operations-weur"
});

const euRegulatedMemory = new NeutronAIClient({
  baseUrl,
  token: requiredEnv("NEUTRON_EU_TOKEN"),
  nucleusId: "regulated-cases-eu"
});

export function storeGlobalProductKnowledge(text: string) {
  return globalMemory.remember({
    scopeId: "kb:approved-products",
    type: "knowledge",
    privacyClass: "public",
    text
  });
}

export function storeWesternEuropeSupportLesson(text: string) {
  return westernEuropeMemory.remember({
    scopeId: "history:support-resolutions",
    type: "tool_lesson",
    privacyClass: "tenant",
    text
  });
}

export function storeEuRegulatedCase(input: {
  caseId: string;
  minimizedSummary: string;
}) {
  return euRegulatedMemory.remember({
    scopeId: `case:${input.caseId}`,
    type: "experience",
    privacyClass: "user_private",
    text: input.minimizedSummary,
    metadata: {
      dataClass: "eu-regulated-case",
      source: "approved-case-summary"
    }
  });
}

Do not accept the Nucleus ID, placement mode, privacy class, or unrestricted scope IDs from a browser or model. Expose domain-specific functions whose routing policy is fixed on the trusted server.

Recall EU case context

const euCaseContext = await euRegulatedMemory.agentContext({
  scopeIds: [
    "case:case-4821",
    "policy:eu-case-handling",
    "kb:approved-products"
  ],
  agentId: "agent:eu-case-support",
  task: "Prepare the next authorized case-support step.",
  privacyClasses: ["tenant", "user_private"],
  tokenBudget: 1_200,
  cachePolicy: {
    mode: "prefer_cache",
    keyMode: "intent_profile",
    ttlSeconds: 120,
    includeDynamicRag: true,
    allowSensitive: false
  }
});

All three scopes must exist inside regulated-cases-eu. The call cannot retrieve a scope from product-knowledge-global.

Verify jurisdictional readiness

Use the Nucleus token for day-to-day health and placement checks:

const placement = await euRegulatedMemory.getNucleusPlacement("regulated-cases-eu");
const health = await euRegulatedMemory.getNucleusHealth("regulated-cases-eu");

const blockingWarnings = new Set([
  "jurisdictional_do_subnamespace_unavailable",
  "jurisdictional_archive_bucket_missing"
]);

if (health.warnings.some((warning) => blockingWarnings.has(warning))) {
  throw new Error(`EU Nucleus is not ready: ${health.warnings.join(", ")}`);
}

console.info({ placement, health });

Return to the placement architecture and production checklist.

Global, Regional, and Jurisdictional Memory

Python