45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
# beavergram
|
|
|
|
A read-only Telegram client that keeps everything. A userbot on your own account logs every incoming message into Postgres, including the ones later deleted or edited, along with media, reactions, presence and stories. A web client reads that archive back, and an MCP server hands it to agents.
|
|
|
|
Useful on its own: a Telegram where nothing disappears. In the [beaver](https://git.kotikot.com/beaver) setup it is one of the agent's hands - the dispatcher reads chat history by the `chat_id` stored in a person's card.
|
|
|
|
## What it keeps
|
|
|
|
- **Messages** with edits as versions and deletions as flags, so a message removed in Telegram is still in the archive with its history.
|
|
- **Media** on disk, content-addressed, with the versions of a replaced photo.
|
|
- **Voice** transcribed through Telegram's own transcription (Premium), queued when the quota runs out.
|
|
- **Presence** as a time series (TimescaleDB), read receipts, stories.
|
|
- **Capture policy** from your Telegram folders with per-chat overrides: channels nothing, groups messages only, private chats everything, by default.
|
|
- **Annotations and watches**: your notes on chats and rules that fire alerts, both yours to write in the web client.
|
|
|
|
Nothing is ever deleted from the archive.
|
|
|
|
## Parts
|
|
|
|
- `backend/` - `userbot` (kurigram, the capture loop and jobs) and `api` (FastAPI: the web API, the MCP server, and the built frontend as static files).
|
|
- `frontend/` - SvelteKit, `adapter-static`; a chat client over the archive: folders, chat list, thread with media, versions and the deleted messages inline, search, stories, presence graphs.
|
|
- `docker-compose.yml` - includes `backend/` (Postgres with TimescaleDB, `userbot`, `api`) and `frontend/` (the dev server); profiles `external` and `services`.
|
|
|
|
## MCP
|
|
|
|
Read-only: `search_messages_tool`, `list_chats`, `get_chat_history` (with deleted messages included), `get_deleted_messages`, `get_message_versions`, `get_media`, `get_callbacks`, `presence_history`, `get_peer_history`, `get_stories`, `get_annotations`, `list_watches`, `list_alerts`. The one write is `set_watch`. There are no send, edit or delete tools and there will not be.
|
|
|
|
## Run
|
|
|
|
```sh
|
|
make env # .env and docker-compose.override.yml from the examples
|
|
make -C backend session # log the account in once; the session file stays in backend/sessions
|
|
make deploy # build what changed, migrate, start the containers
|
|
```
|
|
|
|
`COMPOSE_PROFILES` in `.env` selects what runs on the machine, `docker-compose.override.yml` in each part holds the published ports and the `caddy` network aliases. The web client and the MCP endpoint are served by `api`; the bearer for both is `AUTH__TOKEN`.
|
|
|
|
## Develop
|
|
|
|
```sh
|
|
make fmt
|
|
make check
|
|
make -C frontend dev
|
|
```
|