@mnexium/sdk 0.2.0 → 0.2.1

package/README.md

@@ -224,6 +224,43 @@ const task = await alice.state.get('current_task');
 await alice.state.delete('current_task');
 ```
 
+### Records (Structured Data)
+
+Define typed schemas and work with structured records:
+
+```typescript
+// 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');
+```
+
 ### Chat History
 
 ```typescript
@@ -280,6 +317,7 @@ const mnx = new Mnexium({
     recall: false,
     profile: false,
     history: true,
+    memoryPolicy: 'mp_sales_v1', // Or false to disable policy for a request
   },
 });
 ```
@@ -298,9 +336,31 @@ Every `process()` and `chat.process()` call supports these options:
 | `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' | 'auto' | false`, `tables: string[]`, `sync: boolean`, `recall: boolean` |
 | `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:
+
+```typescript
+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:
@@ -362,6 +422,7 @@ See the [examples/](./examples/) directory for runnable demos:
 | `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 |

package/dist/index.d.mts

@@ -5,6 +5,17 @@
 interface ProviderConfig {
     apiKey: string;
 }
+type MnxRecordsLearnMode = 'force' | 'auto' | false;
+interface MnxRecordsConfig {
+    /** Enable record recall (inject existing records as context) */
+    recall?: boolean;
+    /** Records extraction mode: "auto" (best effort), "force" (must attempt), false (off) */
+    learn?: MnxRecordsLearnMode;
+    /** Whether extraction should be synchronous (blocking) */
+    sync?: boolean;
+    /** Restrict extraction to specific tables */
+    tables?: string[];
+}
 /** Default settings for all process() calls */
 interface MnexiumDefaults {
     /** Default model to use */
@@ -35,6 +46,10 @@ interface MnexiumDefaults {
     temperature?: number;
     /** Force regenerate trial key on every request (for testing) */
     regenerateKey?: boolean;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Default records behavior for process/chat requests */
+    records?: MnxRecordsConfig;
 }
 interface MnexiumConfig {
     /** Mnexium API key. If omitted, a trial key will be auto-provisioned. */
@@ -82,6 +97,10 @@ interface ChatSessionOptions {
     temperature?: number;
     /** Custom metadata attached to saved logs */
     metadata?: Record<string, unknown>;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Records extraction/recall behavior */
+    records?: MnxRecordsConfig;
 }
 /** Options for creating a Chat */
 interface ChatOptions {
@@ -109,6 +128,10 @@ interface ChatOptions {
     temperature?: number;
     /** Custom metadata attached to saved logs */
     metadata?: Record<string, unknown>;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Records extraction/recall behavior */
+    records?: MnxRecordsConfig;
 }
 /** Options for listing chat history */
 interface ChatHistoryListOptions {
@@ -160,6 +183,10 @@ interface ChatProcessOptions {
     metadata?: Record<string, unknown>;
     /** Force regenerate trial key */
     regenerateKey?: boolean;
+    /** Override memory policy: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Override records extraction/recall behavior */
+    records?: MnxRecordsConfig;
 }
 /** Options for the simplified process() API */
 interface ProcessOptions {
@@ -195,6 +222,10 @@ interface ProcessOptions {
     metadata?: Record<string, unknown>;
     /** Force regenerate trial key (for key recovery) */
     regenerateKey?: boolean;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Records extraction/recall behavior */
+    records?: MnxRecordsConfig;
 }
 /** Response from process() */
 interface ProcessResponse {
@@ -216,6 +247,8 @@ interface ProcessResponse {
     provisionedKey?: string;
     /** Claim URL for trial key */
     claimUrl?: string;
+    /** Records extraction result metadata when sync records mode is enabled */
+    records?: unknown;
     /** Full raw response (for advanced use) */
     raw: ChatCompletionResponse;
 }
@@ -258,15 +291,10 @@ interface MnxOptions {
     metadata?: Record<string, unknown>;
     /** Force regenerate trial key (for key recovery) */
     regenerateKey?: boolean;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
     /** Records configuration */
-    records?: {
-        /** Enable record recall (inject existing records as context) */
-        recall?: boolean;
-        /** Enable record extraction: true = async, "sync" = await and return results (non-streaming only) */
-        learn?: boolean | 'sync';
-        /** Limit extraction to specific record types */
-        types?: string[];
-    };
+    records?: MnxRecordsConfig;
 }
 interface ChatCompletionOptions extends MnxOptions {
     /** Model to use (e.g., 'gpt-4o-mini', 'claude-3-sonnet', 'gemini-1.5-pro') */
@@ -305,6 +333,7 @@ interface MnxResponseData {
     subject_id: string;
     provisioned_key?: string;
     claim_url?: string;
+    records?: unknown;
 }
 interface ChatCompletionResponse {
     id: string;

package/dist/index.d.ts

@@ -5,6 +5,17 @@
 interface ProviderConfig {
     apiKey: string;
 }
+type MnxRecordsLearnMode = 'force' | 'auto' | false;
+interface MnxRecordsConfig {
+    /** Enable record recall (inject existing records as context) */
+    recall?: boolean;
+    /** Records extraction mode: "auto" (best effort), "force" (must attempt), false (off) */
+    learn?: MnxRecordsLearnMode;
+    /** Whether extraction should be synchronous (blocking) */
+    sync?: boolean;
+    /** Restrict extraction to specific tables */
+    tables?: string[];
+}
 /** Default settings for all process() calls */
 interface MnexiumDefaults {
     /** Default model to use */
@@ -35,6 +46,10 @@ interface MnexiumDefaults {
     temperature?: number;
     /** Force regenerate trial key on every request (for testing) */
     regenerateKey?: boolean;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Default records behavior for process/chat requests */
+    records?: MnxRecordsConfig;
 }
 interface MnexiumConfig {
     /** Mnexium API key. If omitted, a trial key will be auto-provisioned. */
@@ -82,6 +97,10 @@ interface ChatSessionOptions {
     temperature?: number;
     /** Custom metadata attached to saved logs */
     metadata?: Record<string, unknown>;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Records extraction/recall behavior */
+    records?: MnxRecordsConfig;
 }
 /** Options for creating a Chat */
 interface ChatOptions {
@@ -109,6 +128,10 @@ interface ChatOptions {
     temperature?: number;
     /** Custom metadata attached to saved logs */
     metadata?: Record<string, unknown>;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Records extraction/recall behavior */
+    records?: MnxRecordsConfig;
 }
 /** Options for listing chat history */
 interface ChatHistoryListOptions {
@@ -160,6 +183,10 @@ interface ChatProcessOptions {
     metadata?: Record<string, unknown>;
     /** Force regenerate trial key */
     regenerateKey?: boolean;
+    /** Override memory policy: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Override records extraction/recall behavior */
+    records?: MnxRecordsConfig;
 }
 /** Options for the simplified process() API */
 interface ProcessOptions {
@@ -195,6 +222,10 @@ interface ProcessOptions {
     metadata?: Record<string, unknown>;
     /** Force regenerate trial key (for key recovery) */
     regenerateKey?: boolean;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
+    /** Records extraction/recall behavior */
+    records?: MnxRecordsConfig;
 }
 /** Response from process() */
 interface ProcessResponse {
@@ -216,6 +247,8 @@ interface ProcessResponse {
     provisionedKey?: string;
     /** Claim URL for trial key */
     claimUrl?: string;
+    /** Records extraction result metadata when sync records mode is enabled */
+    records?: unknown;
     /** Full raw response (for advanced use) */
     raw: ChatCompletionResponse;
 }
@@ -258,15 +291,10 @@ interface MnxOptions {
     metadata?: Record<string, unknown>;
     /** Force regenerate trial key (for key recovery) */
     regenerateKey?: boolean;
+    /** Memory policy override: policy ID string, or false to disable policy for this request */
+    memoryPolicy?: string | false;
     /** Records configuration */
-    records?: {
-        /** Enable record recall (inject existing records as context) */
-        recall?: boolean;
-        /** Enable record extraction: true = async, "sync" = await and return results (non-streaming only) */
-        learn?: boolean | 'sync';
-        /** Limit extraction to specific record types */
-        types?: string[];
-    };
+    records?: MnxRecordsConfig;
 }
 interface ChatCompletionOptions extends MnxOptions {
     /** Model to use (e.g., 'gpt-4o-mini', 'claude-3-sonnet', 'gemini-1.5-pro') */
@@ -305,6 +333,7 @@ interface MnxResponseData {
     subject_id: string;
     provisioned_key?: string;
     claim_url?: string;
+    records?: unknown;
 }
 interface ChatCompletionResponse {
     id: string;

package/dist/index.js

@@ -96,7 +96,9 @@ var Chat = class {
       temperature: options.temperature ?? this.options.temperature,
       stream: options.stream,
       metadata: options.metadata ?? this.options.metadata,
-      regenerateKey: options.regenerateKey
+      regenerateKey: options.regenerateKey,
+      memoryPolicy: options.memoryPolicy ?? this.options.memoryPolicy,
+      records: options.records ?? this.options.records
     });
   }
 };
@@ -603,6 +605,11 @@ var ChatCompletionsResource = class {
     } else if (options.googleKey) {
       headers["x-google-key"] = options.googleKey;
     }
+    if (options.memoryPolicy === false) {
+      headers["x-mnx-memory-policy"] = "false";
+    } else if (typeof options.memoryPolicy === "string" && options.memoryPolicy.trim()) {
+      headers["x-mnx-memory-policy"] = options.memoryPolicy;
+    }
     const body = {
       model: options.model,
       messages: options.messages,
@@ -622,6 +629,7 @@ var ChatCompletionsResource = class {
         system_prompt: options.systemPrompt,
         metadata: options.metadata,
         regenerate_key: options.regenerateKey,
+        memory_policy: options.memoryPolicy,
         records: options.records
       }
     };
@@ -999,6 +1007,8 @@ var Mnexium = class {
     const maxTokens = options.maxTokens || this.defaults.maxTokens;
     const temperature = options.temperature ?? this.defaults.temperature;
     const regenerateKey = options.regenerateKey ?? this.defaults.regenerateKey ?? false;
+    const memoryPolicy = options.memoryPolicy ?? this.defaults.memoryPolicy;
+    const records = options.records ?? this.defaults.records;
     const headers = {};
     const provider = detectProvider(model);
     if (provider === "anthropic" && this.anthropicConfig?.apiKey) {
@@ -1012,6 +1022,11 @@ var Mnexium = class {
     } else if (this.googleConfig?.apiKey) {
       headers["x-google-key"] = this.googleConfig.apiKey;
     }
+    if (memoryPolicy === false) {
+      headers["x-mnx-memory-policy"] = "false";
+    } else if (typeof memoryPolicy === "string" && memoryPolicy.trim()) {
+      headers["x-mnx-memory-policy"] = memoryPolicy;
+    }
     const body = {
       model,
       messages: [{ role: "user", content: options.content }],
@@ -1029,7 +1044,9 @@ var Mnexium = class {
         summarize,
         system_prompt: systemPrompt,
         metadata,
-        regenerate_key: regenerateKey
+        regenerate_key: regenerateKey,
+        memory_policy: memoryPolicy,
+        records
       }
     };
     if (options.stream) {
@@ -1062,6 +1079,7 @@ var Mnexium = class {
       } : void 0,
       provisionedKey: raw.mnx.provisioned_key,
       claimUrl: raw.mnx.claim_url,
+      records: raw.mnx.records,
       raw
     };
   }

package/dist/index.mjs

@@ -61,7 +61,9 @@ var Chat = class {
       temperature: options.temperature ?? this.options.temperature,
       stream: options.stream,
       metadata: options.metadata ?? this.options.metadata,
-      regenerateKey: options.regenerateKey
+      regenerateKey: options.regenerateKey,
+      memoryPolicy: options.memoryPolicy ?? this.options.memoryPolicy,
+      records: options.records ?? this.options.records
     });
   }
 };
@@ -568,6 +570,11 @@ var ChatCompletionsResource = class {
     } else if (options.googleKey) {
       headers["x-google-key"] = options.googleKey;
     }
+    if (options.memoryPolicy === false) {
+      headers["x-mnx-memory-policy"] = "false";
+    } else if (typeof options.memoryPolicy === "string" && options.memoryPolicy.trim()) {
+      headers["x-mnx-memory-policy"] = options.memoryPolicy;
+    }
     const body = {
       model: options.model,
       messages: options.messages,
@@ -587,6 +594,7 @@ var ChatCompletionsResource = class {
         system_prompt: options.systemPrompt,
         metadata: options.metadata,
         regenerate_key: options.regenerateKey,
+        memory_policy: options.memoryPolicy,
         records: options.records
       }
     };
@@ -964,6 +972,8 @@ var Mnexium = class {
     const maxTokens = options.maxTokens || this.defaults.maxTokens;
     const temperature = options.temperature ?? this.defaults.temperature;
     const regenerateKey = options.regenerateKey ?? this.defaults.regenerateKey ?? false;
+    const memoryPolicy = options.memoryPolicy ?? this.defaults.memoryPolicy;
+    const records = options.records ?? this.defaults.records;
     const headers = {};
     const provider = detectProvider(model);
     if (provider === "anthropic" && this.anthropicConfig?.apiKey) {
@@ -977,6 +987,11 @@ var Mnexium = class {
     } else if (this.googleConfig?.apiKey) {
       headers["x-google-key"] = this.googleConfig.apiKey;
     }
+    if (memoryPolicy === false) {
+      headers["x-mnx-memory-policy"] = "false";
+    } else if (typeof memoryPolicy === "string" && memoryPolicy.trim()) {
+      headers["x-mnx-memory-policy"] = memoryPolicy;
+    }
     const body = {
       model,
       messages: [{ role: "user", content: options.content }],
@@ -994,7 +1009,9 @@ var Mnexium = class {
         summarize,
         system_prompt: systemPrompt,
         metadata,
-        regenerate_key: regenerateKey
+        regenerate_key: regenerateKey,
+        memory_policy: memoryPolicy,
+        records
       }
     };
     if (options.stream) {
@@ -1027,6 +1044,7 @@ var Mnexium = class {
       } : void 0,
       provisionedKey: raw.mnx.provisioned_key,
       claimUrl: raw.mnx.claim_url,
+      records: raw.mnx.records,
       raw
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnexium/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Official Mnexium SDK for JavaScript/TypeScript - Add memory to your AI applications",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -28,6 +28,7 @@
     "example:claims": "cd examples && npm run claims",
     "example:state": "cd examples && npm run state",
     "example:profile": "cd examples && npm run profile",
+    "example:records": "cd examples && npm run records",
     "example:prompts": "cd examples && npm run prompts",
     "example:streaming": "cd examples && npm run streaming",
     "example:events": "cd examples && npm run events",