SkyKoiSKYKOIDocs
Docs/Architecture/Koi Runtime

Koi Runtime

How the embedded koi works: workspace, sessions, tools, skills, and memory.

The koi runtime is the brain of each Koi instance. It runs Claude Opus 4.6 via AWS Bedrock with a full tool system, persistent memory, and workspace-based configuration.

Workspace Files

Each koi has a workspace directory at /home/ubuntu/koi/ containing files that define its personality, instructions, and memory. On the first turn of each session, the koi runtime injects these files into the context:

  • •KOIS.md — Operating instructions, memory workflow, session behavior, and work style rules
  • •SOUL.md — Persona definition: tone, boundaries, expertise, and personality traits
  • •USER.md — Who the user is and how to address them
  • •TOOLS.md — User-maintained tool notes (e.g., camera names, SSH hosts, TTS preferences)
  • •IDENTITY.md — Koi name, theme, and emoji (used for mention patterns and reactions)
  • •BOOTSTRAP.md — One-time first-run ritual (deleted after completion)
  • •HEARTBEAT.md — Optional tiny checklist for heartbeat runs

💡SkyKoi pre-seeds these workspace files during EC2 provisioning via the user-data script. The koi can also modify its own workspace files as it runs.

Session Management

Sessions are stored as JSONL transcripts. The session store maps session keys to session IDs with metadata (timestamps, token counts, channel info).

  • •Direct chats collapse to koi:<koiId>:main for continuity across sessions
  • •Cron jobs use cron:<job.id> sessions
  • •Daily reset at 4:00 AM local time (configurable)
  • •Idle reset with sliding window (optional)
  • •Manual reset via /new or /reset commands

Built-in Tools

Core tools are always available (subject to tool policy):

  • •read — Read file contents (text + images)
  • •write — Create or overwrite files
  • •edit — Precise text replacement in files
  • •exec — Execute shell commands with background continuation (exec.security: "full", exec.host: "gateway")
  • •process — Manage running exec sessions (poll, log, send-keys, kill)
  • •browser — Control a web browser (navigate, snapshot, click, type, evaluate)
  • •web_search — Search the web via Brave Search API
  • •web_fetch — Fetch and extract readable content from URLs
  • •image — Analyze images with vision models
  • •tts — Convert text to speech (ElevenLabs)
  • •message — Send messages across channels
  • •nodes — Control paired iOS/Android/macOS devices
  • •canvas — Present UI on node displays

Memory System

Memory is plain Markdown in the workspace. The koi "remembers" only what gets written to disk:

  • •memory/YYYY-MM-DD.md — Daily log (append-only). Read today + yesterday on session start.
  • •MEMORY.md — Curated long-term memory. Only loaded in the main private session (security measure).
  • •Automatic memory flush — Before session compaction, the koi gets a silent turn to write durable notes to disk.

Skills

Skills are plugin folders containing a SKILL.md with YAML frontmatter and instructions. They teach the koi how to use specific tools or perform specific tasks. Skills load from three locations (workspace wins on name conflict):

  • •Bundled skills — Shipped with the koi runtime
  • •Managed skills — Managed skills directory (shared across kois)
  • •Workspace skills — <workspace>/skills (per-koi, highest priority)
NextGateway Architecture →