@personize/sdk 0.5.0 → 0.5.2

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)
@@ -346,69 +340,10 @@ const client = new Personize({
 
 ## Skills
 
-The SDK ships with AI-assistant skills in `skills/` that teach Claude Code, Codex, and Cursor how to use the SDK for common workflows.
-
-### Integration Builder (`skills/integrations/`)
-
-Build CRM/database sync integrations. Connect Salesforce, HubSpot, Postgres, or any data source to Personize memory with batch memorization and scheduled deployment.
-
-```
-skills/integrations/
-├── CLAUDE.md                  # Main skill instructions
-├── templates/
-│   ├── salesforce.md          # Salesforce connector pattern
-│   ├── hubspot.md             # HubSpot connector pattern
-│   └── postgres.md            # Postgres/MySQL pattern
-└── deploy/
-    ├── Dockerfile             # Container deployment
-    ├── render.yaml            # Render cron service
-    └── github-action.yml      # GitHub Actions schedule
-```
-
-### Governance (`skills/governance/`)
-
-Manage guidelines as code — maintain a `governance/guidelines/` folder of `.md` files and sync them to the Personize API.
+AI-assistant skills for Claude Code, Codex, and Cursor are available separately:
 
+```bash
+npx skills add personizeai/personize-skills --all
 ```
-skills/governance/
-├── CLAUDE.md                  # Main skill instructions
-├── sync.ts                    # CLI sync script
-└── github-action.yml          # CI sync on push
-```
-
-### AI Content Pipelines (`skills/content-pipelines/`)
-
-Build intelligent, memory-powered AI systems that follow a 10-step agentic loop: **Observe → Remember → Recall → Reason → Plan → Decide → Generate → Act → Update → Repeat**. Includes ready-to-run recipe scripts for product intelligence memorization, smart notifications, web page personalization, cold outreach, and more — plus channel delivery templates for SendGrid, Slack, Twilio, and generic webhooks.
-
-```
-skills/content-pipelines/
-├── CLAUDE.md                              # Main skill instructions (10-step loop)
-├── recipes/
-│   ├── product-intelligence.ts            # Memorize everything: usage, ML, searches, content, uploads, telemetry
-│   ├── smart-notification.ts              # Uniquely personalized alerts via smartDigest
-│   ├── web-personalization.ts             # AI generates UI variable values for personalized web pages
-│   ├── cold-outreach-sequence.ts          # 3-email cold outreach with sequence tracking
-│   ├── meeting-prep-brief.ts              # On-demand meeting prep brief generator
-│   ├── product-usage-alert.ts             # Usage monitoring + smart alerts
-│   ├── health-check-message.ts            # Customer health assessment + check-in
-│   └── batch-pipeline.ts                  # Configurable generic batch pipeline
-└── channels/
-    ├── sendgrid.md                        # Email delivery (SendGrid, SES, Resend)
-    ├── slack.md                           # Slack webhooks + Web API
-    ├── twilio.md                          # SMS + WhatsApp via Twilio
-    └── webhook.md                         # Generic HTTP POST (in-app, CRM, Zapier)
-```
-
-### n8n Workflow Builder (`skills/n8n-workflows/`)
-
-Generate importable n8n workflow JSON files that sync data between Personize and 400+ apps — no code required. Supports batch sync in (source → Personize), sync out (Personize → destination), webhook-triggered real-time ingestion, and per-record AI enrichment.
 
-```
-skills/n8n-workflows/
-├── CLAUDE.md                                # Main skill instructions
-└── templates/
-    ├── hubspot-to-personize.json            # HubSpot contacts → Personize
-    ├── gsheets-to-personize.json            # Google Sheets → Personize
-    ├── webhook-to-personize.json            # Webhook → Personize (real-time)
-    └── personize-to-slack.json              # Personize → Slack digest
-```
+See [personizeai/personize-skills](https://github.com/personizeai/personize-skills) for the full catalog.

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

@@ -393,6 +393,12 @@ export interface PromptOptions {
     provider?: string;
     context?: string;
     sessionId?: string;
+    /**
+     * Multimodal attachments (images, PDFs, documents).
+     * Max 10 attachments, 20 MB per attachment, 50 MB total.
+     * In multi-step mode, attachments are sent with the first instruction only.
+     */
+    attachments?: PromptAttachment[];
     /**
      * Evaluation configuration.
      * - `true` — server-side auto-evaluation with default criteria
@@ -414,16 +420,6 @@ export interface PromptOptions {
     };
     /** Per-MCP tool selection override (allowlist or denylist per MCP) */
     mcpTools?: McpToolSelection[];
-    /**
-     * Images or documents to send with the prompt (multimodal input).
-     *
-     * In multi-step mode (`instructions`), attachments are sent with the
-     * **first instruction** only — subsequent steps reference them via
-     * conversation history.
-     *
-     * Limits: max 10 attachments, 20 MB each, 50 MB total.
-     */
-    attachments?: Attachment[];
 }
 /** Prompt response when outputs/evaluation are used. */
 export interface PromptResponse {
@@ -602,6 +598,8 @@ 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;
     /** Filter results to a specific entity by email. */
@@ -611,40 +609,6 @@ export interface RecallOptions {
     /** 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;
@@ -652,7 +616,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 {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@personize/sdk",
-    "version": "0.5.0",
+    "version": "0.5.2",
     "description": "Official Personize SDK",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -18,11 +18,11 @@
     },
     "repository": {
         "type": "git",
-        "url": "https://github.com/hataheri/personize-sdk.git"
+        "url": "https://github.com/personizeai/personize-sdk.git"
     },
     "homepage": "https://personize.ai",
     "bugs": {
-        "url": "https://github.com/hataheri/personize-sdk/issues"
+        "url": "https://github.com/personizeai/personize-sdk/issues"
     },
     "keywords": [
         "personize",