Persistence Layer Architecture Breakdown

I've completed a comprehensive exploration of the @packages/opencode/src/project/ persistence layer. Here's what I found:

🏗️ Architecture Summary

The system uses a hybrid storage model:

📊 Core Data Hierarchy

Project (1)
├── id: git root commit hash
├── worktree: /path/to/repo
├── sandboxes: string[] (additional directories)
├── permission: Ruleset
└── Session (N)
    ├── id, slug, parentID (for forks)
    ├── directory: working dir
    ├── permission?: Ruleset (override)
    └── Message (N)
        ├── role: "user" | "assistant"
        ├── agent: string (which agent handled this)
        ├── model: { providerID, modelID }
        ├── tokens, cost
        └── Part (N)
            ├── type: "text" | "tool" | "reasoning" | "step-start" | "step-finish" | "snapshot" | "patch" | "compaction" | "subtask"
            └── state: pending | running | completed | error (for tools)

🔗 Key Relationships

Project ↔ Sessions

• Cardinality: 1:N with cascade delete
• Storage: project_id FK in session table
• Location: ~/.local/share/opencode/opencode.db

Sessions ↔ Checkpoints (Snapshots)

• Mechanism: Git tree hashes stored in step-start/step-finish parts
• Location: ~/.local/share/opencode/snapshot/{project_id}/ (bare git repo)
• Trigger: Every reasoning step boundary
• Retention: 7-day auto-prune via scheduled GC

Project ↔ Worktrees ↔ Sandboxes

Project.Info = {
  worktree: string,      // Primary git worktree
  sandboxes: string[],   // Additional isolated directories
}

• Worktree: Main git repository root
• Sandboxes: Additional directories for multi-root workspaces
• Session.directory: Determines which sandbox/worktree a session operates in

📈 Growth Model: How Storage Expands Per Request

Per User Request (one turn):

Compaction Strategy

Overflow Detection:

const usable = model.limit.input - reserved  // reserved ≈ 20K tokens
if (tokenCount >= usable) → trigger compaction

Pruning Algorithm:

1. Scan messages backwards
2. Accumulate tool output token estimates
3. After 40K tokens, mark old tool outputs for pruning
4. If >20K found, compact them
5. Render as "[Old tool result content cleared]"

🧠 Agent Knowledge Hierarchy

Critical Finding: Agents Are Stateless

Built-in Agents

💾 Storage Locations

~/.local/share/opencode/
├── opencode.db                    # SQLite database (all tables)
├── storage/
│   ├── session_diff/{id}.json     # Session-level diffs
│   └── share/{id}.json            # Share metadata
└── snapshot/{project_id}/         # Bare git repos per project
    └── (git objects for checkpoints)

⚠️ Open Questions & Potential Issues

1. Snapshot Orphaning: No explicit cleanup when sessions deleted; relies on git gc
2. Sandbox Usage: Unclear when sessions use sandboxes vs. primary worktree
3. Fork Divergence: Forked sessions reference parent snapshots; unclear how divergence is tracked
4. Compaction Races: What happens if user sends message during compaction?
5. Permission Inheritance: When does session permission override project default?

📁 Key Files for Deep Dives

Would you like me to dive deeper into any specific area? For example:

• Trace the exact flow of a request through the persistence layer
• Analyze the compaction algorithm in detail
• Examine how snapshots are created and restored
• Review the permission merging logic