Skip to content

Adding a Persona Preset

How to add an official persona preset to the seed catalog. Locale variants of an existing preset are covered in Adding a Locale.

  1. Create src/db/seed/catalog/personas/<name>/ with one file per language (en-US.ts, ja.ts), each exporting persona: PersonaInput, and register each in personas/index.ts. There is no directory scan. Required fields:

    • preset_lineage_id: identical in every language variant. It makes the variants one character and becomes the persona’s persona_lineage_id, which scopes its memories. A locale without a variant lists the base-language or en-US variant instead.
    • name, desc, attributes, paired sampleDialoguesIn / sampleDialoguesOut, language, avatarPath, triggerWords.
    • Do not author preset_attribute_public_flags. personaSeed.ts derives it: the first attribute is public and the rest are private.
    • Add the lineage to OFFICIAL_LINEAGE_IDS in personaSeed.ts and to the naming snapshot in tests/unit/db/personaNamingCatalog.test.ts.
    • Optional isNsfw: true hides the preset from /persona default and /setup; the age-restricted /nsfw persona default lists only NSFW presets. Personas created from it copy the flag, and only /nsfw persona import accepts a file that carries it.
  2. Put the avatar image in the folder and set avatarPath to the folder; the first image alphabetically is used.

  3. Optionally add sprites under sprites/ and list them per locale file:

    sprites: [
    { name: "mad", file: "sprites/mad.png", usageInstructions: "Use when angry or annoyed." },
    { name: "shy", file: "sprites/shy.png", isIdentity: false },
    ],

    name becomes the sprite_key, file is relative to avatarPath, usageInstructions is prompt guidance, and isIdentity renders the name as sprite (Persona). Optionally add a full-body character reference for reference-based image generation, in every locale file: characterReference: "character-reference/front.png". Keep it in a subfolder, because an image directly in the folder could become the avatar; bun run check-seed-catalogs enforces this.

  4. Add the lineage’s Natural Nudges defaults to PRESET_NATURAL_NUDGE_DEFAULTS in src/db/seed/catalog/personas/naturalNudges.ts, keyed by preset_lineage_id. Every language variant shares one entry, and the seeder fails without it. idleNudges takes one to a few PersonaAuthoredIdleNudge definitions (at most 20), each with:

    • id: a stable slug of up to 24 letters, digits, _, or -, unique within the list. Never rename it once shipped, because the runtime key and a persona’s local on/off choice use it.
    • category: ping_user, revive_topic, start_topic, or play_scene. Skip the prerequisite the category already implies (CATEGORY_IMPLIED_PREREQUISITES), and keep recommended_tools free of a tool a tool:<name> prerequisite already requires. The /config editor saves them that way.
    • title, brief, agenda_hint: English text shared by every language variant, with {persona}, {target}, and {partner} placeholders. Write from the character’s attributes and interests, and require a tool:<name> prerequisite for any brief that needs a tool, such as tool:image for a picture or tool:web_search for current facts.
    • Avoid a Ping User or Play Scene entry unless the brief needs a target or a partner. Entries add to the built-in and server nudges and share their frequency and daily limit. Interests drive Active Nudges, so idle nudges do not repeat them.
  5. Add or edit shared system prompt presets in src/db/seed/catalog/systemPrompts.ts if needed.

  6. Keep each image under 1 MiB; bun run compress-media shrinks oversized art.

Applying a preset through /setup or /persona default creates a copy-on-write pointer: personas.is_pointer = true with preset_lineage_id and preset_language. Reads resolve text and config from the live persona_presets row, so seed edits reach every pointer persona after the next boot.

  • Sprites upload once to the immutable presets/ storage prefix into preset_sprites, and every pointer persona resolves them live. Removing a sprite from the array removes it everywhere.
  • Avatars upload once to presets/, recording preset_avatar_shared_url and preset_avatar_hash. Pointer alters resolve that URL live. A pointer main persona uses the bot’s guild avatar, which reconcilePresetMainAvatars re-uploads per guild when applied_avatar_hash != preset_avatar_hash.
  • Character references upload once to presets/, recording preset_char_ref_shared_url. Pointer personas resolve it live; a fork keeps it, and changing the avatar removes it.
  • The first local content edit, including changing the main avatar in /config, turns the pointer into an independent copy that keeps persona_id and persona_lineage_id. Memory writes do not. /persona default restores the pointer and discards local changes.
  • /persona export writes a self-contained copy stamped with preset_lineage_id. Import re-links to the official pointer only when the content exactly matches the seeded preset of that lineage.
Terminal window
bun run check-seed-catalogs # names, paired dialogues, attributes, sprite files, prompts, nudge defaults
bun run check-media-size
bun run check
bun run lint
bun run test tests/unit/naturalNudges/idleNudges.test.ts

Then seed a dev database and check /setup, /persona default, /persona export, and /persona import. A pointer persona should show the seeded values, pick up a seed edit after cache invalidation, and become a copy on its first local edit. Open /config > Persona > Nudges to see the seeded idle nudges. See Persona Presets for the pointer model.