Turritopsis

Eine gemeinsame Übergabeschicht für langfristige Projekte.

1 Mensch + 4 Agenten. 71 Tage. 500K Zeilen aktiven Codes.

Agenten kommen und gehen. Projekte sollten nicht vergessen.

Dein Coding-Agent kann den Code lesen. Turritopsis sagt ihm:

• was jetzt wahr ist;

• warum das Projekt so geworden ist;

• wo die aktuelle Arbeit aufgehört hat;

• was bereits fehlgeschlagen ist;

• welche Grenzen nicht überschritten werden dürfen;

• und wo es weitergeht.

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

Turritopsis ist kein privater Agentenspeicher, keine Code-Indizierung, keine Sitzungsfortsetzung, kein Projekt-Wiki und kein Chunked-RAG. Es ist ein kleiner, Git-freundlicher Adressraum für Projektwissen, das Code und Git nicht zuverlässig rekonstruieren können.

Ein MCP, viele Agenten: ein praxiserprobter Workflow

Turritopsis entstand aus einem Menschen, der ein reales Langzeitsystem mit vier verschiedenen Agenten über Chat-, Coding-, lokale und VPS-Arbeitsbereiche betrieb. Sie teilten keinen privaten Speicher und keine kontinuierliche Sitzung. Sie teilten eine Projektkarte über ein MCP.

Chat-Fenster waren zum Denken da. ChatGPT und Claude konnten Brainstorming mit langem Kontext, Produktentscheidungen und schwierige Design-Gespräche in der Konversationsoberfläche halten, wo sie hingehörten. Ihr Kontext- und Token-Budget wurde für das Denken ausgegeben, anstatt das Repository wiederholt zu rekonstruieren.

Coding-Fenster waren für die Ausführung da. Ein sauberer Coding-Agent konnte ankommen, list_stages, search_stages und get_stage aufrufen und in Sekunden übernehmen. Er brauchte kein eigenes Agent-Gedächtnissystem, keine Wiedergabe alter Gespräche und kein neu geschriebenes Übergabedokument. Saubere Fenster blieben sauber, ohne technischen Fortschritt zu verlieren.

Ein günstigeres Modell übernahm die Routinewartung. Es konnte aktuelle Diffs und veraltete Verifikationsdaten prüfen, evidenzgestütztes Wissen aktualisieren und unsichere Fakten ungelöst lassen. Teure Modelle waren Entscheidungen vorbehalten, die sie verdienten.

Der Mensch bearbeitete die Richtung, nicht die Buchhaltung. Die Web-UI bot eine Projektkarte, einen Stage-Editor, Live-Markdown-Vorschau, Revisionskonflikte, Vorschläge und Verlauf. Der Mensch korrigierte Prioritäten, Grenzen und Projektbedeutung, während Agenten Implementierungsdetails aus nachvollziehbaren Belegen pflegten.

Das praktische Ergebnis war Kontinuität, ohne jeden Agenten zu zwingen, das Gedächtnissystem zu werden. Agenten konnten verschwinden, Sitzungen enden, und ein neues Coding-Fenster konnte dennoch die aktuelle Wahrheit finden und die Arbeit fortsetzen.

Related MCP server: handoff-mcp

Installation und Start

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 verwendet streamable MCP und lauscht standardmäßig nur auf Loopback:

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

Öffne http://127.0.0.1:3013/ für die menschliche Projektkarte. Derselbe Prozess bedient:

• / — Projektkarte, Suche, Stage-Leser/-Editor, Übergabe, Authority, Vorschläge und Verlauf;

• /mcp — die vier MCP-Werkzeuge;

• /api/... — die lokale UI-API, gestützt auf dieselbe Turritopsis-, Store-, Such- und Update-Implementierung.

turritopsis ui ist ein expliziter Alias, wenn nur die menschliche Oberfläche gewünscht ist. Nach der Installation werden keine Node-Laufzeit, kein Frontend-Build, kein LLM und kein API-Schlüssel benötigt.

Die Remote-Freigabe ist explizit (--host 0.0.0.0) und sollte hinter einer Authentifizierungsschicht platziert werden.

Agent-Onboarding-Skill

Das Repository enthält einen Codex-kompatiblen Skill unter skills/turritopsis-onboarding/. Kopiere dieses Verzeichnis in deinen Codex-Skills-Ordner und rufe dann $turritopsis-onboarding auf, wenn ein Agent ein Projekt initialisiert, beitritt oder wieder aufnimmt. Der Skill lehrt den installierten Agenten, universelle Stage-Verantwortlichkeiten und projektspezifische Suiten zu wählen, anstatt die Current-Namen eines Projekts zu kopieren.

Wissensmodell

Ein Current leitet eine dauerhafte Familie von Projektfragen. Current-Namen sind projektspezifisch; anatomy, flow, bounds, manual und genesis sind für einige langlaufende Agent-Systeme nützlich, aber keine universellen Standardwerte für jedes SDK, jede Datenbank, jeden mobilen Client, jede ML-Pipeline oder jedes Gerät.

Ein Stage ist eine vollständige, benannte Wissensregion – kein beliebiges Textstück. Stage-Markdown kann englische oder chinesische Metadaten enthalten:

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

Halte aktuelle Wahrheit, historische Erklärung und deterministisch generierte Fakten in getrennten Stages. Status: historical präsentiert sich nie stillschweigend als aktuelle Autorität. Ein generierter Stage sollte sagen, dass manuelle Bearbeitungen überschrieben werden.

Vier MCP-Werkzeuge

• list_stages(current?) bildet Currents oder kompakte Stage-Metadaten ab, niemals Körper.

• search_stages(...) bietet erklärbares gewichtetes Routing oder exakte Zeilen-/Kontextübereinstimmungen.

• get_stage(stage_id) gibt einen vollständigen Stage und seine Body-Hash-Revision zurück.

• update_stage(...) unterstützt Ersetzen/Anhängen, optional expected_revision, Akteursprotokolle, rollierende Backups und Konfliktantworten.

Suchgewichte bewahren die bewährte Live-Routing-Reihenfolge: Stage-ID, Suchhinweise, Titel, Authority, Zusammenfassung, Zweck, Status/Verifikation, Current, dann Überschriften/Körper. semantic ist ein erklärbarer Router für strukturierte Felder; es beansprucht keine Embeddings.

Alle Lesevorgänge laden stages.json neu. Schreibvorgänge nehmen eine Dateisperre, vergleichen nur die Ziel-Stage-Revision, schreiben über eine temporäre Datei mit fsync, ersetzen die kanonische Datei atomar, hängen changelog.jsonl an und behalten rollierende Backups.

Struktur und Wartung

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

Gewöhnliches turritopsis init fragt nach den Hauptmodulen und erstellt anfängliche Current-/Stage-Adressen. --modules liefert dieselbe Antwort nicht-interaktiv.

Der Kaltstart ist bewusst in einen lokalen deterministischen Scan und eine Klassifizierung durch den installierten Agenten aufgeteilt:

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 ist ein Kompatibilitätsalias für den ersten Befehl. Es liest einen begrenzten Projektbaum, README-Dateien, Manifeste, CI-/Konfigurationsdokumente und andere nicht sensible Textmaterialien und schreibt dann scan-evidence.json, scan-anomalies.json und scan-run.json. Es verwendet kein Modell, kein Netzwerk, keinen Anbieter und keinen API-Schlüssel. Ein erneutes Ausführen von scan setzt bei den gespeicherten Belegen fort, sofern nicht explizit --refresh angegeben ist, sodass ein unterbrochener Agent die Scan-Kosten nie erneut zahlen muss.

Der installierte Agent – nicht ein zweites externes LLM – klassifiziert diese Belege. apply-skeleton validiert Schema, Herkunft, Current- und Stage-IDs, Belegpfade, Stage-Typ/Frische, leere Verantwortlichkeiten, doppelte Authority, Müllschubladen und Fragmentierung, bevor es stages.json atomar erstellt. Es überschreibt niemals eine bestehende Wissensbasis; spätere Schreibvorgänge müssen das revisionsgeschützte update_stage verwenden. Kanonisches Wissen beginnt weiterhin als explizite Platzhalter und muss aus verifizierten Belegen gefüllt werden.

Optionale LLM-gestützte Wartung verwendet .turritopsis/config.json; Scannen und Skeleton-Anwendung lesen es nie:

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

Unterstützte Anbieter sind openai, anthropic und openai-compatible. Kompatible Anbieter erfordern base_url. Einstellungen können mit TURRITOPSIS_LLM_PROVIDER, TURRITOPSIS_LLM_MODEL, TURRITOPSIS_LLM_API_KEY_ENV, TURRITOPSIS_LLM_BASE_URL, TURRITOPSIS_LLM_TIMEOUT und TURRITOPSIS_LLM_MAX_TOKENS überschrieben werden. API-Schlüsselwerte werden nur aus der konfigurierten Umgebungsvariable gelesen und niemals in Projektdateien geschrieben.

turritopsis maintain prüft aktuelle Git-Änderungen, fehlende referenzierte Pfade und das Verifikationsalter. Für jeden betroffenen kuratierten Stage sendet es den aktuellen Körper und begrenzte Projektbelege an das konfigurierte LLM, validiert das zurückgegebene JSON und die zitierten Beleg-IDs, aktualisiert Verified und schreibt dann über den normalen Stage-Revisions-, Sperr-, Backup-, atomaren Ersetzungs- und Changelog-Pfad. Wenn die Belege unzureichend sind, muss das Modell no_change zurückgeben.

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 bewahrt bei Bedarf einen Review-zuerst-Abweichungsbericht; --apply wendet weiterhin einen explizit überprüften Vorschlag an. Sie sind optionale Workflows, keine Einschränkungen der normalen evidenzgestützten Wartung.

--schedule installiert oder ersetzt einen pfadbezogenen Eintrag in der Crontab des aktuellen POSIX-Benutzers. Das obige Beispiel läuft jeden Tag um 03:00 in der lokalen Zeitzone des Cron-Hosts, schreibt die Ausgabe nach .turritopsis/maintenance-cron.log und ist bei Wiederholung idempotent. Es schreibt niemals einen API-Schlüssel in die Crontab: Die in config.json benannte api_key_env muss bereits in der Cron-Umgebung verfügbar sein. --show-schedule und --unschedule prüfen oder entfernen nur den markierten Block von Turritopsis für dieses Projekt. Auf Hosts ohne crontab rufe denselben Befehl turritopsis maintain --model CHEAP_MODEL aus CI oder dem nativen Scheduler auf.

Die einzige Ausnahme für automatisches Schreiben ist ein explizit generierter Stage mit einer deterministischen Generator-Konfiguration:

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

Eingebaute deterministische Typen sind git_revision, file_hash und path_exists. Ihre Ausgabe ist sichtbar als automatisch generiert markiert und verwendet kein LLM.

Kern-Liste/Suche/Get/Update, Web-UI, MCP-Bereitstellung, Scan und Skeleton-Anwendung erfordern kein LLM und keinen API-Schlüssel. Nur die optionale automatische kuratierte Wartung tut das.

Lizenz

Turritopsis ist Open-Source-Software, die unter der standardmäßigen MIT-Lizenz veröffentlicht wird. Kommerzielle Nutzung, Modifikation, Verbreitung, Unterlizenzierung und private Nutzung sind unter der Bedingung des Lizenzhinweises gestattet.

Entwicklung

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