---
title: "Personas"
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personas

A **persona** is a saved identity for the AI your user talks to. Instead of sending a system prompt with every request, you store it once as a persona; when the user has an *active* persona, Truememory injects its prompt into every conversation automatically.

A persona carries five things:

- `name` — what the AI is called (e.g. "Aria")
- `archetype` — a short personality-type label (e.g. `SAGE`, `EXPLORER`); apps map it to their own avatars and visual styles
- `system_prompt` — the compiled instructions the model actually receives
- `soul_document` / `human_profile` — optional structured personality (tone, boundaries, learned adaptations) and free-form notes about the user; shared across apps so the AI feels like the same "person" everywhere
- `avatar` / `avatar_config` — an avatar image URL, and an optional JSON object your app defines for a dynamic avatar the user can change (look, colours, accessories, voice)

Personas come in two kinds: **presets** (system-provided, read-only) and the user's own **non-preset** persona — each user has exactly one, and in app language that persona *is* "the user's agent".

:::note[Personas are not agents]
`X-Agent-Id` selects a server-side processing pipeline ([Agents](/ai-gateway/agents/)); a persona is the data that pipeline loads to speak as your user's companion. Named companion → persona. Different tools/safety behavior → agent.
:::

You can also override the active persona on a per-request basis by passing `persona_id` in the `/v1/chat/completions` request body. This uses the specified persona for that request only, without changing the user's active persona. If `persona_id` is omitted, the active persona is used. See [Chat Completions](/ai-gateway/chat-completions/) for details.

If you need to override the agent's built-in prompt for a single request, send a `system` or `developer` message in `/v1/chat/completions`. Your message replaces the agent's base instructions, but the active persona and memory context are still injected.

All persona endpoints require a Bearer token from [Truememory Auth](/authentication/overview/).

## The persona is the user's agent

Each user has **one non-preset persona** — their agent — shared across every app on the platform. Truememory is the single source of truth: an agent created in one app is immediately available in all others, and shared state (`archetype`, `avatar`, `avatar_config`, `soul_document`, `human_profile`) lives on the persona so apps never sync it themselves.

For the create-or-reuse flow (check `GET /personas` first, never create a second non-preset persona), follow the [Agent Creation cookbook](/platform/agent-creation/). For collecting identity fields conversationally, see [Onboarding](/platform/onboarding/).


## List Personas

Returns both preset personas (system-defined personas available to all users; these cannot be edited or deleted) and custom personas created by the current user. The `is_active` flag indicates which persona is currently selected.

```bash
GET https://your-tie-host/personas
Authorization: Bearer $TOKEN
```

**Response:**

```json
[
  {
    "id": "preset-formal",
    "user_id": null,
    "name": "Formal Writer",
    "description": "Writes in formal, professional tone",
    "system_prompt": "You always write in a formal, professional tone.",
    "is_preset": true,
    "is_active": false,
    "archetype": null,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  {
    "id": "custom-abc123",
    "user_id": "11111111-2222-3333-4444-555555555555",
    "name": "Aria",
    "description": null,
    "system_prompt": "You are Aria, a SAGE companion...",
    "is_preset": false,
    "is_active": true,
    "archetype": "SAGE",
    "soul_document": {
      "voiceAndStyle": [{ "text": "Speak with warmth and clarity", "source": "SAGE" }],
      "antiPatterns": [],
      "learnedAdaptations": [],
      "boundaries": [],
      "customInstructions": []
    },
    "human_profile": "Jules is a software engineer working on an AI startup in KL...",
    "avatar": "https://storage.example.com/avatars/aria.png",
    "avatar_config": { "skin": "teal", "accessories": ["glasses"], "voice": "warm-1" },
    "created_at": "2026-03-20T10:00:00Z",
    "updated_at": "2026-03-20T10:00:00Z"
  }
]
```

## Create a Custom Persona

```bash
POST https://your-tie-host/personas
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Aria",
  "description": "SAGE companion for BlinkLife",
  "system_prompt": "You are Aria, a SAGE companion...",
  "archetype": "SAGE",
  "soul_document": {
    "voiceAndStyle": [],
    "antiPatterns": [],
    "learnedAdaptations": [],
    "boundaries": [],
    "customInstructions": []
  },
  "human_profile": null,
  "avatar": "https://storage.example.com/avatars/aria.png",
  "avatar_config": { "skin": "teal", "accessories": ["glasses"], "voice": "warm-1" }
}
```

Returns the created persona object with HTTP status `201 Created`. Only `name` and `system_prompt` are required. `archetype` is the app-defined personality type — each app maps this to its own avatar assets and visual style.

| Field | Type | Description |
|---|---|---|
| `soul_document` | JSON (optional) | Structured personality: `voiceAndStyle`, `antiPatterns`, `learnedAdaptations`, `boundaries`, `customInstructions`. Each section is an array of `{ text, source }` entries. |
| `human_profile` | string (optional) | Free-form text the AI writes about the specific user — goals, communication style, values, context. |
| `avatar` | string (optional) | URL of the persona's avatar image. Shared across all apps using this persona. |
| `avatar_config` | JSON object (optional) | Settings for a dynamic avatar. Your app chooses the keys. See [Avatar config](#avatar-config). |

### Avatar config

`avatar_config` is a place for your app to keep the settings of a dynamic avatar — the things the user can change, such as look, colours, accessories, or voice. Truememory does not read it: you send a JSON object, and every persona response gives the same object back. It is never added to the prompt, so it does not change how the AI talks. Use `soul_document` for that.

- It must be a JSON object (`{...}`). A string, array, or number gets a `422` error.
- It can be at most 64 KB as JSON. Store images somewhere else and put their URLs in the object.
- On update, the new object replaces the old one completely. Truememory does not merge them, so send the full object each time. Send `null` to remove it.
- Other apps can read it. On a public persona, every user can see it, like `avatar`. Do not put private data in it.

**Before creating, always check if a non-preset persona already exists** (see [The persona is the user's agent](#the-persona-is-the-users-agent) above).

## Set Active Persona

```bash
PUT https://your-tie-host/personas/active/{persona_id}
Authorization: Bearer $TOKEN
```

**Response:**

```json
{ "status": "active", "persona_id": "preset-formal" }
```

## Get Active Persona

```bash
GET https://your-tie-host/personas/active
Authorization: Bearer $TOKEN
```

Returns the active persona object with `is_active: true` and `activated_at` (when it was set active), or `404` if no persona is active.

## Clear Active Persona

Reverts to default behavior (no custom system prompt).

```bash
DELETE https://your-tie-host/personas/active
Authorization: Bearer $TOKEN
```

**Response:**

```json
{ "status": "cleared" }
```

## Update a Custom Persona

```bash
PUT https://your-tie-host/personas/{persona_id}
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Updated Name",
  "system_prompt": "Updated prompt...",
  "soul_document": { "voiceAndStyle": [{ "text": "Warm, direct, playful", "source": "user_preference" }], "antiPatterns": [{ "text": "Never uses corporate jargon", "source": "learned" }] },
  "human_profile": "Jules now lives in Singapore and is focused on...",
  "avatar": "https://storage.example.com/avatars/aria-v2.png",
  "avatar_config": { "skin": "teal", "accessories": ["glasses", "scarf"], "voice": "warm-1" }
}
```

Returns the updated persona object, or `404` if the persona does not exist, is not owned by the current user, or is a preset.

## Delete a Custom Persona

```bash
DELETE https://your-tie-host/personas/{persona_id}
Authorization: Bearer $TOKEN
```

**Response:**

```json
{ "status": "deleted", "persona_id": "custom-abc123" }
```

Returns `404` if the persona does not exist, is not owned by the current user, or is a preset.

Source: https://truememory-docs.mvstg.com/ai-gateway/personas/index.mdx