steno-personal

Your Telegram and WhatsApp conversations, connected to your AI agents.

Agents have no way into your personal Telegram or WhatsApp. This gives them one, and only ever a read: both apps reachable over MCP, on a computer you control, staying current as new messages arrive. Context that was split across two apps — what you agreed to, who said it, when — becomes one thing an agent can search, so it works from what you actually said instead of what you can be bothered to paste into a prompt.

It connects to your accounts — your Telegram account, your number as a linked WhatsApp device — reads what is already there, and writes nothing back. No bot, no second phone number, no account on our servers. Runs on a laptop, a Mac mini, or a Raspberry Pi at home — or on Railway in one click.

• Read-only by construction — the code has no way to send a message, mark a chat read, set your presence, or change your profile. See PRIVACY.md.

• Yours — one container, one volume, one SQLite file. No sign-up. Two things can leave the machine and both are listed in PRIVACY.md: enrichment, off until you turn it on, and anonymous usage events — that a feature was used, never what it was used on — which you can turn off.

• One person, not two accounts — the address book links the same human across both apps, so a chat and a transcript say Ada whether she wrote from Telegram or from WhatsApp.

• Agent-ready — MCP tools to list, search and read chats, fetch an attachment, and list the people in your address book.

Quick start · Deploy on Railway · Connect an agent · Teams → Steno.chat

Licensed under the GNU Affero General Public License v3.0.

Quick start

You need Docker and a couple of minutes. No computer you can leave on? Railway runs it for about $5 a month.

Start with Telegram — it carries the lower risk. WhatsApp is optional; read the WhatsApp risk before you pair it.

git clone https://github.com/0xmythril/steno-personal.git
cd steno-personal
docker compose up

The first boot creates the volume and applies migrations. No key is printed to the log; the first visit sets the instance up.

1. Open http://localhost:3000 — a fresh instance lands on Setup.

2. Connect Telegram: consent screen, then a QR code you scan with the phone. The account you pair is what the archive reads, and it is also how you prove the archive is yours if you ever lose your key. Add WhatsApp later under Connections.

3. Press Create my access key. It is shown exactly once — save it. It logs you into the portal and authenticates your agents. Optionally register a passkey for the browser you are in, so that browser logs in with Touch ID, Windows Hello, or your phone.

4. Wait while it reads your history. Chats appear as they land. Create more keys under Settings — one per agent or device.

Lost your key? Choose Pair your phone again on the login page: the same account gets you a new one. Every other path — no phone, start over — is in Lost access.

Stop with docker compose down; your data stays in the data volume. Throw everything away with docker compose down -v.

More ways to run it — bare Node, reverse proxy, upgrades, every environment variable: docs/self-hosting.md.

Related MCP server: telegram-notes-mcp

Deploy on Railway

The path if you have no computer to leave on. One click gives you a service built from this repo's Dockerfile, a 5 GB volume mounted at /data, and a generated SECRET_KEY. Open the generated *.up.railway.app URL as soon as the deploy is green and finish Setup: pair a channel, save your first key.

What it costs. Railway's Hobby plan is $5 a month and includes $5 of usage, which one instance sitting quietly should stay inside. The free trial and the Free plan cap a volume at 0.5 GB and the template asks for 5 GB, so plan on Hobby.

Before you click

1. A Railway deploy has a public URL. Until you have your first access key, Setup is open to whoever reaches that URL first (once you have started pairing, every other visitor is refused on both channels until you finish) — so claim the deploy promptly. Afterwards, an access key (or a passkey) is the only thing between the internet and your archive; read docs/threat-model.md.

2. Pair Telegram here. Read the WhatsApp paragraph before you pair WhatsApp on any cloud host: that is where account restrictions are most likely, and a machine at home is the safer place for it.

New to Railway? Signing up through https://railway.com?referralCode=45_zFw gives you starter credits. It is the maintainer's referral link — Railway pays a share of your first year's bills to this project — and it is entirely optional.

Publishing the template yourself, or self-hosting on Railway without it, is in docs/self-hosting.md.

Connect your agent

Agents talk to https://<your-host>/mcp (or http://localhost:3000/mcp on your laptop) with an access key as a bearer token.

There is no --read-only flag to remember, because there is nothing to switch off: every tool declares itself read-only to the client, and the code has no path that sends. Read-only is how it is built, not a mode it is in.

Fastest path: Settings → create a key → Copy instructions under "Let the agent set itself up" → paste into an agent that can edit its own MCP config. It verifies with whoami.

{
  "mcpServers": {
    "steno-personal": {
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer sp_your_key_here" }
    }
  }
}

claude mcp add --transport http steno-personal https://<your-host>/mcp \
  --header "Authorization: Bearer sp_your_key_here"

{
  "mcpServers": {
    "steno-personal": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://<your-host>/mcp",
        "--header", "Authorization: Bearer sp_your_key_here"
      ]
    }
  }
}

Ask it "which chat accounts are connected?" — that is whoami, and it answers with channels and display names, never a phone number.

A key reads the whole archive. Create one key per agent, put the scope in the agent's own instructions (channel, kind, named chats), and revoke on any doubt. All seven tools, their filters and the agent safety notes: docs/mcp.md.

Telegram

Nothing to set up. The project ships its own registered Telegram application — the same thing Telegram Desktop and every open-source client does — so a fresh deploy can pair Telegram straight away. You log in with your own account; the application only names the software. To run under an application of your own, register one at https://my.telegram.org and set TELEGRAM_API_ID and TELEGRAM_API_HASH; TELEGRAM_API_ID=0 runs without Telegram at all.

On Connections, read the consent screen and press Connect, then scan the QR with Telegram → Settings → Devices → Link Desktop Device. If your account has two-step verification, the page asks for that password and stores it encrypted just long enough for the worker to use it once.

The connection is read-only: it never marks anything read, never shows you as online, and never sends. It appears in Telegram's own device list as steno-personal, and removing it there revokes it here within seconds.

The WhatsApp risk, in one paragraph

WhatsApp publishes no personal-archive API, so this connects as a linked device on your own number through an unofficial client library.

This connects through an unofficial WhatsApp client. Use it at your own risk.

Your number can be restricted or banned. You are shown these same sentences on the consent screen before the QR code, you accept the risk yourself, and nothing in this project can remove it. There is no flag that makes it safe, and the risk is higher on a public cloud host than on a machine at home.

Telegram carries no comparable risk: it connects through Telegram's own published user API, the same one every third-party Telegram client uses.

steno-personal is not affiliated with Telegram, WhatsApp, or Meta.

Need it for a team?

For teams, shared group archives, or if you would rather not link your own account, use Steno.chat. It records through its own number, so your personal account stays unlinked.

People (address book)

The People page links the same human across Telegram and WhatsApp, so a chat and a transcript can say Ada whether she wrote from Telegram or from WhatsApp. It fills itself in from your contacts and direct chats; you merge, alias, hide, and add notes. It is your own annotation over the archive — nothing is sent back to either channel.

Matching rules, merges, and exactly what an agent sees: docs/people.md.

Configuration

Every variable is optional; empty means unset. These are the ones most people touch — the full table is in docs/self-hosting.md.

The one optional third party. Image text extraction and voice-note transcription are off until you save an OpenRouter key in Settings. Leave it blank and that traffic never leaves your machine.

Backups

Everything is under DATA_DIR. Stop the app first — a copy taken while it is still writing can be a moment behind — then copy the directory.

docker compose stop app
docker run --rm -v steno-personal_data:/data -v "$PWD:/backup" \
  busybox tar czf /backup/steno-backup.tar.gz -C /data .
docker compose start app

Restoring, bare Node, and Railway volumes: docs/self-hosting.md.

Documentation

Stuck?

The three things people hit first:

• No key in the log. That is normal — the first key is handed out on /setup, never printed. Locked out later? Lost access.

• Setup says the instance already has an owner. A key exists, so Setup is closed. Log in with a key, or Pair your phone again on the login page.

• WhatsApp keeps disconnecting. Its session ends if the phone is offline for long, and instantly if you unlink from the phone. Re-pair from Connections. Repeated forced logouts can be the first sign of a restriction.

More in Troubleshooting. Still stuck? Ask in Q&A; if it looks like a bug, open one. A security problem goes to the private advisory form, never a public issue.

Contributing

Issues and pull requests are welcome; read CONTRIBUTING.md first — it lists the promises the code keeps and what the project will not become. Conduct is covered by CODE_OF_CONDUCT.md.

Licence

GNU Affero General Public License v3.0; see LICENSE for the full text. Because it is the AGPL, if you modify it and let other people use your modified version over a network, you have to offer them your source too.

Follow along

• Source: https://github.com/0xmythril/steno-personal — watch the repository or its Releases page to hear about new versions.

• Maintainer: 0xmythril, who also posts about it on X at https://x.com/0xmythril.

• Want the next version early? Changes are integrated on staging and run on a private staging instance before they reach main. What is being tested is tagged as a pre-release — vX.Y.Z-rc.N on the releases page — so you can check the tag out and run it yourself. There is no shared instance to log into: this is one archive for one person.