Waku Agent: локальный ИИ-агент на 95 строках кода

Waku Agent - это локальный ИИ-ассистент, весь основной цикл которого умещается в 95 строк Python. Работает на твоём ноуте, память лежит в одном SQLite-файле, управляется из терминала, браузера или Telegram-бота. Опенсорс, MIT, репозиторий: github.com/ShenSeanChen/waku-agent - на момент публикации около 900 звёзд.

Что такое Waku Agent

Waku - учебный, но полностью рабочий агент от Sean Chen. Идея простая: собрать всё, из чего реально состоит агент (harness, loop, memory, eval), в такой маленький и читаемый код, чтобы за вечер можно было открыть и разобрать до последней функции. Ты не пользователь коробки, а владелец кода.

Всё запускается локально. Файлы, пароли и переписка с диска никуда не уезжают. Из ключей нужен один - от нейросети, которую ты подключаешь: Anthropic, OpenAI, Gemini, DeepSeek, Kimi, GLM или OpenRouter (один ключ на сотни моделей).

Что умеет из коробки

• Ходить в интернет (через Tavily API или бесплатный DuckDuckGo) и опираться на свежие данные.
• Планировать встречи, добавлять и читать события в календаре (локальный ICS + опционально Apple Calendar и Google Calendar).
• Читать почту (Apple Mail на macOS) и собирать утренний брифинг из календаря, писем и памяти.
• Держать заметки и "личные факты" - предпочтения, дни рождения, привычки.
• Общаться голосом с wake word "waku waku" - слушает микрофон, отзывается на фразу.
• Подключать сторонние MCP-сервера как инструменты - файловая система, БД, что угодно.
• Делегировать код-задачи агенту pi в headless-режиме.

Управление - из терминала, локального дашборда localhost:7777 или Telegram-бота, которого ты заводишь у @BotFather.

Как устроен: четыре столпа

Waku специально сделан прозрачным. Каждый файл маппится на одну идею:

1. Harness (гейтвей) - cli, telegram, voice, dashboard. Один вход, один процесс.
2. Loop - 95 строк на Python: reason -> act -> observe -> repeat. Никакого LangGraph, никаких скрытых слоёв. Два стоппера: модель сама решила не звать инструменты или сработал max_iterations. Крутиться вечно не будет.
3. Memory - SQLite-файл .waku/state.db. Три типа памяти: semantic (факты), episodic (события и чаты), procedural (навыки в markdown). Плюс retrieval gate: дешёвая модель сначала решает "нужна ли этому сообщению память вообще?", чтобы не дёргать базу на каждый "привет".
4. Eval / LLM-Ops - два набора тестов: детерминированные (сработал ли правильный tool - 0 или 1) и LLM-as-judge (был ли ответ полезным - процент). Их можно гонять как release gate: make gate, оба должны позеленеть, иначе версия не выезжает.

Всё это видно вживую: открой дашборд, задай задачу и смотри, как гейт решает, как крутится цикл, какие инструменты стреляют, сколько токенов и денег ушло. Расходы пишутся в append-only ledger .waku/usage.jsonl, демо-ресет их не стирает.

Как поднять за вечер

Waku поставляется готовым пакетом. Простой путь:

pip install waku-agent
waku            # чат в терминале
waku dashboard  # или дашборд -> localhost:7777

При первом запуске сам скажет, какой ключ положить в .env. Если хочешь читать код и менять под себя - клонируй репо и работай через uv.

Если возиться с pip, venv и ключами не хочется, отдай это Claude Code. Открой пустую папку, запусти claude и вставь запрос:

Склонируй github.com/ShenSeanChen/waku-agent, изучи README.
Подними проект через uv (uv venv, uv pip install -e ., .env из .env.example).
Помоги выбрать провайдера - спроси, какой ключ у меня есть
(Anthropic / OpenAI / OpenRouter), и подскажи, куда его вписать.
Заведи Telegram-бота через @BotFather: попроси у меня токен и мой
Telegram user id, положи их в .env как TELEGRAM_BOT_TOKEN и
TELEGRAM_ALLOWED_USER.
Запусти "uv run waku dashboard" и покажи ссылку на localhost:7777.
Подскажи, что мне написать в чат, чтобы убедиться, что память
сохраняется между сессиями.

Claude пройдёт установку по README сам, будет запрашивать ключи по мере надобности. Если ты в Claude Code впервые - начни с гайда для новичков.

Управление из Telegram

Ставишь pip install -e '.[telegram]', пишешь @BotFather, кладёшь токен в .env, запускаешь make telegram - и агент отвечает тебе с телефона. Работает по long-polling, публичный URL и вебхуки не нужны. Обязательно выстави TELEGRAM_ALLOWED_USER=<твой id> - иначе бот открыт для всех, кто его найдёт.

Память, которую можно открыть

Киллер-фича Waku - память, которая живёт как обычный файл. SQLite-таблицы видно во вкладке Database на дашборде, а рядом Waku регенерирует человекочитаемый .waku/MEMORY.md после каждого хода. Хочешь исправить факт - открываешь и правишь. Хочешь забыть - говоришь агенту "забудь X", он вызывает manage_memory и удаляет.

Отдельно есть SOUL.md - файл с твоими устойчивыми предпочтениями (работаю с утра, не звони мне в четверг, зови меня Миша). И .waku/skills/ - папка навыков, которые агент сам предлагает сохранить, когда ты его чему-то научил.

Кому подойдёт, а кому нет

Подойдёт, если хочешь понять, из чего собран агент, и держать свою уменьшенную копию Claude Desktop / ChatGPT под контролем. Хорошая точка входа, если планируешь строить собственных агентов и не хочешь тащить тяжёлый фреймворк.

Не подойдёт, если ждёшь готовый продукт с UI, подпиской и техподдержкой. Waku - это blueprint, а не сервис. Тебе всё равно нужен ноут, API-ключ и полчаса терпения на первый запуск.

Частые вопросы

Waku Agent бесплатный?

Сам код - MIT, бесплатный. Платишь только за токены нейросети, которую подключишь (или используешь бесплатные лимиты DeepSeek / OpenRouter). Отдельная инфраструктура не нужна, агент крутится на твоём ноуте.

Куда уходят мои данные?

Никуда. Память в локальном SQLite .waku/state.db, SOUL.md и MEMORY.md - тоже локально. Наружу уходят только запросы к API той нейросети, которую ты сам выбрал.

Чем это отличается от Hermes Agent?

Одна архитектура, но Waku в разы меньше по коду и заточен на "читаемость за вечер". Hermes богаче фичами и подойдёт, если нужен готовый ассистент без вникания в устройство. Подробный разбор Hermes - в отдельном материале.

Нужно уметь программировать?

Для запуска - нет. Клонирование, зависимости и .env - работа Claude Code, ты только подкидываешь ключи. Для того, чтобы менять поведение (дописать инструмент, поправить loop) - базовое знание Python сильно облегчит жизнь.

Работает на Windows?

Основной набор - да (pip install и терминал). Часть завязана на macOS: голосовой режим через say и интеграция с Apple Calendar / Mail. Всё остальное (Telegram, Google Calendar, MCP, evals) кросс-платформенное.

Коротко

Waku Agent - самый маленький из "настоящих" опенсорсных агентов сегодня. 95 строк на loop, SQLite для памяти, дашборд, чтобы видеть каждую мысль, Telegram, чтобы дёргать с телефона. Запускается локально, ключ нужен один, ставится за вечер одним запросом в Claude Code. Если хочешь понять, как устроены агенты, а не только пользоваться ими - начинать имеет смысл именно с этого репо.

Что дальше

Если хочешь собрать такую систему у себя - у меня есть курс по вайбкодингу и работе с нейросетями в клубе Мандарин Лаб: mandarinedu.ru. Первые уроки открыты бесплатно.

Если нужно внедрить ИИ в бизнес - процессы, агентов, автоматизацию под вашу задачу - пишите мне напрямую: t.me/Philigranchik. Разберу задачу и скажу, что реально автоматизируется, а что нет.