DOCSEARCHbyAlgolia
Submit Docs

Kai 9000 Documentation

repository·main·Indexed 21 days ago

https://github.com/simonschubert/kai

An open-source AI assistant with persistent memory, interactive UI, and autonomous tool execution. It features a sandboxed Linux environment on Android, support for the Model Context Protocol (MCP) to connect to remote tool servers, and a specialized architecture for persistent memory and autonomous heartbeats. Available across mobile, desktop, and web platforms.

Tokens
46.1K
Snippets
60
Records
202
Agent score
72%

What's inside Kai 9000

  1. Overview of Kai AI Assistant

    main

    Kai is an open-source AI assistant designed with Kotlin Multiplatform and Compose Multiplatform. It is built to provide a persistent, autonomous experience across Android, iOS, Windows, Mac, Linux, and Web platforms.

    Key capabilities include:

    • Persistent Memory: Automatically remembers facts, preferences, and learnings across different conversations.
    • Customizable Personality: Users can define the AI's behavior via an editable system prompt.
    • Multi-Service Fallback: Supports 11+ LLM providers with an automatic fallback mechanism if a provider fails.
    • Autonomous Operation: Features a 'Heartbeat' system for periodic self-checks and tool execution (e.g., web search, shell commands, calendar events).
    • Local Security: Conversations are stored locally using encryption.

  2. Overview of Kai Build

    main
    Kai Build is a specialized, Android-only coding environment integrated within the Kai app. Unlike the standard chat interface, Kai Build operates as a separate product surface with its own lifecycle and constraints. It does not share a conversation store with the chat interface and does not include Alpine sandbox tools. It relies on shared proot native libraries for its underlying execution environment.

  3. Understand the Heartbeat system architecture

    main
    The Heartbeat system is a background monitoring and reporting mechanism composed of several specialized components. It uses a TaskScheduler to run a polling loop that triggers heartbeat checks. The core logic is split between a HeartbeatPromptBuilder (which handles pure prompt assembly) and a HeartbeatManager (which acts as a wrapper to gather inputs and manage logs). Data is persisted via AppSettings, and remote interactions (like conversation creation) are handled by RemoteDataRepository.

  4. Skill Marketplace standards and sources

    main

    Kai uses the Claude Code plugin-marketplace standard to discover skills from GitHub repositories.

    Discovery Logic:

    1. An explicit allowlist in the source takes precedence.
    2. If no allowlist exists, Kai looks for a .claude-plugin/marketplace.json file for authoritative lists and groupings.
    3. If neither is present, Kai scans skill folders under the repository's root (defaulting to skills/).
    4. Any folder listed in the source's exclude set is ignored.

    Curated Marketplaces:

    • Anthropic (anthropics/skills): Focuses on document/data processing (PDF, DOCX, etc.) and creative tasks. Many Claude-specific developer tools are excluded to favor mobile-friendly use cases.
    • Superpowers (obra/superpowers): A popular repository where Kai surfaces only broadly useful methodology skills (e.g., brainstorming, writing-plans) via an allowlist, excluding deep coding-flow tools.

  5. Understand the Tooling architecture in Kai

    main

    Kai's tools feature enables the AI to perform external actions (e.g., web search, shell commands, memory operations) by invoking executable functions during a conversation. The system relies on four core abstractions:

    • Tool: An executable function with a schema (name, description, parameters), a timeout (defaulting to 30 seconds), and an execute method that processes parsed arguments and returns a result.
    • Tool Schema: The machine-readable definition (name, description, and parameter map including type, description, and required flags) sent to the AI provider to inform it of available capabilities.
    • Tool Info: Metadata used for the settings UI, including an id, human-readable name/description, and the current enabled state. This is provided by the platform layer for all tools.
    • Tool Executor: The bridge component that receives raw JSON tool-calls from the AI, looks up the corresponding tool, parses arguments into a typed map, manages the execution timeout, handles errors, and truncates results that are too large.

  6. Available Email Tools

    main

    Email tools are available when the email feature is enabled and accounts are configured.

    Account Referencing: Tools accept either an internal account ID or the account's email address. If only one account is connected, the reference can be omitted. If a reference is invalid, the error will list connected accounts to assist correction.

    Sent Mail Auditing: After sending a reply or a new email, a copy is saved to the account's Sent folder. The system resolves the folder in this order:

    1. The folder configured during account setup.
    2. The Sent mailbox advertised by the server.
    3. Common Sent folder names.
    4. A newly created folder (if none exist).

    Note: Gmail accounts are skipped as Gmail handles its own sent storage. Saving is best-effort; failure to save a copy will not prevent the email from being sent, but will return a warning.

  7. SMS Sync State and Data Structures

    main

    The SMS system maintains a global sync state to manage polling and message tracking. Key fields include:

    • lastSeenId: The largest inbox _id pushed into the pending queue.
    • lastSyncEpochMs: Timestamp of the last successful poll.
    • lastAttemptEpochMs: Timestamp of the last attempted poll (success or failure).
    • unreadCount: Number of inbox rows fetched in the last poll that were not marked read.
    • lastError: A human-readable error string if the last poll failed.

  8. Understand the Kai Memory System

    main

    Kai's memory system allows the AI to learn and retain information across conversations by storing persistent key-value entries. These memories are injected into the system prompt to provide context for every new interaction.

    Key Concepts:

    • Memory: A persistent entry containing a descriptive key, content, category, hit count, and an optional source. Memories survive app restarts and are shared across all conversations.
    • Categories: Memories are organized into four types:
      • General: User preferences, facts, and important information.
      • Learning: Successful approaches and patterns that worked well.
      • Error: Error resolutions and known issues.
      • Preference: User corrections and explicit preferences.
    • Reinforcement: A mechanism where the AI increments a memory's hit count when it proves useful. Memories with 5 or more hits become candidates for Promotion.
    • Promotion: The process of graduating a well-reinforced memory into the permanent 'soul' or system prompt. Once promoted, the memory is removed from the standard memory store.

  9. Understand the Heartbeat feature

    main

    Heartbeat is a user-controlled, periodic automatic self-check mechanism. It allows the AI to review pending tasks, email status, new emails, SMS, notifications, and learned memories at a configurable interval during specified active hours.

    Key behaviors:

    • Silent Operation: If the AI finds nothing requiring attention, it responds with HEARTBEAT_OK and the user sees nothing.
    • Active Reporting: If something requires follow-up, the response is saved to a dedicated heartbeat type conversation and surfaced via a dismissible banner (on Desktop/Web/iOS) or a push notification (on Android).
    • User Control: The AI cannot enable, disable, or reschedule heartbeats. All settings (toggle, interval, active hours) must be managed via the Settings UI.
    • Task Integration: The AI can create HEARTBEAT-trigger tasks using schedule_task with on_heartbeat: true. These tasks are appended to every heartbeat run under a ## Heartbeat Additions section.
    // Example of how the AI creates heartbeat-triggered tasks
schedule_task({
  on_heartbeat: true,
  // ... other task parameters
});

  10. Understand the Kai Build product surface and lifecycle

    main

    Kai Build operates as a separate, full-screen mode distinct from the standard chat interface.

    • Access: On Android, it is accessed via the "Open Kai Build" button located next to "Start Interactive UI" in the empty chat state.
    • Navigation: It occupies the entire screen with no navigation destination or second launcher icon. Using the system back gesture or the top-bar close button returns you to the chat, preserving any drafted messages.
    • Persistence: The mode is not persisted across app restarts but survives screen rotation.
    • Storage Architecture:
      • The Linux rootfs and agent binaries are stored in the app-private kai-build/ directory.
      • Project code is stored in an external-files folder that is bind-mounted to /root/projects. This ensures project files are reachable via USB/MTP while keeping executables on a non-noexec partition.

  11. Android Daemon Service Lifecycle and Recovery

    main

    The Android implementation of the daemon is designed for resilience:

    • Persistence: The service returns START_STICKY, instructing Android to restart the service if the system kills it.
    • Auto-Start/Recovery: The service is automatically (re)started every time the MainActivity is brought to the foreground. This allows the daemon to recover if OEM battery managers or task killers have terminated it.
    • Error Handling: On Android 12+, the app catches and ignores ForegroundServiceStartNotAllowedException (which occurs if the app tries to start the service while not in the foreground), allowing for a retry on the next app launch or foreground transition.

  12. How Daemon Mode works in Kai 9000

    main

    Daemon Mode allows Kai 9000 to execute background tasks on Android even when the app is not in the foreground. It uses an Android Foreground Service to prevent the system from killing the process.

    Platform Availability:

    • Android: Fully supported via a foreground service.
    • Desktop, iOS, Web: Daemon mode is a no-op (has no effect).

    Background Capabilities: The daemon's task scheduler polls every 60 seconds to handle:

    • Scheduled tasks: Executes due tasks via the AI pipeline.
    • Heartbeat checks: Periodic self-checks.
    • Email polling: Fetches new emails from configured accounts.
    • SMS polling: Checks for new incoming SMS messages.