@personize/sdk 0.5.1 → 0.5.3

package/README.md

@@ -43,8 +43,6 @@ console.log(me.data.plan.limits);
 | POST | `/api/v1/smart-recall` | `client.memory.smartRecall(opts)` |
 | POST | `/api/v1/recall` | `client.memory.recall(opts)` |
 | POST | `/api/v1/search` | `client.memory.search(opts)` |
-| POST | `/api/v1/upsert` | `client.memory.upsert(opts)` |
-| POST | `/api/v1/upsert` | `client.memory.upsertBatch(opts)` |
 | POST | `/api/v1/batch-memorize` | `client.memory.memorizeBatch(opts)` |
 | POST | `/api/v1/smart-memory-digest` | `client.memory.smartDigest(opts)` |
 | **Guidelines** | | |
@@ -170,8 +168,9 @@ console.log(research.data?.evaluation?.finalScore);
 
 ```typescript
 // Memorize content (dual extraction: structured + free-form)
+// Tip: prepend identity field hints to ensure demographic properties are captured
 await client.memory.memorize({
-    content: 'Meeting notes: John prefers email contact.',
+    content: 'Also extract First Name, Company Name, and Job Title if mentioned.\n\nMeeting notes: John prefers email contact. He is VP of Sales at Acme Corp.',
     speaker: 'Sales Rep',
     enhanced: true,
     tags: ['meetings'],
@@ -194,11 +193,14 @@ const fast = await client.memory.smartRecall({
     fast_mode: true,
 });
 
-// Direct recall — simple memory lookup (no reflection)
+// Direct recall — DynamoDB lookup: properties + freeform memories (no AI, type required)
 const direct = await client.memory.recall({
     query: 'What do we know about Acme?',
+    type: 'Contact',
     email: 'john@acme.com',
 });
+// direct.data.memories — structured properties from Snapshot
+// direct.data.freeformMemories — AI-extracted memories from Freeform table
 
 // Search/filter records by property conditions
 const found = await client.memory.search({
@@ -209,15 +211,17 @@ const found = await client.memory.search({
     pageSize: 50,
 });
 
-// Batch sync — unified call with per-property extractMemories flag
+// Batch sync — unified call with per-property extractMemories control
+// IMPORTANT: Set extractMemories: true on rich text fields (notes, transcripts, descriptions)
+// to enable AI extraction and semantic search. Without it, only structured storage occurs.
 await client.memory.memorizeBatch({
     source: 'Hubspot',
     mapping: {
         entityType: 'contact',
         email: 'email',
         properties: {
-            email:     { sourceField: 'email',    collectionId: 'col_std', collectionName: 'Standard' },
-            full_name: { sourceField: 'fullname', collectionId: 'col_std', collectionName: 'Standard' },
+            email:     { sourceField: 'email',    collectionId: 'col_std', collectionName: 'Standard', extractMemories: false },
+            full_name: { sourceField: 'fullname', collectionId: 'col_std', collectionName: 'Standard', extractMemories: false },
             notes:     { sourceField: 'notes',    collectionId: 'col_gen', collectionName: 'Generated', extractMemories: true },
         },
     },
@@ -234,16 +238,6 @@ const digest = await client.memory.smartDigest({
 });
 console.log(digest.data?.compiledContext); // ready-to-use markdown for LLM prompts
 
-// Structured upsert — no AI extraction
-await client.memory.upsert({
-    type: 'Contact',
-    properties: {
-        email: { value: 'john@acme.com', collectionId: 'col_123' },
-        company: { value: 'Acme Corp' },
-    },
-    matchKeys: { email: 'john@acme.com' },
-    source: 'crm-sync',
-});
 ```
 
 ### Agents
@@ -336,7 +330,7 @@ const client = new Personize({
 **New in 0.4.0:**
 - `client.test()` — Verify API key validity
 - `client.agents.get(id)` — Get agent details and expected inputs
-- `client.memory.recall(opts)` — Direct memory lookup (no reflection, low latency)
+- `client.memory.recall(opts)` — Direct DynamoDB lookup: properties + freeform memories (no AI)
 - `client.memory.search(opts)` — Search/filter records with `property`-based conditions
 - `client.evaluate.memorizationAccuracy(opts)` — Three-phase memorization evaluation
 - `attachments` on `PromptOptions` — Multimodal support (images, PDFs, documents)

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, GuidelinesResponse, GuidelineSectionOptions, GuidelineUpdatePayload, GuidelineCreatePayload, GuidelineHistoryResponse, GuidelineHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartGuidelinesOptions, SmartGuidelinesResponse, PromptOptions, PromptResponse, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, SearchOptions, SearchResponse, UpsertOptions, UpsertBatchOptions, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse } from './types';
+import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, GuidelinesResponse, GuidelineSectionOptions, GuidelineUpdatePayload, GuidelineCreatePayload, GuidelineHistoryResponse, GuidelineHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartGuidelinesOptions, SmartGuidelinesResponse, PromptOptions, PromptResponse, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, SearchOptions, SearchResponse, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse } from './types';
 export declare class Personize {
     private client;
     private _organizationId?;
@@ -121,14 +121,6 @@ export declare class Personize {
          * Returns matching record IDs with optional property values and memories.
          */
         search: (data: SearchOptions) => Promise<ApiResponse<SearchResponse>>;
-        /**
-         * POST /api/v1/upsert — Structured upsert (no AI extraction)
-         */
-        upsert: (data: UpsertOptions) => Promise<ApiResponse>;
-        /**
-         * POST /api/v1/upsert — Batch upsert (memories array format)
-         */
-        upsertBatch: (data: UpsertBatchOptions) => Promise<ApiResponse>;
         /**
          * POST /api/v1/batch-memorize — Unified batch sync with per-property extractMemories flag.
          * Properties with extractMemories: true go through AI extraction + vectors.

package/dist/client.js

@@ -227,28 +227,6 @@ class Personize {
                 const response = await this.client.post('/api/v1/search', data);
                 return response.data;
             },
-            /**
-             * POST /api/v1/upsert — Structured upsert (no AI extraction)
-             */
-            upsert: async (data) => {
-                const organizationId = await this.getOrganizationId();
-                const response = await this.client.post('/api/v1/upsert', {
-                    ...data,
-                    orgId: organizationId,
-                });
-                return response.data;
-            },
-            /**
-             * POST /api/v1/upsert — Batch upsert (memories array format)
-             */
-            upsertBatch: async (data) => {
-                const organizationId = await this.getOrganizationId();
-                const response = await this.client.post('/api/v1/upsert', {
-                    ...data,
-                    orgId: organizationId,
-                });
-                return response.data;
-            },
             /**
              * POST /api/v1/batch-memorize — Unified batch sync with per-property extractMemories flag.
              * Properties with extractMemories: true go through AI extraction + vectors.

package/dist/types.d.ts

@@ -561,10 +561,14 @@ export interface SmartRecallOptions {
     minScore?: number;
     /** CRM record ID for entity scoping. */
     record_id?: string;
+    /** CRM record ID (camelCase alias). */
+    recordId?: string;
     /** Filter results to a specific entity by email. */
     email?: string;
     /** Website URL for entity scoping. */
     website_url?: string;
+    /** Website URL (camelCase alias). */
+    websiteUrl?: string;
     /** Entity type filter (e.g. 'Contact', 'Company'). */
     type?: string;
     /** Scope results to specific collections by ID. */
@@ -598,49 +602,21 @@ export type RecallProOptions = SmartRecallOptions;
 export interface RecallOptions {
     /** Natural-language query. */
     query: string;
+    /** Entity type (e.g. 'Contact', 'Company'). Required by the /recall endpoint. */
+    type: string;
     /** CRM record ID for entity scoping. */
     record_id?: string;
+    /** CRM record ID (camelCase alias). */
+    recordId?: string;
     /** Filter results to a specific entity by email. */
     email?: string;
     /** Website URL for entity scoping. */
     website_url?: string;
+    /** Website URL (camelCase alias). */
+    websiteUrl?: string;
     /** Additional filters. */
     filters?: Record<string, unknown>;
 }
-export interface UpsertOptions {
-    /** Entity type (e.g. 'Contact', 'Company') */
-    type: string;
-    /** Properties to store: { propertyName: { value, collectionId?, collectionName? } } */
-    properties: Record<string, {
-        value: PropertyValue;
-        collectionId?: string;
-        collectionName?: string;
-    }>;
-    /** Match keys for dedup (e.g. { email: 'john@example.com' }) */
-    matchKeys?: {
-        email?: string;
-        websiteUrl?: string;
-    };
-    /** Source label (e.g. 'CRM Sync') */
-    source?: string;
-}
-export interface UpsertBatchOptions {
-    /** Entity type */
-    type: string;
-    /** Array of memory items to upsert */
-    memories: Array<{
-        memoryName: string;
-        result: PropertyValue | Record<string, unknown>;
-        collection?: string;
-        collectionId?: string;
-    }>;
-    /** Contact email for record matching */
-    email?: string;
-    /** Company website for record matching */
-    websiteUrl?: string;
-    /** Source label */
-    source?: string;
-}
 export interface BatchMemorizePropertyMapping {
     /** Source field name in the row data */
     sourceField: string;
@@ -648,7 +624,7 @@ export interface BatchMemorizePropertyMapping {
     collectionId: string;
     /** Target collection name */
     collectionName: string;
-    /** If true, AI extraction + vector embeddings are created for this property. Default: false (structured storage only). */
+    /** AI extraction + vector embeddings for this property. Default: false. Set to true for rich text fields (notes, transcripts, descriptions) that benefit from AI extraction and semantic search. */
     extractMemories?: boolean;
 }
 export interface BatchMemorizeMapping {
@@ -678,20 +654,32 @@ export interface BatchMemorizeOptions {
 export interface SmartDigestOptions {
     /** CRM record ID */
     record_id?: string;
+    /** CRM record ID (camelCase alias). */
+    recordId?: string;
     /** Contact email */
     email?: string;
     /** Company website URL */
     website_url?: string;
+    /** Website URL (camelCase alias). */
+    websiteUrl?: string;
     /** Entity type ('Contact', 'Company'). Auto-inferred if omitted. */
     type?: string;
     /** Max tokens for compiled context (default: 1000) */
     token_budget?: number;
+    /** Max tokens (camelCase alias). */
+    tokenBudget?: number;
     /** Max free-form memories to include (default: 20) */
     max_memories?: number;
+    /** Max memories (camelCase alias). */
+    maxMemories?: number;
     /** Include DynamoDB property snapshot (default: true) */
     include_properties?: boolean;
+    /** Include properties (camelCase alias). */
+    includeProperties?: boolean;
     /** Include LanceDB free-form memories (default: true) */
     include_memories?: boolean;
+    /** Include memories (camelCase alias). */
+    includeMemories?: boolean;
 }
 export interface SmartDigestResponse {
     success: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@personize/sdk",
-    "version": "0.5.1",
+    "version": "0.5.3",
     "description": "Official Personize SDK",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",