@mnexium/sdk 0.1.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,6 +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?: MnxRecordsConfig;
 }
 interface ChatCompletionOptions extends MnxOptions {
     /** Model to use (e.g., 'gpt-4o-mini', 'claude-3-sonnet', 'gemini-1.5-pro') */
@@ -296,6 +333,7 @@ interface MnxResponseData {
     subject_id: string;
     provisioned_key?: string;
     claim_url?: string;
+    records?: unknown;
 }
 interface ChatCompletionResponse {
     id: string;
@@ -419,6 +457,74 @@ interface SystemPromptCreateOptions {
     /** Set as default prompt for the project */
     isDefault?: boolean;
 }
+/** A record schema definition */
+interface RecordSchema {
+    project_id: string;
+    type_name: string;
+    fields: Record<string, RecordFieldDef>;
+    display_name?: string;
+    description?: string;
+    created_at: string;
+    updated_at: string;
+}
+/** A field definition within a record schema */
+interface RecordFieldDef {
+    type: string;
+    required?: boolean;
+    description?: string;
+    display_name?: string;
+}
+/** Options for defining a record schema */
+interface RecordSchemaDefineOptions {
+    /** Record type name (e.g. 'deal', 'contact') */
+    typeName: string;
+    /** Field definitions */
+    fields: Record<string, RecordFieldDef>;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Description of this record type */
+    description?: string;
+}
+/** A record instance */
+interface MnxRecord {
+    record_id: string;
+    project_id: string;
+    type_name: string;
+    owner_id?: string;
+    visibility: 'public' | 'private';
+    collaborators?: string[];
+    data: globalThis.Record<string, unknown>;
+    summary_text?: string;
+    is_deleted?: boolean;
+    created_at: string;
+    updated_at: string;
+}
+/** Options for inserting a record */
+interface RecordInsertOptions {
+    /** Record data */
+    data: globalThis.Record<string, unknown>;
+    /** Owner subject ID */
+    ownerId?: string;
+    /** Visibility: 'public' (default) or 'private' */
+    visibility?: 'public' | 'private';
+    /** Subject IDs with write access (in addition to the owner) */
+    collaborators?: string[];
+}
+/** Options for querying records */
+interface RecordQueryOptions {
+    /** JSONB field filters */
+    where?: globalThis.Record<string, unknown>;
+    /** Order by field (prefix with - for DESC) */
+    orderBy?: string;
+    /** Maximum results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/** A record search result with similarity score */
+interface RecordSearchResult extends MnxRecord {
+    similarity: number;
+}
 
 /**
  * Streaming support for Mnexium SDK
@@ -597,6 +703,7 @@ declare class SubjectMemoriesResource {
         source?: string;
         visibility?: 'private' | 'shared';
         metadata?: Record<string, unknown>;
+        no_supersede?: boolean;
     }): Promise<any>;
     list(options?: {
         limit?: number;
@@ -731,7 +838,13 @@ declare class ChatResource {
 declare class ChatCompletionsResource {
     private readonly client;
     constructor(client: Mnexium);
-    create(options: ChatCompletionOptions): Promise<ChatCompletionResponse>;
+    create(options: ChatCompletionOptions & {
+        stream: true;
+    }): Promise<StreamResponse>;
+    create(options: ChatCompletionOptions & {
+        stream?: false;
+    }): Promise<ChatCompletionResponse>;
+    create(options: ChatCompletionOptions): Promise<ChatCompletionResponse | StreamResponse>;
 }
 
 /**
@@ -806,6 +919,84 @@ declare class PromptsResource {
     }): Promise<any>;
 }
 
+/**
+ * Records Resource - Structured data management API
+ */
+
+declare class RecordsResource {
+    private readonly client;
+    constructor(client: Mnexium);
+    /**
+     * Define or update a record schema
+     *
+     * @example
+     * await mnx.records.defineSchema('deal', {
+     *   title: { type: 'string', required: true },
+     *   value: { type: 'number' },
+     *   stage: { type: 'string' },
+     *   account_id: { type: 'ref:account' },
+     * }, { displayName: 'Deal', description: 'Sales deals' });
+     */
+    defineSchema(typeName: string, fields: RecordSchemaDefineOptions['fields'], opts?: {
+        displayName?: string;
+        description?: string;
+    }): Promise<RecordSchema>;
+    /**
+     * Get a schema by type name
+     */
+    getSchema(typeName: string): Promise<RecordSchema | null>;
+    /**
+     * List all schemas for the project
+     */
+    listSchemas(): Promise<RecordSchema[]>;
+    /**
+     * Insert a new record
+     *
+     * @example
+     * const deal = await mnx.records.insert('deal', {
+     *   title: 'Acme Renewal',
+     *   value: 500000,
+     *   stage: 'negotiation',
+     * });
+     */
+    insert(typeName: string, data: Record<string, unknown>, opts?: Omit<RecordInsertOptions, 'data'>): Promise<MnxRecord>;
+    /**
+     * Get a record by ID
+     */
+    get(typeName: string, recordId: string): Promise<MnxRecord | null>;
+    /**
+     * Update a record (partial merge)
+     *
+     * @example
+     * await mnx.records.update('deal', 'rec_abc', { stage: 'closed_won', value: 550000 });
+     */
+    update(typeName: string, recordId: string, data: Record<string, unknown>): Promise<MnxRecord>;
+    /**
+     * Soft-delete a record
+     */
+    delete(typeName: string, recordId: string): Promise<void>;
+    /**
+     * Query records with JSONB filters
+     *
+     * @example
+     * const deals = await mnx.records.query('deal', {
+     *   where: { stage: 'closed_won' },
+     *   orderBy: '-value',
+     *   limit: 10,
+     * });
+     */
+    query(typeName: string, opts?: RecordQueryOptions): Promise<MnxRecord[]>;
+    /**
+     * Semantic search across records
+     *
+     * @example
+     * const results = await mnx.records.search('deal', 'large enterprise renewal');
+     */
+    search(typeName: string, query: string, opts?: {
+        limit?: number;
+    }): Promise<RecordSearchResult[]>;
+}
+
 /**
  * Mnexium SDK Client
  */
@@ -826,6 +1017,7 @@ declare class Mnexium {
     readonly profiles: ProfilesResource;
     readonly state: StateResource;
     readonly prompts: PromptsResource;
+    readonly records: RecordsResource;
     constructor(config?: MnexiumConfig);
     /**
      * Process a message with Mnexium's memory-enhanced AI
@@ -903,6 +1095,7 @@ declare class Mnexium {
         body?: unknown;
         headers?: Record<string, string>;
         query?: Record<string, string | number | boolean | undefined>;
+        signal?: AbortSignal;
     }): Promise<Response>;
     /**
      * Internal: Make an API request

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,6 +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?: MnxRecordsConfig;
 }
 interface ChatCompletionOptions extends MnxOptions {
     /** Model to use (e.g., 'gpt-4o-mini', 'claude-3-sonnet', 'gemini-1.5-pro') */
@@ -296,6 +333,7 @@ interface MnxResponseData {
     subject_id: string;
     provisioned_key?: string;
     claim_url?: string;
+    records?: unknown;
 }
 interface ChatCompletionResponse {
     id: string;
@@ -419,6 +457,74 @@ interface SystemPromptCreateOptions {
     /** Set as default prompt for the project */
     isDefault?: boolean;
 }
+/** A record schema definition */
+interface RecordSchema {
+    project_id: string;
+    type_name: string;
+    fields: Record<string, RecordFieldDef>;
+    display_name?: string;
+    description?: string;
+    created_at: string;
+    updated_at: string;
+}
+/** A field definition within a record schema */
+interface RecordFieldDef {
+    type: string;
+    required?: boolean;
+    description?: string;
+    display_name?: string;
+}
+/** Options for defining a record schema */
+interface RecordSchemaDefineOptions {
+    /** Record type name (e.g. 'deal', 'contact') */
+    typeName: string;
+    /** Field definitions */
+    fields: Record<string, RecordFieldDef>;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Description of this record type */
+    description?: string;
+}
+/** A record instance */
+interface MnxRecord {
+    record_id: string;
+    project_id: string;
+    type_name: string;
+    owner_id?: string;
+    visibility: 'public' | 'private';
+    collaborators?: string[];
+    data: globalThis.Record<string, unknown>;
+    summary_text?: string;
+    is_deleted?: boolean;
+    created_at: string;
+    updated_at: string;
+}
+/** Options for inserting a record */
+interface RecordInsertOptions {
+    /** Record data */
+    data: globalThis.Record<string, unknown>;
+    /** Owner subject ID */
+    ownerId?: string;
+    /** Visibility: 'public' (default) or 'private' */
+    visibility?: 'public' | 'private';
+    /** Subject IDs with write access (in addition to the owner) */
+    collaborators?: string[];
+}
+/** Options for querying records */
+interface RecordQueryOptions {
+    /** JSONB field filters */
+    where?: globalThis.Record<string, unknown>;
+    /** Order by field (prefix with - for DESC) */
+    orderBy?: string;
+    /** Maximum results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/** A record search result with similarity score */
+interface RecordSearchResult extends MnxRecord {
+    similarity: number;
+}
 
 /**
  * Streaming support for Mnexium SDK
@@ -597,6 +703,7 @@ declare class SubjectMemoriesResource {
         source?: string;
         visibility?: 'private' | 'shared';
         metadata?: Record<string, unknown>;
+        no_supersede?: boolean;
     }): Promise<any>;
     list(options?: {
         limit?: number;
@@ -731,7 +838,13 @@ declare class ChatResource {
 declare class ChatCompletionsResource {
     private readonly client;
     constructor(client: Mnexium);
-    create(options: ChatCompletionOptions): Promise<ChatCompletionResponse>;
+    create(options: ChatCompletionOptions & {
+        stream: true;
+    }): Promise<StreamResponse>;
+    create(options: ChatCompletionOptions & {
+        stream?: false;
+    }): Promise<ChatCompletionResponse>;
+    create(options: ChatCompletionOptions): Promise<ChatCompletionResponse | StreamResponse>;
 }
 
 /**
@@ -806,6 +919,84 @@ declare class PromptsResource {
     }): Promise<any>;
 }
 
+/**
+ * Records Resource - Structured data management API
+ */
+
+declare class RecordsResource {
+    private readonly client;
+    constructor(client: Mnexium);
+    /**
+     * Define or update a record schema
+     *
+     * @example
+     * await mnx.records.defineSchema('deal', {
+     *   title: { type: 'string', required: true },
+     *   value: { type: 'number' },
+     *   stage: { type: 'string' },
+     *   account_id: { type: 'ref:account' },
+     * }, { displayName: 'Deal', description: 'Sales deals' });
+     */
+    defineSchema(typeName: string, fields: RecordSchemaDefineOptions['fields'], opts?: {
+        displayName?: string;
+        description?: string;
+    }): Promise<RecordSchema>;
+    /**
+     * Get a schema by type name
+     */
+    getSchema(typeName: string): Promise<RecordSchema | null>;
+    /**
+     * List all schemas for the project
+     */
+    listSchemas(): Promise<RecordSchema[]>;
+    /**
+     * Insert a new record
+     *
+     * @example
+     * const deal = await mnx.records.insert('deal', {
+     *   title: 'Acme Renewal',
+     *   value: 500000,
+     *   stage: 'negotiation',
+     * });
+     */
+    insert(typeName: string, data: Record<string, unknown>, opts?: Omit<RecordInsertOptions, 'data'>): Promise<MnxRecord>;
+    /**
+     * Get a record by ID
+     */
+    get(typeName: string, recordId: string): Promise<MnxRecord | null>;
+    /**
+     * Update a record (partial merge)
+     *
+     * @example
+     * await mnx.records.update('deal', 'rec_abc', { stage: 'closed_won', value: 550000 });
+     */
+    update(typeName: string, recordId: string, data: Record<string, unknown>): Promise<MnxRecord>;
+    /**
+     * Soft-delete a record
+     */
+    delete(typeName: string, recordId: string): Promise<void>;
+    /**
+     * Query records with JSONB filters
+     *
+     * @example
+     * const deals = await mnx.records.query('deal', {
+     *   where: { stage: 'closed_won' },
+     *   orderBy: '-value',
+     *   limit: 10,
+     * });
+     */
+    query(typeName: string, opts?: RecordQueryOptions): Promise<MnxRecord[]>;
+    /**
+     * Semantic search across records
+     *
+     * @example
+     * const results = await mnx.records.search('deal', 'large enterprise renewal');
+     */
+    search(typeName: string, query: string, opts?: {
+        limit?: number;
+    }): Promise<RecordSearchResult[]>;
+}
+
 /**
  * Mnexium SDK Client
  */
@@ -826,6 +1017,7 @@ declare class Mnexium {
     readonly profiles: ProfilesResource;
     readonly state: StateResource;
     readonly prompts: PromptsResource;
+    readonly records: RecordsResource;
     constructor(config?: MnexiumConfig);
     /**
      * Process a message with Mnexium's memory-enhanced AI
@@ -903,6 +1095,7 @@ declare class Mnexium {
         body?: unknown;
         headers?: Record<string, string>;
         query?: Record<string, string | number | boolean | undefined>;
+        signal?: AbortSignal;
     }): Promise<Response>;
     /**
      * Internal: Make an API request