Prerequisites

REQUIRED

• ✓Node.js 18+ — runtime for the KyberBot CLI
• ✓Docker — required for memory services
• ✓Claude Code subscription — KyberBot runs on top of Claude Code

OPTIONAL

• ○Telegram account — if you want to message your agent via Telegram
• ○WhatsApp — if you want to message your agent via WhatsApp

node --version    # Should be 18.0.0 or higher
docker --version  # Should show Docker version
claude --version  # Should show Claude Code version

Installation

# Install KyberBot (one time)
git clone https://github.com/KybernesisAI/kyberbot.git
cd kyberbot
npm install && npm run build
cd packages/cli && npm link && cd ../..

# Create your agent
mkdir ~/my-agent && cd ~/my-agent
kyberbot onboard

Think of the kyberbot/ folder like installing an app — you don't work inside it. The agent folder is your agent. Everything it knows, everything it learns, its entire personality and memory — all lives there.

The kyberbot onboard wizard walks you through 7 steps:

Starting Services

# Start all services (leave running)
kyberbot

# In a new terminal — talk to your agent
cd ~/my-agent && claude

This starts memory services (Docker), the REST API server, heartbeat scheduler, sleep agent, and any configured messaging channels. You'll see a splash screen with your agent's name and service status.

kyberbot                   # Start all services
kyberbot --no-sleep        # Disable sleep agent
kyberbot --no-channels     # Disable messaging channels
kyberbot --no-heartbeat    # Disable heartbeat scheduler

First Conversation

When you first open Claude Code in your agent folder, the agent will warmly introduce itself and ask to learn about you. This is normal — it is reading its SOUL.md and USER.md for the first time and wants to fill in the gaps. Share as much or as little as you like — everything gets stored in its brain for future sessions.

> Hey Atlas, what do you know about me?
> Remember that my product launch deadline is June 15th.
> What's on my schedule today?
> Create a skill for tracking my running mileage.

Updating

When a new version is released, the update command handles both the CLI source update and template refresh inside your agent instance:

cd ~/my-agent
kyberbot update              # Full update: CLI source + agent templates
kyberbot update --check      # Preview what would change
kyberbot update --templates  # Only refresh template files

The Core Idea

Most personal AI agent projects follow the same pattern: build a custom framework, wrap an LLM API, manage tokens, handle tool calling, implement memory from scratch, and deploy a server. The result is a complex system that costs money per token and requires ongoing maintenance.

KyberBot takes a different approach: build on top of Claude Code instead of building from scratch. Claude Code is already an exceptional AI agent. It just lacks persistence — memory, identity, scheduling, and communication channels. KyberBot adds exactly those things. Nothing more.

Philosophy

KyberBot is built on three beliefs:

The Claude Code Advantage

By building on Claude Code, KyberBot inherits capabilities that would take months to build from scratch:

Subscription Model

KyberBot costs nothing beyond your Claude Code subscription:

Who Is KyberBot For?

The brain is KyberBot's long-term memory. It has four components that work together to let the agent remember conversations, track relationships, maintain a timeline, and continuously improve memory quality. All data lives locally — nothing leaves your machine unless you opt into Kybernesis Cloud.

Hybrid Search

When the agent searches memory, it combines semantic and keyword search:

Sleep Agent Pipeline

The sleep agent runs continuously in the background, performing six maintenance steps:

KyberBot agents are not static. They evolve over days, weeks, and months through four mechanisms:

Evolution Over Time

What Is Protected

Not everything can be modified by the agent. These files are protected and require manual editing:

Safeguards

Every change the agent makes is trackable via git. Major changes are confirmed before writing. The agent tells you when it updates a living document. Evening reviews summarize what was learned and changed, giving you regular checkpoints to correct course.

git log --oneline SOUL.md    # See how personality evolved
git log --oneline USER.md    # See knowledge accumulation
git diff HEAD~10 SOUL.md     # Compare current vs 10 commits ago
git checkout HEAD~5 SOUL.md  # Revert to an earlier version

Summary

Three markdown files define your agent's identity, knowledge, and routine. The agent reads them at session start and updates them as it learns.

Document Interaction

The three documents work together: SOUL.md tells the agent how to communicate, USER.md tells it what it knows about you, and HEARTBEAT.md tells it what to do on a schedule. When running a heartbeat task, the agent reads all three for context. During conversation, it reads SOUL.md and USER.md and may update them with new information.

Skills are reusable capabilities — markdown files with structured metadata that teach the agent how to perform specific tasks your way, every time.

SKILL.md Format

---
name: running-tracker
description: Track and analyze running mileage
version: 1.0.0
requires_env: []
has_setup: false
---

# Running Tracker

## What This Does
Track daily runs and calculate weekly/monthly totals.

## How to Use
- "log a run"
- "running mileage"
- "how far did I run"

## Implementation
1. Extract: distance, duration, date, notes
2. Store in brain with tag "running"
3. Calculate weekly/monthly totals when queried
4. Compare against goals in USER.md

Auto-Generation

The most powerful way to create skills is to let the agent do it. The skill generator follows a consistent process:

Lifecycle Commands

kyberbot skill list           # List all installed skills
kyberbot skill info <name>    # Show details
kyberbot skill create <name>  # Scaffold a new skill
kyberbot skill remove <name>  # Remove a skill
kyberbot skill setup <name>   # Run skill setup
kyberbot skill rebuild        # Rebuild CLAUDE.md with current skills

Send a message on Telegram or WhatsApp and get a response from your agent with full personality, memory, and skill context. Both channels are optional.

kyberbot channel add telegram

kyberbot channel list                     # List configured channels
kyberbot channel add telegram              # Add Telegram
kyberbot channel add whatsapp              # Add WhatsApp
kyberbot channel add telegram --reverify   # Re-pair Telegram
kyberbot channel remove telegram           # Remove a channel
kyberbot channel status                    # Check status

Three Modes

File Structure

my-agent/
├── SOUL.md              # Agent personality (living)
├── USER.md              # User knowledge (living)
├── HEARTBEAT.md         # Recurring tasks (living)
├── identity.yaml        # Agent identity config
├── .env                 # Secrets and configuration
├── heartbeat-state.json # Scheduler state
│
├── brain/               # Markdown knowledge files
│   ├── projects/
│   └── people/
│
├── skills/              # Skill files
│   └── my-skill/
│       └── SKILL.md
│
├── data/                # Runtime data (gitignored)
│   ├── chromadb/        # Vector storage
│   ├── entity-graph.db  # Entity graph
│   ├── timeline.db      # Timeline
│   └── sleep.db         # Sleep agent state
│
├── .claude/             # Claude Code config
│   ├── CLAUDE.md        # Operating instructions
│   └── settings.local.json
│
└── logs/                # Application logs

Kybernesis is an optional cloud service that provides a queryable workspace memory for your agent. KyberBot works fully offline without it — Kybernesis adds cross-device access and cloud-backed recall that complements your local brain.

Setup

KYBERNESIS_API_KEY=your_api_key_here

That's all. No agent_id, no workspace_id, no identity.yaml changes. Can also be configured during onboarding.

kyberbot kybernesis query "..."     # Search cloud workspace memory
kyberbot kybernesis list            # Browse all memories
kyberbot kybernesis status          # Check connection status
kyberbot kybernesis disconnect      # Switch to local-only memory

Disconnecting

To switch back to local-only memory:

kyberbot kybernesis disconnect

This removes the API key from .env. After disconnecting, restart the server and Claude. Your cloud memories are preserved — nothing is deleted. To reconnect later, add the key back to .env.

Privacy

Kybernesis sees only the queries you send to it. It does NOT see your .env, local brain, WhatsApp/Telegram sessions, or Claude Code credentials. Data is encrypted in transit and at rest. You can delete your workspace and all data at any time. Kybernesis does not use your data for model training.

Using Without Kybernesis

KyberBot is fully functional without Kybernesis. All memory, search, and agent features work locally. Kybernesis adds convenience (cloud-backed recall, cross-device access) but is not required for any core functionality. The entire brain is in your project directory under data/ and brain/ — back it up with any method you prefer.

Complete reference for all KyberBot CLI commands. 16 top-level commands, 38 subcommands.

Core

run: --no-channels, --no-sleep, --no-heartbeat, -v/--verbose  |  update: --check, --templates  |  status: --json

Memory

Brain

Sleep Agent

Heartbeat

Skills

Sub-Agents

Channels

Kybernesis Cloud