Angela Assistant

A self-evolving AI assistant with long-term memory, autonomous scheduling, smart home control, and image generation. Built with Dart and Flutter in a client-server architecture.

Inspired by Angela Balzac from Expelled from Paradise.

Features

Multi-Assistant System

Create multiple independent assistants, each with their own personality, memory, conversations, and tools. Every assistant can use a different LLM model and provider.

• Works with any OpenAI-compatible endpoint: OpenRouter, Anthropic, OpenAI, Google, Ollama, etc.
• Per-assistant model, API key, and base URL configuration
• Optional vision support with avatar image injection

Autonomous Self-Evolution (Uber-Ich)

Each assistant has a private daily reflection session that runs automatically at 3 AM. During this session the assistant can:

• Review recent conversations across all channels
• Modify its own persona (identity, personality traits, speech patterns, behavioral guidelines)
• Create, update, or delete recollections and timers
• Manage its agenda
• Reflect on its relationship with the user

The reflection is invisible to the user and uses elevated tools not available during normal chat. This is how the assistant grows and adapts over time.

Long-Term Memory

A 10-field structured memory model maintained automatically by a background LLM process:

• Long-term: user profile, preferences, background
• Medium-term: active projects, recent events, current concerns
• Relationship: self-revelations, interaction patterns
• Psychological: user psychology model
• Short-term: top of mind

Memory is updated periodically (every 20 messages) and injected into every conversation.

Recollections

A persistent knowledge base the assistant manages itself:

• Categorized entries (notes, tracking, bookmarks, etc.)
• Pinned entries are always included in context; non-pinned entries are listed by title and readable on demand
• Optional expiration dates for time-limited information
• Used for the "two-self dialogue" system: the chatting self and thinking self leave notes for each other

Skills

A markdown-based procedural library each assistant reads on demand and authors at runtime:

• Per-assistant directory of SKILL.md files (YAML frontmatter + markdown body)
• Skill index injected into the system prompt with mandatory "load before acting" guidance
• skill_view tool to load a skill's full instructions on demand; skill_manage for the agent to create/edit/delete its own skills
• Bundled how_to_author_skills skill auto-seeded into every assistant on first sight

Self-Scheduling

Assistants can create and manage their own timers:

• One-shot timers (delay or specific time)
• Recurring timers (interval-based)
• Weekday filters and active-hour windows
• Timer-fired tasks execute with full tool access
• Silent responses ([SILENT]) for background work

Smart Home Control

Full Home Assistant integration with 13 actions:

• Device listing and state queries (with domain filtering)
• Control: turn on/off, toggle, set brightness, set color, set temperature
• Scene activation
• State history and energy statistics
• Group and area listing

Image Generation

Anime-style image generation via NovelAI:

• Text-to-image with categorized booru-style tags
• Multi-character scenes with per-character appearance tags
• Style reference support for consistent aesthetics
• 30,000+ tag database with AI-categorized browsing tools
• Generated images displayed inline for vision-capable models

Agenda Board

A Jira-like self-management board with:

• Entry types: epics, stories, tasks, improvements
• Full status workflow with comment history
• Pinned entries for high-priority items

Email and Calendar

• Email: IMAP/SMTP with permission-gated write operations (send, delete, move)
• Calendar: CalDAV access compatible with Google Calendar, Nextcloud, iCloud, Fastmail, mailbox.org

Web Access

• Web search via DuckDuckGo (no API key required)
• Web browser with headless Puppeteer (navigate, click, type, scroll)

Sub-Agents

Assistants can spawn autonomous sub-agents for complex tasks. The orchestrator writes a system prompt and message; the sub-agent runs independently with its own tool set and returns a final answer.

User-Defined Triggers

Attach sandboxed Dart scripts to chat pipeline hooks, in the spirit of AI Dungeon's scripting: count messages, react to keywords, keep hidden state in persistent variables, inject text into the system prompt, or queue background agent runs. The assistant itself has no access to the machinery — it only sees what a script explicitly injects. See the Trigger Scripting Guide.

Architecture

angela-assistant/
├── apps/
│   ├── angela_app/          Flutter desktop client (Linux, macOS, Windows)
│   └── angela_server/       Dart shelf REST + WebSocket server
├── packages/
│   ├── angela_core/         Pure Dart: models, tools, services, database
│   ├── angela_api/          Shared API contract: routes, WS messages, DTOs
│   ├── openrouter_dart/     Agentic LLM framework with tool calling
│   ├── novelai_image_gen/   NovelAI image generation bindings
│   └── booru_tag_db_dart/          Danbooru tag database with search tools

Server (angela_server) — A shelf HTTP + WebSocket server that owns the SQLite database, runs the scheduler (timers + Uber-Ich), and streams agent events to clients in real time.

Client (angela_app) — A Flutter desktop app that connects to the server via REST + WebSocket. Provides the chat interface, assistant management, and settings.

Core (angela_core) — Pure Dart library shared by both: models, repositories, tools, prompt builders, and the AgentRunner that orchestrates all three agent modes (chat, timer, Uber-Ich).

Agent Framework (openrouter_dart) — Agentic LLM client with automatic tool-calling loops, sub-agent support, multimodal messages, and reasoning/thinking support.

Data Flow

• All state lives in a single SQLite database (WAL mode) on the server
• The client communicates exclusively through REST (CRUD) and WebSocket (chat streaming + push notifications)
• Chat messages are sent over WebSocket; the server streams tool events and thinking steps back in real time
• Entity changes (assistant/conversation/recollection/timer/etc.) are broadcast to subscribed clients via WebSocket

Getting Started

See Server README for deployment instructions (Docker, native Dart, Portainer, NAS volumes).

Quick Start with Docker

export ANGELA_AUTH_TOKEN="your-secret-token-here"
docker compose -f apps/angela_server/docker-compose.yml up -d --build

Flutter Client

cd apps/angela_app
flutter pub get
flutter run -d linux

On first launch, enter the server URL (e.g. http://192.168.1.50:8080) and the same auth token.

Technology

• Language: Dart (pure Dart core + Flutter UI)
• Server: shelf + shelf_router + shelf_web_socket
• Database: SQLite (synchronous via package:sqlite3, WAL mode)
• State Management: Riverpod (AsyncNotifierProvider)
• LLM: Any OpenAI-compatible API via openrouter_dart
• Image Generation: NovelAI API
• Smart Home: Home Assistant REST API
• Email: IMAP/SMTP
• Calendar: CalDAV
• Containerization: Docker (two-stage build, debian:bookworm-slim runtime)

License

MIT