@mnexium/sdk

Official Mnexium SDK for JavaScript/TypeScript. Add persistent memory, conversation history, user profiles, and agent state to your AI apps.

Works with OpenAI, Anthropic, and Google Gemini. Bring your own API key.

Installation

npm install @mnexium/sdk

Quick Start

import { Mnexium } from '@mnexium/sdk';

const mnx = new Mnexium({
  apiKey: 'mnx_...', // Optional - auto-provisions trial key if omitted
  openai: { apiKey: process.env.OPENAI_API_KEY },
});

// Get a Subject handle (no network call)
const alice = mnx.subject('user_123');
// Or auto-generate an ID:
const anon = mnx.subject();

// Simple one-off message
const response = await alice.process('Hello!');
console.log(response.content);

// Multi-turn chat with history
const chat = alice.createChat({ history: true, learn: true, recall: true });
await chat.process('My favorite color is blue');
await chat.process('What is my favorite color?'); // Remembers!

Core Concepts

Subject

A Subject is a logical identity (user, agent, org, device) that owns memory, profile, and state. Creating a Subject is instant — no network call.

const alice = mnx.subject('user_123');

// Subject owns all resources
await alice.memories.search('hobbies');
await alice.memories.list();
await alice.profile.get();
await alice.state.get('preferences');
await alice.claims.get('favorite_color');
await alice.chats.list({ limit: 10 });

Chat

A Chat is a conversation thread with a stable chatId. Chats belong to a Subject.

const chat = alice.createChat({
  model: 'gpt-4o-mini',
  history: true,    // Include previous messages
  learn: true,      // Extract memories from conversation
  recall: true,     // Inject relevant memories into context
  profile: true,    // Include user profile in context
});

await chat.process('Hello!');
await chat.process('What did I just say?'); // Has history

Streaming

Real-time streaming responses with async iterators:

const stream = await chat.process({ content: 'Tell me a story', stream: true });

for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

// Metadata available after stream completes
console.log(stream.totalContent);  // Full accumulated text
console.log(stream.usage);         // Token counts
console.log(stream.chatId);        // Chat ID

// Or collect the full response at once
const stream2 = await chat.process({ content: 'Summarize', stream: true });
const text = await stream2.text();

Multi-Provider Support

The SDK auto-detects the provider from the model name:

const mnx = new Mnexium({
  openai: { apiKey: process.env.OPENAI_API_KEY },
  anthropic: { apiKey: process.env.ANTHROPIC_API_KEY },
  google: { apiKey: process.env.GOOGLE_API_KEY },
});

const alice = mnx.subject('user_123');
const chat = alice.createChat({ learn: true, recall: true });

// Switch models freely — memories are shared across providers
await chat.process({ content: 'I love hiking', model: 'gpt-4o-mini' });
await chat.process({ content: 'What do I love?', model: 'claude-sonnet-4-20250514' });
await chat.process({ content: 'Tell me my hobbies', model: 'gemini-2.0-flash' });

API Reference

Memories

// Add a memory
const mem = await alice.memories.add('User prefers dark mode', { source: 'settings' });

// List memories
const memories = await alice.memories.list({ limit: 50 });

// Semantic search
const results = await alice.memories.search('preferences', { limit: 5 });

// Get a specific memory
const memory = await alice.memories.get('mem_abc123');

// Update a memory
await alice.memories.update('mem_abc123', { text: 'Updated text' });

// Delete a memory
await alice.memories.delete('mem_abc123');

// List superseded memories
const old = await alice.memories.superseded();

// Restore a superseded memory
await alice.memories.restore('mem_abc123');

// Query recall events (which memories were used in a chat)
const recalls = await alice.memories.recalls({ chatId: 'chat_xyz' });

Real-time Memory Events

Subscribe to memory changes via SSE:

const events = alice.memories.subscribe();

for await (const event of events) {
  switch (event.type) {
    case 'memory.created':
      console.log('New memory:', event.data);
      break;
    case 'memory.superseded':
      console.log('Memory replaced:', event.data);
      break;
    case 'memory.deleted':
      console.log('Memory removed:', event.data);
      break;
  }
}

// Close the connection
events.close();

Event types: connected, memory.created, memory.updated, memory.deleted, memory.superseded, profile.updated, heartbeat

Claims (Structured Facts)

// Set a claim
await alice.claims.set('favorite_color', 'blue', { confidence: 0.95 });

// Get a specific slot
const color = await alice.claims.get('favorite_color');

// List all claim slots
const slots = await alice.claims.list();

// Get current truth (all active values)
const truth = await alice.claims.truth();

// Get claim history
const history = await alice.claims.history();

// Retract a claim
await alice.claims.retract('clm_abc123');

Profile

// Get profile
const profile = await alice.profile.get();

// Update profile fields
await alice.profile.update([
  { field_key: 'display_name', value: 'Alice' },
  { field_key: 'timezone', value: 'America/New_York' },
]);

// Delete a profile field
await alice.profile.deleteField('timezone');

Agent State

Persist key-value state for workflows, wizards, and agent continuity:

// Set state (with optional TTL)
await alice.state.set('current_task', { step: 3 }, { ttlSeconds: 3600 });

// Get state
const task = await alice.state.get('current_task');

// Delete state
await alice.state.delete('current_task');

Records (Structured Data)

Define typed schemas and work with structured records:

// Define a schema
await mnx.records.defineSchema(
  'deal',
  {
    title: { type: 'string', required: true },
    value: { type: 'number' },
    stage: { type: 'string' },
  },
  { displayName: 'Deal', description: 'Sales opportunities' }
);

// Insert a record
const deal = await mnx.records.insert('deal', {
  title: 'Acme Renewal',
  value: 500000,
  stage: 'negotiation',
});

// Get/update/delete
const found = await mnx.records.get('deal', deal.record_id);
await mnx.records.update('deal', deal.record_id, { stage: 'closed_won' });
await mnx.records.delete('deal', deal.record_id);

// Query/search
const wonDeals = await mnx.records.query('deal', {
  where: { stage: 'closed_won' },
  orderBy: '-value',
  limit: 10,
});
const similar = await mnx.records.search('deal', 'large enterprise renewals');

Integrations

Manage inbound pull and webhook connectors that map external payloads into prompt-ready keys:

// Create a pull integration
const integration = await mnx.integrations.create({
  name: 'Weather Forecast',
  mode: 'pull',
  scope: 'project',
  endpointUrl: 'https://api.open-meteo.com/v1/forecast',
  method: 'GET',
  allowLiveFetch: true,
  cacheTtlSeconds: 300,
  queryTemplate: {
    latitude: '40.7128',
    longitude: '-74.0060',
    current: 'temperature_2m,wind_speed_10m',
  },
  outputMap: [
    { key: 'weather_temp', path: 'current.temperature_2m' },
    { key: 'weather_wind', path: 'current.wind_speed_10m' },
  ],
});

// List / inspect / update / disable
const integrations = await mnx.integrations.list();
const sameIntegration = await mnx.integrations.get(integration.integration_id);
await mnx.integrations.update(integration.integration_id, { cacheTtlSeconds: 600 });
await mnx.integrations.delete(integration.integration_id);

// Execute a dry run or refresh cache
const preview = await mnx.integrations.test(integration.integration_id);
const refreshed = await mnx.integrations.sync(integration.integration_id, {
  subjectId: 'user_123',
  chatId: 'chat_456',
});

// Send a signed webhook payload
await mnx.integrations.webhook(integration.integration_id, {
  current: { temperature_2m: 14.1, wind_speed_10m: 13.8 },
}, {
  secret: 'whsec_...',
  eventId: 'evt_123',
});

console.log(preview.values.weather_temp);
console.log(refreshed.cache_written);

Chat History

// List recent chats
const chats = await alice.chats.list({ limit: 10 });

// Read messages from a specific chat
const messages = await alice.chats.read('chat_abc123');

// Delete a chat
await alice.chats.delete('chat_abc123');

System Prompts

// Create a prompt
const prompt = await mnx.prompts.create({
  name: 'Customer Support',
  promptText: 'You are a helpful customer support agent...',
  isDefault: true,
});

// List all prompts
const prompts = await mnx.prompts.list();

// Update a prompt
await mnx.prompts.update(prompt.id, { promptText: 'Updated instructions...' });

// Preview which prompts will be injected
const resolved = await mnx.prompts.resolve({ subjectId: 'user_123' });

// Use in chat
const chat = alice.createChat({ systemPrompt: prompt.id });

// Delete a prompt
await mnx.prompts.delete(prompt.id);

Configuration

const mnx = new Mnexium({
  apiKey: 'mnx_...',           // Optional — auto-provisions trial key
  baseUrl: 'https://mnexium.com/api/v1', // API base URL
  timeout: 30000,              // Request timeout (ms)
  maxRetries: 2,               // Retry count for failed requests
  openai: { apiKey: '...' },   // OpenAI config
  anthropic: { apiKey: '...' }, // Anthropic config
  google: { apiKey: '...' },   // Google config
  defaults: {                  // Default options for all process() calls
    model: 'gpt-4o-mini',
    learn: true,
    recall: false,
    profile: false,
    history: true,
    memoryPolicy: 'mp_sales_v1', // Or false to disable policy for a request
  },
});

Mnx Parameters

Every process() and chat.process() call supports these options:

Parameter	Type	Default	Description
model	string	'gpt-4o-mini'	Model to use
learn	boolean/'force'	true	Extract memories from conversation
recall	boolean	false	Inject relevant memories into context
profile	boolean	false	Include user profile in context
history	boolean	true	Prepend previous messages from this chat
log	boolean	true	Save messages to chat history
summarize	boolean/string	false	'light', 'balanced', or 'aggressive'
systemPrompt	boolean/string	true	true (auto), false (skip), or prompt ID
memoryPolicy	string/boolean	—	Policy ID string to force a policy, or false to disable policy for this request
records	object	—	Records controls: `learn: 'force'
stream	boolean	false	Enable streaming response
metadata	object	—	Custom metadata attached to saved logs

Memory policy fallback header: the SDK also sends x-mnx-memory-policy when memoryPolicy is set.

• memoryPolicy: false -> x-mnx-memory-policy: false
• memoryPolicy: 'mp_abc123' -> x-mnx-memory-policy: mp_abc123

Records extraction controls:

const response = await mnx.process({
  content: 'Extract and save order details',
  records: {
    learn: 'force',            // 'force' | 'auto' | false
    tables: ['orders'],        // Optional allowlist
    sync: true,                // Wait for write completion
    recall: true,              // Include prior records in context
  },
});

console.log(response.records); // Sync extraction metadata (when returned by backend)

Trial Keys

If you don't provide an API key, Mnexium auto-provisions a trial key:

const mnx = new Mnexium({
  openai: { apiKey: process.env.OPENAI_API_KEY },
});

const alice = mnx.subject('user_123');
await alice.process('Hello!');

// Get the provisioned key to save it
const trial = mnx.getTrialInfo();
console.log('Save this key:', trial?.key);

Claim your trial key at mnexium.com/claim.

Error Handling

import { Mnexium, AuthenticationError, RateLimitError, APIError } from '@mnexium/sdk';

try {
  await alice.process('Hello!');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Current: ${error.current}, Limit: ${error.limit}`);
  } else if (error instanceof APIError) {
    console.error(`API error ${error.status}: ${error.message}`);
  }
}

Raw Response

Access the full API response for advanced use:

const response = await chat.process('Hello!');
console.log(response.raw);    // Full API response object
console.log(response.chatId); // Chat ID
console.log(response.usage);  // { promptTokens, completionTokens, totalTokens }

Examples

See the examples/ directory for runnable demos:

Example	Description
npm run hello	Hello world — chat, history, recall
npm run streaming	Real-time streaming responses
npm run events	Real-time memory event subscriptions
npm run memories	Add, list, search, delete memories
npm run claims	Claims extraction and manual setting
npm run state	Agent state with TTL
npm run profile	User profiles
npm run records	Structured records (schemas, CRUD, query, search)
npm run prompts	System prompt management
npm run multi	Multi-provider (OpenAI, Claude, Gemini)
npm run full	Full API demo

TypeScript

Full TypeScript support with exported types:

import type {
  MnexiumConfig,
  ChatOptions,
  ProcessOptions,
  ProcessResponse,
  ChatHistoryItem,
  StreamChunk,
  MemoryEvent,
} from '@mnexium/sdk';

import { StreamResponse, EventStream } from '@mnexium/sdk';

Supported Models

• OpenAI: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo, o1, o1-mini, o3
• Anthropic: claude-3-opus, claude-3-sonnet, claude-3-haiku, claude-3-5-sonnet, claude-sonnet-4
• Google Gemini: gemini-2.0-flash-lite, gemini-2.5-flash, gemini-1.5-pro, gemini-1.5-flash

Links

• Documentation
• Blog
• Sign Up

License

MIT