Turritopsis

장기 실행 프로젝트를 위한 공유 핸드오프 레이어.

인간 1명 + 에이전트 4개. 71일. 활성 코드 50만 줄.

에이전트는 오고 간다. 프로젝트는 잊지 말아야 한다.

코딩 에이전트는 코드를 읽을 수 있다. 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를 호출하고 몇 초 만에 인계받을 수 있었다. 자체 에이전트 메모리 시스템, 이전 대화 재생, 또는 새로 작성된 핸드오프 문서가 필요하지 않았다. 깨끗한 창은 엔지니어링 진행 상황을 잃지 않고 깨끗하게 유지되었다.

더 저렴한 모델이 일상적인 유지보수를 처리했다. 최근 diff와 오래된 검증 날짜를 검사하고, 증거 기반 지식을 새로 고치고, 불확실한 사실은 해결되지 않은 채로 둘 수 있었다. 비싼 모델은 그럴 만한 결정에만 사용되었다.

인간은 장부 정리가 아닌 방향을 편집했다. Web UI는 프로젝트 맵, 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는 streamable MCP를 사용하며 기본적으로 루프백에서만 수신한다:

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/... — 동일한 Turritopsis, Store, 검색, 업데이트 구현을 기반으로 하는 로컬 UI API.

turritopsis ui는 인간용 표면만 원할 때의 명시적 별칭이다. 설치 후 Node 런타임, 프론트엔드 빌드, LLM, API 키가 필요 없다.

원격 노출은 명시적이며(--host 0.0.0.0) 인증 레이어 뒤에 배치해야 한다.

에이전트 온보딩 스킬

저장소에는 skills/turritopsis-onboarding/에 Codex 호환 Skill이 포함되어 있다. 해당 디렉터리를 Codex 스킬 폴더에 복사한 다음, 에이전트가 프로젝트를 초기화하거나, 합류하거나, 재개할 때 $turritopsis-onboarding을 호출한다. Skill은 설치된 에이전트에게 한 프로젝트의 Current 이름을 복사하는 대신 보편적인 Stage 책임과 프로젝트별 스위트를 선택하는 방법을 가르친다.

지식 모델

Current는 지속적인 프로젝트 질문의 계열을 라우팅한다. Current 이름은 프로젝트별로 다르다. anatomy, flow, bounds, manual, genesis는 일부 장기 실행 에이전트 시스템에 유용하지만 모든 SDK, 데이터베이스, 모바일 클라이언트, ML 파이프라인, 또는 장치에 대한 보편적 기본값은 아니다.

Stage는 임의의 텍스트 청크가 아닌 하나의 완전한 이름 있는 지식 영역이다. Stage Markdown에는 영어 또는 중국어 메타데이터가 포함될 수 있다:

# 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(...)는 replace/append, 선택적 expected_revision, 행위자 로그, 롤링 백업, 충돌 응답을 지원한다.

검색 가중치는 검증된 라이브 라우팅 순서를 유지한다: Stage id, 검색 힌트, 제목, 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 키를 사용하지 않는다. --refresh가 명시적이지 않으면 scan을 다시 실행하면 저장된 증거에서 재개되므로 중단된 에이전트는 스캔 비용을 다시 지불할 필요가 없다.

설치된 에이전트(두 번째 외부 LLM이 아님)가 해당 증거를 분류한다. apply-skeleton은 stages.json을 원자적으로 생성하기 전에 스키마, 출처, Current 및 Stage id, 증거 경로, Stage 유형/신선도, 빈 책임, 중복 Authority, 쓰레기 서랍, 조각화를 검증한다. 기존 지식 베이스를 절대 덮어쓰지 않으며, 이후 쓰기는 개정 보호된 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과 인용된 증거 id를 검증하고, 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은 현재 POSIX 사용자의 crontab에 경로 범위 항목 하나를 설치하거나 교체한다. 위 예제는 cron 호스트의 로컬 시간대에서 매일 03:00에 실행되고, 출력을 .turritopsis/maintenance-cron.log에 쓰며, 반복 시 멱등적이다. crontab에 API 키를 절대 기록하지 않는다: config.json에 지정된 api_key_env는 cron 환경에서 이미 사용 가능해야 한다. --show-schedule과 --unschedule은 이 프로젝트에 대한 Turritopsis 표시 블록만 검사하거나 제거한다. crontab이 없는 호스트에서는 CI 또는 기본 스케줄러에서 동일한 turritopsis maintain --model CHEAP_MODEL 명령을 호출한다.

유일한 자동 쓰기 예외는 결정적 생성기 구성을 가진 명시적으로 생성된 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, Web UI, MCP 서빙, 스캔, 스켈레톤 적용은 LLM과 API 키가 필요 없다. 선택적 자동 큐레이션 유지보수만 필요하다.

라이선스

Turritopsis는 표준 MIT License에 따라 출시된 오픈소스 소프트웨어이다. 상업적 사용, 수정, 배포, 서브라이선스, 개인 사용은 라이선스 고지 요건을 충족하는 경우 허용된다.

개발

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