Repolode
Submit
smixs

smixs/iva-agent

Self-hosted Telegram AI assistant that files your voice notes, photos and messages into a markdown memory vault it can search later.

Open-source alternative to:Notion AI

View on GitHubWebsite
Stars
265
Forks
58
Open issues
24
Last commit
5 hours ago

What is it?

Iva is a Telegram AI assistant that runs on your own server. Messages, voice notes, photos, PDFs and forwarded posts are stored as dated plain-markdown files in an Obsidian-compatible vault, and typed cards for contacts, projects, decisions and notes are built from them over time.

Memory is organized in layers: each day's transcript is kept verbatim, a nightly rollup folds days into weeks, months and years, and a short CORE.md file is included in every prompt. Search combines BM25 with a link-graph rerank, with an optional vector mode. The assistant also handles voice transcription via Deepgram, image description through the model provider's vision model, tasks and reminders, web search through several providers, and Google Workspace via the gws CLI.

Iva installs with a single shell script on Ubuntu or Debian, and a Mac installer is also described. It supports several model providers, including OpenRouter, Ollama Cloud and Claude or OpenAI subscriptions, plus custom OpenAI-compatible endpoints. An optional userbot mode can read and send from a personal Telegram account, which the project flags as against Telegram's terms and at the user's own risk.

Key features

  • 01Transcribes voice notes with Deepgram and describes photos through the model's vision capability.
  • 02Stores every day's messages verbatim as markdown and rolls them up into weekly, monthly and yearly summaries.
  • 03Keeps a CORE.md file that is included in every prompt for persistent context.
  • 04Searches memory with BM25 plus link-graph reranking, with optional vector search.
  • 05Manages tasks, reminders and a daily brief.
  • 06Connects to Gmail, Calendar, Drive, Sheets, Docs and Tasks via the gws CLI, and supports MCP servers and skills.

Use cases

  • Recalling what was agreed with a client months earlier.
  • Turning a long voice note into a task list, a draft email or a meeting card.
  • Keeping a personal CRM of contacts and follow-ups inside Telegram.
  • Running a self-hosted personal assistant that keeps data on your own server.

Quick start

  1. 1

    Get a bot token from BotFather

  2. 2

    Clone the repository

    git clone https://github.com/smixs/iva-agent.git ~/iva
  3. 3

    Run the installer from the clone and answer its questions

    cd ~/iva && bash install.sh
  4. 4

    Message your bot so the wizard can finish setup

Things to know

  • Needs Node.js 24 or newer and a server you run yourself, so self-hosting effort is required.
  • Requires a model provider API key or subscription, and model and transcription calls go to cloud APIs you pay for.
  • The optional userbot feature violates Telegram's terms of service and can get your account limited or banned.

Topics

#personal-agent#telegram-bot#llm#long-term-memory#self-hosted#obsidian#knowledge-graph#voice-assistant#agent#ai-agent

FAQ

What is iva-agent?
Self-hosted Telegram AI assistant that files your voice notes, photos and messages into a markdown memory vault it can search later. Iva is a Telegram AI assistant that runs on your own server. Messages, voice notes, photos, PDFs and forwarded posts are stored as dated plain-markdown files in an Obsidian-compatible vault, and typed cards for contacts, projects, decisions and notes are built from them over time.
Is iva-agent free to use? What license does it have?
iva-agent is open source under the MIT license. Check the license terms before using it in commercial products.
Is iva-agent still maintained?
Actively maintained. The last commit to iva-agent was on Oct 22, 2026.
What can I use iva-agent for?
Recalling what was agreed with a client months earlier. Turning a long voice note into a task list, a draft email or a meeting card. Keeping a personal CRM of contacts and follow-ups inside Telegram. Running a self-hosted personal assistant that keeps data on your own server.
How do I install iva-agent?
Get a bot token from BotFather Clone the repository: git clone https://github.com/smixs/iva-agent.git ~/iva Run the installer from the clone and answer its questions: cd ~/iva && bash install.sh Message your bot so the wizard can finish setup
Where can I get iva-agent?
The source code and installation instructions are on GitHub: https://github.com/smixs/iva-agent

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects