singularity-forge/docs/dev/what-is-pi/07-sessions-memory-that-branches.md

# Sessions — Memory That Branches

Sessions are pi's memory system. They're more sophisticated than simple conversation history.

### Storage Format

Sessions are **JSONL files** (one JSON object per line). Each line is an "entry" with a `type`, `id`, and `parentId`:

```
~/.sf/agent/sessions/--path--to--project--/<timestamp>_<uuid>.jsonl
```

### The Entry Tree

Entries form a **tree structure**, not a linear list. This is the key architectural insight:

```
                    ┌─ [user] ─ [assistant] ─ [tool] ─ [assistant]  ← Branch A
[header] ─ [user] ─┤
                    └─ [user] ─ [assistant]                          ← Branch B (via /tree)
```

Every entry has an `id` and `parentId`. When you navigate to a previous point with `/tree` and continue from there, a new branch is created from that point. **All branches coexist in the same file.** Nothing is deleted.

### Entry Types

| Type | Purpose |
|------|---------|
| `session` | Header — file metadata, version, working directory |
| `message` | A conversation message (user, assistant, tool result, custom) |
| `compaction` | Summary of older messages (created by compaction) |
| `branch_summary` | Summary of an abandoned branch (created by `/tree`) |
| `model_change` | Records when the user switched models |
| `thinking_level_change` | Records when the user changed thinking level |
| `custom` | Extension state (NOT sent to LLM) |
| `custom_message` | Extension-injected message (IS sent to LLM) |
| `label` | User bookmark on an entry |
| `session_info` | Session metadata (display name) |

### Message Types Within Entries

Message entries contain typed message objects:

| Role | What it is |
|------|-----------|
| `user` | User's prompt (text and/or images) |
| `assistant` | LLM's response (text, thinking, tool calls) — includes model, provider, usage stats |
| `toolResult` | Output from a tool execution — includes `details` for rendering and state |
| `bashExecution` | Output from user's `!command` (not from LLM tool calls) |
| `custom` | Extension-injected message |
| `branchSummary` | Summary of an abandoned branch |
| `compactionSummary` | Summary from compaction |

### Context Building

When pi needs to send messages to the LLM, it walks the tree from the current leaf to the root:

1. If there's a compaction entry on the path → emit the summary first, then messages from `firstKeptEntryId` onward
2. If there's a branch summary → include it as context
3. Custom message entries → included in LLM context
4. Custom entries (extension state) → NOT included in LLM context

### Session Commands

| Command | What it does |
|---------|-------------|
| `/tree` | Navigate to any point in the session tree and continue from there |
| `/fork` | Create a new session file from the current branch |
| `/resume` | Browse and switch to a previous session |
| `/new` | Start a fresh session |
| `/name <name>` | Set a display name for the session |
| `/session` | Show session info (path, tokens, cost) |
| `/compact` | Manually trigger compaction |

### Branching in Practice

**`/tree`** — In-place branching. You select a previous point, the conversation continues from there. The old branch is preserved and can be revisited. Pi optionally generates a summary of the branch you're leaving so context isn't lost.

**`/fork`** — Creates a new session file from the current branch. Opens a selector, copies history up to the selected point, and puts that message in the editor for modification. Good for "start fresh but keep the context."

---