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-agent/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 seven 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-agent/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-agent/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-agent/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.
iva updateinstalls releases only (vX.Y.Ztags) — the default.mainholds releases only; every accepted change lands in thebetabranch first.iva betaturns on beta updates: the tip of thebetabranch;iva stableturns them off and goes back tomain(nothing is rolled back — the next release catches up). Then runiva update.- Any installation, 0.4.8 included, switches to beta with one command:
curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/beta/beta.sh | bash. A new installation on beta:curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/beta/install.sh | IVA_BETA=1 bash. - The same switch is in Telegram:
/menu→ 🛠 Maintenance → 🧪 Updates.iva versionshows which one is on.
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-agent.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.
Six 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 |
| Claude (Pro/Max) | your Pro/Max subscription, no API key |
| Custom | your own OpenAI-compatible endpoint |
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 · Reminders · Extending · Plugins · FAQ · Troubleshooting
Документация на русском → docs/ru/
v0.4.11 · 03.10.2026 — expand the latest releases
- 🌙 Nightly memory works on a ChatGPT subscription again: the night call now streams on every provider. Since 0.4.9 the subscription backend answered 400 on the first call of every night. The night's own low reasoning effort is no longer overridden by the chat default.
- 🗂️ A vault
.gitignoreno longer stops the night: files the owner excludes are skipped and named in the log, the rest is committed and the day closes. Ignored files stay on disk, outside the backup. - 🔁 A short provider failure no longer fails the turn: before the answer starts, Iva makes up to three attempts with 5 and 15 second waits and honours
Retry-After. An opened stream or an executed tool is never replayed. - 🤖
gpt-6.1-solin the ChatGPT subscription list: Iva identifies as Codex client 0.159.2, so/modelandiva configshow the new model. - 📅 Task deadlines are stored as dates: "tomorrow" becomes
YYYY-MM-DDin the owner's timezone before it is saved, and a deadline can be corrected withupdate. Old deadlines written as words stay as they are. - 🔧 Google CLI updates without root:
iva updateinstalls and refreshesgwsunder the service user's~/.local. Google sign-in and settings stay as they are. - ⏰ The nightly memory time is configurable:
MEMORY_NIGHT_TIME=HH:mmin.env, 04:00 by default. It takes effect afteriva update --force. - 🔀 OpenCode Go models over Responses:
OPENCODE_PROTOCOL=responsesin.envswitches the Go text wire, with the same key and model settings. chat/completions stays the default. - 📝 The nightly Report reads like a note: 2–5 plain lines in the owner's language, built by code from the night's results. The Report is still off by default.
- 🃏 A Card status on the owner's word: "the project is closed" sets the Card status at once through
write_card, and the night of that day keeps it.
- 🚑 A tool name from Claude no longer fails the turn: an Iva tool runs only under its exact or
mcp__iva__name, with no guessing by case, dash or another prefix. Any other name, Claude's ownBashandReadincluded, returns a tool error listing the available tools, and the model goes on in the same turn. - 🔌 Unparsable tool arguments on Claude no longer fail the turn: arguments that are not JSON reach eve as sent, the model gets an input error and corrects the call in the same turn. A stream cut before the end of the message still fails.
- ♻️ A restart mid-reply no longer blocks the next messages: on the next start Iva moves the interrupted workflow state to quarantine, Bridge closes the broken turn with one line and drains the saved queue, and
/newanswers withoutiva reset. A second start in a row leaves the workflow state alone, and a failed recovery is one journal line that does not keep Iva down. - 🔎 File search no longer hangs the turn: one
greporglobcall stops after 20 seconds, 20 000 files or when the turn is stopped, and returns what it found with a hint to narrow the path.node_modules,.gitand*.trash-*quarantines are skipped. - 🧠 Sonnet 5.5 takes the place of Sonnet 5 on Claude: the model screen and setup offer Fable 5.1, Opus 5.5 and Sonnet 5.5 and write
claude-sonnet-5-5to.env. A Claude Code that does not know Sonnet 5.5 yet keeps Sonnet 5 on the same button, andclaude-sonnet-5in.envstill works. The OpenRouter list offersanthropic/claude-sonnet-5.5.
- 🌙 Nightly memory now runs as four code-driven steps: short structured requests turn the day into Cards, links, CORE and summaries, while code writes the files. The format reaches every supported provider, facts require exact quotes from the owner, and a concurrent human edit is preserved.
- 💾 Claude conversations use the prompt cache again: each request pins the cache breakpoint to a stable conversation prefix instead of the changing tail, so later requests reuse the context already sent.
- 🧪 Releases live in main and beta updates follow the beta branch:
iva betaopts in,iva stablereturns to releases, and updates never move an installation backwards. - 🃏 Cards stay writable after the day, night and merge: a new Compiled Truth cannot replace Card structure with headings or an open code fence, successful nightly writes clear
truth_pending, and repeated facts and multiline Card content survive merge. - 🧹 Iva suggests
/newwhen a conversation fills its context: a quiet hint appears once at 50, 75 and 90 percent in a private Telegram chat, resets after compaction and stays out of groups and background turns. - 🚑 Tool schemas work on every provider again:
write_cardsends one flat object schema for all operations, validates the selected operation itself and tells the model what to correct. A guard checks every tool exactly as eve serializes it. - 🔒 A long Card edit keeps its file lock: a live holder refreshes the lock while it works, the lock of a crashed holder can still be taken after it becomes stale, and a separate ten-minute fuse prevents a stuck section from holding the lock forever.
- 🧠 Nightly Brain reaches the private vault backup again: the derived link graph is no longer committed, and a missing remote is created or attached only after GitHub confirms that the repository is private.
- 🔁 Three observed failures pause that day for the owner: the catch-up stops retrying it, reports the last cause once and waits for
iva jobs skip memory-daily <date>before moving on.
Full history — CHANGELOG.md.
eve 0.51.1, 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.