Repo

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

The .intent/ Directory

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

.intent/
├── 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
└── service.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:

Every event is timestamped, attributed, and indexed. You can query the journal directly:

# List recent events
intent journal list --limit 20

# Filter by type
intent journal list --type decision_enrichment

# Filter by file
intent journal list --file src/auth.ts

# Show full payload
intent journal show <event-id> --payload

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

Episodes

Episodes are isolated workspaces within a project, similar to Git branches but for decisions. Each episode has its own journal and CRDT storage.

# List episodes
intent episode list

# Create a new episode
intent episode create feature-auth

# Create from a specific point in history
intent episode create rollback --from-exchange ex_0_abc123

# Switch active episode
intent episode switch feature-auth

# Show current episode
intent episode current

# Compare episodes
intent episode diff feature-auth --target main

# Merge episodes with LLM-guided analysis
intent episode integrate feature-auth

Episode Integration

intent episode integrate provides a guided merge flow:

1. Analysis: LLM analyzes differences between episodes
2. Interactive Planning: You review each change and decide to apply, skip, or modify
3. Application: Approved changes are applied to the target episode

Commands during planning: list, set, show, all, apply, quit, help.

Search

Natural Language Search

intent ask "What did we decide about the authentication approach?"

The ask command uses Claude with five specialized tools:

• search_decisions to find decisions by content
• search_code to find code by content
• fetch_decision to get full decision details
• get_stats for project statistics
• list_files to browse project structure

Interactive Shell

intent shell

A full AI-powered REPL with natural language queries, slash commands, @ references, and tab completion.

Direct Queries

# Decision timeline
intent timeline

# File version history
intent history src/api.ts

# Interactive file history
intent history src/api.ts -i

# Specific exchange details
intent exchange show <exchange-id>

# Compare file versions
intent diff src/api.ts @3 @5

Version History

Every file maintains complete version history with provenance:

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

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

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

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

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

Snapshots and Digests

Snapshots

Point-in-time captures of the entire CRDT state:

# Create a snapshot
intent snapshot create --title "Before refactor"

# List snapshots
intent snapshot list

# Compare snapshots
intent snapshot diff snap_1 snap_2

Digests

Curated work session packages with optional LLM analysis:

# Create a digest of recent work
intent digest "Authentication implementation"

# Create with specific range
intent digest create --from snap_1 --to snap_2

# Finalize a digest
intent digest finalize <digest-id>

# Record a video walkthrough of the digest
intent digest finalize <digest-id> --record

Cloud Sync

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

# Authenticate
intent login

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

# Register with web platform
intent 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