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”.

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 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.

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. For collecting identity fields conversationally, see 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.

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

Response:

[
  {
    "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

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.

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 above).

Set Active Persona

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

Response:

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

Get Active Persona

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).

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

Response:

{ "status": "cleared" }

Update a Custom Persona

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

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

Response:

{ "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.