TavernAI to KoboldAI Character Conversion

The migration from **TavernAI** to **KoboldAI** represents a move from single-user focused cards to a platform built for expansive, often collaborative, roleplay. While both systems utilize modern LLM concepts, KoboldAI's storage requirements and metadata handling differ significantly from the standard V2 PNG specification used by SillyTavern and TavernAI.

1. Container Translation: PNG Chunks to JSON Arrays

TavernAI cards are binary-heavy; they store data in the auxiliary chunks of a PNG file. KoboldAI, primarily a web-based and potentially self-hosted application, prefers a clean JSON structure for its internal library. Our converter must first perform a binary sweep of the Tavern PNG to locate the chara key, decode the Base64 JSON, and then begin the field-mapping step to fit KoboldAI's "Character Entity" model.

2. Working with Group Chat Dynamics

KoboldAI is renowned for its group chat capabilities. In a standard TavernAI card, the scenario and personality fields are often written with a 1-on-1 interaction in mind. The name, description, personality, scenario, first message and example dialogue are mapped one-to-one from the TavernAI data to KoboldAI. We prioritize the preservation of the persona and description fields, ensuring they are mapped to KoboldAI's core definition blocks to maintain consistent behavior in complex scenes.

3. World Info and Lorebooks

One of KoboldAI's greatest strengths is its "Worlds" feature, which allows for shared lore across multiple characters. TavernAI V2 cards often have "Lorebooks" embedded directly in the PNG. Embedded character books from V2 and V3 cards stay in the converted card. This prevents the loss of character-specific knowledge and ensures that the transition to KoboldAI's more robust world management tools is seamless.

4. Tokens and Formatting

Different frontends use slightly different tokenization for "User" and "Character" references. TavernAI traditionally uses {{user}} and {{char}}. KoboldAI is generally compatible with these, but it also supports more advanced macro replacements. The converter maps fields only; apart from the small changes listed below, it does not edit, clean up or reformat the text inside them.

5. Data Sovereignty and Client-Side Logic

KoboldAI users often choose the platform for its self-hosting possibilities and privacy. We mirror this commitment by performing all conversions locally. By using browser-based JavaScript to handle the binary extraction and JSON mapping, we ensure that your characters—which represent hours of creative effort—never leave your local machine. This "Zero-Server" approach is our core philosophy, providing a secure bridge for the AI character community.