Open source · AGPL-3.0
Recalfy is an open-source AI memory assistant that lives in Telegram. You tell it things in plain language — a birthday, a wifi password, where you parked — and it remembers them, answers when you ask, and messages you when a reminder is due. Self-hosting it is free and takes one command.
v0.1.1 · Updated
npx recalfyBefore you start
Nothing to sign up for here. Your keys stay on your machine, in a file only you can read.
Docker Desktop or OrbStack on a Mac or PC; the installer below puts it on a Linux server for you.
Only to run the setup command. The bot itself runs in a container.
The token comes from @BotFather in thirty seconds. The key is from whichever model provider you pick — or none, with Ollama.
Setup · about three minutes
In Telegram, message @BotFather, send /newbot and answer its two questions. It replies with a token.
Paste the token when asked, pick a model provider and paste its key. Both are checked on the spot, so a typo fails now rather than on your first message.
Send it any message. Whoever sends it becomes the owner — the only person it will ever talk to. No looking up ids.
Setup starts everything and the bot messages you when it's ready. No domain, no HTTPS certificate, no port forwarding.
On a fresh Linux server, this installs Docker and Node first, then runs the same setup:
curl -fsSL https://raw.githubusercontent.com/kolinabir/recalfy/main/install.sh | shThe model
Recalfy saves facts and sets reminders by calling tools. A model that answers in prose instead says “got it” and saves nothing — so pick one that's good at it.
| Provider | Start with | Why |
|---|---|---|
| OpenAI | gpt-5-mini | Reliable; a few dollars a month for one person |
| OpenRouter | openai/gpt-5-mini | One key, hundreds of models |
| Z.ai | glm-5.2 | What recalfy.com runs on; cheap |
| Ollama | qwen3:8b or larger | Free and private; runs on your own machine |
Running costs
A fact is about 15 tokens, and the whole memory goes into every prompt, where it is cached. So the model bill grows with how much you've told it, and stays small.
| Server | $0 on a machine you already have; about $4–6 a month for a small VPS |
|---|---|
| Telegram | $0 |
| Database | $0 — MongoDB runs in the same Docker setup |
| AI model, 500 memories | about $0.75 a month at 30 messages a day (GLM, cached) |
| AI model, 2,000 memories | about $3 a month at the same pace |
| AI model, Ollama | $0 — it runs on your own hardware |
Day to day
npx recalfy statusIs it running?npx recalfy logsWhat it's doing, livenpx recalfy updateDownload the newest versionnpx recalfy backupSave a copy of the whole databasenpx recalfy exportYour memory as Markdownnpx recalfy stopTurn it off, keeping everythingWhich one?
Same bot, same memory model, same reminders. The difference is who keeps it running.
Questions
Yes. The code is open source under the AGPL-3.0 licence and self-hosting costs nothing. You pay only for the AI model you choose — typically under $3 a month for one person — or nothing at all with a local model through Ollama.
No. A self-hosted Recalfy asks Telegram for new messages itself (long polling), so nothing has to reach your machine from outside. It runs behind a home router, on a laptop or on a Raspberry Pi 5 with no port forwarding.
Any OpenAI-compatible chat API whose model supports tool calling: OpenAI, OpenRouter, Z.ai (GLM), Groq, Together, or a local model through Ollama or LM Studio. Tool calling matters because saving facts and setting reminders happen through tools.
In a MongoDB database inside Docker on your own machine. Your messages still pass through Telegram, and each message is sent to the AI provider you picked — unless that provider is Ollama, in which case nothing leaves your hardware.
Yes, on a Raspberry Pi 5 with a 64-bit OS. The image is published for amd64 and arm64, so Apple Silicon Macs and ARM servers work too. A Pi 4 does not: the MongoDB version Recalfy uses needs a newer ARM processor than the Pi 4 has.
It is the same code. Hosted adds a web dashboard, automatic updates and nothing to maintain, for a monthly plan. Self-hosted is free, keeps the database on your machine and lets you pick any model; you run updates and backups yourself, one command each.
No. Each fact is about 15 tokens, so the whole memory is rendered as Markdown and handed to the model on every message. That is cheaper than retrieval at personal scale, and it lets the model see corrections and contradictions instead of guessing which notes are relevant.
Only its owner — the Telegram account that sent the first message during setup. Anyone else who messages the bot is told it is private, and their messages never reach the AI model.
If something's off
Anything not covered here: open an issue on GitHub with the logs, keys removed.
Run npx recalfy logs. A 409 means another copy is running with the same token; a 401 from the model means the key is wrong or out of credit.
Tell the bot where you are — "I'm in Berlin" — and it resets your timezone.
Run sudo usermod -aG docker $USER, then log out and back in.
npx recalfy backup on the old one, stop it, run setup on the new one with the same bot token, then npx recalfy restore the file.