State and Persistence

Kavi persists all session data locally, ensuring that sessions can survive restarts, provide audit trails, and support debugging. All state lives under the .kavi/ directory in your project root.

The .kavi/ Directory

The .kavi/ directory is the root of all Kavi state for a project:

Session Record

Each session has a session.json file that stores the session's metadata and current state:

• Session ID -- unique ULID identifier
• Status -- active, paused, completed, or failed
• Base branch -- the branch the session started from
• Base commit -- the commit hash at session start
• Created at / updated at -- timestamps
• Agent states -- current status of each agent process
• Plan reference -- link to the active plan, if any

The session record is updated as the session progresses and serves as the entry point for resuming a session after a restart.

Event Log (JSONL)

The primary persistence mechanism is a JSONL (JSON Lines) file where each line is a self-contained event. Events capture everything that happens during a session:

• Task events -- task created, started, completed, failed
• Routing events -- route decisions with strategy, confidence, agent
• Approval events -- tool calls intercepted, approved, denied, rules created
• Review events -- threads created, comments added, dispositions set, resolved
• Peer message events -- messages sent between agents
• Plan events -- plan created, approved, modified, completed
• Landing events -- merge started, validation run, succeeded/failed
• Recommendation events -- generated, acted on, dismissed, restored
• Agent output events -- streaming output from agent processes

Each event includes:

{
  "id": "01JXYZ...",
  "type": "task.completed",
  "timestamp": "2025-06-15T10:30:00Z",
  "session_id": "01JXYZ...",
  "payload": {
    "task_id": "01JXYZ...",
    "agent": "codex",
    "duration_ms": 45000
  }
}

The JSONL format is append-only, making it robust against crashes -- partial writes only affect the last line.

SQLite (Optional)

For sessions that generate large volumes of events, Kavi supports an optional SQLite backend. When enabled, events are written to both the JSONL file and a SQLite database:

export KAVI_ENABLE_SQLITE_HISTORY=1

SQLite provides benefits for:

• Querying -- find specific events by type, agent, time range, or task
• Aggregation -- compute statistics like task duration, approval rates, routing patterns
• Performance -- faster reads for large sessions compared to scanning JSONL

The JSONL file remains the source of truth. SQLite is a secondary index that can be rebuilt from the JSONL log.

Task Artifacts

Agents produce artifacts as they work -- generated files, diffs, logs, and other outputs. These are stored in the session's artifacts/ directory, organized by task:

Artifacts complement the event log by preserving the full output of each task, not just the events that occurred.

Landing Reports

Each landing attempt produces a report stored in the session's reports/ directory:

Reports capture the full details of the landing process: which branches were merged, validation output, conflict resolution, and the final result.

State Recovery

If the Kavi daemon crashes or the TUI disconnects, state can be recovered:

1. The session record provides the current state
2. The event log provides the full history
3. Agent worktrees preserve uncommitted work
4. The approval rules ledger retains learned decisions

On reconnection, Kavi replays the event log to reconstruct in-memory state, restarts agent processes if needed, and resumes from where it left off.

Cleanup

Session state accumulates over time. You can clean up old sessions:

• Completed sessions can be archived or deleted
• Agent worktrees from completed sessions are removed automatically
• The integration worktree is always cleaned up after landing

# .gitignore
.kavi/