iulita

README

Iulita.ai

Personal AI assistant that learns from your data, not hallucinations about you.

Most AI assistants forget everything between sessions or hallucinate "memories" from training data. Iulita takes a different approach: it stores only verified facts you explicitly share, builds real insights from cross-referencing your actual data, and never invents things it doesn't know. Your memory is yours — structured, searchable, and under your control.

Console-first: launches a full-screen TUI chat by default. Also runs as a headless server with Telegram, Web Chat, and a web dashboard.

Features

• Fact-based memory — stores only what you explicitly tell it to remember, no hallucinated "knowledge"
• Cross-reference insights — discovers patterns across your facts using clustering and LLM analysis
• Multi-agent orchestration — parallel sub-agents for complex tasks (research + analysis simultaneously)
• Token usage dashboard — per-model, per-day cost tracking; admin dashboard page with filters and summaries; chat-based stats via token_stats skill
• Bookmark (quick save) — save any assistant response as a fact with one click, background LLM refinement
• Console TUI — full-screen chat with markdown rendering, streaming, slash commands
• Multi-channel — Telegram bot, Web Chat (WebSocket), Console TUI
• Temporal decay — older memories naturally lose relevance (configurable half-life)
• Hybrid search — FTS5 full-text + ONNX vector embeddings with MMR reranking
• 25+ skills — web search, Google Workspace, Todoist, Craft, weather, shell exec, multi-agent, and more
• Text skills — extend with custom instructions via Markdown files
• Context compression — automatically summarizes old messages when context window fills up
• Task scheduler — background jobs for insight generation, profile analysis, reminders
• Web dashboard — Vue 3 SPA for managing facts, insights, tasks, channels, users, and settings
• Multi-user — JWT auth, user-scoped data, cross-channel fact sharing
• i18n — 6 languages (English, Russian, Chinese, Spanish, French, Hebrew + RTL)
• Smart model routing — auto-routes to Claude Haiku for background tasks and skill synthesis, Sonnet for reasoning; skills declare their own cost tier via SynthesisModelDeclarer
• ClawhHub marketplace — install community skills from the marketplace or via URL
• Zero-config local install — XDG paths, keyring secrets, interactive setup wizard

Quick Start

git clone https://github.com/iulita-ai/iulita.git
cd iulita
make build
./bin/iulita init    # interactive setup wizard
./bin/iulita         # launch TUI

This launches the interactive TUI. Type messages, use /help for commands, Ctrl+C to exit.

Server Mode

For running as a background service with Telegram, Web Chat, and dashboard:

./bin/iulita --server

Docker

cp config.toml.example config.toml
# Edit config.toml — set claude.api_key at minimum
mkdir -p data
docker compose up -d

On first run without config, the server starts in setup mode — a web wizard at http://localhost:8080 walks you through provider selection, feature configuration, and TOML import.

Pre-built image:

services:
  iulita:
    image: ghcr.io/iulita-ai/iulita:latest

How Memory Works

1. You say "remember that my dog's name is Max"
2. Iulita calls the remember tool and stores the fact in SQLite
3. Later, when relevant, it recalls the fact via hybrid search (FTS5 + vector similarity)
4. Over time, the scheduler cross-references facts and generates insights
5. Old facts decay in relevance unless you access them again

No training data. No hallucinations. Just your verified facts.

Architecture

Console TUI ─┐
Telegram ────┤
Web Chat ────┼→ Channel Manager → Assistant → LLM Provider Chain
                     ↕                ↕
                 UserResolver      Storage (SQLite)
                                     ↕
                               Scheduler → Worker
                               (insights, analysis, reminders)
                                     ↕
                                Event Bus → Dashboard (WebSocket)
                                          → Prometheus Metrics
                                          → Push Notifications
                                          → Cost Tracker

Component	Description
channel/console	Bubbletea TUI with markdown, streaming, slash commands
channel/telegram	Telegram bot with whitelist, debouncing, streaming edits, bookmark button
channel/webchat	WebSocket-based web chat with JWT auth, bookmark support
assistant	Orchestrator: history, memory, skills, compression, approvals, streaming
agent	Multi-agent orchestration: parallel sub-agents, budget enforcement, depth limits
llm/claude	Claude API with prompt caching, streaming, extended thinking, context overflow recovery
llm/ollama	Ollama local LLM for dev/background tasks
llm/openai	OpenAI-compatible provider (fallback)
llm/onnx	Local ONNX embeddings (all-MiniLM-L6-v2, 384 dims)
storage/sqlite	SQLite with FTS5 + ONNX vectors, WAL mode
skill/*	25+ tool implementations
bookmark	Quick-save assistant responses as facts with background LLM refinement
scheduler	Task queue with local + remote worker support
dashboard	GoFiber REST API + embedded Vue 3 SPA
skillmgr	External skill manager (ClawhHub, URL, local)
eventbus	Typed publish/subscribe event bus
memory	TF-IDF clustering, memory export/import
cost	LLM cost tracking with daily limits
metrics	Prometheus counters and histograms

Skills

Skill	Description
remember / recall / forget	Persistent fact memory with hybrid search
orchestrate	Multi-agent parallel execution (researcher, analyst, planner, coder, summarizer)
reminders	Time-based reminders with delivery
directives	Persistent user preferences for the AI
insights	AI-generated cross-reference insights
websearch / webfetch	Web search (Brave + DuckDuckGo) and page summarization
google	Gmail, Calendar, Contacts, Tasks via OAuth2
todoist	Full Todoist task management (CRUD, projects, labels, filters)
tasks	Unified task view across Todoist, Google Tasks, Craft
craft	Craft document search, read, write, tasks
weather	Weather forecasts (Open-Meteo, wttr.in, OpenWeatherMap)
exchange	Currency exchange rates
geolocation	IP-based geolocation
shell_exec	Sandboxed shell command execution (requires admin approval)
delegate	One-shot LLM delegation to secondary providers
pdfreader	PDF document reading
set_language	Switch interface language via chat
skills	List, enable, disable, configure skills at runtime
datetime	Current date/time in user's timezone

Configuration

All settings are in config.toml. Every option can be overridden via environment variables with the IULITA_ prefix:

Config key	Env variable	Description
claude.api_key	IULITA_CLAUDE_API_KEY	Anthropic API key (required)
telegram.token	IULITA_TELEGRAM_TOKEN	Telegram bot token
telegram.allowed_ids	—	Telegram user IDs whitelist
claude.model	IULITA_CLAUDE_MODEL	Model ID
storage.path	IULITA_STORAGE_PATH	SQLite database path
server.address	IULITA_SERVER_ADDRESS	Dashboard listen address (:8080)
proxy.url	IULITA_PROXY_URL	HTTP/SOCKS5 proxy for all requests

See config.toml.example for the full reference with all skill configs.

CLI

Command / Flag	Description
iulita	Launch interactive console TUI (default)
iulita --server / -d	Run as headless server
iulita init	Interactive setup wizard
iulita --doctor	Run diagnostic checks
iulita --version / -v	Print version and exit

Development

make build          # build frontend + Go binary
make build-go       # build Go binary only (skip frontend)
make run            # build + launch console TUI
make console        # run console TUI (go run, no build)
make server         # run headless server mode
make dev            # dev mode with hot-reload (server + Vue dev server)
make test           # run all tests
make tidy           # go mod tidy
make clean          # remove build artifacts
make setup-hooks    # configure pre-commit security hooks
make check-secrets  # scan for leaked secrets

Project Structure

cmd/iulita/          # entrypoint, DI wiring, graceful shutdown
internal/
  assistant/         # orchestrator (LLM loop, memory, compression, approvals)
  agent/             # multi-agent orchestration (runner, orchestrator, budget)
  channel/
    console/         # bubbletea TUI
    telegram/        # Telegram bot
    webchat/         # WebSocket web chat
  bookmark/          # quick-save assistant responses as facts
  channelmgr/        # channel lifecycle manager
  config/            # TOML + env + keyring config, setup wizard
  domain/            # domain models
  auth/              # JWT auth + bcrypt
  i18n/              # internationalization (6 languages, TOML catalogs)
  llm/               # LLM providers (Claude, Ollama, OpenAI, ONNX)
  scheduler/         # task queue (scheduler + worker)
  skill/             # skill implementations
  skillmgr/          # external skill manager (ClawhHub, URL, local)
  storage/sqlite/    # SQLite repository, FTS5, vectors, migrations
  dashboard/         # GoFiber REST API + Vue SPA
  web/               # web search (Brave, DuckDuckGo, SSRF protection)
  memory/            # TF-IDF clustering, memory export/import
  eventbus/          # publish/subscribe event bus
  cost/              # LLM cost tracking
  metrics/           # Prometheus metrics
  ratelimit/         # rate limiting
  notify/            # push notifications (Pushover, Ntfy)
ui/                  # Vue 3 + Naive UI + UnoCSS frontend
skills/              # text skill files (Markdown)
docs/                # documentation (6 languages)

Tech Stack

• Go 1.25 with pure-Go SQLite (modernc.org/sqlite)
• SQLite (WAL mode) via bun ORM + FTS5 + ONNX vector search
• anthropic-sdk-go — Claude API with prompt caching and extended thinking
• bubbletea + lipgloss + glamour — console TUI
• telegram-bot-api/v5 — Telegram bot with streaming edits
• GoFiber — dashboard HTTP server + WebSocket hub
• Vue 3 + Naive UI + UnoCSS — dashboard frontend
• vue-i18n — frontend internationalization (6 languages)
• koanf — configuration (TOML + env + keyring overlay + DB overrides)
• hugot (ONNX) — local sentence embeddings (all-MiniLM-L6-v2)
• errgroup — parallel sub-agent orchestration
• zap — structured logging
• Prometheus — metrics (LLM, skills, tasks, messages, sessions)
• robfig/cron — cron scheduling for background jobs

Security

• Pre-commit hook blocks secrets via gitleaks
• Telegram user whitelist (allowed_ids)
• JWT auth (bcrypt) for dashboard and web chat
• AES-256-GCM encryption for DB-stored config overrides
• Dual-layer SSRF protection for web fetch/search (pre-flight DNS + connect-time IP check)
• Tool approval levels (auto / prompt / manual) with locale-aware vocabulary in 6 languages
• Sub-agent security: approval-gated skills (shell_exec) excluded from sub-agent tool sets
• Agent depth limit (max 1) prevents infinite agent spawning
• Per-chat and global rate limiting
• Config validation on startup
• CodeQL and gitleaks in CI

Documentation

Full documentation is available in the docs/ directory:

• Getting Started — installation, first run, CLI reference
• Architecture — system overview, message flow, key interfaces
• Memory and Insights — fact storage, temporal decay, embeddings, bookmarks
• Multi-Agent — parallel sub-agents, orchestration, budget system
• Channels — Console TUI, Telegram, WebChat, bookmark button
• LLM Providers — Claude, Ollama, OpenAI, ONNX, provider routing
• Skills — all 25+ tools, approval levels, marketplace
• i18n / l10n — 6 languages, RTL support
• Configuration — layered config, hot-reload
• Storage — SQLite, FTS5, vector search
• Scheduler — background jobs, agent tasks, bookmark refinement
• Dashboard — REST API, Vue 3 SPA
• Security — JWT, SSRF, encryption, tool approvals
• Deployment — Docker, monitoring, backup

Documentation is available in: English | Русский | 中文 | Español | Français | עברית

Contributing

Contributions are welcome. By opening a pull request, you agree to the Contributor License Agreement.

Dedication

This project is dedicated to my grandmother, who devoted her life to raising me. She was my teacher, my guide, and my biggest supporter. She loved her middle name — Iulita — and so this project carries it forward in her honor.

License

MIT — Copyright (c) 2025 Stanislav Gumeniuk