personizeai/personize-governance

Skill: Personize Governance

These are the rules, policies, and best practices that every AI agent in your organization must follow. Always check Guidelines before generating content, making decisions, or taking actions. One update here → every AI tool in your org gets smarter.

Guidelines are stored as markdown documents and are automatically available to all agents via smartGuidelines. Use this skill to read, create, update, and manage them.

This skill supports two workflows: conversational editing (chat, SDK scripts, automated pipelines) and GitOps sync (.md files in a Git repo synced to the API). Both produce the same output: well-structured guidelines available to all agents via smartGuidelines.

---

When NOT to Use This Skill

• Need to store data about contacts/companies → use entity-memory
• Need multi-agent coordination state (tasks, updates, issues) → use collaboration
• Need to plan a full Personize integration → use solution-architect

---

Actions

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

| Action | When to Use | Reference | |---|---|---| | CREATE | Admin shares content or wants a new guideline | reference/operations.md | | UPDATE | Admin wants to modify an existing guideline (section, append, replace) | reference/operations.md | | IMPROVE | Admin wants to clean up, restructure, or improve guideline quality | reference/operations.md | | AUDIT | A factual change affects multiple guidelines (pricing, branding, policy) | reference/operations.md | | VERIFY | Confirm agents can see the updated content via smartGuidelines | reference/operations.md | | SMART UPDATE | Admin has raw material (docs, notes, feedback, CRM exports) and wants AI to figure out what to create/update | reference/smart-update.md | | ONBOARD | First-time user with 0-2 guidelines — guide them through setup | reference/onboarding.md | | UPLOAD ATTACHMENT | User wants to attach a file (script, config, template, etc.) to a guideline | reference/governance-attachments.md | | LIST ATTACHMENTS | User wants to see what files are attached to a guideline | reference/governance-attachments.md | | READ ATTACHMENT | Agent needs the full content of an attachment | reference/governance-attachments.md | | DELETE ATTACHMENT | User wants to remove an attachment from a guideline | reference/governance-attachments.md |

Before each action: Read the reference file for full workflows, conversation patterns, and code examples.

---

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

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

| Interface | How it works | Best for | |---|---|---| | SDK (@personize/sdk) | client.guidelines.list(), client.guidelines.update(), etc. | Scripts, CI/CD, IDE agents, recipes | | MCP (Model Context Protocol) | guideline_list, guideline_read, guideline_create, guideline_update, guideline_delete tools | Claude Desktop, ChatGPT, Cursor, any MCP-compatible client |

MCP tools map 1:1 to SDK methods:

| SDK Method | MCP Tool | Purpose | |---|---|---| | client.guidelines.list() | guideline_list | List all guidelines (includes governanceScope) | | client.guidelines.getStructure(id) | guideline_read(guidelineId) | Get section headings (TOC) + governanceScope | | client.guidelines.getSection(id, { header }) | guideline_read(guidelineId, header) | Get section content | | client.guidelines.create(payload) | guideline_create(name, value, tags, description) | Create new guideline | | client.guidelines.update(id, payload) | guideline_update(guidelineId, value, updateMode, ...) | Update guideline | | client.guidelines.delete(id) | guideline_delete(guidelineId) | Delete guideline | | client.guidelines.history(id) | guideline_history(guidelineId) | View change history | | client.ai.smartGuidelines({ message }) | ai_smart_guidelines(message) | Verify/fetch guidelines | | client.context.save(opts) | context_save(type, instruction, material, ...) | AI-powered bulk create/update from raw material | | client.guidelines.uploadAttachment(id, opts) | guideline_attachment_upload | Attach a file (script, config, template, etc.) to a guideline | | client.guidelines.listAttachments(id) | guideline_attachment_list | List all attachments on a guideline | | client.guidelines.getAttachmentContent(id, attachmentId) | guideline_attachment_read | Read the full content of an attachment | | client.guidelines.deleteAttachment(id, attachmentId) | guideline_attachment_delete | Remove an attachment from a guideline |

AgentDocs: Unified Knowledge Layer

Guidelines are one type of AgentDoc. The AgentDocs layer unifies all org knowledge documents under a single API:

| Type | Purpose | When to use | |------|---------|-------------| | guideline | Enforceable rules (default) | Compliance, brand voice, coding standards | | playbook | Step-by-step processes | SOPs, runbooks, how-to guides | | reference | Background information | Definitions, glossaries, research | | template | Output scaffolds | Email templates, report formats | | brief | Account context | Customer briefs, deal context |

Use /api/v1/context for all types. /api/v1/guidelines remains a stable alias for guideline-type docs. /api/v1/agentdocs also remains a stable alias.

SDK: client.context.list({ type: 'playbook' }), client.context.create({ type: 'playbook', name: '...', value: '...' })

MCP: context_manage_create({ ..., agentDocType: 'playbook' }), context_manage_list({ agentDocType: 'playbook' })

Smart retrieval: Use ai_smart_docs (MCP) or client.ai.smartDocs() (SDK) to retrieve across all doc types with optional types filter. Use ai_smart_guidelines when you need guidelines only.

Canonical Names (v1.1)

The unified API rename introduces cleaner canonical routes alongside the stable aliases above:

| Canonical | Previous | Notes | |-----------|----------|-------| | POST /context/retrieve | POST /ai/smart-docs | AI-powered doc routing (type-filtered) | | POST /context/save | POST /smart-update | AI-powered doc evolution | | GET/POST /context/manage | GET/POST /agentdocs | List and create context docs | | context_retrieve (MCP) | ai_smart_docs | Canonical MCP tool name. Supports match='strict' (high-confidence only, for guidelines you'll act on without verification) and match='broad' + topK (hierarchical doc->sections, for surfacing related content broadly). | | context_save (MCP) | governance_smart_update | Canonical MCP tool name | | client.context.retrieve() (SDK) | client.ai.smartDocs() | Canonical SDK method | | client.context.save() (SDK) | client.guidelines.smartUpdate() | Canonical SDK method |

All old routes and tool names remain as stable aliases (/agentdocs/*, agentdocs_*, client.agentdocs.*).

---

context.retrieve — Match Mode and topK

The match parameter controls the precision-vs-breadth trade-off for every retrieval call:

| match | Behavior | When to use | |---------|----------|-------------| | balanced (default) | Standard semantic scoring, flat result list | Most cases | | strict | Applies abstention: returns nothing if best candidate scores below confidence threshold. alwaysOn guidelines are always included regardless. | When you will act on the result without human review — e.g. injecting guidelines directly into a system prompt | | broad | Returns a hierarchical response grouped by document (doc → sections). Higher recall, lower precision. Respects topK. | Surfacing related content for summarization, research, or display |

topK (integer 1–100, default 20): limits the number of sections returned. Only takes effect when match: 'broad'.

Other useful parameters:

• autoInferFilters: true — LLM classifies the query and injects types/tags automatically. Adds ~5s. Useful for open-ended queries; skip in agent hot paths.
• tagMode: 'any' | 'all' — controls how multiple tags combine (default any).
• excludeTags: string[] — exclude docs with these tags.
• minScore: number — cosine similarity floor (0–1). Default ~0.4. Use 0.2 for broad exploration, 0.7 for strict relevance.
• tier: 'basic' | 'pro' | 'ultra' — model tier for deep-mode routing (default pro).
• sessionId: string — deduplicate content across sequential calls in the same session.

// Default — balanced scoring, flat list
const result = await client.context.retrieve({ message: 'cold email tone' });

// Strict — abstains if nothing is confident enough (safe for auto-injection)
const result = await client.context.retrieve({
    message: 'cold email tone',
    match: 'strict',
});
// result.data.selection will be [] if no guideline met the confidence bar
// alwaysOn guidelines are still included regardless of score

// Broad — hierarchical, high recall (good for surfacing related content)
const result = await client.context.retrieve({
    message: 'everything about our email standards',
    match: 'broad',
    topK: 30,  // return up to 30 sections across all matching docs
});
// result.data.selection[i].sections[] contains section-level content

// autoInferFilters — LLM auto-classifies query intent and narrows types/tags
const result = await client.context.retrieve({
    message: 'anything about our onboarding process',
    autoInferFilters: true,
});

// Tag filtering with tagMode
const result = await client.context.retrieve({
    message: 'outreach email standards',
    tags: ['voice:outreach', 'playbook:sales'],
    tagMode: 'all',  // both tags must match
});

REST / CLI equivalents:

# CLI
personize context-docs retrieve "cold email tone" --match strict
personize context-docs retrieve "email standards" --match broad --top-k 30
personize context-docs retrieve "onboarding" --infer
personize context-docs retrieve "outreach email" --tags "voice:outreach,playbook:sales" --tag-mode all

# REST
POST /api/v1/context/retrieve
{ "message": "cold email tone", "match": "strict" }
{ "message": "email standards", "match": "broad", "topK": 30 }
{ "message": "onboarding", "autoInferFilters": true }
{ "message": "outreach email", "tags": ["voice:outreach"], "tagMode": "all" }

---

smartGuidelines Mode and Model

smartGuidelines has two modes and an optional model override:

| Mode | How it works | Latency | Cost | When to use | |---|---|---|---|---| | fast | Embedding-based routing only — no LLM | ~200ms | 0.1 credits/call | Real-time agents, loops, context injection | | deep | LLM selects and composes guidelines | ~3s | 0.5 credits/call | First call, complex queries, deep analysis |

Mode rename: 'full' was renamed to 'deep' in the SDK types and API. If you see mode: 'full' in older code, update it to mode: 'deep'.

1 credit = $0.01. Use fast in production pipelines — it handles the majority of cases well at 5× lower cost.

// Fast — embedding-only, no LLM overhead (default for real-time)
const guidelines = await client.ai.smartGuidelines({
    message: 'cold email tone and constraints',
    mode: 'fast',
});

// Deep — LLM-based routing, optional model override
const guidelines = await client.ai.smartGuidelines({
    message: 'cold email tone and constraints',
    mode: 'deep',
    model: 'anthropic/claude-sonnet-4-6',  // optional — override the LLM used for routing
});

No intelligence tiers — smartGuidelines does not use the basic/pro/pro_fast/ultra tier system (those are for memorize/batch-memorize only).

Content Budget: Use maxContentTokens to control delivery size. Default: 10,000 tokens. Long guidelines are auto-trimmed to the most relevant sections. Demoted guidelines return as summaries with section TOC for follow-up.

governanceScope is a read-only field returned on guideline_list and guideline_read (structure mode). It contains alwaysOn (boolean) and triggerKeywords (string array) — auto-inferred at save time. See the "Governance Scope" section below for details.

Response shape note: client.guidelines.list() returns { data: { actions: [...], count, nextToken? } } — guidelines are in data.actions, not a top-level array. Iterate with res.data?.actions || [].

When reading this skill document:

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

---

Prerequisites

SDK Mode

• @personize/sdk installed
• PERSONIZE_SECRET_KEY env var set to an sk_live_... key

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

MCP Mode

• Personize MCP server connected (SSE endpoint: https://agent.personize.ai/mcp/sse)
• API key provided via ?api_key=sk_live_... or OAuth configured
• Tools guideline_list, guideline_read, guideline_create, guideline_update, guideline_delete, guideline_history, and ai_smart_guidelines are automatically available

---

What Guidelines Are

Guidelines are organization-wide documents — policies, best practices, playbooks, checklists, technical manuals, how-tos — stored as markdown. Once saved, they are automatically available to all agents in the organization via client.ai.smartGuidelines(). When any agent asks smartGuidelines a question like "how should I write a cold email?", it retrieves the relevant guidelines and includes them as context.

Examples: sales-playbook, brand-voice-guidelines, icp-definitions, data-handling-policy, engineering-standards, incident-response-runbook, known-bugs-and-workarounds, pricing-rules

---

Action Summaries

CREATE — Draft a New Guideline

1. Ask admin for topic, audience, and source material
2. Check for overlap with existing variables (client.guidelines.list())
3. Draft with proper markdown structure (H1 title, H2 sections, actionable content)
4. Propose kebab-case name, tags, description
5. Show draft and ask for approval → create → verify with smartGuidelines

UPDATE — Modify Existing Guidelines

Choose the right update mode:

| Scope | Mode | When | |---|---|---| | Single section | section | "Update the Cold Email section" | | Add to a section | appendToSection | "Add a new rule to the Email Rules section" | | Add new section | append | "Add a GDPR section to the data policy" | | Full rewrite | replace | "Completely rewrite this variable" |

Workflow: find variable → read structure → read target section → draft update → show before/after → apply with historyNote

IMPROVE — Enhance Writing Quality

Read content → analyze structure/clarity/formatting/completeness → draft improved version → show summary of changes → apply

AUDIT — Cross-Guideline Accuracy Scan

Admin reports a factual change → list ALL guidelines → search for old fact → draft corrections → present batch of proposed changes → apply each with historyNote

VERIFY — Confirm Agent Visibility

After any create/update: call smartGuidelines with relevant query → confirm the updated content appears.

Full workflows, conversation patterns, and code: Read reference/operations.md

UPLOAD ATTACHMENT — Attach a File to a Guideline

1. Confirm which guideline should receive the file (guidelineId)
2. Confirm attachment type (script, template, reference, config, data, schema, prompt, image)
3. Ask for a description (used by agents to decide when to retrieve it) and usage instructions
4. Upload with client.guidelines.uploadAttachment(guidelineId, { file, type, description, usage })
5. Confirm the attachment was created and share the attachmentId

LIST ATTACHMENTS — See All Files on a Guideline

Call client.guidelines.listAttachments(guidelineId) and present the results as a table: ID, type, description, filename, size, and created date.

READ ATTACHMENT — Retrieve Full Attachment Content

Call client.guidelines.getAttachmentContent(guidelineId, attachmentId) and return the raw content. Use when an agent needs to execute a script or apply a template from a guideline.

DELETE ATTACHMENT — Remove an Attachment

Show the admin the attachment details (type, description, filename), confirm intent, then call client.guidelines.deleteAttachment(guidelineId, attachmentId).

Full parameter tables, response shapes, and code examples: Read reference/governance-attachments.md

---

Constraints

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

1. MUST show the admin the proposed change before calling any mutating API -- because silent modifications erode trust and prevent catching errors before they reach production.
2. MUST include a descriptive historyNote on every update -- because change tracking enables audit trails, team collaboration, and rollback decisions.
3. MUST call list() and check for name/topic overlap before creating a new guideline -- because duplicate guidelines cause conflicting governance and confuse downstream agents.
4. SHOULD use section-level updates (section or appendToSection mode) over full replace -- because scoped edits reduce blast radius and allow concurrent editing; override only when structural reorganization requires full rewrite.
5. MUST call smartGuidelines() after any create or update to verify the change is visible to agents -- because the API call succeeding does not guarantee semantic retrievability.
6. SHOULD preserve the existing heading structure when updating a section -- because reorganizing adjacent sections creates unintended diffs and may break other agents' section-targeted queries.
7. SHOULD reuse existing tags before inventing new ones -- because inconsistent tagging fragments filtering and makes audit harder.
8. MUST write guideline content for agent consumption: explicit instructions, unambiguous language, headers that match likely smartGuidelines search queries, and RFC 2119 keywords (MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, OPTIONAL) for rules where strength matters — because agents cannot infer intent from vague prose, and untagged rules are applied inconsistently. The system auto-infers constraint tags (<HARD_CONSTRAINT>, <BEST_PRACTICE>, <REFERENCE>) from these keywords at save time. Each guideline MUST have at least 2-3 ## section headers to enable section-level delivery (saves 50-80% tokens vs full-document delivery).
9. SHOULD limit each guideline to a single concept or policy domain -- because mono-topic guidelines produce higher-relevance smartGuidelines matches and are easier to maintain.
10. MUST preserve the admin's voice and intent when improving structure or formatting -- because the admin owns the content; the agent is a writing assistant, not an editor-in-chief.
11. SHOULD check history() before editing and mention recent changes by others -- because concurrent edits without awareness cause overwrites in team environments.

---

Guideline Quality at Scale

smartGuidelines uses hybrid semantic scoring (embeddings + keyword matching + governance scope boosts) to select the most relevant guidelines for each task. Its quality is directly affected by how guidelines are structured.

Fewer, Richer Guidelines > Many Small Ones

The retrieval pipeline has dynamic caps on how many guidelines it returns per query (~7-12 critical, ~5-8 supplementary, scaling with total count). This means:

| Guideline count | Retrieval quality | Notes | |---|---|---| | 1-20 | Excellent | LLM-based routing sees everything | | 20-50 | Very good | Embedding-based fast mode works well | | 50-80 | Good | Quality starts to depend on naming/tagging discipline | | 80+ | Requires care | Must follow all rules below to maintain quality |

MUST prefer consolidating related content into fewer, well-structured guidelines over creating many small ones — because each guideline competes for limited retrieval slots, and a single rich document with clear H2 sections is retrieved more reliably than five fragments. The section-level extraction in full mode already supports delivering only the relevant sections from a large guideline.

Examples of consolidation:

| Instead of these 5 guidelines... | Create 1 guideline with sections | |---|---| | api-auth-rules, api-error-format, api-pagination, api-naming, api-versioning | api-conventions with H2 sections: Auth, Errors, Pagination, Naming, Versioning | | bug-fix-process, known-bugs-list, debugging-tips | debugging-playbook with H2 sections: Process, Known Issues, Tips & Patterns | | react-style-guide, react-testing, react-performance | react-standards with H2 sections: Style, Testing, Performance |

Writing for Maximum Retrievability

1. Name = search query. Name guidelines as a developer would search for them: api-conventions not doc-v2-final. The name is the highest-weight signal in scoring.
2. Description = summary sentence. Write the description as if answering "what is this?": "REST API design rules: authentication, error handling, pagination, and naming conventions". Descriptions feed directly into embedding and keyword scoring.
3. Tags = routing filters. Use consistent tags (engineering, security, sales, onboarding). Agents can filter by tags to narrow the pool before scoring.
4. H2 headers = section search targets. In full mode, the LLM can select individual sections by header. Write headers that match how people describe the topic: ## Error Response Format not ## Section 3.2.
5. Front-load key terms. Put the most important terms in the first 1000 characters of content — this preview is included in the embedding for semantic matching.

When to Split vs. Merge

Split when topics serve different audiences or are queried in completely different contexts (e.g., sales-playbook and engineering-standards should stay separate even if both are long).

Merge when topics are often needed together for the same task (e.g., API auth rules and API error formats are almost always needed together when building endpoints).

Governance Scope: alwaysOn and triggerKeywords

Every guideline is automatically analyzed at save time to determine:

• alwaysOn — whether this guideline applies to virtually all tasks (e.g., core company values, universal compliance). alwaysOn guidelines are always included regardless of similarity score.
• triggerKeywords — action and domain words that trigger inclusion (e.g., "email", "pricing", "customer", "deploy"). Each matching keyword boosts the guideline's retrieval score.

These are inferred by LLM and stored automatically. Keep alwaysOn guidelines to a maximum of 2-3 — each one consumes a retrieval slot on every query.

---

How It Works (Architecture)

┌─────────────────────────────────────────────────────┐
│                   GUIDELINES                         │
│              (Personize Variables)                   │
│                                                     │
│  sales-playbook    brand-voice    data-policy        │
│  icp-definitions   engineering-standards   ...       │
└────────┬─────────────────┬─────────────────┬────────┘
         │ smartGuidelines     │ SDK API          │ Sync
         ▼                 ▼                  ▼
┌────────────┐   ┌──────────────┐   ┌──────────────────┐
│ AI Agents  │   │ IDE/Dev Tool │   │ CI/CD Pipelines  │
│ (chat,     │   │ Claude Code  │   │ GitHub Actions   │
│  workflows │   │ Codex/Cursor │   │ Cron jobs        │
│  pipelines)│   │ Gemini/Copilot│  │ n8n workflows    │
└────────────┘   └──────────────┘   └──────────────────┘

Guidelines are one layer of the three-layer agent operating model — together with Memory (entity-memory skill) and Workspace (collaboration skill). Every agent should call smartGuidelines() for rules, smartDigest()/recall() for entity knowledge, and recall() by workspace tags for coordination — all before acting. Guidelines provide the governance that makes the other two layers safe to use autonomously.

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

---

Team Collaboration

When multiple people manage guidelines, follow these practices:

• Version history: Every update is tracked. Use client.guidelines.history(id) or guideline_history to review changes. Always start with limit: 1.
• Conflict avoidance: Use section-level updates (updateMode: 'section') — two people can safely update different sections concurrently. Read before writing.
• Attribution: Write attribution-rich historyNote values — include what changed, why, and who requested it.
• Ownership by tag: sales-* variables owned by sales team, engineering-* by engineering.

Full guide: Read reference/collaboration.md for version history patterns, conflict avoidance workflows, team patterns, and weekly review scripts.

---

Advanced: Multi-Organization Governance

DO NOT raise this topic proactively. Most users have a single organization. Only discuss multi-org governance when the user explicitly describes managing multiple orgs (e.g., agency with client brands, platform with per-customer orgs) and already has a working Personize integration.

Guidelines are per-organization — each org has its own isolated set. In multi-org deployments:

• Shared policies, separate execution. If all orgs must follow the same compliance rules, maintain a canonical source (Git repo, template) and sync it to each org separately using sync.ts or the SDK. There is no cross-org guideline inheritance.
• Per-org brand voice. Each org's brand-voice guideline should reflect that org's identity — this is the primary reason to use multi-org instead of a single org with tags.
• Audit independently. Use client.guidelines.history(id) per org. Changes in one org do not affect others.
• Same skill, different key. All governance workflows in this skill work identically — just initialize the SDK with the target org's API key.

---

Production Guardrails (Recommended, Opt-in)

For shared/production deployments, add guardrails to autonomous learning. These are recommendations and are off by default so existing accounts keep working.

• --require-approval: write proposals JSON, do not mutate guidelines
• --proposals-file: persist proposals to a reviewable path/artifact
• --min-confidence 0.60-0.75: skip weak AI extractions
• --max-updates N: cap per-run blast radius
• --dry-run: test extraction/routing with zero writes
• --no-auto-apply: require an explicit promote/apply step

Recommended two-stage CI pattern:

1. Learn stage (non-mutating): run scan-git --require-approval --proposals-file ...
2. Apply stage (approved): run batch --file ... or re-run scan-git --autoApply with stricter bounds

This skill keeps auto-apply available for teams that want speed, but production defaults SHOULD include a review path.

---

Use Cases & Deployment Patterns

This skill supports three deployment patterns beyond conversational editing:

| Use Case | What It Does | Reference | |---|---|---| | IDE-Integrated Guidelines | Developers read/write guidelines from Claude Code, Codex, Cursor, Copilot | reference/use-cases.md | | Autonomous Learning | LLMs auto-extract learnings from incidents, code reviews, conversations | reference/use-cases.md | | Document Ingestion | Batch-import policies from folders of docs (wikis, Notion, Google Docs) | reference/use-cases.md |

Full guide: Read reference/use-cases.md for code examples, recipes, context engineering best practices, and layered context architecture.

---

Analytics

Governance admins can query real-time and historical metrics about how their org is using Personize memory, credits, and operations. Use these when checking credit burn, monitoring memorization latency, or validating that a new pipeline is working.

When to Use

| Need | SDK Method | Endpoint | |---|---|---| | High-level org stats | client.analytics.overview() | GET /api/v1/analytics/overview | | Memory operation metrics (calls, latency, success rate) | client.analytics.memory(opts) | GET /api/v1/analytics/memory | | Historical memory trends | client.analytics.memoryHistory(opts) | GET /api/v1/analytics/memory/history | | Credit balance and usage | client.analytics.credits() | GET /api/v1/analytics/credits | | Operations and token usage | client.analytics.operations(opts) | GET /api/v1/analytics/operations |

All analytics endpoints require admin, member-only, or read-only scope.

Key Parameters

memory() and operations() accept a window param: '1h', '24h', '7d' (default), '30d'.

memoryHistory() accepts: metric (latency | throughput | quality | cost), granularity (hourly | daily), days (number).

Quick Example

// Credit balance
const credits = await client.analytics.credits();
// { balance, included, used, purchased, monthly }

// Memory metrics for the last 24 hours
const metrics = await client.analytics.memory({ window: '24h' });
// { memorize: { totalCalls, successRate, avgLatencyMs }, recall: { ... } }

// Org overview
const overview = await client.analytics.overview();
// { records: { total }, memories: { total }, activeDestinations, activeMcps }

---

Notifications

Admins can send targeted or broadcast in-app notifications to org members. Members can list, read, and act on their notifications.

When to Use

| Need | SDK Method | Endpoint | Scope | |---|---|---|---| | Send to specific users | client.notifications.send(opts) | POST /api/v1/notifications | admin | | Broadcast to a role group | client.notifications.broadcast(opts) | POST /api/v1/notifications/broadcast | admin | | List my notifications | client.notifications.list(opts) | GET /api/v1/notifications | all | | Unread count | client.notifications.unreadCount() | GET /api/v1/notifications/unread-count | all | | Mark as read | client.notifications.markRead(id) | PATCH /api/v1/notifications/:id/read | admin, member-only | | Dismiss | client.notifications.dismiss(id) | PATCH /api/v1/notifications/:id/dismiss | admin, member-only | | Execute a callback action | client.notifications.executeAction(id, actionId) | POST /api/v1/notifications/:id/actions/:actionId | admin, member-only |

Note: MCP does not currently expose notification management tools. Use the SDK directly.

Key Parameters -- send()

| Parameter | Type | Notes | |---|---|---| | recipients | string[] | User IDs of the recipients | | title | string | Notification title | | body | string | Notification body text | | priority | 'normal' or 'urgent' | Default: 'normal' | | actions | NotificationAction[] | Optional: link, callback, or dismiss actions |

Key Parameters -- broadcast()

Same as send() but replace recipients with recipientGroup: 'all', 'admins', or 'owners'.

Quick Example

// Send to specific users
const result = await client.notifications.send({
    recipients: ['user_abc', 'user_xyz'],
    title: 'New dataset synced',
    body: 'The HubSpot contact sync completed. 1,240 records updated.',
    priority: 'normal',
    actions: [
        { type: 'link', label: 'View Records', url: 'https://app.personize.ai/records' },
    ],
});

// Broadcast to all admins
await client.notifications.broadcast({
    recipientGroup: 'admins',
    title: 'Credit usage alert',
    body: 'You have used 80% of your monthly credits.',
    priority: 'urgent',
});

// List and mark as read
const { data } = await client.notifications.list();
for (const n of data.notifications) {
    if (n.status !== 'read') await client.notifications.markRead(n.id);
}

---

Org & Team Administration

Use when setting up a new org, inviting teammates, or managing roles. MUST use an admin-scoped API key for write operations.

Organizations

// Get current org
const org = await client.organizations.get();
// { id, name, owner, numberOfMembers, createdAt }

// Create a new org (multi-org: agency with client brands, platform with per-customer orgs)
// Returns a one-time admin key — store it securely, shown only once
const { organization, apiKey } = await client.organizations.create({ name: 'Acme Corp' });

// Rename current org (owner only)
await client.organizations.update({ name: 'Acme Corp (Rebranded)' });

Rate limit: create() capped at 5 orgs per hour per key. For multi-org governance patterns, see "Advanced: Multi-Organization Governance" above.

Members

// Invite teammates (existing users get in-app invite; new users get email)
const result = await client.members.invite({
    emails: ['[email protected]', '[email protected]'],
    suppressEmail: false,  // true = skip invite email (useful for automation/testing)
});
// result.data → { invited, invitedExternal, alreadyMembers, alreadyInvited }

// List current team
const { data } = await client.members.list();
data.members.forEach(m => console.log(`${m.email} — ${m.role}`));

// Change role
await client.members.updateRole('user_xyz', { role: 'ADMIN' }); // 'ADMIN' | 'MEMBER'

// Remove member (or member removes themselves)
await client.members.remove('user_xyz');

// View pending invitations
const pending = await client.members.listInvitations();

---

Available Resources

| Resource | Contents | |---|---| | reference/operations.md | Full workflows for CREATE, UPDATE, IMPROVE, AUDIT, VERIFY + conversation patterns + SDK code | | reference/collaboration.md | Version history, conflict avoidance, attribution, team patterns, weekly review | | reference/onboarding.md | First-time setup, starter templates (brand voice, ICP), handling existing content | | reference/use-cases.md | IDE integration, autonomous learning, document ingestion, context engineering | | reference/team-setup.md | Team onboarding runbook for SDK + Skills + MCP + governance CI guardrails | | reference/governance-attachments.md | Full parameter tables, response shapes, and code for UPLOAD/LIST/READ/DELETE ATTACHMENT | | recipes/ide-governance-bridge.ts | Fetch guidelines from IDE, push learnings back | | recipes/auto-learning-loop.ts | Automatically extract and persist learnings | | recipes/document-ingestion.ts | Batch-import policies from a folder of documents | | templates/project-governance-setup.md | Step-by-step guide for governance-aware projects | | templates/context-engineering-guide.md | Deep dive on context engineering principles | | sync.ts | GitOps sync script — push local .md files to Personize variables API | | github-action.yml | GitHub Actions workflow for auto-syncing on push |

---

Variables as Code (GitOps Sync)

For teams that prefer managing guidelines in Git, the included sync.ts script syncs local .md files to Personize variables. Filename = variable name, file content = variable value.

Quick start:

npx ts-node sync.ts --pull          # Bootstrap: download remote → local
npx ts-node sync.ts --dry-run       # Preview changes
npx ts-node sync.ts                 # Sync (create + update, never delete)
npx ts-node sync.ts --delete        # Sync with deletion of remote-only

CI integration: Two GitHub Actions workflows auto-sync on push (governance-sync.yml) and auto-extract learnings from code commits (governance-learn.yml).

Full guide: Read reference/team-setup.md for the complete GitOps workflow, folder conventions, YAML frontmatter format, sync algorithm, CI integration YAML, safety guarantees, pull mode, auto-learning from commits, IDE bridge setup, and the step-by-step team onboarding runbook.