personize-memory（记忆拟人化）

Skill: Personize Memory

This is your persistent memory for everything you know about a record — contacts, companies, employees, members, locations, devices, and more. Store and retrieve: customer data, interaction history, inputs, actions you've taken, reports, notes, and observations. Always consult Memory before acting on a record. Always update Memory after meaningful interactions.

Internal principle: Bad data in = bad personalization out. Memory is the foundation. Get it right, and every downstream feature (emails, notifications, dashboards, agents) gets better automatically.

When This Skill is Activated

This skill gives you the ability to store and retrieve data using the Personize SDK's memory system.

If the developer hasn't given a specific instruction yet, introduce yourself:

"I have access to the Memory skill. I can help you store data into Personize memory (memorize) and retrieve it (recall) — including batch syncs, semantic search, entity digests, and data export. What data are you working with?"

If the developer says something about storing, syncing, importing, or ingesting data, jump to MEMORIZE.

If the developer says something about retrieving, querying, searching, or assembling context, jump to RECALL.

When NOT to Use This Skill

• For CRM sync with deploy templates → see the CRM / Database Sync section below
• Need no-code visual workflows → use no-code-pipelines
• Need durable scheduled pipelines with retries → use code-pipelines
• Need to manage organizational rules, not entity data → use governance
• Need multi-agent coordination state → use collaboration

Works With Both SDK and MCP — One Skill, Two Interfaces

This skill works identically whether the LLM accesses memory via the SDK (code, scripts, IDE agents) or via MCP (Claude Desktop, ChatGPT, Cursor MCP connection).

MCP tools map to SDK methods:

MCP-Only Feature: Self-Memory (about='self')

MCP tools support an about parameter that the SDK does not expose directly:

• about='lead' (default) — store/recall about a contact or company. Requires email, website_url, or record_id.
• about='self' — store/recall about the current user (preferences, working style, goals). No identifier needed — identity is resolved automatically.

// MCP: Store user preferences
memory_store_pro(content="I prefer formal communication. My timezone is PST.", about="self")

// MCP: Recall user preferences
memory_recall_pro(query="What are my preferences and working style?", about="self", generate_answer=true)

Canonical API Names (v1.1)

• memory_save replaces memory_store_pro as the canonical MCP tool name
• memory_retrieve replaces memory_recall_pro / smartRecall
• Old tool names still work — use whichever you prefer

When reading this skill document:

• If you're connected via MCP, use the MCP tool names (memory_store_pro, memory_recall_pro, etc.)
• If you're running via SDK, use the client.memory.* methods
• All workflows, rules, and best practices apply equally to both interfaces

Actions

You have 6 actions. Use whichever matches what the developer needs.

Before each action: Read the reference file for full method signatures, decision trees, code examples, and common mistakes.

Action: MEMORIZE

Store data into Personize memory. The right method depends on what you're storing and how much of it.

Which Method to Use

The extractMemories Decision

extractMemories defaults to false. You must set extractMemories: true on rich text fields to enable AI extraction and semantic search. Without it, batch-synced data is stored as structured properties only — no memories, no vector embeddings, no semantic recall.

Rule of thumb: Always set extractMemories: true on any field containing free-form text. If you skip it, those fields get stored as properties but produce zero memories — smartRecall() and smartDigest() won't find them.

Quick Example

// Single item — AI extraction with identity hints
await client.memory.memorize({
    content: 'Also extract First Name, Last Name, Company Name, and Job Title if mentioned.\n\nCall with Sarah Chen (VP Eng, Initech). She mentioned they are evaluating SOC2 compliance tools. Main pain point: manual audit prep taking 2 weeks per quarter. Budget approved for Q2.',
    speaker: 'Sales Team',
    email: 'sarah.chen@initech.com',
    enhanced: true,
    tags: ['call-notes', 'sales', 'source:manual'],
});

// Batch sync — per-property control
await client.memory.memorizeBatch({
    source: 'Hubspot',
    mapping: {
        entityType: 'contact',
        email: 'email',
        runName: 'hubspot-contact-sync',
        properties: {
            full_name:    { sourceField: 'firstname', collectionId: 'col_xxx', collectionName: 'Contacts', extractMemories: false },
            job_title:    { sourceField: 'jobtitle',  collectionId: 'col_xxx', collectionName: 'Contacts', extractMemories: false },
            last_notes:   { sourceField: 'notes',     collectionId: 'col_xxx', collectionName: 'Contacts', extractMemories: true },
        },
    },
    rows: crmContacts,  // array of objects from your CRM
});
// ⚠️ memorizeBatch() is async — records land in ~1-2 minutes (EventBridge → Lambda).
// Verify with search() or smartDigest() after processing completes.

Intelligence Tiers (memorize + batch-memorize)

memorize() and memorizeBatch() accept a tier param that selects the LLM pipeline and credit rate. Defaults to pro — no breaking change for existing callers.

Available tiers: basic, pro (default), pro_fast, ultra. For current rates, see personize.ai.

Tiers also control maxProperties (15–50), chunkMaxWords (2000–4000), and minPropertyScore (0.2–0.4). Model fallback is automatic — if the primary model fails, the system routes to the fallback.

await client.memory.memorize({
    content: '...',
    email: 'user@co.com',
    enhanced: true,
    tier: 'basic',       // or 'pro' (default), 'pro_fast', 'ultra'
});

await client.memory.memorizeBatch({
    source: 'HubSpot',
    mapping: { ... },
    rows: contacts,
    tier: 'pro_fast',    // fast LLMs, lower latency
});

Note: These are memorize intelligence tiers — they control the extraction pipeline. For content generation via client.ai.prompt(), see the separate generate tiers below.

Generate Tiers (prompt)

client.ai.prompt() has its own tier system for content generation, separate from memorize tiers. Available tiers: basic, pro (default), ultra. For current rates, see personize.ai.

Pass tier to select a curated model (default). Custom model and provider require BYOK (openrouterApiKey) — without it, the API returns 400.

Constraints

Keywords follow RFC 2119: MUST = non-negotiable, SHOULD = strong default (override with stated reasoning), MAY = agent discretion.

1. MUST include at least one tag on every memorize() call (e.g. tags: ['source:hubspot', 'type:interaction', 'team:sales']) -- because tags serve two purposes: (a) filtering, attribution, and workspace scoping, and (b) property selection boosting — tags that match a property definition's own tags array give that property a +15% score boost during extraction, making extraction context-aware. For example, tags: ["qualification"] boosts properties tagged ["qualification"] like Decision Maker or Budget.
2. SHOULD include a timestamp in the content or use the timestamp parameter -- because temporal ordering lets recall distinguish recent facts from stale ones.
3. MUST NOT pre-process content with an LLM before calling memorize() with enhanced: true -- because double-processing wastes tokens and the extraction pipeline is optimized for raw input.
4. MUST NOT manually deduplicate before memorizing -- because the platform deduplicates at cosine 0.92 similarity and runs background consolidation; client-side dedup adds complexity with no benefit.
5. SHOULD memorize generated outputs (emails, notifications, reports) after delivery -- because the feedback loop lets future recalls see what was already sent, preventing repetition.
6. SHOULD use client.collections.create/update/delete() or the web app for schema changes -- because collections define the extraction schema and ad-hoc creation risks inconsistency.
7. MUST call client.me() before batch operations to read plan rate limits -- because exceeding limits causes 429 errors and partial syncs with no automatic resume.
8. SHOULD prepend extraction hints for identity/demographic fields (name, company, title, location) when those fields may be empty for the record -- because the property selector uses embedding similarity, and generic identity fields score low against specific content; hints ensure they are selected alongside the content-relevant properties without limiting the selector. See reference/memorize.md → "Extraction Hints" for the full pattern.

Full guide: Read reference/memorize.md for complete method signatures, data mapping patterns, all source-specific recipes (CRM, database, webhook, CSV), batch strategies, error handling, and the feedback loop.

CRM / Database Sync

For production-grade data sync from CRMs and databases (Salesforce, HubSpot, Postgres), this skill includes source-specific connector templates and deployment configs:

• Source templates: templates/salesforce.md, templates/hubspot.md, templates/postgres.md — fetch patterns, auth setup, field mapping for each source
• Deployment: deploy/Dockerfile, deploy/render.yaml, deploy/github-action.yml — scheduled sync on Render, GitHub Actions, or any container platform
• Advanced patterns: reference/sync-advanced-patterns.md — incremental sync with state tracking, multi-source architecture, batch export with pagination, complete end-to-end example

The integration pattern: initialize project → client.me() for auth + limits → fetch rows from source → client.collections.list() for collection IDs → build property mapping → memorizeBatch() in chunks with 429 retry → verify with search() or smartDigest(). See recipes/data-sync.ts for a runnable example.

Action: RECALL

Retrieve data from Personize memory. The right method depends on what kind of answer you need.

Which Method to Use

smartRecall() vs recall(): Use smartRecall() for most use cases — it supports reflection, answer generation, mode, and infers type from email/website_url. Use recall() only for simple direct lookups — type is required (e.g. type: 'Contact').

Identifier behavior — how email, websiteUrl, recordId, type-only, and no identifier affect each endpoint (error vs empty vs org-wide search) → read reference/identifier-scenarios.md.

When to Use What

Need specific facts about a topic?         → smartRecall()
Need full context about ONE entity?         → smartDigest()
Need to filter/segment a list of records?   → search()
Need organizational rules/guidelines?       → smartGuidelines()

Building a generation prompt?               → smartGuidelines() + smartDigest() + smartRecall()
                                              (governance + entity + task-specific facts)

Quick Example

// Semantic search — find specific facts (recommended)
const results = await client.memory.smartRecall({
    query: 'what pain points did this contact mention?',
    email: 'sarah.chen@initech.com',
    type: 'Contact',
    limit: 10,
    minScore: 0.4,
    include_property_values: true,
});

// Fast recall — skip reflection, ~500ms response
const fast = await client.memory.smartRecall({
    query: 'what do we know about this contact?',
    email: 'sarah.chen@initech.com',
    type: 'Contact',
    mode: 'fast',
});

// Entity digest — compiled context for one person
const digest = await client.memory.smartDigest({
    email: 'sarah.chen@initech.com',
    type: 'Contact',
    token_budget: 2000,
    include_properties: true,
    include_memories: true,
});
// digest.data.compiledContext → ready-to-inject markdown

// Entity digest via custom key (e.g. LinkedIn URL, student number)
const linkedinDigest = await client.memory.smartDigest({
    customKeyName: 'linkedin_url',
    customKeyValue: 'sarah-chen-12345',
    token_budget: 2000,
});
// Works with any customKeyName used during memorize

// Filtered export — find all enterprise contacts
const exported = await client.memory.search({
    type: 'Contact',
    returnRecords: true,
    pageSize: 50,
    groups: [{
        conditions: [
            { property: 'plan_tier', operator: 'EQ', value: 'enterprise' },
            { property: 'email', operator: 'IS_SET' },
        ],
    }],
});

// --- Advanced search patterns ---

// Key-only lookup: find by CRM key without property conditions
const byEmail = await client.memory.search({
    email: 'sarah@acme.com',
    returnRecords: true,
});

// Custom key lookup
const student = await client.memory.search({
    type: 'Student',
    customKeyName: 'studentNumber',
    customKeyValue: 'S-2024-1234',
    returnRecords: true,
});

// Secondary key: find Students by email (even though primary key is studentNumber)
const studentByEmail = await client.memory.search({
    type: 'Student',
    email: 'alice@university.edu',
    returnRecords: true,
});

// Cross-type: find ALL records with this email across ALL entity types
const allTypes = await client.memory.search({
    email: 'john@acme.com',
    returnRecords: true,
});
// Returns Contacts, Students, Employees — whatever has this email

Advanced Search: Key-Only, Secondary Key, and Cross-Type

search() supports three advanced patterns beyond property filtering:

When you don't have the primary key but have a stored property value (like a LinkedIn URL), use a property condition filter instead:

const byLinkedIn = await client.memory.search({
    type: 'Contact',
    returnRecords: true,
    groups: [{ conditions: [{ property: 'linkedin_url', operator: 'EQ', value: 'https://linkedin.com/in/johndoe' }] }],
});

Full reference: See reference/recall.md → "Advanced Search Patterns" for all patterns, trade-offs, and when-to-use guidance.

The Three-Layer Agent Operating Model

Memory is one of three layers every agent should assemble before acting: Guidelines (organizational rules via smartGuidelines()), Memory (entity knowledge via smartDigest()/recall()), and Workspace (coordination state via workspace-tagged recall()/memorize()). All three together: the agent acts within governance, with full context, in coordination with others.

Full architecture guide: See the collaboration skill's reference/architecture.md for the complete three-layer model, composition patterns, and adoption path.

Cross-Entity Context

Memory gives you everything about ONE entity. But agents often need context from related entities — the company a contact works at, other contacts at the same account, related deals or projects.

Pattern: Multi-entity context assembly

// When working on a contact, also pull their company context
const [contactDigest, companyDigest] = await Promise.all([
    client.memory.smartDigest({ email: 'sarah@acme.com', type: 'Contact', token_budget: 1500 }),
    client.memory.smartDigest({ website_url: 'https://acme.com', type: 'Company', token_budget: 1000 }),
]);
// Now you know Sarah AND you know Acme — funding stage, tech stack, team size, etc.

When to pull cross-entity context:

• Working on a contact → also pull their company
• Working on a deal → also pull the contact AND the company
• Generating account-level content → pull all contacts at that company
• Detecting patterns → export across entity types and cross-reference

The Context Assembly Pattern

Most generation pipelines combine multiple recall methods:

async function assembleContext(email: string, task: string): Promise<string> {
    const sections: string[] = [];

    // 1. Governance — rules and guidelines
    // Use mode: 'fast' for real-time agents (~200ms), 'full' for deep analysis (~3s)
    const governance = await client.ai.smartGuidelines({
        message: `${task} — guidelines, tone, constraints`,
        mode: 'fast', // embedding-only routing, no LLM overhead
    });
    if (governance.data?.compiledContext) {
        sections.push('## Guidelines\n' + governance.data.compiledContext);
    }

    // 2. Entity context — everything about this person
    const digest = await client.memory.smartDigest({
        email,
        type: 'Contact',
        token_budget: 2000,
        include_properties: true,
        include_memories: true,
    });
    if (digest.data?.compiledContext) {
        sections.push('## Recipient Context\n' + digest.data.compiledContext);
    }

    // 3. Task-specific facts — semantic search
    const recalled = await client.memory.smartRecall({
        query: task,
        email,
        type: 'Contact',
        mode: 'fast',
        limit: 10,
        minScore: 0.3,
    });
    if (recalled.data?.results && Array.isArray(recalled.data.results) && recalled.data.results.length > 0) {
        sections.push('## Relevant Facts\n' + recalled.data.results.map((m: any) =>
            `- ${m.text || m.content || JSON.stringify(m)}`
        ).join('\n'));
    }

    return sections.join('\n\n---\n\n');
}

New: Add groupByRecord: true to group results by record instead of a flat list. Returns recordGroups array with topScore, matchCount, and top 3 matches per record. No extra cost.

Recall Pricing

All read operations charge a flat per-call rate regardless of mode ('fast', 'deep', etc.). Mode choice affects latency and depth, not cost. For current rates, see personize.ai.

Use mode: 'fast' in loops and batch pipelines to minimize latency.

Constraints

Keywords follow RFC 2119: MUST = non-negotiable, SHOULD = strong default (override with stated reasoning), MAY = agent discretion.

1. MUST set an explicit token_budget on every smartDigest() call -- because the default (1000) may truncate critical context for deep personalization or waste tokens for simple lookups.
2. SHOULD set minScore on smartRecall() (0.3 for broad context, 0.5+ for precision) -- because omitting it returns low-relevance noise that dilutes the context window.
3. SHOULD use mode: 'fast' for context injection, real-time UIs, and batch processing -- because it cuts recall latency from ~10-20s to ~500ms; override for exploratory queries where reflection adds value.
4. SHOULD assemble context from all three layers (smartGuidelines + smartDigest + smartRecall) before generating -- because single-source context produces governance-blind, entity-ignorant, or task-irrelevant output. Use mode: 'fast' for real-time agent flows (~200ms), mode: 'deep' for first-call or complex planning tasks (~3s). (Note: 'full' was renamed to 'deep' in SDK types and API.)
5. MAY set include_property_values: true on smartRecall() -- because it returns structured properties alongside semantic results, useful when the caller needs both.
6. MUST paginate export() calls using page and pageSize -- because unbounded exports can time out or exceed memory limits on large datasets. Default pageSize is 50.
7. MAY cache smartDigest() results within a single pipeline run when the same entity is referenced multiple times -- because redundant API calls waste tokens and add latency.

Full guide: Read reference/recall.md for complete method signatures, query writing strategies, token budget tuning, scoring thresholds, all context assembly patterns, export filtering, and performance optimization.

Action: CRUD Operations (Update, Delete, History)

Use these operations when the developer needs to directly modify, delete, or query history for memory data — as opposed to AI-powered memorization.

When to use CRUD vs Memorize

Public API Endpoints (/api/v1/memory/...)

All require sk_live_ API key.

Conditional Writes (Optimistic Concurrency)

Pass expectedVersion on update/bulk-update to prevent concurrent overwrites:

await client.memory.update({
  recordId: 'rec-123',
  propertyName: 'deal_stage',
  propertyValue: 'negotiation',
  expectedVersion: 12,  // 409 if another write happened since you last read
});

Array Operations

Mutate array-typed properties without read-modify-write races:

// Push items (with dedup)
await client.memory.update({
  recordId, propertyName: 'tags',
  arrayPush: { items: ['vip'], unique: true },
});

// Remove items by value
await client.memory.update({
  recordId, propertyName: 'tags',
  arrayRemove: { items: ['trial'] },
});

// Patch matching objects in-place
await client.memory.update({
  recordId, propertyName: 'tasks',
  arrayPatch: { match: { taskId: 'abc' }, set: { status: 'done' } },
});

Filter By Property (No LLM)

Deterministic structured filter — no tokens, no latency:

const result = await client.memory.filterByProperty({
  conditions: [
    { propertyName: 'status', operator: 'equals', value: 'active' },
    { propertyName: 'score', operator: 'gt', value: 50 },
  ],
  logic: 'AND',
  limit: 100,
});
// result.data.records → [{ recordId, type, matchedProperties, lastUpdatedAt }]
// result.data.totalMatched, result.data.nextToken

Operators: equals, notEquals, contains, gt, lt, gte, lte, exists, isEmpty

Update Example

// Update a single property
const result = await client.memory.update({
  recordId: 'rec-123',
  type: 'contact',
  propertyName: 'company_name',
  propertyValue: 'Acme Corp',
});
// result.data → { previousValue, newValue, version, stores }

Bulk Update

const result = await client.memory.bulkUpdate({
  recordId: 'rec-123',
  type: 'contact',
  updates: [
    { propertyName: 'company_name', propertyValue: 'Acme Corp' },
    { propertyName: 'deal_stage', propertyValue: 'closed_won' },
  ],
  expectedVersion: 5,  // optional concurrency guard
});
// result.data.results → [{ propertyName, previousValue, newValue, status }]

Property History

const history = await client.memory.propertyHistory({
  recordId: 'rec-123',
  propertyName: 'deal_stage',  // optional — omit for all properties
  limit: 20,
});
// history.data.entries → [{ entryId, propertyName, propertyValue, updatedBy, createdAt, source }]

Query Properties (LLM-powered)

const matches = await client.memory.queryProperties({
  propertyName: 'pain_points',
  query: 'concerns about compliance or security',
  type: 'Contact',
  limit: 50,
});
// matches.data.matches → [{ recordId, propertyValue, matchReason }]

Delete with Recovery

All deletes are soft-deletes with a 30-day recovery window. During this window, cancelDeletion restores the data.

// Soft-delete a record
await client.memory.deleteRecord({
  recordId: 'rec-123',
  type: 'contact',
});

// Undo within 30 days
await client.memory.cancelDeletion({
  recordId: 'rec-123',
  type: 'contact',
});

Webhook Events

All mutations fire webhook events: memory.property.updated, memory.properties.bulk_updated, memory.updated, memory.deleted, memory.record.deleted, memory.record.deletion_cancelled.

Action: FIND SIMILAR RECORDS

When to use: User wants to find lookalikes, related records, "find more like this", or records connected through shared properties/memories.

SDK: client.memory.similar({seed: {email}, dimensions, topK}) MCP: memory_find_similar CLI: personize memory similar --email <email>

Key parameters:

Tiers: very_similar (>=0.75), similar (>=0.5), somewhat_similar (>=0.3)

Example:

// Find 10 records most similar to john@acme.com
const result = await client.memory.similar({
    seed: { email: 'john@acme.com' },
    topK: 10,
    dimensions: 'hybrid',
});
// result.data.results[0].recordId, .score, .tier, .matchBreakdown
// result.data.tiers.very_similar = ['REC#...', ...]

Cost: 1 credit per request.

See reference/similar.md for full parameter and response reference.

Action: SEGMENT AUDIENCE

When to use: User wants to bucket, tier, or segment records relative to a seed record or text description.

SDK: client.memory.segment({seed: {email} | {text}, maxPerTier}) MCP: memory_segment CLI: personize memory segment --email <email> or --text "description"

Key parameters:

Example:

// Segment all records relative to an ICP description
const result = await client.memory.segment({
    seed: { text: 'Enterprise SaaS CTO interested in AI automation' },
    maxPerTier: 20,
});
// result.data.tiers.very_similar.recordIds = ['REC#...', ...]
// result.data.tiers.very_similar.count = 12
// result.data.tiers.not_similar.approximate = true

Cost: 2 credits per request.

See reference/segment.md for full parameter and response reference.

SDK Method Reference

import { Personize } from '@personize/sdk';
const client = new Personize({ secretKey: process.env.PERSONIZE_SECRET_KEY! });

Memorize Methods

Recall Methods

Similarity Methods

CRUD Methods

Key Type Signatures

// memorize() — single item
interface MemorizeProOptions {
    content: string;           // The text to memorize
    speaker?: string;          // Who said/wrote it
    timestamp?: string;        // When it happened
    email?: string;            // Match to contact by email
    website_url?: string;      // Match to company by website
    record_id?: string;        // Match to record by ID
    enhanced?: boolean;        // Enable AI extraction (default: false)
    tags?: string[];           // Categorization tags
    max_properties?: number;   // Max properties to extract
    schema?: Record<string, unknown>; // Extraction schema hint
    extractionPrompt?: string;       // Guide what extraction focuses on (max 500 chars)
    actionId?: string;         // Target collection ID
}

// memorizeBatch() — batch sync
interface BatchMemorizeOptions {
    source: string;            // Source system label ('Hubspot', 'Salesforce')
    mapping: {
        entityType: string;    // 'contact', 'company'
        email?: string;        // Source field name for email
        website?: string;      // Source field name for website
        runName?: string;      // Tracking label
        properties: Record<string, {
            sourceField: string;       // Source field name in row data
            collectionId: string;      // Target collection ID
            collectionName: string;    // Target collection name
            extractMemories?: boolean; // AI extraction for this property
        }>;
    };
    rows: Record<string, unknown>[]; // Source data rows
    dryRun?: boolean;          // Validate without writing
    chunkSize?: number;        // Rows per chunk (default: 1)
}

// smartRecall() — semantic search (recommended)
interface SmartRecallOptions {
    query: string;             // Natural language query
    limit?: number;            // Max results (default: 10)
    minScore?: number;         // Minimum relevance score (0-1)
    email?: string;            // Scope to one contact
    website_url?: string;      // Scope to one company
    record_id?: string;        // Scope to one record
    type?: string;             // Entity type filter (optional — inferred from email/website_url)
    include_property_values?: boolean; // Include structured properties
    enable_reflection?: boolean;       // AI reflects on results
    generate_answer?: boolean;         // AI generates a direct answer
    mode?: 'fast' | 'deep';    // 'fast' skips reflection + answer gen, ~500ms; 'deep' enables full reflection (default: 'deep')
    min_score?: number;        // Server-side score filter (in fast mode, defaults to 0.3)
}

// recall() — direct lookup (simpler, type required)
interface RecallOptions {
    query: string;             // Natural language query
    type: string;              // Entity type — REQUIRED (e.g. 'Contact', 'Company')
    record_id?: string;        // Scope to one record
    email?: string;            // Scope to one contact
    website_url?: string;      // Scope to one company
    filters?: Record<string, unknown>; // Additional filters
}

// smartDigest() — entity context
interface SmartDigestOptions {
    email?: string;            // Contact email
    website_url?: string;      // Company website
    record_id?: string;        // Record ID
    type?: string;             // Entity type ('Contact', 'Company')
    customKeyName?: string;    // Custom identifier field (e.g. 'linkedin_url', 'student_number')
    customKeyValue?: string;   // Custom identifier value
    token_budget?: number;     // Max tokens for output (default: 1000)
    max_memories?: number;     // Max memories to include (default: 20)
    include_properties?: boolean; // Include structured properties (default: true)
    include_memories?: boolean;   // Include free-form memories (default: true)
}

The Data Model

┌─────────────────────────────────────────────────────────────┐
│                    PERSONIZE MEMORY                          │
│                                                             │
│  ┌───────────────────┐    ┌──────────────────────────────┐  │
│  │  STRUCTURED DATA  │    │     SEMANTIC MEMORIES         │  │
│  │  (DynamoDB)       │    │     (Vector Store)            │  │
│  │                   │    │                              │  │
│  │  Records:         │    │  AI-extracted facts from:    │  │
│  │  ├─ email: "..."  │    │  ├─ Call notes              │  │
│  │  ├─ plan: "pro"   │    │  ├─ Support tickets         │  │
│  │  ├─ title: "VP"   │    │  ├─ Email threads           │  │
│  │  └─ login_count:5 │    │  ├─ Meeting transcripts     │  │
│  │                   │    │  └─ Generated outputs        │  │
│  └───────────────────┘    └──────────────────────────────┘  │
│           │                            │                    │
│           ▼                            ▼                    │
│     search() filters           smartRecall() searches        │
│     memorize() writes          memorizeBatch() writes       │
│     smartDigest() reads both ──────────┘                    │
└─────────────────────────────────────────────────────────────┘

• Structured data = exact key-value pairs. Queryable by field, filterable, paginated.
• Semantic memories = AI-extracted facts with vector embeddings. Searchable by meaning.
• smartDigest combines both into a single, token-budgeted markdown block.

Available Resources

Entity Type Management

Entity types define the schema for your memory records (Contact, Company, Employee, etc.). Each org has system-built types and can have custom types. Use these endpoints to inspect and customize entity type metadata -- you cannot change the slug or archive system types.

When to Use

SDK Methods

Note: MCP does not currently expose entity type management tools. Use the SDK or REST API directly.

Key Parameters -- update()

Constraints:

• slug and isSystem cannot be changed via API (silently ignored)
• System types cannot be archived (returns 403)
• Restore an archived custom type: update(id, {status: 'Active'})

Quick Example

// List all entity types
const types = await client.entityTypes.list();
// types.data -> EntityTypeResponse[]

// Update label and icon
await client.entityTypes.update('act_xxx', {
    name: 'Lead',
    pluralLabel: 'Leads',
    icon: 'user-plus',
    color: '#4F46E5',
});

// Archive a custom entity type
await client.entityTypes.archive('act_xxx');

// Restore it later
await client.entityTypes.update('act_xxx', { status: 'Active' });

Signal Memorization Patterns

@personize/signal uses entity memory for its feedback loop and deferred notification pipeline. Understanding these patterns helps when debugging Signal behavior or building custom integrations.

Tag Conventions

Feedback Loop

After every SEND decision, Signal memorizes what was sent:

await client.memory.memorize({
    content: `[SIGNAL] Sent "${subject}" via ${channel} (score: ${score}). ${reasoning}`,
    email,
    enhanced: true,
    tags: ['signal:sent', `signal:channel:${channel}`, `signal:type:${eventType}`],
});

On the next evaluation for the same entity, the engine recalls recent signal:sent memories (step 3, 4th parallel call). The AI sees what was recently sent and can SKIP to avoid repetition — even if the pre-check dedup window has expired.

Deferred → Digest Pipeline

1. Defer (score 40-60): memorize() with tags ['signal:deferred', 'signal:pending-digest', eventType]
2. Digest build: smartRecall({query: 'deferred notifications', tags: ['signal:deferred']}) retrieves pending items
3. Compile: prompt() generates a personalized digest from all deferred items + entity context
4. Deliver: Channel sends the compiled digest
5. Mark processed: memorize() with tag signal:digest — future digest builds skip already-compiled items

Querying Signal History

// What notifications has Signal sent to this contact?
const sent = await client.memory.smartRecall({
    query: 'notifications sent by signal',
    email: 'jane@acme.com',
    type: 'Contact',
    mode: 'fast',
    limit: 10,
});

// What's pending in the digest queue?
const pending = await client.memory.smartRecall({
    query: 'deferred notifications pending digest',
    email: 'jane@acme.com',
    type: 'Contact',
    mode: 'fast',
    limit: 20,
});