⌇ ariadne

Find the conversation.
Turn scattered X/Twitter archives and tweet datasets into readable, attributable reply branches.

documentation · PyPI · Python API · MIT

A social export remembers posts. The conversation around them is often somewhere else: a parent in another archive, a quote in a community dataset, an older post in the cache.

Ariadne merges those sources, selects the posts you care about, follows every known reply-parent chain toward its root, attaches quote context, and renders the result root → target.

It does not pretend sparse data is complete. Missing posts stay visible as placeholders and warnings unless you ask for --strict.

Start here

Requires Python 3.11 or newer. The distribution is ariadne-x; the command and import are both ariadne.

uv tool install ariadne-x
ariadne interactive

Or build directly from a personal archive:

ariadne build \
  --archive ~/Downloads/twitter-archive.zip \
  --for-user alice \
  --since 2024-01-01 \
  --format markdown \
  --output conversations.md

That is the whole basic loop:

archives + dumps + cache
          ↓
     choose targets
          ↓
follow known parent IDs
          ↓
 quotes + root-to-target branches

Choose your path

Imported archives form a local, searchable library:

ariadne dumps import ~/Downloads/twitter-archive.zip --name personal
ariadne dumps search "remembered phrase" --user alice
ariadne dumps show https://x.com/alice/status/1234567890123456789

# Imported dumps join ordinary builds automatically.
ariadne build --for-user alice --since 2024-01-01 --format raft -o alice.jsonl

Each import becomes a self-contained SQLite database under ~/.ariadne/dumps. The source is never modified, and removing an import never removes the source. Parquet imports additionally need DuckDB:

uv tool install 'ariadne-x[parquet]'

Read the archive library guide →

From Python

The CLI is a thin front end over a typed synchronous API:

from pathlib import Path
import ariadne

options = ariadne.BuildOptions(
    archive=Path.home() / "Downloads" / "twitter-archive.zip",
    for_user="alice",
    since="2024-01-01",
)

result = ariadne.build(options)

for conversation in result:
    print(conversation.target_id)

documents = result.raft_documents()
result.save("out/branches.jsonl", "raft")

Use no_dumps=True when a build must ignore the persistent archive library. Named failures derive from AriadneError, including ConfigurationError, NoTargetsError, ReconstructionError, and SourceError.

Read the Python API reference →

Pick an output

The openai renderer keeps Ariadne's conversation envelope; consumers extract conversations[i].messages. Role names describe position in the branch, not the speaker's intent.

Inspect the schemas →

What Ariadne follows

• One target's ancestor path back to its root—not sibling replies or a whole tree.
• Older parents even when --since limits the starting targets.
• Reply and quote edges across different imported dumps.
• Quote context, with root quote-tweets spliced onto their quoted post by default.

Ordinary archive builds stay local. --target-user is the convenience exception: it tries unofficial RSS and oEmbed unless disabled. Those sources can recover recent text but usually cannot prove reply edges. X API reads are separately opt-in through --fetch and --fetch-user-timeline and may be billable.

Read the source and network policy →

A few useful commands

ariadne inspect-archive ~/Downloads/twitter-archive.zip
ariadne dumps interactive
ariadne build --help

# Bluesky uses its public API and the same renderers.
ariadne bluesky alice.bsky.social --since 2024-01-01 --format raft

Reference

• Documentation site
• Persistent archive library
• Python API
• Source behavior
• Output schemas
• Raft handoff

Development

uv sync --extra dev --extra parquet
uv run pytest
uv run ruff check .
uv run mypy src

MIT licensed. The thread was there all along.