Intent Repo

Intent Repo is the storage layer. Decisions are versioned alongside your source code—consumable by humans and agents, diffable across releases, searchable forever. Your project's reasoning travels with it.

The .intent/ Directory

When you run intent init, Intent creates a .intent/ directory in your project root:

.intent/
├── config.json              # Project configuration
├── episodes.db              # Episode metadata (SQLite)
├── active-episode           # Name of current episode
├── episodes/
│   └── main/                # Default episode
│       ├── db/
│       │   └── journal.db   # Event log with FTS index
│       └── crdt-storage/    # Per-file version history
├── state/                   # Catchup snapshots
├── service.log              # Daemon logs
├── service.pid              # Process ID
└── service.sock             # Unix socket for RPC

This directory contains your complete decision history. Commit it to version control, and your project's reasoning travels with your code.

The Journal

The journal (journal.db) is the system of record. Every event in Intent flows through the journal:

The journal is a SQLite database with FTS5 full-text indexing. This enables instant search across all your decisions:

# Search decisions
intent ask "how did we implement rate limiting?"

# Query the journal directly
intent journal list --type decision_enrichment --limit 10

CRDT Storage

Intent uses Automerge CRDTs (Conflict-free Replicated Data Types) for version history. Each file gets its own CRDT document in .intent/episodes/{episode}/crdt-storage/.

Why CRDTs instead of Git-style diffs?

CRDTs enable:

• Offline work that syncs cleanly later
• Real-time collaboration without locks
• Per-character attribution (who typed what)
• Provenance marks (which exchange created each section)

Episodes

Episodes are isolated workspaces within a project—similar to Git branches, but for decisions.

# List episodes
intent episode list

# Create a new episode
intent episode create feature-auth

# Switch to an episode
intent episode switch feature-auth

# Compare episodes
intent episode diff main feature-auth

Each episode has its own:

• Journal (event history)
• CRDT storage (file versions)
• Decision history

Episode Integration

When work is complete, integrate an episode back to main:

intent episode integrate feature-auth --mode llm

The --mode llm option uses semantic merging—an LLM analyzes changes and produces a coherent merge, not just a mechanical line-by-line diff.

Search

Intent provides multiple ways to find decisions:

Natural Language Search

The intent ask command uses Claude to search your decision history conversationally:

intent ask "why did we choose PostgreSQL over MongoDB?"

The AI agent has access to five search tools:

• search_decisions — Find decisions by content
• search_code — Find code by content
• fetch_decision — Get full decision details
• get_stats — Project statistics
• list_files — Browse project structure

Interactive Shell

For exploratory search, use the interactive shell:

intent shell

The shell supports:

• Natural language queries
• @ references (@src/auth.ts, @ex_0_abc123)
• Slash commands (/timeline, /history, /diff)
• Command history and tab completion

Direct Queries

Query the journal directly for structured data:

# Recent decisions
intent timeline

# File history
intent history src/auth/middleware.ts

# Specific exchange
intent exchange ex_0_abc123

# Diff between versions
intent diff src/auth.ts@v3 src/auth.ts@v5

Version History

Every file has complete version history with provenance:

$ intent history src/auth/middleware.ts

v5  2024-01-15 14:32  "Add token refresh logic"
    Exchange: ex_0_ghi789
    Intent: Handle expired tokens gracefully

v4  2024-01-15 14:28  "Add error responses"
    Exchange: ex_0_def456
    Intent: Return proper HTTP status codes

v3  2024-01-15 14:20  "Initial JWT validation"
    Exchange: ex_0_abc123
    Intent: Validate tokens on protected routes

Restore Previous Versions

# Preview a version
intent show src/auth.ts@v3

# Restore a version
intent restore src/auth.ts@v3

Cloud Sync (Optional)

Intent is local-first by default—your data stays in your project. Cloud sync is optional and provides:

• Team visibility — See what others are working on
• Cross-device access — Continue on another machine
• Backup — Off-site copy of your decision history
• Arena integration — Real-time collaboration features

Enable cloud sync:

intent login
intent remote set https://sync.intent.build
intent web register

Sync uses WebSocket with resume tokens for offline tolerance. If you lose connection, changes queue locally and sync when reconnected.

Git Integration

Intent complements Git, not replaces it. While Git tracks what changed, Intent tracks why.

# Generate a commit from an exchange
intent commit ex_0_abc123

# Export provenance to git notes
intent export --format git-notes

You can link Intent sessions to Git commits and PRs, providing reviewers with the full context of why changes were made.

Storage Efficiency

Intent is designed for long-term storage:

• Incremental snapshots — Only changes are stored
• Content deduplication — Identical content stored once
• FTS indexing — Search without scanning all content
• Configurable retention — Archive old episodes

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

Next Steps