DOCSEARCHbyAlgolia
Submit Docs

Character Card V2 Specification

repository·main·Indexed 41 days ago

https://github.com/malfoyslastname/character-card-spec-v2

A standardized format for character cards used in AI roleplay ecosystems. V2 introduces enhanced control via system_prompt and post_history_instructions, integrated lore through the character_book field, and a nested data structure to maintain backward compatibility with V1. It defines mandatory fields such as spec, spec_version, and extensions for custom data, and provides guidelines for implementing alternate greetings and creator notes.

Tokens
4.8K
Snippets
8
Records
23
Agent score
52%

What's inside Character Card Spec V2

  1. Overview of Character Card V2 Specification

    main

    The Character Card V2 Specification is a proposed format for character cards designed to provide botmakers with more control over the user experience and to consolidate character and lore data. It aims for compatibility with the existing 'V1' ecosystem (including repositories like Pygmalion booru and characterhub.org, and frontends like SillyTavern, RisuAI, and agnai).

    Key improvements in V2 include:

    • Enhanced Control: Using system_prompt and post_history_instructions to allow botmakers to define the interaction experience, reducing the need for users to manually adjust sensitive settings.
    • Integrated Lore: The character_book field allows attaching a lorebook directly to the character card, distinguishing between 'World books' and 'Character books'.
    • Communication: The creator_notes field enables botmakers to provide important information to users.
    • Feature Expansion: The alternate_greetings field allows for multiple greeting options.

  2. Handle extensions and data preservation

    main

    The extensions field is a mandatory Record<string, any> that MUST default to {}. It is used for arbitrary JSON key-value pairs.

    Critical Rules for Developers:

    • Editors: Character editors MUST NOT destroy unknown key-value pairs when importing or exporting cards. They MUST preserve all data in extensions.
    • Applications: Applications MAY store unspecified data here. It is highly recommended to namespace keys to prevent conflicts (e.g., "agnai/voice": ... or "my_app": { "key": "value" }).
    • Scope: extensions exists at the top level of the card, within the character_book, and within each individual character_book entry.

  3. Use the `extensions` field for custom data

    main

    The extensions field is a mandatory object (defaulting to {}) used to store arbitrary key-value pairs. This allows for future-proofing and compatibility with various frontends.

    Implementation Guidelines:

    • Namespacing: It is highly encouraged to namespace your keys within extensions to prevent conflicts with other tools.
    • Data Integrity: Frontends and editors must never destroy unknown key-value pairs within the extensions object. They should be preserved even if the specific tool does not recognize them.
    • Scope: extensions exists at the top level of data and also within each entry of a character_book.

  4. Compare Character Card V1 and V2 Specifications

    main

    The Character Card specification has evolved from V1 to V2. The primary difference is that V2 introduces a spec identifier and nests all character data within a data object. This nesting prevents older V1-only editors from accidentally destroying V2-specific fields when saving a card.

    V1 Specification

    In V1, fields are top-level. A card is identified as V1 if the spec field is undefined.

    V2 Specification

    A card is identified as V2 if spec === 'chara_card_v2'. All character attributes are contained within data.

    Mandatory V2 Fields:

    • spec: Must be 'chara_card_v2'
    • spec_version: e.g., '2.0'
    • data.name
    • data.description
    • data.personality
    • data.scenario
    • data.first_mes
    • data.mes_example
    • data.extensions: A mandatory object (defaults to {}).

    New V2 Fields:

    • data.creator_notes
    • data.system_prompt
    • data.post_history_instructions
    • data.alternate_greetings (Array of strings)
    • data.tags (Array of strings)
    • data.creator
    • data.character_version
    • data.character_book (Optional)
    type TavernCardV1 = {
  name: string
  description: string
  personality: string
  scenario: string
  first_mes: string
  mes_example: string
}

type TavernCardV2 = {
  spec: 'chara_card_v2'
  spec_version: '2.0'
  data: {
    name: string
    description: string
    personality: string
    scenario: string
    first_mes: string
    mes_example: string
    creator_notes: string
    system_prompt: string
    post_history_instructions: string
    alternate_greetings: Array<string>
    character_book?: CharacterBook
    tags: Array<string>
    creator: string
    character_version: string
    extensions: Record<string, any>
  }
}

type TavernCard = TavernCardV1 | TavernCardV2

  5. Use the character_book (Lorebook) feature

    main

    The character_book is a character-specific lorebook.

    • Frontend Behavior: Frontends MUST use the character lorebook by default. It SHOULD take full precedence over user "world books" or "memory books".
    • Editor Behavior: Character editors MUST save lorebooks in the specified CharacterBook format.

    CharacterBook Schema

    type CharacterBook = {
  name?: string
  description?: string
  scan_depth?: number // Memory: Chat History Depth
  token_budget?: number // Memory: Context Limit
  recursive_scanning?: boolean // Whether entry content can trigger other entries
  extensions: Record<string, any>
  entries: Array<CharacterBookEntry>
}

  6. Embedding methods for Character Card V1

    main

    Character Card V1 data can be embedded using the following methods:

    • .json file: A standalone JSON file with no image. This is discouraged due to poor user-friendliness.
    • PNG/APNG: The JSON string is encoded in base64 and stored inside the Chara EXIF metadata field.
    • WEBP: Not supported by the specification due to technical ambiguities.

  7. Format example conversations in `mes_example`

    main

    Example conversations in the mes_example field MUST use the <START> delimiter to mark the beginning of a new conversation block.

    Implementers MAY transform <START> (e.g., into an OpenAI System message).

    Example conversations SHOULD be included in the prompt by default until the conversation history fills the context window, at which point they SHOULD be pruned to make room for actual history. This pruning behavior MAY be user-configurable.

    <START>
{{user}}: hi
{{char}}: hello
<START>
{{user}}: hi
Haruhi: hello

  8. Implement `system_prompt` and `post_history_instructions` logic

    main

    V2 introduces two fields designed to give botmakers control over model behavior. Frontends should implement them with the following priority logic:

    system_prompt

    Used to define the core instructions for the AI.

    • Default Behavior: If data.system_prompt is a non-empty string, it should completely replace the user's global system prompt.
    • Fallback: If data.system_prompt is an empty string, the frontend should fall back to the user's global system prompt or an internal default.

    post_history_instructions

    Instructions placed after the conversation history, which carry stronger weight in modern LLMs (often referred to as 'Jailbreak' or 'UJB' in other tools).

    • Default Behavior: If data.post_history_instructions is a non-empty string, it should override the user's global post-history instructions (UJB/Jailbreak).
    • Fallback: If data.post_history_instructions is an empty string, the frontend should fall back to the user's global settings or an internal default.

  9. Handle magic string replacements in V1 prompts

    main

    When constructing prompts for an AI, implementers MUST perform a case-insensitive replacement of the following magic strings using the values from the card fields:

    • {{char}} or <BOT> $\rightarrow$ the value of the card's name field.
    • {{user}} or <USER> $\rightarrow$ the application's set display name (a default value for the user's name MUST exist).

    Note: Whether {{user}} and <USER> should be replaced inside the name field is currently an unspecified edge case.

  11. Use `spec_version` for specification versioning

    main
    The spec_version field must be set to "2.0". This field tracks minor versions or extensions to the specification. To ensure backward compatibility, future minor versions of the spec MUST be non-breaking, meaning they can add new fields but cannot remove existing fields or change the types of existing fields.

  12. Store custom data in the `extensions` object

    main

    The extensions field is an object used to store application-specific data that is not part of the core Character Card V2 specification.

    Implementation Details:

    • Default Value: {}
    • Structure: An object where property names are strings and values can be any valid JSON value.
    • Critical Requirement: Applications importing V2 character cards MUST NOT destroy or strip unknown fields inside the extensions object to ensure data persistence for other applications.
    {
  "data": {
    "extensions": {
      "text_color": "#ff3333",
      "agnai/voice": { "service": "elevenlabs", "id": "Bella" },
      "risu": {
        "expressions": {
          "happy": "https://cdn.risu.com/mary_happy.png",
          "sad": "https://cdn.risu.com/mary_sad.png"
        }
      }
    }
  }
}