iva-agent

EN · RU [](https://github.com/smixs/iva-agent/releases) [](LICENSE) [](https://eve.dev/docs/introduction) [](https://nodejs.org) [](https://github.com/smixs/iva-agent/releases) Site · Use cases · Features · Install · Memory · What's new · 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:** 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 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. 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 daily brief. - **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** — read and send from your _own_ account, not just the bot; connect by chat (QR, no terminal). 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; `/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 (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 `.env` switch 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 and used at your own risk — reading is far safer than sending. Details: docs/userbot.md. Security & privacy