Turritopsis

A shared handoff layer for long-running projects.

CI Python 3.10+ License: MIT

1 human + 4 agents. 71 days. 500K lines of active code.

Agents come and go. Projects shouldn't forget.

Your coding agent can read the code. Turritopsis tells it:

• what is true now;
• why the project ended up this way;
• where the current work stopped;
• what has already failed;
• which boundaries must not be broken;
• and where to continue.

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

Turritopsis is not private agent memory, code indexing, session continuation, a project wiki, or chunked RAG. It is a small, Git-friendly address space for project knowledge that code and Git cannot reliably reconstruct.

One MCP, many agents: a field-tested workflow

Turritopsis grew out of one human running a real long-term system with four different agents across chat, coding, local, and VPS workspaces. They did not share a private memory or a continuous session. They shared one project map through one MCP.

Chat windows were for thinking. ChatGPT and Claude could keep long-context brainstorming, product decisions, and difficult design conversations in the conversational surface where they belonged. Their context and token budgets were spent on reasoning instead of repeatedly reconstructing the repository.

Coding windows were for execution. A clean coding agent could arrive, call list_stages, search_stages, and get_stage, and take over in seconds. It did not need its own agent-memory system, a replay of old conversations, or a newly written handoff document. Clean windows stayed clean without losing engineering progress.

A cheaper model handled routine maintenance. It could inspect recent diffs and stale verification dates, refresh evidence-backed knowledge, and leave uncertain facts unresolved. Expensive models were reserved for decisions that deserved them.

The human edited direction, not bookkeeping. The Web UI provided a project map, Stage editor, live Markdown preview, revision conflicts, proposals, and history. The human corrected priorities, boundaries, and project meaning while agents maintained implementation detail from traceable evidence.

The practical result was continuity without forcing every agent to become the memory system. Agents could disappear, sessions could end, and a new coding window could still find the current truth and continue the work.

Evidence, including failures

A preregistered cold-start evaluation ran the same blank Agent workflow against four third-party open-source projects: fd, Datasette, Atuin, and Bruno. Across 293,261 lines and 5,271 files, it produced 56 project-shaped Stages in 23m31s. All 56 were structurally complete and preserved explicit unknowns. The evaluation also found weak top-1 retrieval, coverage dilution on fragmented repositories, and the hard boundary between repository snapshot truth and live operational truth.

Read the full methodology, frozen commits, results, corrections, and limitations in EVALUATION.md. The negative results are part of the evidence, not edited out of the story.

Install and 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 uses streamable MCP and listens only on loopback by default:

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

Open http://127.0.0.1:3013/ for the human Project Map. The same process serves:

• / — Project Map, search, Stage reader/editor, handoff, Authority, proposals, and history;
• /mcp — the four MCP tools;
• /api/... — the local UI API, backed by the same Turritopsis, Store, search, and update implementation.

turritopsis ui is an explicit alias when only the human surface is wanted. No Node runtime, frontend build, LLM, or API key is needed after installation.

Remote exposure is explicit (--host 0.0.0.0) and should be placed behind an authentication layer.

Agent onboarding skill

The repository includes a Codex-compatible Skill at skills/turritopsis-onboarding/. Copy that directory into your Codex skills folder, then invoke $turritopsis-onboarding when an agent initializes, joins, or resumes a project. The Skill teaches the installed Agent how to choose universal Stage responsibilities and project-specific suites instead of copying one project's Current names.

Scenario Skill packs

Four optional Skills adapt the universal Stage contract to long-lived human–Agent systems:

Skill	Use it for
turritopsis-agent-memory	Evidence ingestion, accepted knowledge, recall, correction, retention, and rebuildable indexes
turritopsis-human-facing-pwa	A PWA or web UI that is the human's first-class entry into an Agent or service
turritopsis-personal-ai-assistant	Consent, private channels, proactive behavior, tool actions, relationship continuity, and human direction
turritopsis-persistent-agent-runtime	Long-running sessions, relays, schedulers, tools, health, recovery, and context continuity

Copy only the directories you need from skills/ into your Agent's skills folder. Invoke the base onboarding Skill plus one or more packs, for example:

Use $turritopsis-onboarding and $turritopsis-agent-memory to map this repository.
Use $turritopsis-onboarding, $turritopsis-personal-ai-assistant, and
$turritopsis-persistent-agent-runtime to design the smallest sufficient Stage suite.

The packs are lenses, not templates. They recommend Stage responsibilities and judgment rules while leaving Current names and the final suite project-specific. Each includes one fictional fixture; none contains the authors' private paths, infrastructure, or project vocabulary.

Knowledge model

A Current routes a durable family of project questions. Current names are project-specific; anatomy, flow, bounds, manual, and genesis are useful for some long-running Agent systems, not universal defaults for every SDK, database, mobile client, ML pipeline, or device.

A Stage is one complete, named knowledge region—not an arbitrary text chunk. Stage Markdown may contain English or Chinese metadata:

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

Keep current truth, historical explanation, and deterministic generated facts in separate Stages. Status: historical never silently presents itself as current authority. A generated Stage should say that manual edits will be overwritten.

Four MCP tools

• list_stages(current?) maps currents or compact Stage metadata, never bodies.
• search_stages(...) provides explainable weighted routing or exact line/context matches.
• get_stage(stage_id) returns one complete Stage and its body-hash revision.
• update_stage(...) supports replace/append, optional expected_revision, actor logs, rolling backups, and conflict responses.

Search weights preserve the proven live routing order: Stage id, search hints, title, authority, summary, purpose, status/verification, Current, then headings/body. semantic is an explainable structured-field router; it does not claim embeddings.

All reads reload stages.json. Writes take a file lock, compare only the target Stage revision, write through a temporary file with fsync, atomically replace the canonical file, append changelog.jsonl, and keep rolling backups.

Structure and maintenance

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

Ordinary turritopsis init asks for the main modules and creates initial Current/Stage addresses. --modules supplies the same answer non-interactively.

Cold start is deliberately split into a local deterministic scan and an installed-Agent classification:

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

The CLI exposes the same read/revision path, so an Agent never needs to inspect installed package source. Read one Stage or all skeleton placeholders:

turritopsis get-stage project.handoff
turritopsis get-stage --all

For one body, use:

turritopsis update-stage project.handoff \
  --body-file handoff.md \
  --expected-revision CURRENT_BODY_HASH \
  --actor codex \
  --mode replace

A stale revision exits non-zero and prints the current revision; it never silently overwrites the newer body.

For a cold start with many Stages, turritopsis update-stages --help prints the batch manifest schema. One command validates every Stage and expected revision, then writes the complete batch atomically:

turritopsis update-stages --manifest updates.json --actor codex

turritopsis init --scan is a compatibility alias for the first command. It reads a bounded project tree, README files, manifests, CI/configuration documents, and other non-sensitive text materials, then writes scan-evidence.json, scan-anomalies.json, and scan-run.json. It uses no model, network, provider, or API key. Re-running scan resumes from the saved evidence unless --refresh is explicit, so an interrupted Agent never has to pay the scan cost again.

The installed Agent—not a second external LLM—classifies that evidence. apply-skeleton validates schema, provenance, Current and Stage ids, evidence paths, Stage type/freshness, empty responsibilities, duplicate Authority, garbage drawers, and fragmentation before atomically creating stages.json. It never overwrites an existing knowledge base; later writes must use revision-protected update_stage. Canonical knowledge still starts as explicit placeholders and must be filled from verified evidence.

classification.agent_self_reported records only the classifier's own free-text label. It is useful for debugging but is not trustworthy provider/model provenance. The scanner reports every tree, material, or structure budget truncation in scan-run.json.warnings. It also records a 14-Stage files-per-Stage estimate so a large repository is visibly identified as map-only before Stage writing begins.

Optional LLM-backed maintenance uses .turritopsis/config.json; scanning and skeleton application never read it:

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

Supported providers are openai, anthropic, and openai-compatible. Compatible providers require base_url. Settings can be overridden with TURRITOPSIS_LLM_PROVIDER, TURRITOPSIS_LLM_MODEL, TURRITOPSIS_LLM_API_KEY_ENV, TURRITOPSIS_LLM_BASE_URL, TURRITOPSIS_LLM_TIMEOUT, and TURRITOPSIS_LLM_MAX_TOKENS. API key values are read only from the configured environment variable and are never written to project files.

turritopsis maintain checks recent Git changes, missing referenced paths, and verification age. For each affected curated Stage it sends the current body and bounded project evidence to the configured LLM, validates the returned JSON and cited evidence ids, updates Verified, then writes through the normal Stage revision, lock, backup, atomic replace, and changelog path. If evidence is insufficient, the model must return 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 preserves a review-first drift report when desired; --apply still applies an explicitly reviewed proposal. They are optional workflows, not restrictions on normal evidence-backed maintenance.

--schedule installs or replaces one path-scoped entry in the current POSIX user's crontab. The example above runs every day at 03:00 in the cron host's local timezone, writes output to .turritopsis/maintenance-cron.log, and is idempotent when repeated. It never writes an API key into crontab: the api_key_env named in config.json must already be available to the cron environment. --show-schedule and --unschedule inspect or remove only Turritopsis' marked block for this project. On hosts without crontab, invoke the same turritopsis maintain --model CHEAP_MODEL command from CI or the native scheduler.

The sole automatic-write exception is an explicitly generated Stage with a deterministic generator configuration:

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

Built-in deterministic types are git_revision, file_hash, and path_exists. Their output is visibly marked auto-generated and does not use the LLM.

Core list/search/get/update, Web UI, MCP serving, scan, and skeleton application require no LLM and no API key. Only optional automatic curated maintenance does.

License

Turritopsis is open-source software released under the standard MIT License. Commercial use, modification, distribution, sublicensing, and private use are permitted subject to the license notice requirement.

Development

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