Zorai

Core Architecture#

Zorai employs a daemon-first architecture where all core state—sessions, threads, tasks, approvals, goal runs, and memory—is held by the background-resident zorai-daemon. The Electron desktop app, TUI, CLI, MCP clients, and Slack/Discord/Telegram gateways serve only as lightweight views connecting to the same daemon; closing any interface does not interrupt background AI execution.

Multi-Agent System (The Fires)#

10 specialized agents named after Slavic mythology:

• Swarog: Primary work agent—planning, tool use, sub-agent orchestration, memory, persistent goal running
• Rarog: Guidance/coordination agent—context passing, handoffs, notification dispatch
• Weles: Governance/guardian agent—command interception, sandboxing, approval workflows, WORM audit logs
• Swarozyc: Fast execution agent—narrow-scope rapid implementation
• Radogost: Negotiation/analysis agent—trade-off comparison and routing
• Domowoj: Environment guardian agent—local stability and repair
• Swietowit: Architecture-aware agent—global context
• Perun: Decisive execution agent—infrastructure and security
• Mokosh: Reliability agent—operations and stability
• Dazhbog: Synthesis/explanation agent—translating ambiguity into actionable plans

Interaction directives include @agent ... (visible thread participation), !agent ... (hidden internal DM), and handoff (thread ownership transfer).

Persistent Goal Running & Task Management#

• Goal Runners: Accept long-term goals, auto-plan and dispatch subtasks, resume after disconnection, and record reflections and reusable skills
• Workspace Kanban: Jira-style task flow (Todo → In Progress → In Review → Done) with assigner, reviewer, history, and local JSON mirror

Layered Memory & Semantic Retrieval#

• SOUL.md: Agent identity file defining core persona and constraints
• MEMORY.md: Curated situational and semantic memory
• USER.md: SQLite-backed operator profile with preferences, language, and feedback patterns
• Runtime Search: semantic_query, session_search, onecontext_search, search_history

Governance & Security#

• Command Interception: WELES intercepts dangerous commands before execution
• Sandbox Isolation: High-risk operations execute within sandbox boundaries
• Approval Workflows: High-risk operations trigger human approval with impact scope warnings
• WORM Audit Logs: All governance decisions written to immutable logs
• AST Validator + Credential Scrubber: Built into the daemon
• Time-Travel Snapshots: CRIU Checkpoint/Restore-based snapshot capture and rollback (e.g., Ctrl+Shift+T)

LLM Provider & Model Configuration#

21+ providers supported: OpenAI, Anthropic, Ollama (local), OpenRouter, Groq, Together, Cerebras, Hugging Face, DeepInfra/Qwen, Kimi, MiniMax, Alibaba Tongyi, Z.AI, Featherless, OpenCode Zen, Chutes, and custom endpoints. Per-role model assignment is supported (frontier models for strategy, fast models for implementation, local models for privacy-sensitive scenarios).

Extensibility#

• Plugin System: Runtime or built-in plugins extending components, commands, YAML views, assistant tools, and domain-specific executors. Built-in plugins: Gmail, Google Calendar, Slack, Discord, Telegram, Web Search
• MCP Protocol: zorai-mcp provided as MCP Server (JSON-RPC), enabling external agents to connect via standard MCP
• Voice Workflow: TUI hotkeys for recording/transcription (Ctrl+L), read-aloud (Ctrl+P), stop (Ctrl+S); desktop app provides corresponding controls

Installation#

# Quick install (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/mkurman/zorai/main/scripts/install.sh | sh

# NPM install (cross-platform)
npm install -g zor-ai

Pre-built binaries available for Linux x86_64, macOS Intel/ARM64, Windows x64. Source build via Cargo for daemon and TUI.

Architecture Overview#

Operator layer (multiple frontends) connects to the core zorai-daemon via IPC (Unix socket / TCP). Daemon internals include PTY session management, Agent runtime, Workspace tasks, Execution queue, Goal runners, Approval flow, Snapshot Engine (CRIU C/R), WORM Ledger, FTS5 History (SQLite), etc. Inter-module communication uses zorai-protocol with bincode serialization. Core built as a Rust workspace; frontend on React/TypeScript + Electron 33+.