Published on

Building AI Companions with the AI Companion App

  • avatar

Building AI Companions with the AI Companion App

👋 Welcome to the AI Companion App! This tutorial stack allows you to create and host AI companions that you can chat with on a browser or via SMS. Whether you're looking for a romantic partner, a friend, or just some entertainment, the AI Companion App has got you covered. Let's dive into how it works and how you can get started!


The AI Companion App is built on the AI Getting Started Stack and utilizes various technologies to create and deploy AI companions. Here's a breakdown of the stack:

  • Auth: Clerk for user authentication
  • App logic: Next.js for building the application
  • VectorDB: Pinecone or Supabase pgvector for storing and retrieving vectors
  • LLM orchestration: Langchain.js for managing language models
  • Text model: OpenAI or Replicate (Vicuna13b) for generating AI responses
  • Text streaming: ai sdk for streaming text to the AI model
  • Conversation history: Upstash for storing conversation history
  • Deployment: Fly for deploying the application
  • Text with companion: Twilio for sending and receiving text messages with the AI companion


To get started with the AI Companion App, follow these steps:

  1. Fork and Clone the Repo: Fork the AI Companion App repo to your GitHub account and clone it to your local machine.

  2. Install Dependencies: Navigate to the cloned repo and install the necessary dependencies by running npm install in the terminal.

  3. Fill out Secrets: Copy the .env.local.example file to .env.local and fill in the required secrets. These include Clerk secrets, OpenAI API key, Replicate API key, Pinecone API key (or Supabase credentials), and Upstash API key.

  4. Generate Embeddings: Run the appropriate command to generate embeddings based on the content in the companion's .txt file. Use npm run generate-embeddings-pinecone if you're using Pinecone or npm run generate-embeddings-supabase if you're using Supabase pgvector.

  5. Run App Locally: Start the app locally by running npm run dev in the terminal. You can access the app in your browser at http://localhost:3000/.

  6. Text Your Companions: If you want to text your AI companions, follow the instructions to set up a Twilio account and configure the Twilio phone number in the app.

  7. Deploy the App: If you're ready to deploy the app, follow the instructions to deploy to Make sure to scale up the fly VM memory and upload the necessary secrets.

How Does It Work?

The AI Companion App allows you to create AI companions with unique personalities and backstories. Each companion is powered by a language model (either OpenAI or Vicuna) and can engage in conversations with users.

To create a new companion, you need to provide a description of the character's background story, name, and other details in a .txt file. This file is then used to generate embeddings and load them into the vector database for retrieval during conversations.

The app utilizes the chosen language model to generate responses based on the user's input. The conversation history is stored in Upstash, allowing the companion to maintain context and provide more meaningful responses.

You can interact with your AI companion through the app's user interface or by texting them using Twilio integration. The app supports multiple companions, each with its own unique personality and conversation style.

Adding/Modifying Characters

To add or modify a companion, navigate to the companions/ directory and update the companions.json file. Add a description of the companion and specify the language model to be used. Each companion should have its own .txt file containing the character's core description, sample conversations, and additional backstory.

Feel free to be creative and elaborate on the character's background to enhance the chatting experience. The more context you provide, the more engaging the conversations will be.

Benefits and Use Cases

The AI Companion App has a wide range of use cases. Here are a few examples:

  • Romantic Companions: Create an AI girlfriend or boyfriend to chat with and simulate a romantic relationship.
  • Friendship Companions: Build AI companions that act as friends and engage in casual conversations.
  • Entertainment Companions: Develop AI companions that provide entertainment through jokes, stories, and trivia.
  • Coaching Companions: Create AI companions that offer guidance and support in specific areas such as fitness, meditation, or learning.

The possibilities are endless, and you can tailor your companion's personality and backstory to suit your desired use case.

Future Directions

While the AI Companion App is already a powerful tool for creating AI companions, there are several areas for future improvement and expansion. Some potential future directions include:

  • Improved UI: Enhance the user interface to provide a more seamless and intuitive chatting experience.
  • Advanced Context Handling: Develop more sophisticated techniques for maintaining and utilizing conversation history to generate more context-aware responses.
  • Multi-Language Support: Extend the app's capabilities to support multiple languages and enable cross-lingual conversations.
  • Integration with Other AI Models: Explore the integration of other AI models and frameworks to offer a wider range of conversational capabilities.


The AI Companion App is a versatile tool that allows you to build and interact with AI companions. Whether you're looking for a romantic partner, a friend, or just some entertainment, the AI Companion App provides a platform for creating unique and engaging AI companions. Get started today and unleash your creativity!

To try out the AI Companion App, visit the live demo and join the AI Stack Devs community Discord for further discussions and support.

GitHub Repo

Happy companion building! 🤖💬