Episode 13: Session & Session History

Key Takeaway: A session is Claude Code's smallest unit of work. Understanding its boundaries enables efficient session management.

13.1 What is a Session

A session is one complete Claude Code conversation — from launch to exit (or /clear).

flowchart LR
    A[Launch Claude Code] --> B[Session starts]
    B --> C[Conversation]
    C --> D{User action}
    D -->|Continue| C
    D -->|/clear| E["Session reset
New session begins"]
    D -->|Exit Claude Code| F[Session ends]
    E --> C

13.2 Session Data Storage

Each session has a unique ID (UUID), with all data stored in:

~/.claude/projects/-Users-eric-work-teachagent/
├── e437f4ea-...-ed7c.jsonl   ← Current session transcript
├── e437f4ea-...-ed7c/         ← Session config directory
├── ccadf395-...-9a50.jsonl   ← Previous session
└── memory/                    ← Persistent memory (cross-session)

13.3 Session History (JSONL Transcript)

Each session's complete conversation is saved in a .jsonl file:

{"type":"user","content":"read project",...}
{"type":"assistant","content":[{"type":"text",...},{"type":"tool_use","name":"Read",...}],...}
{"type":"tool_result","content":"full file contents...",...}

The JSONL file IS the complete context — every message sent to the API is recorded here.

HUD reads this file for tool activity, agent status, todo progress, and more.

13.4 Session vs Cache Relationship

flowchart TD
    subgraph "Session A"
        A1["Request 1: Write cache"] --> A2["Request 2: Cache hit"]
        A2 --> A3["Request 3: Cache hit"]
    end
    subgraph "Session B"
        B1["Request 1: No cache exists"]
        B2["Request 2: Rebuild cache"] --> B3["Request 3: Cache hit"]
    end
    A3 -->|"/clear or new session"| B1

Key point: Cache does not persist across sessions. First turn of every new session is the most expensive.

13.5 Session vs Memory

Next Episode: Episode 14 covers the Memory system — how cross-session persistent memory works.