⚡ KAIROS — Proactive AI Agent

Inspired by Leaked Claude Code

A proactive, always-on AI agent system that runs in the background — built for Hermes Agent.

Inspired by Claude Code's KAIROS system, adapted for the Hermes Agent ecosystem. KAIROS doesn't wait for you to ask — it thinks ahead, consolidates memories, watches for events, and reaches out when it matters.

🚀 Features

🧠 Memory Consolidation (AutoDream)

Every N sessions, KAIROS automatically reviews recent conversations and distills them into long-term memory. It reads session logs, identifies key decisions and patterns, and updates MEMORY.md — so it gets smarter over time without you having to tell it what to remember.

⚡ Event Triggers

Register triggers that fire on:

• File changes — watch directories and react to new/modified/deleted files
• Log patterns — regex-based monitoring on log files
• Heartbeat intervals — time-based checks at configurable intervals

📬 Push Notifications

KAIROS can proactively send you messages via Telegram, WhatsApp, or any connected platform — no prompting needed. It notifies you when something important happens, when tasks complete, or when it needs your attention.

😴 Sleep Cycles

Unlike a busy-waiting daemon, KAIROS can sleep between ticks. It only wakes when there's work to do, conserving resources while staying ready.

📁 Project Structure

kairos/
├── __init__.py          # Package exports
├── kairos_service.py    # Core service — tick loop, task orchestration
├── auto_dream.py        # Memory consolidation — session → MEMORY.md
├── triggers.py          # Trigger engine — file/log/heartbeat events
└── push.py              # Push bridge — deliver to Telegram/WhatsApp

🛠️ How It Works

Gateway Start
    ↓
KAIROS Service starts (background thread)
    ↓
15-minute tick loop
    ├─ Check triggers (file changes, log patterns, heartbeat timers)
    ├─ Check session count → trigger AutoDream if threshold reached
    └─ Process any pending jobs
    ↓
AutoDream Consolidation
    ├─ Fork sub-agent with session logs + current MEMORY.md
    ├─ Sub-agent reads, analyzes, updates MEMORY.md
    └─ Deliver summary to user if configured
    ↓
Push notifications sent when needed

⚙️ Requirements

• Hermes Agent — KAIROS is designed to run as part of Hermes
• Python 3.11+
• Connected messaging platforms (Telegram, WhatsApp, etc.)
• Background gateway running with KAIROS_ENABLED=true

📦 Installation

Quick Install (Recommended)

curl -sL https://raw.githubusercontent.com/KhanPalash/KAIROS/main/install.sh | bash

Manual Install

Option A: Git Clone

# Clone into Hermes Agent
git clone https://github.com/KhanPalash/KAIROS.git ~/.hermes/hermes-agent/kairos

# Or clone elsewhere and add to PYTHONPATH
git clone https://github.com/KhanPalash/KAIROS.git /path/to/kairos

Option B: Standalone

git clone https://github.com/KhanPalash/KAIROS.git
cd KAIROS
pip install -e .

Enable KAIROS

Once installed, enable it:

export KAIROS_ENABLED=true
hermes gateway run

Or configure in your config.yaml:

kairos:
  enabled: true
  model: "minimax-m2.5-free"      # Model for consolidation tasks
  auto_dream_threshold: 5          # Sessions before auto-dream
  tick_interval: 900               # 15 minutes in seconds

🔧 Configuration

📡 API Reference

Register a Trigger

kairos = get_kairos()
kairos.register_trigger(
    name="watch_logs",
    trigger_type="log_pattern",
    pattern=r"ERROR.*",
    prompt="An error was detected in the log. Analyze: {match}",
    skills=["web"],
    deliver="origin"
)

Send a Push Notification

kairos.push("Heads up — something important happened!", deliver="origin")

Sleep

kairos.sleep(duration=3600)  # Sleep for 1 hour

🤖 Background

KAIROS was inspired by the leaked Claude Code KAIROS system. It was reverse-engineered, adapted, and rebuilt in Python for the Hermes Agent framework.

The core philosophy: an agent shouldn't just respond — it should think, anticipate, and act.

📜 License

MIT — do whatever you want with it. Attribution appreciated.

Built with ⚡ by Khan Palash & Hermes Agent