EN · RU
[](https://github.com/smixs/iva/releases)
[](LICENSE)
[](https://eve.dev/docs/introduction)
[](https://nodejs.org)
[](https://github.com/smixs/iva/releases)
[Use cases](#why-people-run-iva) · [Features](#features) · [Install](#install) · [Memory](#the-memory-tree) · [What's new](#whats-new) · [Docs](#documentation)
](LICENSE){kind=link}
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 command installs it:
curl -fsSL https://raw.githubusercontent.com/smixs/iva/main/install.sh | bash
Why people run Iva
- "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.
How it works
The bridge long-polls Telegram, so no public HTTPS, domain or webhook is needed. Iva runs as two systemd user services, two systemd watchdog timers and five in-process eve schedules — operations live in docs/deploy.md.
Wondering what you'd actually use an agent for? → 25+ real scenarios — business, work, everyday life.
Features
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.1 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. - **Personal CRM** — who your people are, what you agreed, when to follow up. - **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, Calendar, Drive, Sheets, Docs and Tasks from chat via the `gws` CLI; installed for you, with a 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 send from your _own_ account, not just the bot; connect by chat (QR, no terminal). Rough and buggy — opt-in, **at your own risk**. A server-side anti-ban guardrail (FloodWait compliance + randomized pacing + circuit-breaker) is enforced, not just advised. [Details](docs/userbot.md). - **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; `/usage` reports it for free.The Memory Tree
| 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 message lands verbatim in a daily markdown log — nothing is paraphrased on arrival.
- 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.
A secretary inside Telegram
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, catches the messages that actually need you, and replies as you.
- All of Telegram — groups, channels, unreads, search and the full history of your personal account.
- Onboarding in chat — tell the bot to connect your Telegram, scan a QR. No terminal.
- Anti-ban guardrail on the server — FloodWait compliance, a randomized delay after every send, and a circuit-breaker that pauses sending after three FloodWaits in 24 hours. It is enforced in the proxy rather than asked for in a prompt, and it wraps the three outbound calls that actually get accounts flagged: messages, files, forwards. Joins, invites, contact imports and reactions are not wrapped — those limits live in the skill file, which is a prompt.
- Read-only mode — one
.envswitch and Iva can read and search but physically cannot send.
[!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.
Security & privacy
Web pages, search results, voice transcripts, captions and the vision model's description of a picture reach the model only through a prompt-injection sanitizer. On a forwarded text message the same gate annotates the turn with a warning instead of filtering the text, and document bodies, userbot-read chats and agent-browser output are not screened at all. Everything that leaves through the Outbox 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 and the full boundary: docs/security.md.
Install
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.
Brand-new VPS, still logged in as root? Run bash <(curl -fsSL https://raw.githubusercontent.com/smixs/iva/main/bootstrap.sh) first: it creates your sudo user (with lingering enabled), updates the box, and turns on a firewall, fail2ban and SSH hardening. It asks three things — a login, its password, and the timezone — and no SSH key. Then log in as that user with that password and run the installer above. Details: docs/install.md.
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.
The first minute
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.
git clone https://github.com/smixs/iva.git ~/iva
cd ~/iva && bash install.sh
Providers & cost
Four model providers. Pick one and fill its block in .env:
| Provider | How you pay |
|---|---|
| OpenCode Go | API key, ~$10/mo ($5 first month) |
| 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-pro, 131k context. On Go it runs about $14–15/mo all-in ($10 model + $4–5 VPS; the model's first month is $5), no markup; voice rides Deepgram's free starter credit. Model lists, limits and the search matrix: docs/providers.md.
Documentation
Use cases · Install · Configuration · Memory · Providers · Security · Deploy · Commands & CLI · Menu · Extending · FAQ · Troubleshooting
Документация на русском → docs/ru/
What's New
v0.3.23 · 16.08.2026 — expand the latest releases ### 16.08.2026 #### v0.3.23 - A one-time reminder no longer gets lost silently: reminders go through the new `iva remind` command. When it fires, the agent checks whether the task is still open and words the message itself; the code delivers it with retries on network and Telegram failures. If the brain is down, the original text arrives with a ⏰. - A custom skill works right away: a skill dropped into `data/custom/agent/skills/` is visible on the next turn — no rebuild, no restart. Remove the file and the skill is gone. ### 15.08.2026 #### v0.3.22 - The `iva` CLI no longer reorders PATH for child processes: a directory already on PATH is not added a second time, so the paths the caller put first stay first. Shipped as a port of contributor PR #177. - The setup wizard no longer writes hybrid memory mode without an embedding key: with no key and no other source it keeps the free BM25 search and says so in one line. `iva doctor` reads the same resolver as the runtime and names all three sources. Closes issue #180. #### v0.3.21 - A stuck turn can be stopped: the Stop button works through the engine's public interface, long turns no longer die on a timeout, and the bot answers /start. - Memory search is 15× faster — the index is built once and updated only on change; the nightly pass processes only the cards that changed. - A typo in `MODEL_PROVIDER` no longer borrows another provider's config silently: the agent refuses with the four accepted names, and every repair path leads to the fix. Shipped as a port of contributor PR #171. - Re-running the installer is cheap: finished stages are skipped, any failure rolls back on every exit path, secrets never land in /tmp, your edits are never lost. - The description of an incoming photo now passes the injection screen — text on an image no longer reaches the agent as an instruction. ### 14.08.2026 #### v0.3.20 - Morning memory reports no longer arrive unasked: the nightly pass writes the vault silently. The report switch lives in `/menu` → 🔔 Notices, next to the morning digest switch, and applies the same night. An installation that used to get the report hears once where to turn it back on. - Every message Iva sends on her own now speaks one language — the one you picked. The report became a human note: 3-5 lines about what she remembered, no internal jargon. - Alerts now say what broke, what it costs and what to do. The same problem repeats at most once a week; a problem that changed or came back speaks at once.Full history — CHANGELOG.md.
Built on
eve 0.30.8, 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.
Thanks
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.
License
MIT — take it, change it, run it on a hundred servers; just don't blame anyone if something breaks.