Bubble

An open-source, config-driven AI character platform. Create custom AI personalities with their own speaking styles, knowledge bases, long-term memory, and deploy them as Discord bots.

Architecture

This project is structured as a unified, modular TypeScript codebase:

• src/core: Platform-independent AI engine. Handles prompt generation, few-shot training example matching, long-term memory vector storage, and AI providers.
• src/discord: Discord bot adapter that handles message events, formats inputs, and backfills chat history on restart.
• src/index.ts: Entry point that loads the configuration and boots the character bot.

Features

• 🤖 Multiple AI Providers: Native support for OpenAI, Gemini, and OpenRouter (or any OpenAI-compatible custom endpoint).
• 🧠 Short-Term Memory: Keeps a sliding window of recent messages per channel. Backfills context from Discord chat history on start so it never forgets previous messages.
• 💾 Long-Term Memory: Automatically embeds and saves conversation turns to a local JSON file (data/ltm.json), recalling relevant past conversations via vector search.
• 📚 Knowledge Base: Stores custom facts injected into the character's system prompt.
• 🎯 Training Examples: Learns how to speak using editable user/assistant dialog pairs, retrieving only the most contextually relevant examples via semantic similarity.
• 🔧 Declarative Config: Configure the entire bot's brain, API endpoints, keys, and personality rules in bubble.config.json.

---

Setup & Running

1. Installation

Install the project dependencies:

npm install

2. Configuration

Create a .env file at the root:

DISCORD_TOKEN=your_discord_token_here

Edit bubble.config.json at the root of the project to configure your character:

{
"id": "luna",
"name": "Luna",
"personality": "You are a sarcastic character with a sharp tongue...",
"rules": [
"Keep responses short.",
"Never use emojis."
],
"boundaries": [
"Never break character."
],
"provider": {
"type": "openai-compatible",
"baseUrl": "https://api.cerebras.ai/v1",
"apiKey": "${CEREBRAS_API_KEY}",
"model": "model-name"
},
"embeddings": {
"type": "gemini",
"model": "gemini-embedding-001",
"apiKey": "${GEMINI_API_KEY}"
},
"memory": {
"shortTermLimit": 20,
"longTermTopK": 5
},
"context": {
"trainingTopK": 2,
"trainingMinSimilarity": 0.25
}
}

Note: Any API keys in the config using the ${VAR_NAME} syntax will be populated from your environment variables at runtime.

3. Build & Run

Compile the TypeScript code and start the bot:

npm run build
npm start

---

License

MIT