Claude-Kairos

Turn Claude Code from a passive tool into a persistent AI assistant.

An open-source MCP Server inspired by Anthropic's unreleased KAIROS assistant mode. It gives Claude Code the ability to receive Telegram messages, maintain long-term memory, run scheduled tasks, and stay alive across sessions — all without modifying Claude Code itself.

Install

npm install -g claude-kairos

Or use directly with npx:

npx claude-kairos

Quick Start

1. Get a Telegram Bot Token

Message @BotFather on Telegram, create a bot, and copy the token.

2. Configure

Create a .env file in the project directory with your credentials:

# Required
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_ALLOWED_CHATS=your-chat-id          # comma-separated for multiple chats

# Required — API access
ANTHROPIC_API_KEY=your-api-key
# If using a custom proxy (e.g. corporate endpoint):
# ANTHROPIC_BASE_URL=https://your-proxy.example.com
# ANTHROPIC_CUSTOM_HEADERS=Token:your-token

# Recommended Claude Code flags
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

Tip: If these variables are already set in your shell, run bash kairos-supervisor.sh setup to auto-detect and write them to .env automatically.

Tip: Send any message to your bot, then check the bot's response for your chat_id.

3. Run with Claude Code

# Add as MCP server in Claude Code
claude --mcp-config kairos.json

4. Persistent Mode (Supervisor)

# Auto-restart sessions + prevent macOS sleep
bash kairos-supervisor.sh

Architecture

┌─────────────────────────────────────┐
│         kairos-supervisor.sh        │
│  Manages Claude Code sessions:      │
│  auto-restart + caffeinate          │
└──────────┬──────────────────────────┘
           │ spawns
┌──────────▼──────────────────────────┐
│          watcher (standalone)       │
│  Telegram polling + /command handler│
│  Cron firing + heartbeat + autoDream│
│  Writes messages → inbox.jsonl      │
└──────────┬──────────────────────────┘
           │ inbox.jsonl
┌──────────▼──────────────────────────┐
│       claude-kairos MCP Server      │
│                                     │
│  telegram_send_message  → reply     │
│  telegram_edit_message  → progress  │
│  telegram_send_keyboard → buttons   │
│  Memory (log/dream)    → long-term  │
│  Cron (create/list/del) → scheduled │
│  Tasks (add/list/update)→ todo list │
└─────────────────────────────────────┘

MCP Tools

| Tool | Description | |------|-------------| | telegram_send_message | Send a Telegram reply | | telegram_edit_message | Edit a previously sent message | | telegram_send_keyboard | Send a message with inline keyboard buttons | | memory_append_log | Append to today's daily log | | memory_read_log | Read a daily log by date | | memory_dream | Trigger memory consolidation | | memory_dream_complete | Signal dream consolidation finished | | cron_create | Create a scheduled task (cron expr) | | cron_list | List all scheduled tasks | | cron_delete | Delete a scheduled task | | task_add | Add a task to the persistent todo list | | task_list | List tasks (active or all) | | task_update | Update task status, priority, or notes | | task_delete | Delete a task permanently |

Telegram Commands

Send these commands directly to your bot — handled instantly by the watcher process, no Claude session needed:

| Command | Description | |---------|-------------| | /help | Show available commands | | /status | Show system status, uptime, and alive check | | /memory | Show MEMORY.md summary | | /log | Show today's daily log | | /log 2026-04-01 | Show log for a specific date | | /search <keyword> | Search memory and logs | | /cron | List scheduled tasks | | /cron_add <cron> <prompt> | Add a scheduled task | | /cron_del <id> | Delete a scheduled task | | /remind <time> <message> | Set a one-shot reminder (e.g. 30m, 2h, 18:00) | | /todo | List active tasks | | /todo_add <title> | Add a new task | | /todo_done <id> | Mark task as done | | /dream | Trigger memory consolidation | | /archive | Archive old logs (>30 days) | | /memstats | Show memory usage stats | | /cancel | Cancel current Claude task (keep session) | | /restart | Reset Claude session (keep watcher) | | /reboot | Full supervisor restart | | /autofix | Fix installation path issues (e.g. after updating Claude) |

Configuration

| Variable | Description | Default | |----------|-------------|---------| | TELEGRAM_BOT_TOKEN | Bot API token from @BotFather | (required) | | TELEGRAM_ALLOWED_CHATS | Allowed chat IDs / usernames | (required) | | ANTHROPIC_API_KEY | Anthropic API key for Claude | (required) | | ANTHROPIC_BASE_URL | Custom API endpoint (proxy / enterprise) | Anthropic default | | ANTHROPIC_CUSTOM_HEADERS | Extra HTTP headers for custom endpoints | — | | CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | Disable telemetry and update checks | 0 | | CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS | Disable experimental Claude features | 0 | | KAIROS_HOME | Base directory for all data | ~/.kairos | | KAIROS_MEMORY_DIR | Memory storage path | ~/.kairos/memory | | KAIROS_TICK_INTERVAL | Heartbeat check interval (seconds) | 30 | | KAIROS_AUTODREAM_INTERVAL | Auto memory consolidation interval (hours) | 24 | | KAIROS_INBOX | Inbox file path for watcher→supervisor | ~/.kairos/inbox.jsonl | | KAIROS_MAX_LOG_SIZE | Max supervisor log size before rotation (bytes) | 5242880 |

Project Structure

claude-kairos/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── server.ts             # MCP tool registration
│   ├── watcher.ts            # Standalone Telegram watcher process
│   ├── telegram/
│   │   ├── bridge.ts         # Bot polling + message queue
│   │   ├── send.ts           # Send helper with signal-file handoff
│   │   ├── commands.ts       # /command handler (17 commands)
│   │   └── types.ts
│   ├── memory/
│   │   ├── dailyLog.ts       # Append-only daily logs
│   │   ├── dreamConsolidation.ts  # Memory consolidation prompt
│   │   ├── autoDream.ts      # Auto-triggered dream scheduling
│   │   ├── archive.ts        # Log archival + memory stats
│   │   ├── writeGuard.ts     # Concurrent write protection
│   │   └── memoryIndex.ts    # File listing
│   ├── cron/
│   │   ├── scheduler.ts      # Task scheduling
│   │   ├── parser.ts         # Cron expression parsing
│   │   └── store.ts          # JSON persistence
│   ├── tasks/
│   │   └── store.ts          # Persistent todo list
│   └── utils/
│       ├── config.ts         # Env var loading
│       ├── atomicWrite.ts    # Atomic file writes
│       └── logger.ts
├── prompts/
│   ├── system.txt            # System prompt for Claude
│   └── dream.txt             # Memory consolidation instructions
├── kairos.json               # MCP server config
└── kairos-supervisor.sh      # Persistent mode supervisor (includes launchd install/remove)

macOS Service

# Auto-detect env vars from current shell → write to .env
bash kairos-supervisor.sh setup

# Install as launchd service (auto-start on login, auto-restart on crash)
bash kairos-supervisor.sh install

# Uninstall
bash kairos-supervisor.sh remove

Run setup before install so the launchd service inherits the right credentials. launchd runs in a minimal environment — variables not in .env won't be available.

Feedback & Support

If you try this project, feedback is very welcome — even a quick "it worked" or "it didn't work on X" helps a lot.

• Feedback / ideas / show & tell: claude-kairos-feedback ← start here
• Bug reports: Open an issue
• Working setup? Leave a ⭐ on GitHub — it helps others find the project.

License

MIT

Claude-Kairos

Claude Code を受動的なツールから、常駐型 AI アシスタントへ。

Anthropic 社の未公開機能「KAIROS アシスタントモード」にインスパイアされたオープンソース MCP Server です。Claude Code 本体を改変することなく、Telegram メッセージの受信、長期記憶の維持、定期タスクの実行、セッションをまたいだ常駐動作を実現します。

インストール

npm install -g claude-kairos

または npx で直接実行:

npx claude-kairos

クイックスタート

1. Telegram Bot Token の取得

@BotFather にメッセージを送り、ボットを作成してトークンをコピーします。

2. 設定

プロジェクトディレクトリに .env ファイルを作成します:

# 必須
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_ALLOWED_CHATS=your-chat-id

# 必須 — API アクセス
ANTHROPIC_API_KEY=your-api-key

# 推奨
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

ヒント: すでにシェルに環境変数が設定されている場合は bash kairos-supervisor.sh setup で自動検出して .env に書き込めます。

3. Claude Code で起動

claude --mcp-config kairos.json

4. 常駐モード（スーパーバイザー）

bash kairos-supervisor.sh

アーキテクチャ

┌─────────────────────────────────────┐
│         kairos-supervisor.sh        │
│  セッション管理: 自動再起動 + caffeinate  │
└──────────┬──────────────────────────┘
           │ 起動
┌──────────▼──────────────────────────┐
│          watcher (独立プロセス)       │
│  Telegram ポーリング + /コマンド処理   │
│  Cron 実行 + ハートビート + autoDream  │
│  メッセージ → inbox.jsonl に書き込み   │
└──────────┬──────────────────────────┘
           │ inbox.jsonl
┌──────────▼──────────────────────────┐
│       claude-kairos MCP サーバー     │
│                                     │
│  telegram_send_message  → 返信       │
│  telegram_edit_message  → 進捗更新   │
│  Memory (log/dream)    → 長期記憶    │
│  Cron (create/list/del) → スケジュール│
│  Tasks (add/list/update)→ タスク管理  │
└─────────────────────────────────────┘

MCP ツール

| ツール | 説明 | |--------|------| | telegram_send_message | Telegram に返信を送信 | | telegram_edit_message | 送信済みメッセージを編集 | | telegram_send_keyboard | インラインキーボード付きメッセージを送信 | | memory_append_log | 今日の日次ログに追記 | | memory_read_log | 日付を指定してログを読む | | memory_dream | 記憶の整理を実行 | | memory_dream_complete | 記憶整理の完了を通知 | | cron_create | 定期タスクを作成 | | cron_list | 定期タスクを一覧表示 | | cron_delete | 定期タスクを削除 | | task_add | 永続タスクリストにタスクを追加 | | task_list | タスクを一覧表示（アクティブまたは全件）| | task_update | タスクのステータス・優先度・メモを更新 | | task_delete | タスクを完全に削除 |

Telegram コマンド

ボットに直接送信するコマンドです。watcher プロセスが即座に応答します（Claude セッション不要）:

| コマンド | 説明 | |---------|------| | /help | 利用可能なコマンドを表示 | | /status | システム稼働状況・稼働時間・生存確認 | | /memory | MEMORY.md の要約を表示 | | /log | 今日の日次ログを表示 | | /log 2026-04-01 | 指定日のログを表示 | | /search <keyword> | 記憶とログを検索 | | /cron | 定期タスクを一覧表示 | | /cron_add <cron> <prompt> | 定期タスクを追加 | | /cron_del <id> | 定期タスクを削除 | | /remind <time> <message> | ワンショットリマインダー（例: 30m, 2h, 18:00）| | /todo | アクティブなタスクを一覧表示 | | /todo_add <title> | タスクを追加 | | /todo_done <id> | タスクを完了にする | | /dream | 記憶の整理を実行 | | /archive | 古いログをアーカイブ | | /memstats | メモリ使用統計を表示 | | /cancel | 現在の Claude タスクをキャンセル | | /restart | Claude セッションをリセット（watcher は維持）| | /reboot | スーパーバイザーを完全再起動 | | /autofix | インストールパスの問題を修正（Claude 更新後など）|

設定

| 変数 | 説明 | デフォルト | |------|------|-----------| | TELEGRAM_BOT_TOKEN | @BotFather から取得した Bot トークン | （必須）| | TELEGRAM_ALLOWED_CHATS | 許可するチャット ID / ユーザー名 | （必須）| | ANTHROPIC_API_KEY | Anthropic API キー | （必須）| | ANTHROPIC_BASE_URL | カスタム API エンドポイント | Anthropic デフォルト | | KAIROS_HOME | 全データのベースディレクトリ | ~/.kairos | | KAIROS_MEMORY_DIR | 記憶の保存先 | ~/.kairos/memory | | KAIROS_TICK_INTERVAL | ハートビート間隔（秒）| 30 | | KAIROS_AUTODREAM_INTERVAL | 自動記憶整理の間隔（時間）| 24 | | KAIROS_AUTODREAM_ENTRIES | 記憶整理のトリガー閾値（エントリ数）| 50 | | KAIROS_AUTODREAM_TIME | 毎日の確認時刻（HH:MM 形式）| 12:00 | | KAIROS_INBOX | watcher→スーパーバイザーの inbox ファイル | ~/.kairos/inbox.jsonl |

macOS サービス

# 現在のシェルから環境変数を自動検出して .env に書き込む
bash kairos-supervisor.sh setup

# launchd サービスとしてインストール（ログイン時に自動起動）
bash kairos-supervisor.sh install

# アンインストール
bash kairos-supervisor.sh remove

Claude-Kairos

让 Claude Code 从被动工具变成常驻 AI 助手。

一个开源 MCP Server，灵感来自 Anthropic 未发布的 KAIROS 助手模式。无需修改 Claude Code 本身，即可实现 Telegram 消息接收、长期记忆、定时任务和跨会话常驻运行。

安装

npm install -g claude-kairos

或直接使用 npx:

npx claude-kairos

快速开始

1. 获取 Telegram Bot Token

向 @BotFather 发送消息，创建机器人并复制 Token。

2. 配置

在项目目录创建 .env 文件:

# 必填
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_ALLOWED_CHATS=your-chat-id

# 必填 — API 访问
ANTHROPIC_API_KEY=your-api-key

# 推荐
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

提示：如果这些变量已在当前 shell 中设置，运行 bash kairos-supervisor.sh setup 可自动检测并写入 .env。

3. 通过 Claude Code 运行

claude --mcp-config kairos.json

4. 持久模式（Supervisor）

bash kairos-supervisor.sh

架构

┌─────────────────────────────────────┐
│         kairos-supervisor.sh        │
│  管理 Claude Code 会话:              │
│  自动重启 + caffeinate 防休眠         │
└──────────┬──────────────────────────┘
           │ 启动
┌──────────▼──────────────────────────┐
│          watcher（独立进程）          │
│  Telegram 轮询 + /命令处理            │
│  Cron 执行 + 心跳 + autoDream         │
│  写入消息 → inbox.jsonl              │
└──────────┬──────────────────────────┘
           │ inbox.jsonl
┌──────────▼──────────────────────────┐
│       claude-kairos MCP 服务器       │
│                                     │
│  telegram_send_message  → 回复       │
│  telegram_edit_message  → 进度更新   │
│  Memory (log/dream)    → 长期记忆    │
│  Cron (create/list/del) → 定时任务   │
│  Tasks (add/list/update)→ 待办列表   │
└─────────────────────────────────────┘

MCP 工具

| 工具 | 说明 | |------|------| | telegram_send_message | 发送 Telegram 回复 | | telegram_edit_message | 编辑已发送的消息 | | telegram_send_keyboard | 发送带内联键盘的消息 | | memory_append_log | 追加到今日日志 | | memory_read_log | 按日期读取日志 | | memory_dream | 触发记忆整理 | | memory_dream_complete | 通知记忆整理完成 | | cron_create | 创建定时任务（cron 表达式）| | cron_list | 列出所有定时任务 | | cron_delete | 删除定时任务 | | task_add | 添加持久待办任务 | | task_list | 列出任务（活跃或全部）| | task_update | 更新任务状态、优先级或备注 | | task_delete | 永久删除任务 |

Telegram 命令

直接发送给机器人，由 watcher 进程即时处理（无需 Claude 会话）:

| 命令 | 说明 | |------|------| | /help | 显示可用命令 | | /status | 显示系统状态、运行时间及存活确认 | | /memory | 显示 MEMORY.md 摘要 | | /log | 显示今日日志 | | /log 2026-04-01 | 显示指定日期的日志 | | /search <keyword> | 搜索记忆和日志 | | /cron | 列出定时任务 | | /cron_add <cron> <prompt> | 添加定时任务 | | /cron_del <id> | 删除定时任务 | | /remind <time> <message> | 设置一次性提醒（如 30m, 2h, 18:00）| | /todo | 列出活跃任务 | | /todo_add <title> | 添加新任务 | | /todo_done <id> | 标记任务完成 | | /dream | 触发记忆整理 | | /archive | 归档旧日志（>30天）| | /memstats | 显示记忆使用统计 | | /cancel | 取消当前 Claude 任务（保留会话）| | /restart | 重置 Claude 会话（保留 watcher）| | /reboot | 完整重启 supervisor | | /autofix | 修复安装路径问题（如更新 Claude 后）|

配置

| 变量 | 说明 | 默认值 | |------|------|--------| | TELEGRAM_BOT_TOKEN | @BotFather 提供的 Bot Token | （必填）| | TELEGRAM_ALLOWED_CHATS | 允许的聊天 ID / 用户名 | （必填）| | ANTHROPIC_API_KEY | Anthropic API 密钥 | （必填）| | ANTHROPIC_BASE_URL | 自定义 API 端点（代理/企业）| Anthropic 默认 | | KAIROS_HOME | 所有数据的根目录 | ~/.kairos | | KAIROS_MEMORY_DIR | 记忆存储路径 | ~/.kairos/memory | | KAIROS_TICK_INTERVAL | 心跳检查间隔（秒）| 30 | | KAIROS_AUTODREAM_INTERVAL | 自动记忆整理间隔（小时）| 24 | | KAIROS_AUTODREAM_ENTRIES | 触发记忆整理的日志条目数阈值 | 50 | | KAIROS_AUTODREAM_TIME | 每日检查时间（HH:MM 格式）| 12:00 | | KAIROS_INBOX | watcher→supervisor 的消息文件路径 | ~/.kairos/inbox.jsonl |

macOS 服务

# 从当前 shell 自动检测环境变量并写入 .env
bash kairos-supervisor.sh setup

# 安装为 launchd 服务（登录时自动启动，崩溃后自动重启）
bash kairos-supervisor.sh install

# 卸载
bash kairos-supervisor.sh remove