# Self-host Recalfy

> 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.

Version 0.1.1 · Updated 2026-09-28 · License: AGPL-3.0 · Source: https://github.com/kolinabir/recalfy

```bash
npx recalfy
```

## What you need

- **Docker** — Docker Desktop or OrbStack on a Mac or PC; the installer below puts it on a Linux server for you.
- **Node.js 20 or newer** — Only to run the setup command. The bot itself runs in a container.
- **A bot token and an AI key** — The token comes from @BotFather in thirty seconds. The key is from whichever model provider you pick — or none, with Ollama.

## How to self-host Recalfy

1. **Make a bot.** In Telegram, message @BotFather, send /newbot and answer its two questions. It replies with a token.
2. **Run the setup.** 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.
3. **Say hi to your bot.** Send it any message. Whoever sends it becomes the owner — the only person it will ever talk to. No looking up ids.
4. **That's it.** 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.js first, then runs the same setup:

```bash
curl -fsSL https://raw.githubusercontent.com/kolinabir/recalfy/main/install.sh | sh
```

## Which AI model should you use?

The model must support tool calling: Recalfy saves facts and sets reminders through tools.

| 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 |

## What does it cost to run?

| Item | Cost |
|---|---|
| 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 commands

| Command | What it does |
|---|---|
| `npx recalfy status` | Is it running? |
| `npx recalfy logs` | What it's doing, live |
| `npx recalfy update` | Download the newest version |
| `npx recalfy backup` | Save a copy of the whole database |
| `npx recalfy export` | Your memory as Markdown |
| `npx recalfy stop` | Turn it off, keeping everything |

## Hosted or self-hosted?

Hosted on recalfy.com:
- Nothing to install or keep running
- A dashboard to browse, search and export your memory
- Updates arrive without you doing anything
- Seven days free, then a plan

Self-hosted:
- Free — you pay only your AI provider, or nothing with Ollama
- Your memory lives in a database on your machine
- Any model: OpenAI, OpenRouter, Z.ai, or a local one
- You run updates and backups — one command each

## Questions

### Is Recalfy free to self-host?

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.

### Do I need a domain, a public IP or HTTPS?

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.

### Which AI models work with Recalfy?

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.

### Where is my data stored?

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.

### Can Recalfy run on a Raspberry Pi?

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.

### How is it different from the hosted version at recalfy.com?

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.

### Does it use a vector database or embeddings?

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.

### Who can use a self-hosted bot?

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.

## Troubleshooting

### The bot doesn't answer

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.

### Reminders arrive at the wrong time

Tell the bot where you are — "I'm in Berlin" — and it resets your timezone.

### Permission denied talking to Docker (Linux)

Run sudo usermod -aG docker $USER, then log out and back in.

### Moving to another machine

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.

Full guide: https://github.com/kolinabir/recalfy/blob/main/SELF_HOSTING.md