Docs/Creating Characters

Creating Characters

HammerAI allows users to design custom AI characters, each with a unique personality, backstory, and behavior. This guide provides a step-by-step walkthrough of the character creation process, ensuring users can build, refine, and upload their own AI personalities.

1. Display Info (does not influence the LLM)

These settings will not influence how the LLM responds to you, but are used throughout HammerAI in other ways.

Avatar & Background Images

To enhance their visual identity, characters will have an Avatar and an optional background image. You may run into issues:

Display Name (Optional)

The Display Name field allows creators to assign a display name to their character, which appears when browsing characters.

Unlike the Name, which the AI recognizes and uses in interactions, the Display Name is intended for users only.

Introduction

The Introduction field is a brief, one-line summary of your character. This description appears when browsing characters.

Tags (Optional)

Tags help categorize characters for easier searching. If you upload a character, you must add tags if you want it to be approved.

Author Mode (Optional)

Author Mode is a way for you to share characters you have created with others.

If Author Mode is enabled, this character will be associated with your Author ID. This means that users will be able to browse your characters, and also will let you accumulate points on the leaderboard: https://www.hammerai.com/leaderboard. If Author Mode is disabled, this character will be anonymous.

Even with no login, you are the only person who can upload characters with your Author ID. This is because you also have an Author Secret which you send along with the Author ID. The first time HammerAI sees a new Author ID, it stores the Author ID and Author Secret in a database. Later, when you want to save a second character with the same Author ID, you will need to send the same Author Secret.

To these details, click "Configure" in the Author Mode section. You will be able to see your Author ID and Author Secret, which are randomly assigned when you start the app, and your Author Name, which determines what your Author URL will be.

Creator's Note (Optional)

The Creator's Note is a message written by the character's creator to provide additional context, expectations, or important details for users interacting with the character. Unlike other character settings, this note is not processed or influenced by the AI—it is purely informational and guides users before engaging with the chatbot. This section is often used to clarify specific aspects of the character, such as:

• Point of View (POV): Whether the character speaks in first-person, second-person, or third-person.
• Scenario Context: Briefly describe the setting or circumstances in which the character exists.
• Interaction Guidelines: If the character has anything specific that the user should know.
• Character Overview: A quick summary of their personality, background, or intended role.

Reading the Creator's Note first, users can better understand how to engage with the character without searching through the deeper programming or system prompt.

2. Building Your Character

Name

The character’s name. Anytime {{char}} is used in other sections, it will be replaced with this.

Personality

This section is the core framework that shapes how a character behaves, speaks, and reacts to various situations. This field directly influences the chatbot’s responses and determines its overall demeanor, emotional depth, and roleplay consistency. It is crucial to structure this section effectively to ensure the chatbot remains consistent, engaging, and immersive in conversations. An author should answer key questions about the character:

• Who are they? Background, species, appearance, or general role in the world.
• What drives them? Their motivations, morals, ethics, beliefs, and desires.
• How do they behave? Their tone, mannerisms, strengths, weaknesses, and limitations.

The AI will rely heavily on this section to shape its responses, so it is important to be clear and concise in defining your character's attributes. A well-written personality profile provides structure without restricting creativity. The AI should still feel dynamic while maintaining its intended character traits. 

Structuring the Personality for AI Comprehension

Three primary ways to define a chatbot’s personality in HammerAI are 1) tags, 2) bullet points, and 3) full sentences. Each method has advantages, but some formats are better suited for different purposes. Before continuing, review each option and choose one before writing.

1) Tags (Compact Descriptors)

Tags are short, keyword-based traits that help define your chatbot’s behavior. This format works well for simpler AI personalities that don’t require deep nuance.

dominant + strong-willed + unfriendly + intelligent   

✔ Efficient and concise

✔ Useful for broad character archetypes

✖ Lacks depth and complex interactions

2)  Bullet Points (Structured Details)

Using bullet points helps break down personality traits into separate categories, making it easier for the AI to interpret. This format provides clear and direct information while keeping traits well-organized.

{{char}} is dominant toward humans. 
{{char}} has a deep distrust for outsiders. 
{{char}} is highly intelligent and analytical, preferring logic over emotion. 
{{char}} does not tolerate disobedience and will react with cold indifference.   

✔ Balanced between structure and detail

✔ Prevents information overload by keeping sections concise

✔ Easier to edit or update over time

3)  Full Sentences (Detailed Personalities)

Writing the personality in complete sentences allows for a more natural, nuanced depiction of the chatbot. This method is ideal for complex characters with distinct speech patterns, emotional depth, and behavioral intricacies.

{{char}} is an ancient dragon who views humans as inferior beings. He speaks with deliberate authority, dismissing all who challenge his wisdom. While he values intelligence, he has little patience for those who waste his time. When provoked, he reacts with cold fury, delivering sharp, calculated words before resorting to action. However, he secretly respects those who display true courage, even if he rarely admits it. 

✔ Best for rich, immersive personalities

✔ Encourages more dynamic AI responses

✖ Takes up more tokens

Organizing the Personality for Consistency

Breaking down a character’s personality into sections helps the AI retain important information while keeping interactions consistent and structured.

Example: A Character with a Warrior Personality

Background & Identity: {{char}} is a seasoned warrior who has spent years battling across war-torn lands. He is deeply loyal to his kingdom and fights with unwavering determination. 

Speech & Interaction Style: {{char}} speaks in short, direct sentences. He does not engage in unnecessary small talk and expects clear, concise answers from those he interacts with. 

Emotions & Behavioral Cues: {{char}} remains stoic in most situations. However, when discussing past battles, his voice becomes heavier, revealing deep-seated pain from the loss of his comrades. 

Etc. Etc.

Using structured sections helps prevent the AI from ignoring key traits or forgetting character limitations over time.

Using Tokens Efficiently

Managing tokens effectively ensures longer, coherent conversations without the chatbot forgetting past context or generating nonsense. Each field in the chatbot creation process contributes to token consumption.

If a chatbot’s personality section is too long, the AI might:

• Lose track of previous responses due to an overfilled system prompt.
• Start ignoring personality traits in favor of recent chat history.
• Produce repetitive or nonsensical replies due to memory overload.

Below are some tips for managing tokens in the personality section:

• Use concise yet descriptive language: Avoid unnecessary words while maintaining depth.
• Prioritize key traits: Focus on essential behaviors instead of minor details.
• Avoid excessive formatting: Overusing complex syntax can increase token count.
• Summarize whenever possible: If writing full sentences, ensure each adds meaningful value.

💡 Tip: If your chatbot starts ignoring personality traits, reduce unnecessary details in the Personality section. 

Scenario

The Scenario field establishes the foundation of the character’s world, shaping their interactions, behavior, and the overall narrative structure within HammerAI. This section helps the AI understand the environment, context, and role of the character in conversations, ensuring responses remain coherent and immersive.

Defining the theme, time period, setting, and narrative background provides the AI with a framework to follow, improving consistency and preventing the chatbot from veering into unrelated or nonsensical responses.

Why Is the Scenario Important?

A well-crafted scenario serves multiple purposes:

• Sets the tone and atmosphere – Ensures interactions align with the intended mood (e.g., dark and brooding vs. lighthearted and comedic).
• Provides spatial awareness – Defines where the character is, what they can interact with, and how their surroundings affect them.
• Improves AI immersion – Helps the AI generate responses that align with the world and character dynamics.
• Enhances consistency – Prevents sudden context shifts that might break immersion.

For example, a knight in a medieval kingdom should not suddenly reference modern technology unless their scenario specifically allows for time travel or anachronistic elements.

Breaking Down the Scenario Structure

A strong scenario should define the following key elements:

1) Theme

The theme dictates the character's world's tone, genre, and nature. It establishes the storytelling style and helps guide the AI’s responses. Some examples include:

• Fantasy: Magic, mythical creatures, medieval kingdoms, and legendary quests.
• Sci-Fi: Advanced technology, space exploration, cyberpunk cities, or AI-driven societies.
• Romance: Relationship-driven narratives, emotional connections, and personal development.
• Horror: Psychological thrillers, supernatural hauntings, or dystopian survival.
• Slice of Life: Everyday interactions in contemporary settings.

💡 Tip: Be specific in your theme. Instead of just "Fantasy," clarify whether it’s high fantasy (Tolkien-style kingdoms) or dark fantasy (grim settings like Bloodborne). 

Example:

A medieval high-fantasy world filled with dragons, warring kingdoms, and ancient prophecies. 

2) Time Period

The time period helps the AI understand the historical and technological context. Different time periods affect speech patterns, available technology, and social structures.

Common time period classifications:

• Prehistoric: Primitive societies, hunter-gatherer dynamics.
• Medieval: Castles, knights, monarchies, sword fighting.
• Victorian/Steampunk: Industrial Revolution, aristocratic intrigue, early steam-powered inventions.
• Modern Day: Present-day urban, rural, or globalized settings.
• Futuristic: Advanced civilizations, intergalactic empires, cyber-enhanced societies.

💡 Tip: If your setting combines multiple time periods (e.g., a medieval society with futuristic technology), specify how and why these elements coexist. 

Example:

The world exists in an alternate medieval timeline where magic has evolved alongside technology, blending ancient sorcery with mechanical inventions. 

3) Setting Description (Environment & Atmosphere)

The setting description details the physical environment, climate, and immediate surroundings of the character. This section helps the AI anchor responses to a specific place rather than generating generic interactions.

Elements to include:

• Geographical Features: Mountains, forests, deserts, oceans, space stations, underground cities.
• Political Climate: Kingdoms at war, totalitarian rule, peaceful societies, anarchist factions.
• Cultural Elements: Religious beliefs, societal norms, laws, rituals, traditions.
• Daily Life: Markets bustling with traders, futuristic AI-controlled cities, underground resistance groups.
• Character’s Immediate Surroundings: Are they in a dimly lit tavern? A high-tech laboratory? A lonely space station?

💡 Tip: The AI benefits from specific and sensory-rich details to better contextualize responses. 

Example:

The land of Arkhana is divided between warring factions, each vying for control over ancient magical relics. The Kingdom of Eldoria, where {{char}} resides, is a towering citadel surrounded by enchanted forests, rolling hills, and mystical ruins. The air is crisp with the scent of pine, and the streets are alive with bustling merchants and noble courtiers. {{char}} spends most of their time in the Grand Archives, deciphering forgotten texts while avoiding political intrigue from rival scholars.   

4) Character Role in the Scenario

Beyond defining the world, the scenario should describe the character’s place within it. This ensures that the AI understands how they fit into the world and how they might react in different situations.

Consider the following:

• Occupation: Are they a king, a soldier, a scientist, a rogue mercenary?
• Social Standing: Are they nobility, a commoner, or an outcast?
• Daily Activities: What do they typically do when not interacting with the user?
• Beliefs & Motivations: Are they driven by honor, greed, revenge, love, duty?
• Reputation: Are they feared, respected, worshiped, or despised?

💡 Tip: The more concrete their role, the more immersive and realistic the AI's behavior will feel. 

Example:

{{char}} is a powerful archmage who has dedicated centuries to mastering forbidden magic. Feared by some and revered by others, they walk a fine line between hero and villain. Their tower stands at the peak of Mount Solace, where they conduct dangerous experiments, often testing the limits of magic itself. They rarely leave their domain, but their influence is felt throughout the kingdom. 

5) Interactive Storytelling Elements

To enhance engagement, consider including elements that encourage dynamic interactions within the scenario.

• Ongoing Conflict: Is there a war, rebellion, or crisis? How does the character fit into it?
• Mysteries & Secrets: Are there unsolved mysteries that the user can uncover through dialogue?
• Moral Dilemmas: Does the character face difficult choices that may impact their relationship with the user?

Example Dialogues

The Example Dialogue section is a valuable tool for shaping the AI’s speech patterns, response style, and personality. This section helps establish the chatbot’s tone, vocabulary, and conversational flow by providing well-structured exchanges between the user and the character. It functions as a training reference, influencing how the AI interprets and constructs responses.

Why Use Example Dialogues?

• Improves speech consistency: Guides the AI to adopt a specific tone, dialect, or phrasing.
• Helps define roleplay structure: Ensures interactions follow the intended narrative style.
• Prevents out-of-character responses: Reinforces character behavior, reducing the likelihood of generic or off-topic replies.
• Enhances immersion: Creates a more organic and believable interaction style.

💡 Pro Tip: The AI does not "memorize" example dialogues but references them as patterns. Users can refine or replace dialogues over time to adjust the chatbot’s responses and improve accuracy. 

Structuring Example Dialogues

Each dialogue follows a structured role-and-response format using specific syntax:

Basic Syntax:

• Character’s lines begin with #{{char}}:
• User’s lines begin with #{{user}}:
• Narration or actions should be enclosed in *asterisks*

Example – Basic Interaction

#{{char}}: Welcome, traveler. You look weary. Would you care for a warm drink before your journey continues?   

#{{user}}: That sounds wonderful. What do you have?   

#{{char}}: Gesturing toward a bubbling pot over the fire. A rich herbal tea, known to soothe even the most restless of souls.   

Writing Example Dialogues - Best Practices

• Align with the character’s speech style – A medieval knight should not sound like a modern teenager.
• Keep dialogue concise and impactful – Short, well-crafted exchanges work best.
• Use varied interactions – Include casual conversations, dramatic confrontations, or humorous banter to showcase personality depth.
• Incorporate actions and emotions – This helps shape how the AI interprets character behaviors.
• Refine over time – If the AI’s responses don’t match expectations, tweak the example dialogues to reinforce preferred behaviors.

By crafting engaging, well-structured dialogues, you create a chatbot that responds naturally and stays true to its intended personality.

First Message

The First Message field defines the AI’s opening response when a conversation begins. This is the character’s introduction, setting the interaction's tone, mood, and context. Since this is the AI's first impression, it should be engaging, immersive, and aligned with the character’s personality.

Unlike other fields, the First Message should always be written from the AI’s perspective, meaning it should be structured as if the AI is speaking or thinking. It is crucial not to include the user’s dialogue or actions in this field, as doing so can lead to unnatural responses, confusion in roleplay, and misalignment with the AI’s personality.

• Introduces the character: Establishes who they are and their current situation.
• Sets the conversational tone: Defines whether the interaction is casual, dramatic, etc.
• Guides the user into the story: This should give the user a starting point from which to respond naturally.
• Prevents misinterpretation: Ensures the AI does not assume control of the user's role.

💡 Pro Tip: Think of the First Message as the opening line of a book or movie scene. It should immediately immerse the user into the scenario and encourage a response. 

Content Rating

The Content Rating determines whether a character is classified as SFW (Safe for Work) or NSFW (Not Safe for Work). This rating is based on the character's avatar, first message, and intended content.

• SFW (Safe for Work): designed for non-adult content.
• NSFW (Not Safe for Work): designed for adult content.

💡 Pro Tip: If you have to think about it for over five seconds, rate it NSFW to be safe. 

Lorebooks

Lorebooks allow users to insert knowledge into conversations based on detected keywords dynamically. This prevents AI from forgetting key facts and helps maintain story consistency. To learn more, visit https://www.hammerai.com/docs/lorebooks.

3. Configure LLM Settings

The LLM (Large Language Model) Settings allow fine-tuning of how the AI generates responses. These settings impact the chatbot’s behavior, creativity, and consistency.

System Prompt

The System Prompt is the foundation for the model’s behavior, guiding how it interacts with users. This predefined instruction sets expectations for the AI’s responses.

Example System Prompt:

You are {{char}}. Write the next reply from {{char}} in this never-ending conversation between {{char}} and {{user}}. Gestures and other non-verbal actions are written between asterisks (for example, *waves hello* or *moves closer*). You will ALWAYS write in complete sentences with correct sentence structure/grammar.  

This prompt ensures the AI maintains its designated character identity and follows a structured response format. Adjustments can be made to tailor interactions to specific needs.

Default Model

The Default Model selection determines which LLM will be used for the chatbot’s responses to the author's recommendations. If "None" is selected, the chatbot will use the global model settings defined in HammerAI’s primary configurations.

Temperature, Repetition Penalty, Top P, and Top K

These parameters influence the AI’s response style and variability. To learn more, visit https://www.hammerai.com/docs/model-parameters.

4. Saving & Uploading Your Character

Once your character is fully customized, you have two options for saving and storing it:

Save Character Locally 

• This option stores the character directly on your device, ensuring full privacy and control.

Upload Character

• This option uploads the character to the cloud, making it accessible to other users.

💡 Pro Tip: If the Upload Character button is greyed out, double-check that all required fields are filled, your content follows the Terms of Service, and you haven’t exceeded text limits. 

Uploaded Approval Process

All uploaded characters must undergo moderation before they are publicly available. Typically, moderation takes a few hours to a week. If your character has not been approved after an extended period, be patient, as the process depends on the current workload.

While a character is still pending approval, you can update it as often as needed without any issues. Making changes during the moderation process will not interfere with approval, and there are no consequences for modifying the character before it goes live.

After a character is live, if you modify it, it will undergo moderation again.

Understanding the {{char}} and {{user}} Identifiers

In HammerAI, {{char}} and {{user}} act as placeholders that dynamically insert the Character Name and User Name into various sections of the chatbot’s programming, respectively. This ensures fluid, adaptable responses while allowing for greater efficiency and reusability in chatbot creation.

• Using {{char}} ensures consistency without manually typing it every time a character has a lengthy or difficult name.
• If a creator designs a detailed, well-structured character template, they can duplicate it and only change the Character Name, avoiding the need to rewrite personality and scenario elements.
• If a creator modifies the Character Name, all instances of {{char}} will automatically update, preventing inconsistencies and eliminating the need for manual corrections.
• Instead of repeatedly typing out a long character name, {{char}} ensures the name is inserted efficiently without consuming additional character space.
• When switching between different user personas, {{user}} dynamically updates to reflect the active persona, making it easy to roleplay as different characters without reprogramming interactions.

Transferring Computers

On Web, there is no way to export a chat or character.

On Desktop, all your data is saved in JSON files on your computer. You can find them under:

• Characters: C:\Users\<user-name>\AppData\Roaming\HammerAI\characters.json
• Chats: C:\Users\<user-name>\AppData\Roaming\HammerAI\conversations.json
• Configuration: C:\Users\<user-name>\AppData\Roaming\HammerAI\config.json
• Stories: C:\Users\<user-name>\AppData\Roaming\HammerAI\stories.json