# Session File Format

Session files store serialized conversation and runtime metadata on disk for persistence and branching.

## Storage Location

Sessions are stored in `~/.voxcode/agent/sessions/` by default, one directory per session containing one or more JSON files.

## Contents

Each session directory contains:

- **Session metadata** — creation time, last active time, session name, branch label
- **Message timeline** — full history of user prompts and assistant responses
- **Tool execution events** — tool name, input, output, and exit codes for every tool call
- **File context snapshots** — cached file reads and diffs for incremental reasoning
- **Compaction summaries** — condensed history after compaction to fit model context windows
- **System state** — working directory, environment snapshots, provider/model selection

## JSON Structure (Simplified)

```json
{
  "id": "uuid-of-session",
  "name": "my-session",
  "createdAt": "2026-05-26T10:00:00Z",
  "updatedAt": "2026-05-26T12:30:00Z",
  "branch": "main",
  "messages": [
    {
      "role": "user",
      "content": "Refactor src/parser.ts for readability",
      "timestamp": "2026-05-26T10:00:01Z"
    },
    {
      "role": "assistant",
      "content": "...",
      "toolCalls": [...],
      "timestamp": "2026-05-26T10:00:30Z"
    }
  ],
  "compaction": {
    "count": 3,
    "lastSummary": "..."
  }
}
```

## Security

Treat session files as sensitive project artifacts when they contain private code or prompts. They are stored in `~/.voxcode/` under your home directory with standard file permissions.

For details on working with sessions, see [sessions.md](sessions.md).
