What is person.run?
person.run is an API platform for creating, deploying, and managing persistent AI personas. Unlike generic chatbots, personas carry a stable identity — a name, background, occupation, emotional memory, and evolving timeline of experiences. Every conversation a persona has shapes how it responds next.
You define a persona with a simple seed — name, age, location, and occupation — and person.run generates the rest: personality traits, communication style, domain knowledge, and an initial memory. From there, each interaction deepens the persona through its timeline.
Core concepts
person.run is built around a few key ideas. Understanding these will help you get the most out of the platform.
Persona
A durable synthetic individual
A persona is the identity anchor for all research interactions: stable profile, evolving memory, and consistent voice.
Read full concept docs ->
Skill
A reusable research task
A skill defines what you ask and how you evaluate it, so prompt execution can be repeated across personas and studies.
Read full concept docs ->
Cohort
A targeted segment within your audience
A cohort groups personas with shared attributes so you can reason about segment-specific behavior before scaling to full populations.
Read full concept docs ->
Population
A complete synthetic panel
A population combines cohorts into a balanced audience model you can run repeatable studies against at scale.
Read full concept docs ->
Study
A controlled run across a population
A study binds a skill to a target population, runs at scale, and returns structured evidence for product decisions.
Read full concept docs ->
In addition to those workflow concepts, the platform relies on memory, prompting, and consistency mechanics described below.
Personas
A persona is a persistent AI identity. It has a name, age, location, occupation, and a generated summary that captures its personality. Personas are scoped to a tenant (your organization) and identified by a UUID. Once created, a persona retains its identity across every conversation.
Timeline & Memory
Every persona maintains a timeline — an ordered sequence of memories. Each memory records facts, feelings, emotion tags, and an interpretation. Memories have a type (normal, pride, shame, repressed, revised, or exaggerated) and a strength score from 0–100 that influences how vividly the persona recalls them. Vivid memories (75+) surface readily; faded memories (<40) are hazy or fragmented.
Prompting
When you send a prompt, person.run retrieves relevant memories using vector similarity search (RAG), structures them by strength and type, and generates a response that stays in character. The persona's communication style, emotional state, and domain knowledge all shape the output. Responses can be synchronous, asynchronous (job-based), or streamed token-by-token.
Consistency
person.run can run consistency checks across a persona's timeline to detect contradictions, sequence gaps, and non-monotonic event times. This helps maintain believable, coherent identities even as personas accumulate hundreds of memories.
Memory types
Each memory in a persona's timeline carries a type that shapes how the persona relates to it. This creates nuanced, psychologically realistic recall behavior.
| Type | Behavior |
|---|---|
normal | Standard recall — the persona remembers and discusses it naturally |
pride | The persona recalls this enthusiastically, may bring it up unprompted |
shame | The persona is reluctant to discuss this, may deflect or minimize |
repressed | The persona resists recalling this; it may surface only under pressure |
revised | A corrected version of an earlier memory; replaces the original in recall |
exaggerated | The persona embellishes or dramatizes this memory |
Architecture overview
The platform is organized around a clear request flow:
- You authenticate with an API key scoped to your tenant.
- Your request hits the REST API, which validates input against typed contracts.
- Rate limits and usage quotas are enforced before any work begins.
- For prompts, the persona package orchestrates memory retrieval, prompt construction, and AI generation.
- Responses are persisted as model responses with embeddings for future RAG retrieval.
- Timeline entries and consistency checks keep the persona coherent over time.
Authentication
Every API request requires an x-api-key header. API keys are created from the dashboard and scoped to a single tenant. Each key carries rate limits and usage quotas that you can monitor from the dashboard.