A persistent, self-aware AI system with a dedicated Ego layer at the center, not a frontier model.
Kairos inverts the conventional LLM harness topology: a small, always-on Ego model maintains a continuous sense of self, routes work to ephemeral task models, re-voices every output in its own consistent voice, and runs a proactive loop that surfaces observations without being prompted. Specialist and reasoning models are conscripted as subordinate workers — not the center of gravity.
Kairos operates under its own digital identity (its own email, GitHub account, credentials), keeps the owner's personal accounts structurally isolated, and holds a formal map of what it can and cannot modify about itself as first-class self-knowledge.
Requirements: Docker, pnpm ≥ 8, Node 20, Python 3.12, uv.
git clone <this-repo> kairos
cd kairos
make bootstrap # install deps, generate schemas, prepare env
cp .env.example .env
# edit .env — set provider keys + vault master
make up # start all services
make doctor # verify healthFrontend: http://localhost:3000 · Control plane: http://localhost:4000 · Cognition: http://localhost:5000
docs/ Normative architecture + technical specs + ADRs
services/
control-plane/ NestJS — Layer 0 (policy, vault iface, approval state machine, sessions, audit)
cognition/ Python — Ego process, model routing, task dispatch, utility workers
frontend/ Next.js — 3-pane chat UI, briefing view, approval UX
executor/ Docker image — Tool Execution Lane (sandboxed per-call)
packages/ Shared TypeScript schemas + event types
infra/ Docker Compose, Cloudflare Tunnel refs, migration runner
scripts/ Bootstrap, doctor, seed, credential rotation
Start here:
- Architecture — full system specification (normative)
- Product Overview — narrative introduction
- Glossary — Ego, Stratum, Blast Radius, Layer, etc.
- AGENTS.md — working rules for AI assistants in this repo
Technical:
- Data Model · HTTP API · WebSocket API
- Ego Runtime · Memory · Model Routing
- Approval State Machine · Layer Map
- Observability · Self-State Schema
- ADRs — architecture decision records (0001–0012)
Security:
Operations:
Standards:
See CONTRIBUTING.md. All Kairos-authored work lives on kairos/* branches with an attribution block on every PR. See DEV-CHECKLIST.md for the phased build plan.
MIT — see LICENSE.