EN · RU
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- "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. 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.
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
gwsCLI; 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.
- 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 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.
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.
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.
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.
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, ~$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.
Use cases · Install · Configuration · Memory · Providers · Security · Deploy · Commands & CLI · Menu · Extending · FAQ · Troubleshooting
Документация на русском → docs/ru/
v0.3.24 · 16.08.2026 — expand the latest releases
- A crash at the wrong moment no longer corrupts data: memory cards, settings and service state are written atomically with fsync — a killed process leaves the old file or the new one, never an empty or half-written one.
- The Telegram bridge does not lose messages: polling has a single owner, incoming updates survive crashes in a durable queue, and buttons are only acknowledged after the action really happened.
- An update can be killed at any point: the installation stays on the old version or reaches the new one; the next run cleans up. Rollback is a symlink flip — no network, no rebuild.
- Every process resolves one data directory: CLI, agent, bridge, nightly jobs and their children use one formula. A broken config is an explicit error, not a silent split of memory into two trees.
/menu,/model,/thinkand their buttons work only in a private chat.- A corrupt file is preserved, not overwritten: damaged health history and unreadable cards stay byte-identical on disk and raise an alert. Timezone and context window are validated; a missing
CORE.mdis a normal start.
- A one-time reminder no longer gets lost silently: reminders go through the new
iva remindcommand. 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.
- The
ivaCLI 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 doctorreads the same resolver as the runtime and names all three sources. Closes issue #180.
- 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_PROVIDERno 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.
- 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.
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.
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.