Skip to main content

​
Agent Sessions

The Wafer agent maintains conversation history in sessions. Resume previous conversations, list past sessions, and manage your interaction history.

​
Quick Start

# List recent sessions
wafer agent --list-sessions

# Resume the last session
wafer agent -r last "Continue our conversation"

# Resume a specific session
wafer agent -r abc123 "What were we discussing?"

# Get session details
wafer agent --get-session abc123

​
Session Features

Sessions preserve:
  • Full conversation history
  • Tool execution results
  • File context and modifications
  • Model configuration
This lets you:
  • Continue multi-turn optimizations
  • Return to previous analysis
  • Build on prior context

​
Commands

​
List Sessions

View recent sessions: 
wafer agent --list-sessions
Output: 
Recent Sessions:

  ID        Started              Turns  Last Message
  abc123    2024-01-15 10:30    12     "The optimization improved..."
  def456    2024-01-14 15:45    5      "Here's the trace analysis..."
  ghi789    2024-01-14 09:00    3      "Bank conflicts occur when..."

Use 'wafer agent -r <ID>' to resume a session.

​
Resume Session

Continue a previous conversation: 
# Resume by ID
wafer agent -r abc123 "What was the final speedup?"

# Resume the most recent session
wafer agent -r last "Continue"

# Resume from a specific turn
wafer agent -r abc123 --from-turn 5 "Let's try a different approach"
Options:
OptionDescription
-r, --resumeSession ID or last
--from-turnBranch from specific turn number

​
Get Session Details

View full session content: 
wafer agent --get-session <session-id>
Output: 
Session: abc123
Started: 2024-01-15 10:30:00
Turns: 12
Model: claude-opus-4-5-20251101

Messages:
  [1] User: How do I optimize this matmul kernel?
  [2] Assistant: Looking at your kernel, there are several...
  [3] User: Can you show me the memory access pattern?
  [4] Assistant: [Used tool: read kernel.cu]
      The current access pattern shows...
  ...

​
Session Branching

Create alternative conversation branches: 
# Original conversation went in one direction
wafer agent -r abc123 --from-turn 5 "Actually, let's try vectorization instead"
This creates a new session branching from turn 5, letting you explore different optimization paths without losing the original conversation.

​
Session Storage

Sessions are stored locally:
PlatformLocation
macOS~/.wafer/sessions/
Linux~/.wafer/sessions/
Windows%USERPROFILE%\.wafer\sessions\
Sessions include:
  • Conversation messages
  • Tool call history
  • Model responses
  • Timestamps and metadata

​
Use Cases

​
Multi-Day Optimization

# Day 1: Start optimization
wafer agent -t optimize-kernel --args kernel=./matmul.cu "Optimize for H100"
# ... work on optimizations ...

# Day 2: Resume and continue
wafer agent -r last "What was the next step?"

​
Exploring Alternatives

# Try approach A
wafer agent "How should I handle the edge cases?"
# Agent suggests approach A...

# Branch and try approach B
wafer agent -r last --from-turn 3 "What if we used padding instead?"

​
Reviewing Past Analysis

# List sessions
wafer agent --list-sessions

# Find the trace analysis session
wafer agent --get-session def456

# Resume with new questions
wafer agent -r def456 "Can you elaborate on the memory bottleneck?"

​
Session Limits

  • Sessions are stored for 30 days by default
  • Large sessions may be truncated when resumed
  • Tool outputs are summarized in session history

​
JSON Output

Get session data as JSON for scripting: 
wafer agent --get-session abc123 --json > session.json

​
Next Steps

Agent Overview

Learn agent basics.

Templates

Use pre-configured templates.

CLI Overview

Other CLI commands.

Configuration

Configure the CLI.