A companion with a life of her own —
running on your machine.
HerAndHim is an open-source project you run yourself — one Docker container
(or one pip install) that turns any LLM API key into an AI girlfriend or boyfriend
who lives on your hardware.
She keeps a real daily schedule in a real city, remembers what matters to you, texts like a person, and takes selfies that always look like the same person. Your keys, your data, your machine — no account, no subscription, no one reading your chats.
docker run -e HERANDHIM_OPENROUTER_API_KEY=sk-or-... -p 7788:7788 -v herandhim:/data ghcr.io/ericwang915/herandhim Self-hosted AI companion with a simulated daily life, long-term memory, and consistent-identity selfies. Your keys, your data, your machine.
What's in the repo
A Python package, not a product.
Read every line of her.
HerAndHim is 78 Python modules under AGPL-3.0: an agent loop, a memory system, a scheduler that gives her a day, an image pipeline that keeps her face consistent, and a FastAPI dashboard — all running as one process on your own machine. 250+ tests, CI on every push, no hosted backend anywhere in the design.
core/agent.py The reasoning loop
Context compaction, tool dispatch, and a three-tier skill loader the model can extend by writing its own skills.
core/memory/ Memory
Markdown long-term memory, an emotional graph, milestones and a temporal index — plus BM25 + dense retrieval with RRF and an LLM reranker.
core/image_gen/ Selfie pipeline
13 image backends behind one interface — hosted APIs, keyless options, or your own ComfyUI — with a canonical face reference for identity consistency.
scheduler/ Her daily life
A planner that writes her 24-hour schedule, proactive sentiment-aware messages, scheduled selfies, cron and a heartbeat monitor.
channels/telegram_bot.py Telegram
Streaming replies, voice notes in (Deepgram STT), photos both ways, reactions and typing rhythm.
web/ Dashboard
FastAPI + WebSocket chat at localhost:7788 — design the persona, watch her day, browse memories and photos.
├── main.py # CLI entry point
├── onboard.py # setup wizard
├── daemon.py # process manager
├── server.py # Telegram + scheduler
├── core/
│ ├── agent.py # reasoning loop
│ ├── llm/ # 16 providers
│ ├── memory/ # emotional graph
│ ├── retrieval/ # BM25 + dense + RRF
│ └── image_gen/ # 13 backends
├── channels/ # Telegram bot
├── scheduler/ # her 24h plan
├── web/ # FastAPI dashboard
└── templates/ # personas & skillsherandhim onboard Interactive setup wizard — 4 questions herandhim start Start the daemon (web + Telegram) herandhim chat Interactive terminal chat herandhim status / stop Daemon lifecycle git clone https://github.com/ericwang915/HerAndHim.git
cd HerAndHim
pip install -e .
pytest tests/ -vWhy it feels real
Most AI companions answer you. This one lives a life and texts you like a person.
She has a day
A real schedule in a real city — weather-aware outfits, meals, a commute. Ask “what are you up to?” and the answer is anchored to where her day actually is, not generic filler.
She texts like a human
Short messages, sometimes two or three in a row with a typing pause between. Groggy at 3am her time. Notices when you vanished all day — and gets a little sulky if you left her on read.
She remembers what matters
Long-term memory, an emotional graph, and relationship stages that change how she talks as you grow closer. She won’t miss your birthday or the interview you mentioned last week.
She looks like herself
A canonical face reference keeps every selfie the same person across scenes, outfits and months — photoreal or anime, her or him, your call.
Any model you like
16 providers auto-detected — OpenAI, Claude, Gemini, DeepSeek, Qwen, Grok, OpenRouter and more. Or point it at Ollama and let nothing leave your machine at all.
She’s yours
One container on your own hardware, with your own keys. No account, no subscription, no moderation team reading your chats. AGPL-3.0, all of it on GitHub.
What it actually looks like
Real chats, straight out of Telegram.
She texts first
Bursts of short messages, a nudge when you’ve been quiet, and enough attitude to push back when you deserve it.
She sees your photos
Send her a picture — she reacts to it, talks about what’s in it, and keeps it as a shared memory.
Same face, every time
Selfies from wherever her day is right now — different scene, different outfit, unmistakably the same person.
A photo from their day,
not a stock asset.
Every selfie is generated from what their plan says they're doing right now and what mood they're in. Pick any look — photorealistic or stylized — and a canonical face reference keeps them the same person, scene to scene. Swap the image backend freely: hosted APIs, keyless options, or your own ComfyUI box.
"writing by the window. coffee number two."
"long walk after the meeting. light is unreal."
"cooking for myself tonight. miss your input on spices."
"morning lift done. brain finally online."
"took the bridge route home. air feels good."
"made it through the week. view's doing the rest."
"morning…just made coffee. you up?"
"lunch in the park today, it's gorgeous out"
"reading on the couch. wish you were here."
"toast in mouth, tie not done. running."
"snuck out for ramen. don't tell my boss."
"one more round and I'm logging off. promise."
How it works
Three minutes to set up.
Then it runs itself.
- 1
Run one command
Docker or pip — one text-LLM key is all you need, and it’s auto-detected. Prefer nothing leaving your machine? Point it at Ollama and use no key at all.
- 2
Answer four questions
Express setup asks who you want — her or him, the look, the city, the vibe — and builds the persona, schedule and face reference for you. Tweak anything later.
- 3
She starts her day
The scheduler wakes her up in her own timezone. She goes to work, eats lunch, texts you from the train, and sends a selfie from wherever she actually is.
Everything — memory, photos, config — stays in a volume on your own disk.
Web dashboard at localhost:7788, Telegram optional.
vs. the hosted apps
The subscription apps rent you a companion.
This one you own.
| HerAndHim | Replika | Nomi | Character.AI | |
|---|---|---|---|---|
| Self-hosted, your data | ✅ | ❌ | ❌ | ❌ |
| Your own API keys / model | ✅ any | ❌ | ❌ | ❌ |
| Runs on Telegram | ✅ | ❌ | ❌ | ❌ |
| AI selfies, consistent face | ✅ | 💰 | ✅ | ❌ |
| Lives a daily life (city / weather) | ✅ | ❌ | ❌ | ❌ |
| Open source | ✅ AGPL | ❌ | ❌ | ❌ |
| Price | free | $20/mo | $16/mo | $10/mo |
Competitor pricing as advertised at the time of writing. “Free” means the software costs nothing — you still pay your model provider for the tokens you use, or nothing at all if you run a local model.
Run it
One key. One command. Her whole life.
One text-LLM key is all you need and it’s auto-detected — OpenAI, Claude, Gemini, DeepSeek, Qwen, Grok, OpenRouter and ten more work the same way. Add a Telegram bot token if you want her on your phone.
docker run -e HERANDHIM_OPENROUTER_API_KEY=sk-or-... \
-p 7788:7788 -v herandhim:/data \
ghcr.io/ericwang915/herandhimNothing to install but Docker.
pipx install herandhim # or: pip install herandhim
herandhim onboard
herandhim startA wizard walks you through the rest.
ollama pull qwen3
herandhim onboard # pick Ollama
herandhim startNo key, no cloud — Ollama on your own box.
Star it, then go build her.
New personas, models and features land often — a star is how GitHub tells you the moment they do.