TavernAI to Agnai Character Conversion

The migration from **TavernAI** to **Agnai** represents a move from single-user focused cards to a platform built for expansive, often collaborative, roleplay. While both systems utilize modern LLM concepts, Agnai'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. Agnai, 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 semantic re-mapping process to fit Agnai's "Character Entity" model.

2. Optimizing for Group Chat Dynamics

Agnai 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. When porting to Agnai, our tool ensures that the character's core traits are extracted in a way that remains coherent when multiple characters are present in the same context window. We prioritize the preservation of the persona and description fields, ensuring they are mapped to Agnai's core definition blocks to maintain consistent behavior in complex scenes.

3. World Info and Lore Persistence

One of Agnai'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. Our conversion logic extracts these lore entries and formats them so they can be easily integrated into Agnai's memory system. This prevents the loss of character-specific knowledge and ensures that the transition to Agnai's more robust world management tools is seamless.

4. Token Normalization and Formatting

Different frontends use slightly different tokenization for "User" and "Character" references. TavernAI traditionally uses {{user}} and {{char}}. Agnai is generally compatible with these, but it also supports more advanced macro replacements. Our converter sanitizes the first_mes and mes_example fields to ensure they are free of artifacts that might trigger formatting errors in the Agnai UI, while maintaining the intended speaking style of the original creator.

5. Data Sovereignty and Client-Side Logic

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