Evaluate: Tree-structured session storage (Pi pattern) for terraphim_persistence

[AlexMikhalev]

Parent Epic

#682 -- Evaluate Pi architectural patterns

Pattern

Pi (badlogic/pi-mono) uses tree-structured JSONL for session storage. Each entry has id and parentId fields, enabling in-place branching without creating new files. A visual /tree navigator lets users jump to any point and continue from there. All branches are preserved in a single file.

Current State

• terraphim_persistence (Epic: Leverage Paperclip features into AI Dark Factory #637-Phase 5: File-based approval gates for ADF #642) plans to use Persistable trait + DeviceStorage with SQLite/redb backends
• Claude Code uses linear JSONL with lossy auto-compaction (no branching within a session)
• ADF session persistence (Phase 2: Session persistence for Claude Code agents in ADF #639) captures Claude Code's --output-format stream-json output as linear JSONL
• terraphim-agent sessions import reads linear JSONL from ~/.claude/projects/

Evaluation Questions

1. Does tree-structured JSONL improve debugging and replay for ADF agent sessions? Current linear format loses context on compaction. Tree format preserves all branches.
2. Is the id/parentId overhead justified? Each entry gains two fields. Measure storage and parse overhead for typical 500-2000 message sessions.
3. Can tree structure coexist with Claude Code's linear format? terraphim-agent imports Claude Code sessions. If we adopt tree format internally, we need a conversion layer.
4. Does the tree structure enable new capabilities? E.g., comparing different agent approaches on the same prompt, replaying from a checkpoint with different models.

Acceptance Criteria

• Document trade-offs (storage overhead, parsing complexity, tooling requirements)
• Prototype tree-structured session format for terraphim_persistence
• Benchmark parse performance vs linear JSONL for 1000+ entry sessions
• Decision: adopt, adapt, or reject with rationale

References

• Pi session format: https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/session.md
• terraphim_persistence: Epic: Leverage Paperclip features into AI Dark Factory #637
• ADF session persistence: Phase 2: Session persistence for Claude Code agents in ADF #639