Turritopsis

Una capa de traspaso compartida para proyectos de larga duración.

1 humano + 4 agentes. 71 días. 500K líneas de código activo.

Los agentes van y vienen. Los proyectos no deberían olvidar.

Tu agente de codificación puede leer el código. Turritopsis le dice:

• qué es verdad ahora;

• por qué el proyecto terminó así;

• dónde se detuvo el trabajo actual;

• qué ha fallado ya;

• qué límites no deben romperse;

• y dónde continuar.

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

Turritopsis no es memoria privada de agente, indexación de código, continuación de sesión, una wiki de proyecto ni RAG fragmentado. Es un pequeño espacio de direcciones amigable con Git para el conocimiento del proyecto que el código y Git no pueden reconstruir de manera fiable.

Un MCP, muchos agentes: un flujo de trabajo probado en el campo

Turritopsis surgió de un humano que ejecutaba un sistema real a largo plazo con cuatro agentes diferentes en espacios de trabajo de chat, codificación, local y VPS. No compartían una memoria privada ni una sesión continua. Compartían un mapa de proyecto a través de un MCP.

Las ventanas de chat eran para pensar. ChatGPT y Claude podían mantener lluvias de ideas de contexto largo, decisiones de producto y conversaciones de diseño difíciles en la superficie conversacional donde pertenecían. Sus presupuestos de contexto y tokens se gastaban en razonamiento en lugar de reconstruir repetidamente el repositorio.

Las ventanas de codificación eran para la ejecución. Un agente de codificación limpio podía llegar, llamar a list_stages, search_stages y get_stage, y hacerse cargo en segundos. No necesitaba su propio sistema de memoria de agente, una reproducción de conversaciones antiguas ni un documento de traspaso recién escrito. Las ventanas limpias permanecían limpias sin perder progreso de ingeniería.

Un modelo más barato se encargaba del mantenimiento rutinario. Podía inspeccionar diffs recientes y fechas de verificación obsoletas, actualizar el conocimiento respaldado por evidencia y dejar hechos inciertos sin resolver. Los modelos caros se reservaban para decisiones que los merecían.

El humano editaba la dirección, no la contabilidad. La interfaz web proporcionaba un mapa de proyecto, editor de Stage, vista previa de Markdown en vivo, conflictos de revisión, propuestas e historial. El humano corregía prioridades, límites y significado del proyecto mientras los agentes mantenían el detalle de implementación a partir de evidencia trazable.

El resultado práctico fue continuidad sin obligar a cada agente a convertirse en el sistema de memoria. Los agentes podían desaparecer, las sesiones podían terminar, y una nueva ventana de codificación aún podía encontrar la verdad actual y continuar el trabajo.

Related MCP server: handoff-mcp

Instalar y comenzar

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 usa MCP transmisible y escucha solo en loopback por defecto:

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

Abre http://127.0.0.1:3013/ para el Mapa de Proyecto humano. El mismo proceso sirve:

• / — Mapa de Proyecto, búsqueda, lector/editor de Stage, traspaso, Autoridad, propuestas e historial;

• /mcp — las cuatro herramientas MCP;

• /api/... — la API de UI local, respaldada por la misma implementación de Turritopsis, Store, búsqueda y actualización.

turritopsis ui es un alias explícito cuando solo se quiere la superficie humana. No se necesita runtime de Node, compilación de frontend, LLM ni clave de API después de la instalación.

La exposición remota es explícita (--host 0.0.0.0) y debe colocarse detrás de una capa de autenticación.

Habilidad de incorporación de agentes

El repositorio incluye una Skill compatible con Codex en skills/turritopsis-onboarding/. Copia ese directorio en tu carpeta de skills de Codex y luego invoca $turritopsis-onboarding cuando un agente inicialice, se una o reanude un proyecto. La Skill enseña al Agente instalado cómo elegir responsabilidades universales de Stage y suites específicas del proyecto en lugar de copiar los nombres de Current de un proyecto.

Modelo de conocimiento

Un Current enruta una familia duradera de preguntas del proyecto. Los nombres de Current son específicos del proyecto; anatomy, flow, bounds, manual y genesis son útiles para algunos sistemas de Agente de larga duración, no son predeterminados universales para cada SDK, base de datos, cliente móvil, pipeline de ML o dispositivo.

Un Stage es una región de conocimiento completa y nombrada, no un fragmento de texto arbitrario. El Markdown de Stage puede contener metadatos en inglés o chino:

# 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.

Mantén la verdad actual, la explicación histórica y los hechos generados determinísticamente en Stages separados. Status: historical nunca se presenta silenciosamente como autoridad actual. Un Stage generado debe decir que las ediciones manuales serán sobrescritas.

Cuatro herramientas MCP

• list_stages(current?) mapea currents o metadatos compactos de Stage, nunca cuerpos.

• search_stages(...) proporciona enrutamiento ponderado explicable o coincidencias exactas de línea/contexto.

• get_stage(stage_id) devuelve un Stage completo y su revisión de hash de cuerpo.

• update_stage(...) admite reemplazo/agregado, expected_revision opcional, registros de actor, copias de seguridad rotativas y respuestas de conflicto.

Los pesos de búsqueda preservan el orden de enrutamiento en vivo probado: id de Stage, pistas de búsqueda, título, autoridad, resumen, propósito, estado/verificación, Current, luego encabezados/cuerpo. semantic es un enrutador de campos estructurados explicable; no afirma incrustaciones.

Todas las lecturas recargan stages.json. Las escrituras toman un bloqueo de archivo, comparan solo la revisión del Stage objetivo, escriben a través de un archivo temporal con fsync, reemplazan atómicamente el archivo canónico, agregan a changelog.jsonl y mantienen copias de seguridad rotativas.

Estructura y mantenimiento

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

El turritopsis init ordinario pregunta por los módulos principales y crea direcciones iniciales de Current/Stage. --modules proporciona la misma respuesta de forma no interactiva.

El arranque en frío se divide deliberadamente en un escaneo determinista local y una clasificación del Agente instalado:

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 es un alias de compatibilidad para el primer comando. Lee un árbol de proyecto acotado, archivos README, manifiestos, documentos de CI/configuración y otros materiales de texto no sensibles, luego escribe scan-evidence.json, scan-anomalies.json y scan-run.json. No usa modelo, red, proveedor ni clave de API. Volver a ejecutar scan reanuda desde la evidencia guardada a menos que --refresh sea explícito, por lo que un Agente interrumpido nunca tiene que pagar el costo del escaneo nuevamente.

El Agente instalado—no un segundo LLM externo—clasifica esa evidencia. apply-skeleton valida esquema, procedencia, ids de Current y Stage, rutas de evidencia, tipo/frescura de Stage, responsabilidades vacías, Autoridad duplicada, cajones de basura y fragmentación antes de crear atómicamente stages.json. Nunca sobrescribe una base de conocimiento existente; las escrituras posteriores deben usar update_stage protegido por revisión. El conocimiento canónico aún comienza como marcadores de posición explícitos y debe completarse con evidencia verificada.

El mantenimiento opcional respaldado por LLM usa .turritopsis/config.json; el escaneo y la aplicación de esqueleto nunca lo leen:

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

Los proveedores compatibles son openai, anthropic y openai-compatible. Los proveedores compatibles requieren base_url. Los ajustes se pueden sobrescribir con TURRITOPSIS_LLM_PROVIDER, TURRITOPSIS_LLM_MODEL, TURRITOPSIS_LLM_API_KEY_ENV, TURRITOPSIS_LLM_BASE_URL, TURRITOPSIS_LLM_TIMEOUT y TURRITOPSIS_LLM_MAX_TOKENS. Los valores de clave de API se leen solo de la variable de entorno configurada y nunca se escriben en archivos del proyecto.

turritopsis maintain comprueba cambios recientes de Git, rutas referenciadas faltantes y antigüedad de verificación. Para cada Stage curado afectado envía el cuerpo actual y la evidencia acotada del proyecto al LLM configurado, valida el JSON devuelto y los ids de evidencia citados, actualiza Verified, luego escribe a través de la revisión normal de Stage, bloqueo, copia de seguridad, reemplazo atómico y ruta de changelog. Si la evidencia es insuficiente, el modelo debe devolver 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 preserva un informe de deriva de revisión primero cuando se desea; --apply aún aplica una propuesta explícitamente revisada. Son flujos de trabajo opcionales, no restricciones sobre el mantenimiento normal respaldado por evidencia.

--schedule instala o reemplaza una entrada con ámbito de ruta en el crontab del usuario POSIX actual. El ejemplo anterior se ejecuta todos los días a las 03:00 en la zona horaria local del host de cron, escribe la salida en .turritopsis/maintenance-cron.log y es idempotente cuando se repite. Nunca escribe una clave de API en crontab: el api_key_env nombrado en config.json ya debe estar disponible para el entorno de cron. --show-schedule y --unschedule inspeccionan o eliminan solo el bloque marcado de Turritopsis para este proyecto. En hosts sin crontab, invoca el mismo comando turritopsis maintain --model CHEAP_MODEL desde CI o el programador nativo.

La única excepción de escritura automática es un Stage generado explícitamente con una configuración de generador determinista:

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

Los tipos deterministas integrados son git_revision, file_hash y path_exists. Su salida está visiblemente marcada como generada automáticamente y no usa el LLM.

El núcleo list/search/get/update, la interfaz web, el servicio MCP, el escaneo y la aplicación de esqueleto no requieren LLM ni clave de API. Solo el mantenimiento curado automático opcional lo hace.

Licencia

Turritopsis es software de código abierto publicado bajo la Licencia MIT estándar. Se permiten el uso comercial, la modificación, la distribución, la sublicencia y el uso privado sujetos al requisito de aviso de licencia.

Desarrollo

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