English · Русский

Your assistant. Your server. Your memory.

Use cases · Features · Quick start · Memory · Docs

---

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

Wondering what you'd actually use an agent for? → 25+ real scenarios — business, work, everyday life.

What's New 🔥

• [23.07.2026] v0.3.0 🎛 A control center in chat: nested /menu covers model & thinking, web search with in-chat key setup, interface language (instant ru/en switch — the whole interface is now bilingual), userbot and Google onboarding, crons, skills and a live status card. Plus a 🎭 character test: 10 button-driven questions, four axes, 16 archetypes — the portrait you accept becomes Iva's live persona from the next message, and a core-memory interview she distills into CORE.md herself
• [23.07.2026] v0.3.0 ⏹️ Control mid-turn: /stop (or the ⏹ button on the status message) interrupts a running turn right from chat, messages sent while Iva is busy queue up instead of vanishing, and the working-status message got an animated loader
• [22.07.2026] v0.2.6 ⬆️ Civilized updates: a quiet daily release check that spends zero model tokens, Update / Later buttons in Telegram, all progress in one animated message, phased update with rollback that preserves your edits — and legacy installs moved to a working update channel. Replies to /restart and /update now show the current model, and emotional venting no longer lands in your identity facts
• [22.07.2026] v0.2.6 🧪 Personal Telegram userbot (beta) — read and send from your own account, not just the bot; onboarding fully in chat (QR, no terminal), with a server-enforced anti-ban guardrail (FloodWait compliance, randomized pacing, circuit-breaker). Opt-in, at your own risk
• [15.07.2026] v0.2.5 🧾 Rich replies: tables, checklists, collapsible blocks and formulas render natively in Telegram (Bot API 10.1), with a graceful fallback for plain text
• [09.07.2026] v0.2.4 📮 Google Workspace from chat: Gmail, Calendar, Drive, Sheets and Docs via the gws CLI — the installer sets it up, the key is registered right in the conversation. Plus an OpenRouter provider, and OpenRouter errors that tell the real reason instead of a misleading "needs function calling"
• [06.07.2026] v0.2.1-0.2.3 🤖 Run Iva on your ChatGPT subscription (MODEL_PROVIDER=codex) — no separate API key; docs split into 10 focused pages with Russian mirrors and llms.txt
• [04.07.2026] v0.2.0 🧠 Memory that finds things by meaning: BM25 + link-graph rerank in any language, facts rewritten (not stacked) when reality changes, strictly typed cards, deterministic gates against prompt injection and secret leaks, optional vector mode with one key
• [29.06.2026] v0.1.7 👁️ Iva sees images — described by your provider's own vision model on the same key, with OCR; any attachment type no longer crashes the turn; nightly rollup records your corrections into CORE, so a fix you make today is followed tomorrow

Full history — CHANGELOG.md.

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.

Features

• 🎙️ 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, not just the current chat window.
• 📇 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 and Docs 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.
• 🛡️ Safe to forward — links, PDFs and other people's messages are screened before the model reads them.
• 📊 Token accounting — every model step is logged; /usage reports it for free.

Memory — the part that compounds

• 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.

Quick start

1. Get a bot token from @BotFather.
2. Run the one-line installer above on any Ubuntu/Debian box — a fresh VPS or your own machine.
3. 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.

Headless installs take --skip-setup or --non-interactive. Wizard walkthrough and an SSH primer for first-time VPS owners: docs/install.md.

How it works

The bridge long-polls Telegram, so no public HTTPS, domain or webhook is needed. The agent, the bridge and five memory timers run as systemd user units on your box — operations live in docs/deploy.md.

Providers & cost

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-pro, 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.

Security & privacy

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.

Commands

In Telegram	On the server
/menu · /help · /task · /digest · /new · /update · /usage	iva status · iva update · iva doctor · iva logs

/menu opens a one-message settings hub — model, web search, language, a character test and a memory interview — that stays responsive even while Iva is busy and costs no model tokens: docs/menu.md.

Full reference, including /usage breakdowns by model and by source: docs/cli.md.

Documentation

Use cases · Install · Configuration · Memory · Providers · Security · Deploy · CLI · Extending · FAQ · Troubleshooting

Документация на русском → docs/ru/

Built on

eve 0.24.4, 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.

License

MIT — take it, change it, run it on a hundred servers; just don't blame anyone if something breaks.