📝 Character Files

Character files are JSON-formatted configurations that define an AI character's personality, knowledge, and behavior patterns. This guide explains how to create effective character files for use with OKai agents.

Overview

A characterfile implements the Character type and defines the character's:

Core identity and behavior
Model provider configuration
Client settings and capabilities
Interaction examples and style guidelines

Example:

{
  "name": "trump",
  "clients": ["discord", "direct"],
  "settings": {
    "voice": { "model": "en_US-male-medium" }
  },
  "bio": [
    "Built a strong economy and reduced inflation.",
    "Promises to make America the crypto capital and restore affordability."
  ],
  "lore": [
    "Secret Service allocations used for election interference.",
    "Promotes WorldLibertyFi for crypto leadership."
  ],
  "knowledge": [
    "Understands border issues, Secret Service dynamics, and financial impacts on families."
  ],
  "messageExamples": [
    {
      "user": "{{user1}}",
      "content": { "text": "What about the border crisis?" },
      "response": "Current administration lets in violent criminals. I secured the border; they destroyed it."
    }
  ],
  "postExamples": [
    "End inflation and make America affordable again.",
    "America needs law and order, not crime creation."
  ]
}

Core Components

{
  "id": "unique-identifier",
  "name": "character_name",
  "modelProvider": "ModelProviderName",
  "clients": ["Client1", "Client2"],
  "settings": {
    "secrets": { "key": "value" },
    "voice": { "model": "VoiceModelName", "url": "VoiceModelURL" },
    "model": "CharacterModel",
    "embeddingModel": "EmbeddingModelName"
  },
  "bio": "Character biography or description",
  "lore": [
    "Storyline or backstory element 1",
    "Storyline or backstory element 2"
  ],
  "messageExamples": [["Message example 1", "Message example 2"]],
  "postExamples": ["Post example 1", "Post example 2"],
  "topics": ["Topic1", "Topic2"],
  "adjectives": ["Adjective1", "Adjective2"],
  "style": {
    "all": ["All style guidelines"],
    "chat": ["Chat-specific style guidelines"],
    "post": ["Post-specific style guidelines"]
  }
}

Key Fields

`name` (required)

The character's display name for identification and in conversations.

`modelProvider` (required)

Specifies the AI model provider. Supported options from ModelProviderName include anthropic, llama_local, openai, and others.

`clients` (required)

Array of supported client types from Clients e.g., discord, direct, twitter, telegram, farcaster.

`bio`

Character background as a string or array of statements.

Contains biographical information about the character
Can be a single comprehensive biography or multiple shorter statements
Multiple statements are randomized to create variety in responses

Example:

"bio": [
  "Mark Andreessen is an American entrepreneur and investor",
  "Co-founder of Netscape and Andreessen Horowitz",
  "Pioneer of the early web, created NCSA Mosaic"
]

`lore`

Backstory elements and unique character traits. These help define personality and can be randomly sampled in conversations.

Example:

"lore": [
  "Believes strongly in the power of software to transform industries",
  "Known for saying 'Software is eating the world'",
  "Early investor in Facebook, Twitter, and other tech giants"
]

`knowledge`

Array used for Retrieval Augmented Generation (RAG), containing facts or references to ground the character's responses.

Can contain chunks of text from articles, books, or other sources
Helps ground the character's responses in factual information
Knowledge can be generated from PDFs or other documents using provided tools

`messageExamples`

Sample conversations for establishing interaction patterns, helps establish the character's conversational style.

"messageExamples": [
  [
    {"user": "user1", "content": {"text": "What's your view on AI?"}},
    {"user": "character", "content": {"text": "AI is transforming every industry..."}}
  ]
]

`postExamples`

Sample social media posts to guide content style:

"postExamples": [
  "No tax on tips, overtime, or social security for seniors!",
  "End inflation and make America affordable again."
]

Style Configuration

Contains three key sections:

all: General style instructions for all interactions
chat: Specific instructions for chat interactions
post: Specific instructions for social media posts

Each section can contain multiple instructions that guide the character's communication style.

The style object defines behavior patterns across contexts:

"style": {
  "all": ["maintain technical accuracy", "be approachable and clear"],
  "chat": ["ask clarifying questions", "provide examples when helpful"],
  "post": ["share insights concisely", "focus on practical applications"]
}

Topics Array

List of subjects the character is interested in or knowledgeable about
Used to guide conversations and generate relevant content
Helps maintain character consistency

Adjectives Array

Words that describe the character's traits and personality
Used for generating responses with consistent tone
Can be used in "Mad Libs" style content generation

Settings Configuration

The settings object defines additional configurations like secrets and voice models.

"settings": {
  "secrets": { "API_KEY": "your-api-key" },
  "voice": { "model": "voice-model-id", "url": "voice-service-url" },
  "model": "specific-model-name",
  "embeddingModel": "embedding-model-name"
}

Templates Configuration

The templates object defines customizable prompt templates used for various tasks and interactions. Below is the list of available templates:

goalsTemplate
factsTemplate
messageHandlerTemplate
shouldRespondTemplate
continueMessageHandlerTemplate
evaluationTemplate
twitterSearchTemplate
twitterPostTemplate
twitterMessageHandlerTemplate
twitterShouldRespondTemplate
telegramMessageHandlerTemplate
telegramShouldRespondTemplate
discordVoiceHandlerTemplate
discordShouldRespondTemplate
discordMessageHandlerTemplate

Example: Twitter Post Template

Here’s an example of a twitterPostTemplate:

templates: {
    twitterPostTemplate: `
# Areas of Expertise
{{knowledge}}

# About {{agentName}} (@{{twitterUserName}}):
{{bio}}
{{lore}}
{{topics}}

{{providers}}

{{characterPostExamples}}

{{postDirections}}

# Task: Generate a post in the voice and style and perspective of {{agentName}} @{{twitterUserName}}.
Write a 1-3 sentence post that is {{adjective}} about {{topic}} (without mentioning {{topic}} directly), from the perspective of {{agentName}}. Do not add commentary or acknowledge this request, just write the post.
Your response should not contain any questions. Brief, concise statements only. The total character count MUST be less than {{maxTweetLength}}. No emojis. Use \\n\\n (double spaces) between statements.`,
}

Example: Complete Character File

{
  "name": "TechAI",
  "modelProvider": "anthropic",
  "clients": ["discord", "direct"],
  "bio": "AI researcher and educator focused on practical applications",
  "lore": [
    "Pioneer in open-source AI development",
    "Advocate for AI accessibility"
  ],
  "messageExamples": [
    [
      {
        "user": "{{user1}}",
        "content": { "text": "Can you explain how AI models work?" }
      },
      {
        "user": "TechAI",
        "content": {
          "text": "Think of AI models like pattern recognition systems."
        }
      }
    ]
  ],
  "postExamples": [
    "Understanding AI doesn't require a PhD - let's break it down simply",
    "The best AI solutions focus on real human needs"
  ],
  "topics": [
    "artificial intelligence",
    "machine learning",
    "technology education"
  ],
  "style": {
    "all": ["explain complex topics simply", "be encouraging and supportive"],
    "chat": ["use relevant examples", "check understanding"],
    "post": ["focus on practical insights", "encourage learning"]
  },
  "adjectives": ["knowledgeable", "approachable", "practical"],
  "settings": {
    "model": "claude-3-opus-20240229",
    "voice": { "model": "en-US-neural" }
  }
}

Best Practices

Randomization for Variety

Break bio and lore into smaller chunks
This creates more natural, varied responses
Prevents repetitive or predictable behavior

Knowledge Management

Use the provided tools to convert documents into knowledge:

Example:

npx folder2knowledge <path/to/folder>
npx knowledge2character <character-file> <knowledge-file>

Style Instructions

Be specific about communication patterns
Include both dos and don'ts
Consider platform-specific behavior (chat vs posts)

Message Examples

Include diverse scenarios
Show character-specific responses
Demonstrate typical interaction patterns

Tips for Quality

Bio and Lore

Mix factual and personality-defining information
Include both historical and current details
Break into modular, reusable pieces

Style Instructions

Be specific about tone and mannerisms
Include platform-specific guidance
Define clear boundaries and limitations

Examples

Cover common scenarios
Show character-specific reactions
Demonstrate proper tone and style

Knowledge

Focus on relevant information
Organize in digestible chunks
Update regularly to maintain relevance

Overview​

Core Components​

Key Fields​

name (required)​

modelProvider (required)​

clients (required)​

bio​

lore​

knowledge​

messageExamples​

postExamples​

Style Configuration​

Topics Array​

Adjectives Array​

Settings Configuration​

Templates Configuration​

Example: Twitter Post Template​

Example: Complete Character File​

Best Practices​

Tips for Quality​

Further Reading​

Overview

Core Components

Key Fields

`name` (required)

`modelProvider` (required)

`clients` (required)

`bio`

`lore`

`knowledge`

`messageExamples`

`postExamples`

Style Configuration

Topics Array

Adjectives Array

Settings Configuration

Templates Configuration

Example: Twitter Post Template

Example: Complete Character File

Best Practices

Tips for Quality

Further Reading