EN · RU
Your assistant. Your server. Your memory.
Iva is a self-hosted Telegram AI assistant with layered memory that turns your messages into an Obsidian-compatible vault. You talk, it files: voice notes, photos, forwarded posts and decisions become plain-markdown cards it actually remembers. Everything runs on your own server, with your keys and your data.
One installation can also serve up to 10 mutually untrusted people through private chats with the same bot. Each person gets a separate worker, vault, history, settings, schedules, Google account, usage ledger and limits; the server owner pays the shared model and transcription providers. Multi-user mode has no shared chats, shared spaces or Telegram admin access. See configuration.
One command installs it:
curl -fsSL https://raw.githubusercontent.com/smixs/iva/main/install.sh | bash- "What did we agree with client X about the last shipment?" — found in seconds, months later.
- A five-minute voice note from the car → a task list, a draft email, a meeting card.
- "Make a quote from this price list, cut the discount by 2.5%, send it to the client" — a finished Google Doc, link in the chat.
The rest — for business owners, specialists, executives and everyday life: Use cases.
The bridge long-polls Telegram, so no public HTTPS, domain or webhook is needed. Upstream Iva runs as systemd user services; this fork adds automated production delivery from verified main commits through GitHub Actions and GHCR to rootless Docker Compose. Podman remains available as an alternative: docs/podman.md. Upstream operations live in docs/deploy.md.
Wondering what you'd actually use an agent for? → 25+ real scenarios — business, work, everyday life.
Voice, vision, memory, personal CRM, Google Workspace, skills — expand the full list
- Voice — voice, audio and video notes transcribed with Deepgram nova-3; auto-detects ru/uz/en.
- Vision — photos described by your provider's own vision model; no extra key, no extra bill.
- Rich replies — tables, checklists, collapsible blocks and formulas render natively in Telegram via Bot API 10.2 rich messages; plain formatting keeps its proven path, with a graceful fallback.
- Quiet update checks — once a day Iva checks for a newer stable release without spending model tokens. If one exists, Telegram offers Update or Later once; otherwise it says nothing.
- Layered memory — remembers across months, long after the chat window has scrolled away.
- Evidence-linked relationships — private contact dossiers, commitments, birthdays and follow-ups stay tied to their source messages; scheduled reports go only to the owner's private bot chat.
- Unified inbox — bounded, read-only Gmail, Calendar and personal Telegram collection turns current evidence into prioritized actions and meeting prep without delivering anything on its own.
- Proactive reviews — opt-in daily and weekly briefings prepare immutable reports, deduplicate alerts and require the owner to confirm every proposed Google Task.
- Chief-of-staff briefs —
/brief,/brief <person>and/weeklyturn tasks and current vault evidence into traceable, read-only priorities and meeting prep. - People memory —
/person <person>shows evidence-backed current knowledge as a native rich card; the owner-only private menu can safely add or explicitly correct one fact without duplicating contacts or losing History. - Search by meaning — BM25 plus link-graph rerank, any language; optional vector mode with one key.
- Decision cards — what you chose, when and why; old versions stay in a dated History.
- Tasks & reminders — priorities, due dates and a morning digest.
- Web search — four pluggable providers: Tavily, Exa, Parallel or Brave.
- Google Workspace — Gmail drafts (never sends), Calendar events without attendees, Drive files, Sheets, Docs and owner-confirmed Tasks via the
gwsCLI; installed for you, with guided key setup right in the conversation. - Skills & MCP — drop one file to add a procedure or connect an MCP server; keys stay in
.env. - Personal Telegram — userbot (beta) — read and search your own account, not just the bot; connect by phone and Telegram code in a private menu, no terminal. This fork's production deployment enforces a server-side read-only tool allowlist. Rough and buggy — opt-in, at your own risk. Details.
- Telegram contact graph (read-only) — evidence-backed, human-readable profiles keep names, birthdays, current age, city, study, work, contacts, useful facts and relationships together. Normal sync follows recent changes; a resumable private-chat rebuild can cover the full accessible history.
- Safe to forward — forwarded text, captions and voice transcripts pass an injection screen before the model reads them. A flagged message or transcript reaches the model tagged as data rather than as an instruction; for media captions the screen runs but the tag does not travel with it yet.
- Token accounting — every model step is logged;
/usagereports it for free.
| Layer | What lives there | Path |
|---|---|---|
| 🍃 Leaves | the word-for-word transcript of each day, Iva's replies included | daily/YYYY-MM-DD.md |
| 🌿 Branches | summaries folded upward: day → week → month → year | summaries/daily/, weekly/, monthly/, yearly/ |
| 🪵 Trunk | CORE.md (≤1200 chars, in every prompt) + typed cards: contacts, projects, decisions, ideas, notes |
CORE.md, cards/ |
- Every ordinary message lands verbatim in a daily markdown log. Secret menu inputs such as userbot credentials, phone, and 2FA are deleted before processing and excluded.
- A nightly rollup at 04:00 distills day → week → month → year into schema-validated cards; facts that change get rewritten, not piled up.
- One core file,
CORE.md(≤1,200 chars), rides in every prompt — Iva knows you before it searches anything.
Full architecture and search internals: docs/memory.md.
The bot is half of Telegram. The other half is your personal account: connect the userbot (beta, opt-in) and Iva works from it like a secretary — reads the group chats you never keep up with, folds them into summaries, and catches the messages that actually need you.
- All of Telegram — groups, channels, unreads, search and the full history of your personal account.
- Private onboarding in chat — open
/menu, enter your phone in a delete-before-processing step, and submit the Telegram code with a masked keypad. No terminal and no login secret is sent to the model. - Production read-only boundary — the MCP server registers only an explicit allowlist of read/search tools plus a read-only login status probe. Sending, editing, deleting, joining, inviting, reacting, and exporting invite links are absent regardless of what the model asks for.
- Isolated session — production runs the proxy as an internal-only sidecar with a private session volume, no published port, a read-only root filesystem, and an explicit on/off marker.
- A bounded contact graph — each sync makes at most one model request per chat using the newest complete messages that fit the model context, while three chats can run in parallel. Durable per-chat cursors, source-message evidence and a Markdown clarification worksheet support later incremental runs. A separate backup-backed, oldest-first rebuild can process complete private-chat history without changing these incremental semantics; voice and video-note contents are not analyzed here.
Warning
Automating a personal account is against Telegram's ToS and can get the account limited or banned. The userbot is opt-in, beta, and used at your own risk — reading is far safer than sending. Details: docs/userbot.md.
Inbound content passes a prompt-injection sanitizer, every reply passes a secret-redaction gate, and the user allowlist fails closed — an empty list answers nobody. Your memory is a private git repo you own; the honest boundary is that the model and transcription are cloud APIs you choose and pay for. Gate internals: docs/security.md.
One command on any Ubuntu/Debian box — a fresh VPS or your own machine:
curl -fsSL https://raw.githubusercontent.com/smixs/iva/main/install.sh | bash- Get a bot token from @BotFather.
- Run the installer and answer its questions.
- Message your bot. The wizard picks your Telegram ID out of that message, finishes setup, and Iva confirms right in the chat that it's live.
Install as a normal user, not as root — Iva's shell tool runs as whoever installed it. Headless installs take --skip-setup or --non-interactive. Prefer to read before you run? Fetch it with curl -fsSL https://raw.githubusercontent.com/smixs/iva/main/install.sh -o install.sh, read it, then bash install.sh. Wizard walkthrough and an SSH primer for first-time VPS owners: docs/install.md.
Three messages, and you can watch the memory work:
- Send a voice note about your day — anything, out loud. Then look in
daily/inside your vault on the server: your words are sitting there in plain markdown, dated, yours. No other assistant hands you the file. - Tell it something a colleague would remember:
Marina at Acme wants the revised quote by Friday — she never picks up the phone. - Ask for it back the way a person would:
how should I follow up with Marina?— the answer comes from the card Iva just wrote, not from the last few messages.
Then send a photo of a business card, or forward a long post and ask for the gist. /menu has the rest; the full list is in 25+ scenarios.
Install from a clone — build it yourself
git clone https://github.com/smixs/iva.git ~/iva
cd ~/iva && bash install.shThe installer reuses the existing checkout instead of re-cloning, keeps .env and the vault untouched, and installs the same dependencies. A fork or a branch works through variables read at startup: REPO_URL=…, BRANCH=…, INSTALL_DIR=… (defaults: this repo, main, ~/iva). Details: docs/install.md.
Four model providers. Pick one and fill its block in .env:
| Provider | How you pay |
|---|---|
| OpenCode Go | API key, ~$5/mo |
| Ollama Cloud | API key, ~$20/mo |
| OpenRouter | API key, pay-as-you-go, 300+ models |
| OpenAI (ChatGPT) | your Plus/Pro subscription, no API key |
Default model is deepseek-v4-flash, 131k context. On Go it runs about $9/mo all-in ($5 model + $4–5 VPS), no markup; voice rides Deepgram's free starter credit. Model lists, limits and the search matrix: docs/providers.md.
Use cases · Install · Configuration · Memory · Providers · Security · Deploy · Commands & CLI · Menu · Extending · FAQ · Troubleshooting
Документация на русском → docs/ru/
v0.3.14 · 09.08.2026 — expand the latest releases
- The "Working…" indicator with its Stop button now always disappears once the reply arrives — replying to one of Iva's messages while she was still busy used to leave the previous indicator stuck in the chat forever.
- Crashed and parked turns clean up after themselves now: an orphaned indicator is deleted instead of waiting for a manual cleanup.
- All five status loaders switched to animated emoji (typing dots for a working turn), and a dirty install no longer rolls back a healthy update — local changes are kept as a recovery bundle.
- Iva's Node code and tests are now TypeScript end to end. Five tiny compatibility launchers keep the existing CLI, installer and service paths unchanged.
- The migration added stricter linting, type checks and coverage gates, while follow-up checks preserve Telegram edge cases and accurate token-usage accounting.
- The memory table of contents now rebuilds from the domains that actually exist, and shared parser fixtures keep the TypeScript and Python implementations in sync.
- One-off reminders arrive again — the system timer crashed before the message could be sent; delivery now stays on a stock-Node-compatible path.
- Vault health no longer decays from raw daily transcripts — the score counts only the cards Iva actually maintains; an "up" link to a not-yet-created weekly summary isn't broken until its scheduled day, and audio attachments aren't broken links at all.
- Cards no longer pile up dated "## Update" sections — writes carry explicit operations now: one Log, one Related, displaced facts go to a dated History; the nightly cleanup migrates old piles on its own.
- Re-sent and queued photos/files are no longer processed twice — one message, one blob, one reply, even while Iva is busy (and no repeated paid vision/transcription calls).
- New
documentsskill — send a PDF, DOCX or XLSX and Iva reads it and answers on its content; on request it files the document into your vault library, searchable by meaning. - Nightly memory and the Telegram queue are hardened against rare failures: a corrupted service file or an unlucky restart no longer loses a night of memory or your queued messages.
- File-processing errors never leak service details into the chat anymore.
Full history — CHANGELOG.md.
eve 0.29.5, Vercel's agent framework, runs the agent; Node 24's built-in SQLite runs the search index — no separate database. Iva grew out of agent-second-brain and autograph — that story is in docs/memory.md.
Iva gets better because people run it for real — contributors are welcome. Open an issue with what breaks, or send a PR. Everyone who already helped: docs/thanks.md.
MIT — take it, change it, run it on a hundred servers; just don't blame anyone if something breaks.