MultiFace

MultiFace is a Telegram bot that creates a "Face," a persona built from stats you define, and role-plays as that persona in chat. The current release lets you create, configure, and interact with a Face. A retrieval-based imitation layer (so a Face can chat as a specific real person, using their message history) is in active development and will ship in a future version.

How it works

• Each Telegram chat can create its own Face via /start, which walks you through a short setup.
• A Face is defined by a set of stats (name, age, nationality, talkativeness, toxicity, intelligence, flexibility, etc.) plus an optional freeform "concept," a backstory or scenario you write yourself.
• Faces are stored in a local SQLite database (memory.db), so a Face's personality and conversation history persist between restarts.
• A Face isn't locked to one chat. You can /join an existing Face from another chat using its ID, so multiple chats can talk to (and share memory with) the same persona.
• Message generation runs through a local Ollama model rather than a cloud API, so the bot can run fully offline aside from Telegram itself.

Requirements

• Python 3.10+
• Ollama installed and running locally, with a model pulled (default: aya-expanse:8b-q4_K_S, see Configuration if you want to use a different one)
• A Telegram bot token from @BotFather

Quick start (Windows)

Run start_multiface.bat. It checks that Python and Ollama are installed, installs dependencies, makes sure Ollama is running and the model is pulled, prompts for your Telegram bot token on first run (saved to .env), and then starts the bot. Keep the window open while using the bot; closing it stops the bot.

Installation (manual / other platforms)

pip install .

This reads pyproject.toml and installs everything the bot needs: python-telegram-bot, python-dotenv, requests, and anthropic (reserved for the upcoming RAG-based imitation feature; feel free to remove it from pyproject.toml for now if you want a leaner install).

Proactive messaging (the bot occasionally messaging first) needs the job-queue extra of python-telegram-bot, which isn't pulled in by the base install:

pip install "python-telegram-bot[job-queue]>=20.0"

If this extra isn't installed, the bot still runs fine. It just logs a warning and disables proactive messages.

Configuration

Create a .env file in the project root:

TELEGRAM_BOT_TOKEN=your-telegram-bot-token
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=aya-expanse:8b-q4_K_S
DB_PATH=memory.db

Only TELEGRAM_BOT_TOKEN is required. The other three have sensible defaults and only need to be set if your Ollama setup differs from the default (a different host/port, a different model you've pulled, or a custom database file path/name).

Running the bot

python -m multiface.main

Make sure Ollama is running (ollama serve, or already running as a service) and that the model in OLLAMA_MODEL has been pulled (ollama pull aya-expanse:8b-q4_K_S) before starting the bot.

Commands

Command	Description
/start	Create a new Face for this chat (runs the setup questions)
/join <ID>	Link this chat to an existing Face using its 8-character ID
/clone	Show this chat's Face ID so others can /join it
/myface	Show the current Face's name, ID, and all stats
/reset	Wipe this Face's conversation history (affects every chat linked to it)
/concept	Set a custom backstory/scenario, e.g. /concept your jealous at John and you love Emma. /concept clear removes it, /concept alone shows the current one
/set_name <name>	Set the Face's first name
/set_lastname <name>	Set the Face's last name
/set_talkative <1-10>	How often the Face jumps into conversation
/set_availability <1-10>	How responsive/available the Face is
/set_toxicity <1-10>	How mean/blunt the Face can get (never actual cruelty or abuse)
/set_intelligence <1-100>	The Face's apparent intelligence level
/set_flexibility <1-100>	How open-minded/adaptable the Face is
/set_age <1-100>	The Face's age
/set_language <language>	The language the Face responds in, e.g. /set_language English
/set_nationality <nationality>	The Face's nationality, e.g. /set_nationality Japanese
/cancel	Cancel the /start setup flow if you're in the middle of it

Data & privacy

All Face data (stats, concept text, conversation history) lives in the local memory.db SQLite file. Nothing is sent to a third party aside from the prompts sent to your own Ollama instance and, for Telegram itself, to Telegram's servers. If you change a Face's core stats significantly, it's recommended to run /reset afterward so old conversation history doesn't clash with the new personality.

Roadmap

• Retrieval-augmented chat so a Face can imitate a specific real person's tone and history, not just a stat-based persona.

Author

Arsam Alaei

Collaborator

Sören Beigi