Repo

The storage layer. How provenance is versioned alongside your source code using CRDT-backed storage, episodes, and full-text search.

Repo is the storage layer where provenance is versioned alongside your source code. It's local-first, CRDT-backed, and designed for long-term history that's searchable forever.

The `.stoa/` Directory

When you run stoa init, a .stoa/ directory is created in your project:

.stoa/
├── config.json          # Project configuration
├── episodes.db          # Episode metadata (SQLite)
├── active-episode       # Current episode name
├── episodes/
│   └── main/            # Default episode
│       ├── db/
│       │   └── journal.db   # Event log with FTS5 indexing
│       └── crdt-storage/    # Version history per file
├── state/               # Catchup snapshots
├── service.log          # Daemon logs
├── service.pid          # Process ID
└── daemon.sock          # Unix socket for CLI communication

The Journal

The journal (journal.db) is the system of record for all events. It uses SQLite with FTS5 full-text indexing for fast search. Event types include:

Event Type	Description
`file_change`	File create, modify, delete, or rename
`provenance_hint`	AI session file extraction
`decision_enrichment`	AI-generated exchange metadata
`session_enrichment`	AI-generated session summary
`correlation.match`	Link between file change and AI exchange

Every event is timestamped, attributed, and indexed.

CRDT Storage

Stoa uses Automerge CRDTs (Conflict-free Replicated Data Types) for version history. This provides several advantages over Git-style diffs:

Automatic conflict resolution so multiple editors never create merge conflicts
Distributed, offline-tolerant changes that sync correctly even with intermittent connectivity
Per-character attribution where provenance tracks down to individual characters
Provenance marks linking each change to the exchange that created it

Each file in your project has a corresponding CRDT document in crdt-storage/.

Version History

Every file maintains complete version history with provenance:

# Show file at specific version
stoa show src/api.ts@5

# Show at specific exchange
stoa show src/api.ts@ex_0_abc123

# Restore a previous version
stoa restore src/api.ts@3

# Restore all files from an exchange
stoa restore --exchange ex_0_abc123

Restore operations create backups in .stoa/restore-backups/ before making changes.

Cloud Sync

Repo is local-first by default. Enable cloud sync for team visibility:

# Authenticate
stoa login

# Set remote
stoa remote set stoa://sync.stoa.build/your-project

# Register with web platform
stoa web register

Sync uses WebSocket with resume tokens for offline tolerance. The CRDT architecture ensures changes merge cleanly even with intermittent connectivity.

Storage Efficiency

Stoa is designed for long-term storage:

Incremental snapshots where only changes are stored
Content deduplication so identical content is stored once
FTS indexing for fast search without scanning files
Configurable retention to control how much history to keep

Typical storage: approximately 1-5 MB per month of active development.

What's Next

Capture

How provenance is captured from AI sessions

CLI Reference

Full command reference

The .stoa/ Directory