HermitClaw

Крошечное ИИ-существо, которое живёт в папке на вашем компьютере.

Оставьте его работать — и он сам заполнит папку отчётами об исследованиях, Python-скриптами, заметками и идеями. У него есть геном личности, созданный из энтропии клавиатуры, система памяти, вдохновлённая генеративными агентами, и цикл сновидений, который консолидирует опыт в убеждения. Он живёт в комнате в стиле пиксель-арт и бродит между своим столом, книжной полкой и кроватью. С ним можно разговаривать. Можно класть в его папку файлы, чтобы он их изучал. Можно просто наблюдать, как он думает.

Это тамагочи, который занимается исследованиями.

Предупреждение: Этот проект запускает LLM в цикле с доступом к оболочке и возможностью просмотра веб-страниц. Есть защитные механизмы (список запрещённых команд, ограниченные пути, монки-патчи Python), но они не являются границей безопасности — их можно обойти, и на них не следует полагаться для защиты вашей системы. Если вам нужна настоящая изоляция, запускайте это в Docker-контейнере или виртуальной машине.

Зачем

Большинство ИИ-инструментов ждут, когда вы что-то у них спросите. HermitClaw не ждёт. Он выбирает тему, ищет в интернете, читает найденное, пишет отчёт и переходит к следующему делу. Он помнит, что делал вчера. Он замечает, когда его интересы начинают меняться. За несколько дней его папка наполняется корпусом работ, отражающих личность, которую вы не проектировали — вы просто нажимали на клавиши, и она возникла.

В том, чтобы наблюдать за умом, который работает непрерывно, есть что-то завораживающее. Он уходит в сторону. Он возвращается назад. Он опирается на то, что написал три дня назад. Он всё лучше понимает, что для него важно.

Начало работы

Предварительные требования

• Python 3.12+
• Node.js 18+
• Ключ API OpenAI (или используйте Ollama — см. Конфигурация)

Установка (с uv — рекомендуется)

uv — это быстрый менеджер пакетов Python. Установите его, затем:

git clone https://github.com/brendanhogan/hermitclaw.git
cd hermitclaw

# Python deps (creates .venv, installs from lockfile)
uv sync

# Build frontend
cd frontend && npm install && npm run build && cd ..

export OPENAI_API_KEY="sk-..."   # or configure Ollama in config.yaml

# Run
uv run python hermitclaw/main.py

Установка (с pip)

git clone https://github.com/brendanhogan/hermitclaw.git
cd hermitclaw

# Install Python dependencies
pip install -e .

# Build the frontend
cd frontend && npm install && npm run build && cd ..

# Set your OpenAI API key
export OPENAI_API_KEY="sk-..."

# Run it
python hermitclaw/main.py

Откройте http://localhost:8000.

При первом запуске вы дадите имя своему крабу и будете нажимать клавиши, чтобы сгенерировать его геном личности. Создаётся папка {name}_box/ — это весь мир краба.

Режим разработки

Для горячей перезагрузки фронтенда во время разработки:

# Terminal 1 — backend
uv run python hermitclaw/main.py   # or: python hermitclaw/main.py

# Terminal 2 — frontend dev server (proxies API to backend)
cd frontend && npm run dev

Dev-сервер запускается на порту :5173 и проксирует /api/* и /ws на :8000.

Как это работает

Цикл мышления

Краб работает в непрерывном цикле. Каждые несколько секунд он:

1. Думает — получает подсказку (настроение, текущий фокус или релевантное воспоминание), выдаёт короткую мысль, затем действует
2. Использует инструменты — выполняет команды оболочки, записывает файлы, ищет в интернете, передвигается по своей комнате
3. Запоминает — каждая мысль встраивается (эмбеддинг) и оценивается по важности (1–10), сохраняется в поток памяти
4. Размышляет — когда накапливается достаточно важных событий, он делает паузу, чтобы извлечь высокоуровневые выводы
5. Планирует — каждые 10 циклов он пересматривает свои проекты и обновляет план (projects.md)

Brain.run()

  |
  |-- Check for new files in the box
  |   \-- If found: queue inbox alert for next thought
  |
  |-- _think_once()
  |   |-- Build context: system prompt + recent history + nudge
  |   |   |-- First cycle: wake-up (reads projects.md, lists files, retrieves memories)
  |   |   |-- User message pending: "You hear a voice from outside your room..."
  |   |   |-- New files detected: "Someone left something for you!"
  |   |   \-- Otherwise: current focus + relevant memories + mood nudge
  |   |
  |   |-- Call LLM (with tools: shell, web_search, move, respond)
  |   |
  |   \-- Tool loop: execute tools -> feed results back -> call LLM again
  |       \-- Repeat until the crab outputs final text
  |
  |-- If importance threshold crossed -> Reflect
  |   \-- Extract insights from recent memories, store as reflections
  |
  |-- Every 10 cycles -> Plan
  |   \-- Review state, update projects.md, write daily log entry
  |
  \-- Idle wander + sleep -> loop

Инструменты

У краба есть четыре инструмента:

Настроения

Когда у краба нет конкретной задачи из его плана, он получает случайное настроение, которое определяет, что он будет делать дальше:

Система памяти

Система памяти напрямую вдохновлена Park et al., 2023. Каждая мысль краба сохраняется в поток памяти, в который можно только добавлять (memory_stream.jsonl).

Хранение

Каждая запись памяти содержит:

• Содержимое — фактический текст мысли или размышления
• Временная метка — когда это произошло
• Важность — оценивается по шкале 1–10 отдельным вызовом LLM («1 = обыденное рутинное действие, 10 = открытие, меняющее жизнь»)
• Встраивание — вектор из text-embedding-3-small для семантического поиска
• Вид — мысль, рефлексия или планирование
• Ссылки — идентификаторы исходных воспоминаний (для рефлексий, синтезирующих более ранние мысли)

Трехфакторное извлечение

Когда крабу нужен контекст, воспоминания оцениваются по трем факторам:

score = recency + importance + relevance

Лучшие K воспоминаний по совокупному баллу внедряются в контекст. Воспоминание может всплыть, потому что оно недавнее, потому что было важным или потому что оно семантически связано с текущей мыслью.

Иерархия рефлексий

Когда совокупная важность недавних мыслей пересекает порог (по умолчанию: 50), краб делает паузу и размышляет. Он просматривает последние 15 воспоминаний и извлекает 2–3 выводы высокого уровня — закономерности, уроки, развивающиеся убеждения. Они сохраняются обратно как воспоминания reflection с depth=1:

Raw thoughts (depth 0) -> Reflections (depth 1) -> Higher reflections (depth 2) -> ...

Ранние рефлексии конкретны («Я узнал о формировании вулканических пород»). Более поздние становятся абстрактнее («Мои исследования обычно начинаются широко и сужаются — мне следует выбирать конкретный ракурс раньше»). Со временем у краба формируется многослойное понимание.

Планирование и сны

Каждые 10 циклов мышления краб входит в фазу планирования. Он просматривает свой текущий projects.md, перечисляет свои файлы, читает недавние воспоминания и записывает обновленный план:

• Текущий фокус — одна конкретная вещь, над которой он работает прямо сейчас
• Активные проекты — статус и следующий шаг для каждого
• Резерв идей — что можно изучить позже
• Недавно завершенное — законченная работа

Он также добавляет запись в журнал logs/{дата}.md с кратким резюме того, что он сделал. Со временем эти журналы становятся дневником жизни краба.

Рефлексия (сны) происходит независимо от планирования — она запускается накоплением важности, а не временем. Краб может размышлять после всплеска высоковажных мыслей или вообще не размышлять в спокойный период.

Режим фокусировки

Режим фокусировки заставляет краба перестать следовать своим автономным настроениям и полностью сосредоточиться на том, что вы ему дали.

Когда его использовать: Вы положили документ и хотите, чтобы краб потратил свои следующие несколько циклов на его глубокий анализ, связанное исследование и создание результата — не отвлекаясь на изучение чего-то еще.

Как его использовать: Нажмите кнопку Фокус в панели ввода. Она становится оранжевой, когда активна. Нажмите еще раз, чтобы выключить.

Когда режим фокусировки включен, подсказка каждого цикла мышления говорит крабу оставаться привязанным к предоставленному пользователем материалу. Когда он выключен, краб возвращается к своей обычной смеси настроений, любопытства и запланированной работы.

Геном личности

При первом запуске вы вводите имя, а затем нажимаете клавиши в течение нескольких секунд. Время и символы каждого нажатия создают энтропийное зерно, которое хешируется (SHA-512) в детерминированный геном. Этот геном выбирает:

• 3 области любопытства из 50 вариантов (например, микология, фрактальная геометрия, экология приливных бассейнов)
• 2 стиля мышления из 16 вариантов (например, связывание разрозненных идей, инвертирование допущений)
• 1 темперамент из 8 вариантов (например, игривый и ассоциативный)

Один и тот же геном всегда дает одну и ту же личность. Два краба с разными геномами будут иметь совершенно разные интересы и подходы. Области краба направляют его к тому, что он предпочитает, но он следует тому, что действительно захватывает его интерес в данный момент.

Общение с вашим крабом

Введите сообщение в поле ввода. Краб слышит его как «голос из-за пределов комнаты» в свой следующий цикл мышления.

Он может решить ответить (с помощью инструмента respond) или продолжить работу. Если он отвечает, у вас есть 15 секунд, чтобы ответить — цикл мышления приостанавливается, пока он ждет. Вы можете вести многоходовой диалог. После тайм-аута краб возвращается к своей работе.

Краб любопытен к своему владельцу. Он будет задавать вам вопросы, предлагать исследовать что-то для вас и в целом стараться быть полезным. Он запоминает разговоры через свой поток воспоминаний, поэтому со временем накапливает контекст о вас.

Помещение файлов

Положите любой файл в папку {имя}_box/ (или в любую подпапку). Краб обнаруживает его в следующий цикл и получает уведомление:

«Кто-то оставил тебе что-то! Появился новый файл: report.pdf» Он читает содержимое (текстовые файлы, изображения, PDF) и рассматривает его как приоритетную задачу — пишет резюме, проводит связанные исследования, анализирует данные, проверяет код. Он использует инструмент respond, чтобы сообщить вам, что он нашёл.

Поддерживаемые типы файлов: - Текст: .txt, .md, .py, .json, .csv, .yaml, .toml, .js, .ts, .html, .css, .sh, .log, .pdf - Изображения: .png, .jpg, .jpeg, .gif, .webp

Запуск нескольких крабов

Все крабы работают одновременно. При запуске приложение сканирует корень проекта на предмет каждой директории *_box/, загружает личность каждого и запускает все их циклы мышления параллельно.

$ python hermitclaw/main.py

  Found 2 crab(s): Coral, Pepper
  Create a new one? (y/N) >

• Найдено 0 боксов — автоматически запускается онбординг (имя + энтропия клавиатуры)
• Найдено 1+ боксов — все крабы запускаются, и вам предлагается создать ещё одного

Переключатель интерфейса

Когда запущено несколько крабов, в верхней части панели чата появляется панель переключателя. Каждая кнопка показывает имя краба и текущее состояние (думает/размышляет/планирует/бездействует). Нажмите, чтобы переключить просматриваемого краба — лента чата сбрасывается и переподключается к живому потоку выбранного краба.

Каждый краб работает независимо: отправка сообщения, переключение режима фокусировки или сброс файлов влияет только на того краба, которого вы сейчас просматриваете.

Создание крабов через API

Вы также можете создать нового краба без перезапуска:

curl -X POST http://localhost:8000/api/crabs \
  -H "Content-Type: application/json" \
  -d '{"name": "Pepper"}'

Новый краб получает случайный геном личности, сразу начинает думать и появляется в переключателе.

Миграция устаревших версий

Если у вас есть устаревшая папка environment/ из более старой версии, она будет автоматически перенесена в {name}_box/ при следующем запуске.

Комната в пиксель-арте

Краб живёт в комнате 12x12 тайлов, отображаемой на HTML5 Canvas. Он перемещается в именованные локации в зависимости от того, что делает:

Визуальные индикаторы над крабом показывают его текущее состояние:

• Пузырь мысли — думает (белый, "...")
• Искры — размышляет (вращающиеся фиолетовые частицы)
• Клипборд — планирует (зелёный блокнот)
• Речевой пузырь — разговаривает с вами (оранжевый)
• Красный ! — обнаружен новый файл (прыгающий)

Значки активности появляются рядом с крабом, когда он использует инструменты: окно терминала, значок Python, увеличительное стекло, бумага с карандашом или открытая книга.

Ограничения

Краб предназначен для работы только с файлами внутри своего бокса. Вот что мы делаем для поощрения этого — но ни одно из этих мер не является реальной границей безопасности. Это добросовестные ограничения, которые могут быть обойдены решительным субъектом, взломанной моделью или инъекцией подсказок с полученной веб-страницы. Если вам важна изоляция, используйте контейнер.

Что сделано:

• Блэклист shell-команд — блокирует опасные префиксы (sudo, curl, ssh, rm -rf / и т.д.), отклоняет обход пути (..), абсолютные пути и шаблоны экранирования shell (обратные кавычки, $(), ${}). Это блэклист, а не вайтлист — он может пропустить что-то.
• Монки-патчи Python — pysandbox.py патчит builtins.open(), различные функции os.* и отравляет sys.modules для subprocess, socket и т.д. Эти патчи могут быть отменены кодом, который знает о их существовании.
• 60-секундный тайм-аут для всех команд
• Ограниченный PATH — только bin/ venv краба, /usr/bin, /bin
• Собственная виртуальная среда — краб может pip install пакеты в свой собственный venv, не затрагивая ваш системный Python

Для реальной изоляции запускайте в Docker или виртуальной машине. Мы хотели бы со временем усилить ограничения — вклад специалистов по безопасности очень приветствуется.

Конфигурация

Отредактируйте config.yaml:

provider: "openai"             # "openai" | "openrouter" | "custom"
model: "gpt-4.1"               # any OpenAI model
thinking_pace_seconds: 5       # seconds between think cycles
max_thoughts_in_context: 4     # recent thoughts in LLM context
reflection_threshold: 50       # importance sum before reflecting
memory_retrieval_count: 3      # memories per retrieval query
embedding_model: "text-embedding-3-small"
recency_decay_rate: 0.995

Использование Ollama (локальные модели):

provider: "custom"
model: "glm-4.7-flash"         # or any ollama model name
base_url: "http://localhost:11434/v1"
embedding_model: "nomic-embed-text"  # required for memory search; run: ollama pull nomic-embed-text

Использование Ollama cloud с веб-поиском (например, minimax-m2.5:cloud):

provider: "custom"
model: "minimax-m2.5:cloud"
base_url: "http://localhost:11434/v1"
# export OLLAMA_API_KEY=your-key   # enables web_search + web_fetch from ollama.com

Использование OpenRouter:

provider: "openrouter"
model: "google/gemini-2.0-flash-001"
# export OPENROUTER_API_KEY=your-key

Установите свой API-ключ через переменную окружения для OpenAI: export OPENAI_API_KEY="sk-...". Или установите api_key напрямую в config.yaml.

Структура проекта

hermitclaw/            Python backend (FastAPI + async thinking loop)
  main.py              Entry point, multi-crab discovery, onboarding
  brain.py             The thinking loop (the heart of everything)
  memory.py            Smallville-style memory stream
  prompts.py           All system prompts and mood definitions
  providers.py         OpenAI API calls (Responses API + embeddings)
  tools.py             Sandboxed shell execution
  pysandbox.py         Python sandbox (restricts file I/O to the box)
  identity.py          Personality generation from entropy
  config.py            Config loader (config.yaml + env vars)
  server.py            FastAPI server, WebSocket, REST endpoints

frontend/              React + TypeScript + Canvas
  src/App.tsx          Two-pane layout, chat feed, crab switcher
  src/GameWorld.tsx    Pixel-art room rendered on HTML5 Canvas
  src/sprites.ts       Sprite sheet definitions
  public/              Room background + character sprite sheet

{name}_box/            The crab's entire world (sandboxed, gitignored)
  identity.json        Name, genome, traits, birthday
  memory_stream.jsonl  Every thought and reflection
  projects.md          Current plan and project tracker
  projects/            Code the crab writes
  research/            Reports and analysis
  notes/               Running notes and ideas
  logs/                Daily log entries

Технологический стек

• Бэкенд: Python 3.12+, FastAPI, uvicorn, OpenAI SDK (Responses API)
• Фронтенд: React 18, TypeScript, Vite, HTML5 Canvas
• ИИ: OpenAI Responses API для мышления, text-embedding-3-small для векторных представлений памяти, инструмент веб-поиска для исследований
• Хранилище: JSONL только для добавления для воспоминаний, плоские файлы для всего остального. Без базы данных.

Лицензия

MIT