Turritopsis

Общий слой передачи для долгосрочных проектов.

1 человек + 4 агента. 71 день. 500K строк активного кода.

Агенты приходят и уходят. Проекты не должны забывать.

Ваш агент-кодер может читать код. Turritopsis сообщает ему:

• что верно сейчас;

• почему проект стал таким;

• где остановилась текущая работа;

• что уже не сработало;

• какие границы нельзя нарушать;

• и где продолжить.

list_stages()
search_stages("why is release frozen?")
get_stage("project.handoff")

Turritopsis — это не приватная память агента, не индексация кода, не продолжение сессии, не вики проекта и не чанкованный RAG. Это небольшое, дружелюбное к Git адресное пространство для знаний о проекте, которые код и Git не могут надёжно восстановить.

Один MCP, много агентов: проверенный на практике рабочий процесс

Turritopsis вырос из реальной долгосрочной системы, где один человек работал с четырьмя разными агентами в чате, кодинге, локальном и VPS-пространствах. У них не было общей приватной памяти или непрерывной сессии. Их объединяла одна карта проекта через один MCP.

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

Окна кодинга были для выполнения. Чистый агент-кодер мог прийти, вызвать list_stages, search_stages и get_stage и взять работу на себя за секунды. Ему не нужна была собственная система памяти агента, воспроизведение старых разговоров или заново написанный документ передачи. Чистые окна оставались чистыми, не теряя инженерного прогресса.

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

Человек корректировал направление, а не учёт. Веб-интерфейс предоставлял карту проекта, редактор Stage, живой предпросмотр Markdown, конфликты ревизий, предложения и историю. Человек исправлял приоритеты, границы и смысл проекта, пока агенты поддерживали детали реализации на основе отслеживаемых доказательств.

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

Related MCP server: handoff-mcp

Установка и запуск

python -m pip install -e .
turritopsis init --yes --name "My Project" --description "What this project does"
turritopsis init --yes --name "My Project" --modules "API, Worker, Web"
turritopsis add anatomy anatomy.components "Current components"
turritopsis serve --stdio

HTTP использует потоковый MCP и по умолчанию слушает только loopback:

turritopsis serve                 # 127.0.0.1:3013
turritopsis serve --port 4013
turritopsis serve --data /project/.turritopsis/stages.json

Откройте http://127.0.0.1:3013/ для человеческой карты проекта. Тот же процесс обслуживает:

• / — карта проекта, поиск, чтение/редактирование Stage, передача, Authority, предложения и история;

• /mcp — четыре инструмента MCP;

• /api/... — локальный API интерфейса, основанный на той же реализации Turritopsis, Store, поиска и обновления.

turritopsis ui — это явный алиас, когда нужен только человеческий интерфейс. После установки не требуется Node.js, сборка фронтенда, LLM или API-ключ.

Удалённый доступ явный (--host 0.0.0.0) и должен быть размещён за слоем аутентификации.

Навык онбординга агента

Репозиторий включает совместимый с Codex навык в skills/turritopsis-onboarding/. Скопируйте этот каталог в папку навыков Codex, затем вызывайте $turritopsis-onboarding, когда агент инициализируется, присоединяется или возобновляет проект. Навык учит установленного агента выбирать универсальные обязанности Stage и специфичные для проекта наборы, а не копировать имена Current из одного проекта.

Модель знаний

Current маршрутизирует устойчивое семейство вопросов проекта. Имена Current специфичны для проекта; anatomy, flow, bounds, manual и genesis полезны для некоторых долгосрочных систем агентов, но не являются универсальными значениями по умолчанию для каждого SDK, базы данных, мобильного клиента, ML-пайплайна или устройства.

Stage — это одна полная именованная область знаний, а не произвольный фрагмент текста. Markdown Stage может содержать метаданные на английском или китайском:

# Current work and handoff

Type: handoff
Purpose: Tell a new contributor where work currently stands.
Search hints: handoff blocker next step release current work
Summary: Release is frozen pending hardware regression.
Verified: 2026-08-24 by agent
Status: current
Authority: current work, next action
Freshness: volatile

## Update triggers

- The blocker or next action changes.

Держите текущую правду, исторические объяснения и детерминированные сгенерированные факты в отдельных Stage. Status: historical никогда молча не выдаёт себя за текущий авторитет. Сгенерированный Stage должен сообщать, что ручные правки будут перезаписаны.

Четыре инструмента MCP

• list_stages(current?) отображает Current или компактные метаданные Stage, но никогда тела.

• search_stages(...) обеспечивает объяснимую взвешенную маршрутизацию или точные совпадения по строкам/контексту.

• get_stage(stage_id) возвращает один полный Stage и его ревизию по хэшу тела.

• update_stage(...) поддерживает замену/добавление, опциональный expected_revision, журналы действий, скользящие резервные копии и ответы на конфликты.

Веса поиска сохраняют проверенный порядок маршрутизации: id Stage, подсказки поиска, заголовок, authority, сводка, назначение, статус/верификация, Current, затем заголовки/тело. semantic — это объяснимый маршрутизатор по структурированным полям; он не претендует на эмбеддинги.

Все чтения перезагружают stages.json. Записи берут файловую блокировку, сравнивают только ревизию целевого Stage, записывают через временный файл с fsync, атомарно заменяют канонический файл, добавляют changelog.jsonl и сохраняют скользящие резервные копии.

Структура и обслуживание

.turritopsis/
├── stages.json
├── config.json
├── scan-evidence.json
├── scan-anomalies.json
├── scan-run.json
├── changelog.jsonl
├── maintenance.jsonl
├── backups/
└── proposals/

Обычный turritopsis init запрашивает основные модули и создаёт начальные адреса Current/Stage. --modules даёт тот же ответ без интерактивного режима.

Холодный старт намеренно разделён на локальное детерминированное сканирование и классификацию установленным агентом:

turritopsis scan
# The current Codex/Claude Agent reads scan-run.json and scan-evidence.json,
# chooses Stage types and a project suite, then writes skeleton.json.
turritopsis apply-skeleton skeleton.json

turritopsis init --scan — это алиас совместимости для первой команды. Он читает ограниченное дерево проекта, README-файлы, манифесты, CI/конфигурационные документы и другие нечувствительные текстовые материалы, затем записывает scan-evidence.json, scan-anomalies.json и scan-run.json. Он не использует модель, сеть, провайдера или API-ключ. Повторный запуск scan возобновляется с сохранённых доказательств, если только не указан --refresh, поэтому прерванный агент никогда не платит за сканирование снова.

Установленный агент — а не второй внешний LLM — классифицирует эти доказательства. apply-skeleton проверяет схему, происхождение, идентификаторы Current и Stage, пути доказательств, тип/свежесть Stage, пустые обязанности, дублирующий Authority, мусорные ящики и фрагментацию перед атомарным созданием stages.json. Он никогда не перезаписывает существующую базу знаний; последующие записи должны использовать защищённый ревизией update_stage. Канонические знания по-прежнему начинаются как явные заглушки и должны заполняться проверенными доказательствами.

Опциональное обслуживание на основе LLM использует .turritopsis/config.json; сканирование и применение скелета никогда его не читают:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "api_key_env": "OPENAI_API_KEY"
  }
}

Поддерживаемые провайдеры: openai, anthropic и openai-compatible. Совместимые провайдеры требуют base_url. Настройки можно переопределить с помощью TURRITOPSIS_LLM_PROVIDER, TURRITOPSIS_LLM_MODEL, TURRITOPSIS_LLM_API_KEY_ENV, TURRITOPSIS_LLM_BASE_URL, TURRITOPSIS_LLM_TIMEOUT и TURRITOPSIS_LLM_MAX_TOKENS. Значения API-ключей читаются только из настроенной переменной окружения и никогда не записываются в файлы проекта.

turritopsis maintain проверяет недавние изменения Git, отсутствующие указанные пути и возраст верификации. Для каждого затронутого курируемого Stage он отправляет текущее тело и ограниченные доказательства проекта настроенному LLM, проверяет возвращённый JSON и указанные идентификаторы доказательств, обновляет Verified, затем записывает через обычный путь ревизии Stage, блокировки, резервного копирования, атомарной замены и журнала изменений. Если доказательств недостаточно, модель должна вернуть no_change.

turritopsis maintain
turritopsis maintain --model CHEAP_MODEL
turritopsis maintain --proposal-only
turritopsis maintain --schedule "0 3 * * *" --model CHEAP_MODEL
turritopsis maintain --show-schedule
turritopsis maintain --unschedule
turritopsis survey
turritopsis anomalies
turritopsis brief
turritopsis export --format md
turritopsis export --format json --output project-knowledge.json

--proposal-only сохраняет отчёт о расхождениях с приоритетом ревью, когда это нужно; --apply по-прежнему применяет явно проверенное предложение. Это опциональные рабочие процессы, а не ограничения для обычного обслуживания на основе доказательств.

--schedule устанавливает или заменяет одну запись с привязкой к пути в crontab текущего пользователя POSIX. Пример выше запускается каждый день в 03:00 в локальном часовом поясе хоста cron, записывает вывод в .turritopsis/maintenance-cron.log и идемпотентен при повторении. Он никогда не записывает API-ключ в crontab: api_key_env, указанный в config.json, должен быть уже доступен в окружении cron. --show-schedule и --unschedule проверяют или удаляют только отмеченный блок Turritopsis для этого проекта. На хостах без crontab вызывайте ту же команду turritopsis maintain --model CHEAP_MODEL из CI или нативного планировщика.

Единственное исключение для автоматической записи — это явно сгенерированный Stage с детерминированной конфигурацией генератора:

{
  "id": "anatomy.revision",
  "title": "Current Git revision",
  "status": "generated",
  "generator": {"type": "git_revision"},
  "body": ""
}

Встроенные детерминированные типы: git_revision, file_hash и path_exists. Их вывод явно помечен как автоматически сгенерированный и не использует LLM.

Ядро list/search/get/update, веб-интерфейс, обслуживание MCP, сканирование и применение скелета не требуют LLM и API-ключа. Только опциональное автоматическое курируемое обслуживание — требует.

Лицензия

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

Разработка

python -m pip install -e ".[test]"
pytest