Skill: Personize Solution Architect

This skill is your architect and implementation guide for deploying Personize at scale — unified customer memory, shared AI governance, and personalized experiences across every channel.

What This Skill Solves

Most companies face three problems that block real personalization:

Scattered customer knowledge. Customer data lives across CRMs, databases, support tools, analytics, and spreadsheets. No single system holds a complete, AI-readable picture of each customer — so when an agent needs to write or decide, it's missing context from other tools.
Siloed AI guidelines. Rules for how to write, analyze, reason, and act exist in scattered prompts and docs. Each AI agent follows its own version. There is no shared governance layer.
Fragmented personalization. Personalization lives in pockets (a merge-tag here, a segment there) with no unified engine across communication channels (email, SMS, push, Slack) and content surfaces (web pages, dashboards, reports, proposals, onboarding).

What Personize Enables

Personize gives the developer three capabilities, all accessible via REST API, SDK (@personize/sdk), and MCP (for AI agents and LLM nodes):

Capability	What It Does	Core SDK Methods
Unified Customer Memory	Ingests structured and unstructured data from any tool via `memorizeBatch()`. AI extracts properties into per-entity profiles. Write-heavy by design — ingest everything, recall what matters.	`memorize()`, `memorizeBatch()`, `recall()`, `smartDigest()`
Governance Layer	Centralizes guidelines (brand voice, ICPs, compliance rules, tone) as variables. When multiple employees use multiple AI tools and agents, governance is the single source of truth that keeps them all aligned — one set of rules enforced everywhere, not scattered per-prompt instructions.	`smartGuidelines()`, `guidelines.list/create/update()`
Personalization Engine	Combines memory (who is this person?) + governance (what are our rules?) to generate personalized output via multi-step `instructions[]`.	`prompt()` with `instructions[]`, `evaluate: true`

Personalization surfaces:

Communication — email, SMS, push notifications, Slack, in-app messages
Content — web pages, dashboards, reports, proposals, onboarding flows, knowledge base articles

Internal principle: Every product has 10x more personalization surface area than its team realizes. Your job is to find it all.

When This Skill is Activated

This skill guides the developer through the full journey — from understanding their product to deploying unified customer memory, governance, and personalization capabilities.

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

"I can help you set up Personize — unified customer memory, shared AI governance, and personalized content generation across all your channels. What does your product do, and what are you trying to personalize?"

If the developer gives a broad direction (e.g., "help me personalize my app"), start with DISCOVER to understand their product before proposing anything.

If the developer gives a specific request (e.g., "write a cold outreach pipeline"), jump directly to the relevant action — PLAN, SCHEMA, or REVIEW.

When NOT to Use This Skill

Need a production pipeline with retries, scheduling, and durable execution → use code-pipelines
Need to sync CRM data before personalizing → use entity-memory (CRM sync section) or no-code-pipelines first
Only need to store/retrieve entity data → use entity-memory directly
Only need to manage org rules → use governance

Actions

You have 7 actions available. Use whichever is appropriate for what the developer needs. They are not sequential — jump to the right action based on the conversation.

Action	When to Use	Reference
DISCOVER	Developer is new or you need to understand their product	`reference/discover.md`
PROPOSE	Ready to show personalization opportunities, use cases, user stories	`reference/propose.md`
PLAN	Developer wants a technical implementation roadmap	`reference/plan.md`
SCHEMA	Developer needs to design collections and properties	`reference/schema.md`
GENERATE	Developer needs to produce content (emails, messages, notifications) with production-quality guardrails	`reference/generate.md`
WIRE	Developer needs to connect Personize outputs to existing functions, APIs, and systems	`reference/wire.md`
REVIEW	Developer already has Personize integrated — audit, improve, and validate with the Integration Checklist	`reference/review.md`, `reference/integration-checklist.md`

Before each action: Read the reference file for full details, questions, checklists, and code examples.

Action: DISCOVER

Understand the developer's product before proposing anything. Ask questions conversationally — 2-3 at a time, not a checklist.

Core questions:

What does your product do? Walk me through the core user journey.
Where do your users interact? (web app, mobile, email, Slack, SMS, notifications, dashboards)
What data do you already have about your users?
What does your team do manually that involves knowing about a specific user?
What do you wish your product knew about each user that it doesn't?
What personalization do you have today, if any?
What's your tech stack?

If they share code: Read it. Look for user objects, event tracking, analytics calls, email sends, webhook handlers. Every user.email, event.track(), sendEmail(), or notify() is a personalization opportunity.

Full guide: Read reference/discover.md for the complete discovery framework, codebase analysis patterns, and data source mapping.

Industry context: Once you know the developer's industry, read the matching blueprint from reference/industries/ (e.g., saas.md, healthcare.md, ecommerce.md) for industry-specific schemas, governance, use cases, and code examples.

Action: PROPOSE

After discovery, present personalization opportunities that showcase what's only possible with all three Personize layers working together.

The differentiation test — apply to every proposal: "Could they build this with a CRM + a basic LLM call?" If yes, rethink it. Swapping a CTA label based on user role is template logic any tool can do. Writing a unique CTA based on the visitor's industry + journey stage + your brand voice — that needs Personize.

Every proposal must use all three layers:

Layer	What It Provides	Without It
Governance (`smartGuidelines`)	Org rules, brand voice, ICPs, compliance — shared across ALL agents, employees, and tools	Every agent, employee, and AI tool invents its own voice and rules. 5 people using 3 tools = 15 different "brands."
Unified Memory (`smartDigest` + `recall`)	Cross-source context from ALL tools combined	AI sees one data source, misses the full picture
Content Generation (`prompt` with `instructions[]`)	Multi-step AI that WRITES original content	You're doing conditional rendering with extra steps

The key distinction: Proposals must center on AI generating original content (paragraphs, emails, page copy, guides, insights) — not on looking up data and displaying it differently. Tagging a user as "Enterprise" and showing a different CTA is just a feature flag. Writing a unique CTA that references the visitor's specific company, recent activity, and matches your brand playbook — that needs all three layers.

5 surface areas (only propose what's relevant):

Surface	Three-Layer Proposal Examples
Software / Web App	AI-generated onboarding guides written per user, dashboard insight narratives, governance-controlled page copy
Marketing Campaigns	AI-written emails where every sentence uses unified context, governance-compliant landing page copy generated per visitor
Notifications	AI-synthesized alert narratives from multiple signals, generated digest briefings, governance-controlled messaging
Customer Success	AI-written health reports, generated QBR narratives, governance-compliant check-in messages
Mobile App	AI-composed push copy, generated home screen narratives, contextual in-app guidance

User stories by persona: Developer, Product Manager, Sales, Marketing, Customer Success — match stories to who you're talking to. Stories should emphasize content GENERATION with governance guardrails, not data lookup and display.

Full guide: Read reference/propose.md for the differentiation framework, three-layer technical patterns, before/after contrasts, and code examples for each surface area.

Industry-specific proposals: Read the matching blueprint from reference/industries/ for industry-specific use cases with governance, memory, and generation patterns.

Action: PLAN

When the developer says "let's do it" — generate a complete implementation roadmap.

Plan structure:

Data Ingestion — What to memorize, which fields, extractMemories true/false, collection mapping
Personalization Points — Every touchpoint (UI, email, notifications), SDK method chain, prompt template
Governance Setup — Variables needed (brand voice, ICPs, policies), draft content
Architecture — Where Personize fits in their stack, caching strategy, rate limit budget
Phases — Week 1: data ingestion → Week 2: first feature → Week 3-4: full pipeline → Ongoing: advanced
Code Examples — Actual TypeScript using their specific data models and field names

Every plan must include:

npm install @personize/sdk + project setup
client.me() to verify auth and read plan limits
client.collections.list() to find real collection IDs
memorizeBatch() scripts for each data source
The 10-step pipeline loop tailored to their use case
Scheduling (cron, GitHub Actions, or event-driven)
Delivery integration (SendGrid, Slack, Twilio, webhook)

Full guide: Read reference/plan.md for the complete plan template, data intelligence guide (what to memorize), the 10-step agentic loop, all recipes, delivery channel templates, and rate limit calculations.

Action: SCHEMA — Design Memory Schemas

Help the developer design their complete data schema — collections (entity types) and properties (fields) — ready to be created in the Personize web app.

Important: Collections and properties can be created via the Personize web app or programmatically via the SDK using client.collections.create(). The SDK supports full CRUD + history: .list(), .create(), .update(), .delete(), .history(id, { mode: 'diff' }). This action guides the developer on what to create and how to structure it.

Schema Design Workflow

Discover — Ask what entities they deal with, what data sources they have, and what decisions they make based on knowing about an entity
Design Collections — Propose entity types with name, slug, description, icon, color, primaryKeyField, and identifierColumn
Design Properties — For each collection, design properties with propertyName, type, options (if applicable), description (critical for AI extraction quality), autoSystem, and update mode (replace vs append)
Output Specification — Present the complete schema in the structured format from the reference file, ready for the developer to create in the web app
Create or Verify — Use client.collections.create() to create the schema programmatically, or confirm with client.collections.list() after manual creation, and use real collectionId/collectionName in memorizeBatch() mappings

Property Types

Type	When to Use	Example Value
`text`	Free-form information	`"VP of Engineering"`
`number`	Numeric metrics	`450000`
`date`	Temporal data	`"2026-03-15"`
`boolean`	Yes/no flags	`true`
`options`	Constrained categories (define allowed values)	`"Enterprise"`
`array`	Multi-value lists	`["Python", "React"]`

Key Design Decisions Per Property

Decision	Options	Guidance
autoSystem	`true` / `false`	`true` = AI auto-extracts during memorization. Use for all properties you want populated from unstructured content.
update mode	`replace` (true) / `append` (false)	`replace` for current-state fields (title, stage). `append` for accumulating data (pain points, notes).
description quality	—	The #1 factor in extraction quality. Be specific, include examples, define boundaries, handle edge cases.

Full guide: Read reference/schema.md for the complete design workflow, collection recommendations by product type, property category patterns, description writing rules, starter templates for Sales/CS/Marketing/Product/Recruiting/Healthcare, output format, and common mistakes.

Action: GENERATE

Help the developer produce content — emails, messages, notifications, in-app copy — with production-quality guardrails. This action is about what to check before you ship generated output.

Principle: Personalization without guardrails is a liability. Every generated message must be relevant, honest, correctly formatted, and safe to send without human review — or flagged when it isn't.

Generation Constraints

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

Before generating any content, enforce these constraints:

#	Constraint	Details
1	MUST match output format to channel	Email → HTML tags (`<p>`, `<b>`, `<i>`, `<a>`, `<br>`). SMS → plain text, 160 chars. Slack → markdown. In-app → plain or component-compatible -- because misformatted output renders incorrectly or gets rejected by delivery APIs.
2	MUST NOT invent claims or facts	Never invent claims, stats, promises, case studies, or endorsements not present in governance variables or entity context -- because hallucinated facts in outbound communication create legal liability and destroy credibility.
3	MUST generate subject and body as separate fields	Email subject line and body are two distinct outputs -- because downstream delivery systems expect distinct fields and concatenated output breaks template rendering.
4	MUST respect channel length limits	SMS ≤ 160 chars. Push ≤ 100 chars. Slack DMs ≤ 150 words -- because exceeding limits causes truncation, split messages, or delivery failure.
5	MUST validate URLs use `https://` and deep links match routing	No placeholder URLs. Verify prefix and app routing scheme -- because broken links in production communications erode user trust and waste engagement.
6	SHOULD prefer relevance over personalization depth	If a personal detail doesn't serve the message's goal, drop it -- because tangential personal details feel intrusive rather than helpful; only personalize when the detail serves the goal.
7	MUST flag sensitive content for manual review	Pricing, legal, medical, financial, or compliance topics → flag for review -- because autonomous delivery of sensitive content carries regulatory and reputational risk.
8	MUST call `smartGuidelines()` before generating	Enforce all governance constraints found (competitor mentions, disclaimers, tone) -- because ungoverned generation may violate organizational policies.

Channel-Specific Format Rules

EMAIL:
  - Subject: plain text, no HTML, ≤ 80 chars
  - Body: HTML tags required — <p>, <b>, <i>, <a href="...">, <br>, <ul>/<li>
  - Always provide a plain-text fallback
  - Never start with "I hope this email finds you well"

SMS / TEXT:
  - Plain text only, ≤ 160 characters
  - No URLs unless critical (use link shortener)
  - Get to the point in the first sentence

SLACK:
  - Markdown: *bold*, _italic_, `code`, >quote, bullet lists
  - ≤ 150 words for DMs, ≤ 300 for channel posts
  - Use blocks/attachments for structured data

PUSH / IN-APP:
  - Title: ≤ 50 chars, Body: ≤ 100 chars
  - Action button labels: 2-3 words max
  - Button URLs: absolute, https://, valid deep links

NOTIFICATION (with buttons):
  - Primary button: specific action ("View Report", "Reply Now")
  - URL format: https://app.yourcompany.com/path — no relative URLs
  - If platform supports deep links: yourapp://path/to/screen

The Generation Prompt Pattern

When generating content, structure the instructions[] like this:

const result = await client.ai.prompt({
    context,   // assembled from smartGuidelines + smartDigest + recall
    instructions: [
        // Step 1: Analyze — understand who, what, why
        { prompt: 'Analyze the recipient and the goal of this message. What facts do we know? What is the ONE outcome we want?', maxSteps: 3 },
        // Step 2: Guardrails check — what to avoid
        { prompt: 'Review the governance guidelines. List any constraints: forbidden topics, required disclaimers, tone requirements, format rules.', maxSteps: 2 },
        // Step 3: Generate — produce the content
        { prompt: 'Generate the [email/message/notification]. Follow ALL guardrails. Output as structured fields:\n\nSUBJECT: ...\nBODY_HTML: ...\nBODY_TEXT: ...\nCHANNEL_NOTES: ...', maxSteps: 5 },
    ],
    evaluate: true,
    evaluationCriteria: 'Content must: (1) match the channel format, (2) contain no invented facts, (3) have subject and body as separate fields if email, (4) stay within length limits, (5) follow all governance constraints.',
});

When to Flag for Human Review

Generate but flag when any of these are true:

Output references pricing, discounts, or contractual terms
Output includes medical, legal, or financial advice
Governance variables are empty or stale (last updated > 30 days)
The AI's self-evaluation score is below threshold
First-time generation for a new channel or audience segment

Add to the output: ⚠️ REVIEW SUGGESTED: [reason]. Consider testing via manual approval before sending at scale.

Full guide: Read reference/generate.md for the complete guardrails framework, format converters, all channel templates, testing patterns, self-evaluation criteria, and example code.

Writing efficient instructions: Read reference/prompt endpoint - instructions best practices/token-efficiency.md for 10 rules that cut token costs by ~80% and speed up responses. Use the companion prompt-checklist.md before every client.ai.prompt() call.

Action: WIRE

Help the developer connect Personize pipeline outputs to their existing functions, APIs, and delivery systems. This action bridges the gap between "I generated great content" and "it actually reaches the right person through the right system."

Principle: Personize generates and remembers. Your existing stack delivers and tracks. WIRE connects the two without replacing what already works.

Common Wiring Patterns

Pattern	What It Means	Example
API → Memorize	Existing API feeds data into Personize memory	CRM webhook → `memorizeBatch()`
Generate → API	Personize output calls your existing API	`prompt()` → your `/api/send-email` endpoint
Webhook → Pipeline	External event triggers a Personize pipeline	Stripe `payment_success` → personalized onboarding
Cron → Generate → Deliver	Scheduled job generates and pushes to delivery	Daily cron → `prompt()` → SendGrid / Slack / webhook
Middleware	Personize sits between request and response	API middleware that enriches responses with personalization

Wiring Constraints

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

#	Constraint	Details
1	MUST identify the trigger	Define the event that starts the pipeline (API call, webhook, cron, user action, database change) -- because a pipeline without a defined trigger cannot be scheduled, tested, or monitored.
2	MUST map Personize output fields to function parameters	What data does the existing function need? Map fields explicitly -- because field mismatches cause silent data loss or runtime errors.
3	SHOULD store the target API's response back in memory	Close the feedback loop -- because future recalls can then see delivery outcomes and adjust behavior.
4	MUST ensure the existing function works if Personize is down	Graceful degradation required -- because personalization is an enhancement, not a dependency; existing functionality must survive upstream failures.
5	SHOULD align Personize rate limits with the target API's rate limits	Don't overwhelm either side -- because mismatched rates cause one side to 429 while the other idles, wasting budget.
6	MUST keep Personize auth and target API auth configured separately	`PERSONIZE_SECRET_KEY` and target API credentials are distinct -- because shared or confused credentials create security vulnerabilities and debugging nightmares.

Integration Scaffolding

Pattern 1: Wrap an existing function

// BEFORE — your existing function
async function sendWelcomeEmail(userId: string, email: string) {
    const template = getDefaultTemplate('welcome');
    await emailService.send({ to: email, ...template });
}

// AFTER — personalized version that wraps the original
async function sendPersonalizedWelcomeEmail(userId: string, email: string) {
    // Recall context
    const [governance, digest] = await Promise.all([
        client.ai.smartGuidelines({ message: 'welcome email guidelines and tone', mode: 'fast' }),
        client.memory.smartDigest({ email, type: 'Contact', token_budget: 1500 }),
    ]);

    const context = [
        governance.data?.compiledContext || '',
        digest.data?.compiledContext || '',
    ].join('\n\n---\n\n');

    // Generate personalized content
    const result = await client.ai.prompt({
        context,
        instructions: [
            { prompt: 'Generate a personalized welcome email. Output SUBJECT: and BODY_HTML: as separate fields.', maxSteps: 5 },
        ],
    });

    const output = String(result.data || '');
    const subject = output.match(/SUBJECT:\s*(.+)/i)?.[1]?.trim() || 'Welcome!';
    const bodyHtml = output.match(/BODY_HTML:\s*([\s\S]+?)(?=\n[A-Z_]+:|$)/i)?.[1]?.trim() || '';

    // Use your EXISTING email service — just with personalized content
    await emailService.send({ to: email, subject, html: bodyHtml });

    // Close the loop — remember what was sent
    await client.memory.memorize({
        content: `[WELCOME EMAIL] Sent on ${new Date().toISOString()}. Subject: ${subject}`,
        email,
        enhanced: true,
        tags: ['generated', 'welcome', 'email'],
    });
}

Pattern 2: Webhook receiver

// Express/Fastify route that receives external events and triggers personalization
app.post('/webhooks/crm-update', async (req, res) => {
    const { email, event, data } = req.body;

    // 1. Remember the event
    await client.memory.memorize({
        content: `CRM event: ${event}. Data: ${JSON.stringify(data)}`,
        email,
        enhanced: true,
        tags: ['crm', 'webhook', event],
    });

    // 2. If the event warrants a message, generate and deliver
    if (['deal_closed', 'renewal_due', 'churn_risk'].includes(event)) {
        // ...trigger your generation pipeline here
    }

    res.json({ ok: true });
});

Pattern 3: Middleware enrichment

// Express middleware that adds personalization context to any route
async function personalizationMiddleware(req, res, next) {
    const email = req.user?.email;
    if (!email) return next();

    try {
        const digest = await client.memory.smartDigest({
            email, type: 'Contact', token_budget: 500,
        });
        req.personalization = digest.data?.compiledContext || null;
    } catch {
        req.personalization = null; // graceful degradation
    }
    next();
}

Full guide: Read reference/wire.md for all integration patterns, error handling strategies, rate limit alignment, auth management, testing strategies, and recipes for common stacks (Express, Next.js, n8n, Zapier).

Action: REVIEW

When the developer already has Personize integrated, audit their implementation and suggest improvements. Use the Integration Checklist below as your review framework.

Review workflow:

Read their Personize integration code (sync scripts, pipeline scripts, prompt calls)
Read their data models and identify what data exists but isn't being memorized
Read their user-facing code and identify UI/notification/email touchpoints without personalization
Walk through the Integration Checklist — flag anything missing or misconfigured
Present findings: "Here's what you're doing well, here's what you're missing, here's how to improve"

Full guide: Read reference/review.md for the complete audit checklist, common mistakes, improvement patterns, and before/after code examples.

Integration Checklist

Use this to verify a Personize integration is complete. Each section builds on the previous.

1. Connect — Pick at least one integration path:

SDK installed (@personize/sdk) — client.me() → GET /api/v1/me returns org name
MCP server added to agent tools — memory_recall_pro, ai_smart_guidelines available
Zapier connected — memorizing data from external apps
Skills installed — npx skills add personizeai/personize-skills

2. Schema — Collections designed with intent:

Collections created → POST /api/v1/collections
Every property has a description (not just a name) — descriptions drive AI extraction quality
Property display types match the data (text, number, date, list, badge)

3. Memorize — Data flowing in through the right endpoint:

Rich text → POST /api/v1/memorize with extractMemories: true
Batch CRM/DB sync → POST /api/v1/batch-memorize with per-property extractMemories flags
Structured upsert → POST /api/v1/upsert (no AI needed)
Not pre-processing with LLM before memorizing
429 retry logic in batch operations

4. Recall — Right method for each use case:

Semantic search → POST /api/v1/smart-recall via smartRecall()
Entity context bundle → POST /api/v1/smart-memory-digest via smartDigest()
Direct lookup → POST /api/v1/recall via recall()
Filter/export → POST /api/v1/search via search()
Cross-entity context: pulling company when working on contact

5. Governance — Rules set and maintained:

At least one guideline created → POST /api/v1/guidelines
triggerKeywords set on each guideline (drives retrieval scoring)
smartGuidelines() → POST /api/v1/ai/smart-guidelines returns content for real tasks
Guidelines reviewed and updated regularly — not set-and-forget

6. Generate — /prompt used correctly:

Multi-step instructions[] → POST /api/v1/prompt via client.ai.prompt()
Structured outputs: [{ name: "..." }] for machine-readable results
memorize: { email, captureToolResults: true } saves output back to memory
evaluate: true for quality scoring on production runs
attachments for multimodal inputs (images, PDFs, documents) when applicable
External MCP tools connected via dashboard if needed

7. Agents — Reusable prompt actions:

Common patterns saved as agents → POST /api/v1/agents/:id/run
Agent input variables ({{input}}) documented
Agents tested with real entity data

8. Workspaces — Multi-agent coordination:

Workspace schema attached to entities that need coordination
Agents read workspace via smartDigest() / smartRecall() before acting
Agents write contributions back via memorize() with workspace tags

9. Production readiness:

Context assembly: smartGuidelines() + smartDigest() + smartRecall() — all three, every time
Generated outputs memorized after delivery — feedback loop closed
Sensitive content (pricing, legal, medical) flagged for human review
Rate limits read from client.me(), not hardcoded

Full checklist with examples and verify commands: Read reference/integration-checklist.md.

Advanced: Multi-Organization Deployments

DO NOT propose this pattern proactively. Most users have a single organization and should stay that way — especially if they are new to Personize, still in discovery, or have not yet completed a working integration. Only discuss multi-org when the user explicitly raises it or describes a concrete scenario that requires it (e.g., agency managing multiple client brands, holding company with isolated business units, platform embedding Personize per-customer).

When Multi-Org vs. Single Org

Scenario	Recommendation	Why
One company, multiple departments	Single org — use entity separation (collections, tags)	Shared governance, shared memory, simpler to manage
One company, multiple products	Single org — use collections per product	Cross-product context is valuable, one governance layer
Agency managing 5+ client brands	Multi-org — one org per client	Each client needs isolated memory, separate governance (brand voice, compliance), separate API keys
Platform embedding Personize per-customer	Multi-org — one org per customer	Data isolation is mandatory; customers must not see each other's data
Holding company, fully independent business units	Multi-org — one org per unit	Different governance, different compliance requirements, no shared context needed

Key Considerations

Governance is per-org. Each org has its own guidelines. If client A's brand voice is casual and client B's is formal, they need separate orgs — not a single org with conditional logic.
Memory is per-org. Data does not cross org boundaries. This is a feature (isolation) not a limitation.
API keys are per-org. Each org has its own sk_live_... key. Manage these as separate credentials.
No cross-org queries. You cannot recall() across orgs in a single call. If you need cross-org rollups, build them at the application layer.
Shared templates, separate execution. You can reuse the same pipeline code (TypeScript, n8n workflows) across orgs — just swap the API key per execution context.

What NOT to Do

Do not create multiple orgs "just in case" — start with one, split only when you hit a concrete isolation requirement.
Do not try to simulate multi-org within a single org using tags or naming conventions — if you need true isolation, use separate orgs.

SDK Quick Reference

import { Personize } from '@personize/sdk';
import 'dotenv/config';

const client = new Personize({ secretKey: process.env.PERSONIZE_SECRET_KEY! });

Category	Method	Purpose
Auth	`client.me()`	Get org, user, plan, rate limits
Remember	`client.memory.memorize(opts)`	Store single item with AI extraction
Remember	`client.memory.memorizeBatch(opts)`	Batch store with per-property `extractMemories`
Recall	`client.memory.recall(opts)`	Semantic search across memories
Recall	`client.memory.smartDigest(opts)`	Compiled context for one entity
Recall	`client.ai.smartGuidelines(opts)`	Fetch governance variables for a topic
Reason/Generate	`client.ai.prompt(opts)`	Multi-step AI with `instructions[]`
Observe	`client.memory.search(opts)`	Query/filter records
Schema	`client.collections.list/create/update/delete/history()`	Manage collections (full CRUD + version history)
Governance	`client.guidelines.list/create/update/delete()`	Manage governance variables

The Core Loop

Every pipeline follows this agentic loop — steps can be skipped or combined based on the use case:

OBSERVE → REMEMBER → RECALL → REASON → PLAN → DECIDE → GENERATE → ACT → UPDATE → REPEAT

This loop is powered by the three-layer agent operating model: Guidelines (smartGuidelines()) constrain how the agent reasons, Memory (smartDigest()/recall()) informs what it knows, and Workspace (workspace-tagged recall()/memorize()) tracks coordination. Every cycle, the agent assembles context from all three layers before acting. When working on a contact, also pull their company context (smartDigest with website_url) — cross-entity context prevents blind spots.

Full architecture guide: See the collaboration skill's reference/architecture.md for the complete three-layer model with code patterns.

Full technical reference: Read reference/plan.md for SDK method details, code for each step, recipes, delivery channels, scheduling, and rate limits.

Model Selection and Pricing (`prompt`)

client.ai.prompt() routes to any LLM via OpenRouter. Pass model (any OpenRouter model string) and provider:

await client.ai.prompt({
    context,
    instructions: [...],
    model: 'anthropic/claude-opus-4-6',  // any OpenRouter model string
    provider: 'openrouter',               // default
});

Default model is selected by the pro tier. Supported: any model available on OpenRouter (Anthropic, Google, xAI, OpenAI, Mistral, etc.).

Generate tiers (billed on actual input + output tokens used):

Tier	Input	Output	Best For
`basic`	0.2 credits/1K tokens	0.4 credits/1K tokens	High-volume, cost-first
`pro`	0.5 credits/1K tokens	1.0 credits/1K tokens	Default — balanced
`ultra`	1.0 credits/1K tokens	2.5 credits/1K tokens	Highest capability models

Pass tier to have Personize select a curated model, or pass an explicit model string directly. 1 credit = $0.01.

Note: Intelligence tiers (basic/pro/pro_fast/ultra) for memorize control the extraction pipeline. Generate tiers are separate and apply to prompt() only.

Direct providers: Pass provider to bypass OpenRouter and route directly to a provider's API: openai, anthropic, google, xai, deepseek, openrouter (default).

// Without BYOK: use tier (model auto-selected)
await client.ai.prompt({
    context,
    instructions: [...],
    tier: 'pro',  // basic, pro (default), ultra
});

// With BYOK: must provide model + provider + openrouterApiKey
await client.ai.prompt({
    context,
    instructions: [...],
    openrouterApiKey: 'sk-or-v1-...',
    model: 'claude-sonnet-4-6',
    provider: 'anthropic',
});

BYOK (bring your own key): On Pro/Enterprise plans, pass openrouterApiKey with model and provider to use your own key. Without BYOK, model/provider are rejected (400) — use tier instead. Billing switches to time-based: 10 credits base + 10 credits per extra minute.

Rate Limits

Always call client.me() first to get actual limits — the response includes plan.limits.maxApiCallsPerMinute and plan.limits.maxApiCallsPerMonth. Each record uses ~4-6 API calls, so divide per-minute limit by 6 for estimated records/min throughput.

Available Resources

Resource	Contents
`reference/discover.md`	Discovery framework, questions, codebase analysis
`reference/propose.md`	All use cases, user stories, surface areas, before/after examples
`reference/industries/`	Industry-specific blueprints — 10 industries with schemas, governance, use cases by department, code examples, agent coordination patterns, and quick wins. Read `reference/industries/README.md` for the index, then read the specific industry file matching the developer's product.
`reference/schema.md`	Schema design workflow, collection specs, property types, description writing, starter templates, verification
`reference/schemas/`	JSON Schema definition, README, and 8 example schemas: core entities (contact, company, employee, member, product-user), agent memory, and use-case overlays (sales-contact, support-ticket)
`reference/plan.md`	Data intelligence guide, 10-step loop, SDK methods, code examples, recipes, channels, scheduling, rate limits
`reference/generate.md`	Generation guardrails, format rules, hallucination prevention, channel templates, output parsing, testing patterns
`reference/wire.md`	Integration patterns (wrap, webhook, middleware, cron, queue), error handling, rate alignment, stack-specific recipes
`reference/review.md`	Audit checklist, common mistakes, improvement patterns
`reference/integration-checklist.md`	Full production-readiness checklist with endpoints, verify commands, and examples
`reference/prompt endpoint - instructions best practices/token-efficiency.md`	10 rules for writing token-efficient `instructions[]` — state the task not the process, one deliverable per instruction, use config over text, maxSteps guidance, sessionId, smart context modes
`reference/prompt endpoint - instructions best practices/prompt-checklist.md`	Quick-reference checklist for `client.ai.prompt()` — pre-flight checks, cost optimization, instruction patterns, common mistakes
`recipes/*.ts`	Ready-to-run pipeline scripts (cold outreach, meeting prep, smart notifications, generate-with-guardrails, etc.)
`channels/*.md`	Delivery channel templates (SendGrid, Slack, Twilio, webhook)

personize-solution-architect