Character specification

The file

The file holds one JSON object in UTF-8. Every key below is required except backgroundImage. A text field can be an empty string, and lorebook can be an empty array. Cue ignores keys it does not know.

To add a character from a file, open Cue → Settings → Characters and choose Import Downloaded JSON…. To save one as a file, choose Export JSON… on that character.

Example

{
  "id": "night-ferry",
  "name": "Ines",
  "tagline": "Pilot of the last ferry of the night",
  "appearance": "Gray braid, oilskin jacket.",
  "background": "Has run the night ferry for 20 years.",
  "personality": "Dry, patient and observant.",
  "scenario": "You are her only passenger tonight.",
  "greeting": "*Ines checks your ticket.* Sit anywhere.",
  "exampleDialogue": "User: Quiet tonight?\nInes: Always.",
  "instructions": "Keep replies short.",
  "lorebook": [
    {
      "id": "ines-lighthouse",
      "keywords": ["lighthouse", "the light"],
      "content": "Ines knew the lighthouse's last keeper.",
      "enabled": true
    }
  ]
}

Fields

Cue builds the character's system prompt from its text fields. Each non-empty field becomes a section under the heading in the last column, in this order. Empty fields are left out.

Key	Type	What Cue does with it
`id`	string	Any string. Import gives the character a new ID, so a file never replaces a character you already have.
`name`	string	The character's name in Cue and in the prompt (“You are …”). It must contain more than spaces.
`tagline`	string	A one-line summary shown in Cue. Prompt section: Tagline.
`appearance`	string	Prompt section: Appearance.
`background`	string	History, work and relationships. Prompt section: Background.
`personality`	string	How the character thinks and behaves. Prompt section: Personality.
`scenario`	string	Where the story begins. Prompt section: Opening scenario. Cue tells the model to continue from the conversation, not to return to this moment.
`greeting`	string	The first message of every new chat with the character, shown before you type.
`exampleDialogue`	string	Sample exchanges that show the character's voice. Prompt section: Voice examples. Cue tells the model these show style and did not happen.
`instructions`	string	Any other rules for the model. Prompt section: Additional instructions.
`lorebook`	array	Facts added only when they are relevant. See Lorebook entries.
`backgroundImage`	string or null, optional	Chat background art from Cue's catalog. See Images. It never goes into the prompt.

Text fields can hold several paragraphs; write line breaks as \n. Asterisks around actions, as in the greeting above, are plain text to Cue.

A conversation keeps a copy of the character as it was when the conversation started. Editing the character later changes new chats, not that one.

Lorebook entries

A lorebook entry is a fact the model sees only when it is relevant, so a long backstory does not fill every request. Each entry is an object with four required keys:

Key	Type	Meaning
`id`	string	Any string. Import replaces it with a new ID.
`keywords`	array of strings	Words or phrases that bring the entry into the conversation. An empty array means the entry is always included.
`content`	string	The fact itself. An entry with empty content is skipped.
`enabled`	boolean	`false` keeps the entry in the file but never uses it.

Before each reply, Cue looks for the keywords in your new message and the last four messages of the chat. A keyword matches as a whole word or phrase, ignoring case and accents: “light” matches “the light” but not “lighthouse”. Matching entries go beside your message under the heading “Relevant character lore”, not into the system prompt.

Images

backgroundImage accepts only a path to a PNG in Cue's catalog, such as /characters/images/maya-portrait.png. Cue downloads that image from the catalog and keeps a copy for the chat background. A file path, any other website, or a different image type is ignored, and the chat uses your usual background.

The character creator keeps your own uploaded images in its editable creator file. That file is a different format, which only the creator can open. The file it downloads for Cue includes backgroundImage only when the main image came from the catalog.

Catalog cards

Each character in the catalog is a file in this format at /characters/cards/<slug>.json. Install in Cue opens cue://characters/install/<slug>, and Cue downloads that card from the catalog. A card installs only when its id is catalog-<slug>, its name is not empty, and the file is at most 128 KB.