Session Analysis

Session JSONL Analysis

OpenClaw stores session data as JSONL files. Analyzing these reveals user behavior, tool effectiveness, error patterns, and optimization opportunities for workspace files.

Session File Location

All paths relative to CWD (standard: ~/.openclaw/, Docker multi-instance: ~/.openclaw-{name}/):

./agents/main/sessions/sessions.json   # Session index
./agents/main/sessions/*.jsonl         # Session transcripts

Each JSONL line is a JSON object representing a message, tool call, or system event. Sessions reset daily at 4 AM local time by default.

Key Data Extractable

Analysis Workflow

Step 1: Check session index

cat ./agents/main/sessions/sessions.json 2>/dev/null | jq length

Step 2: Locate session files

ls -t ./agents/main/sessions/*.jsonl 2>/dev/null | head -20

Step 3: Extract user messages (what users ask about)

jq -r 'select(.message.role=="user") | .message.content[]? | select(.type=="text") | .text' SESSION_FILE.jsonl

Step 4: Extract tool calls (which tools are used)

jq -r 'select(.message.content[]?.type=="toolCall") | .message.content[] | select(.type=="toolCall") | .name' SESSION_FILE.jsonl

Step 5: Find errors

jq -r 'select(.message.role=="toolResult") | .message.content[]? | select(.type=="text") | .text' SESSION_FILE.jsonl | grep -i "error\|failed\|exception"

Step 6: Calculate costs

jq -s '[.[] | .message.usage.cost.total // 0] | add' SESSION_FILE.jsonl

Step 7: Find user corrections

jq -r 'select(.message.role=="user") | .message.content[]? | select(.type=="text") | .text' SESSION_FILE.jsonl | grep -i "wrong\|incorrect\|no,\|that's not\|I said\|fix\|try again\|redo"

See references/jq-queries.md for the complete jq command reference.

Turning Analysis into Workspace Improvements

User messages → SOUL.md / AGENTS.md

• If users frequently ask in Ukrainian → set default language in SOUL.md
• If users ask multi-part questions → add checklist rule to AGENTS.md
• If users ask about specific domains → sharpen domain expertise in SOUL.md

Tool calls → TOOLS.md

• Most-used tools → document first with correct syntax
• Rarely-used tools → check if agent knows about them, or remove
• Calculate success rates → set priority order

Errors → TOOLS.md / AGENTS.md

• Repeated tool errors → add workaround to TOOLS.md
• Pattern of similar failures → add preventive rule to AGENTS.md

User corrections → SOUL.md / AGENTS.md

• Tone corrections → adjust SOUL.md vibe
• Procedure corrections → add/fix AGENTS.md rules
• Factual corrections → add verification requirements

Costs → HEARTBEAT.md

• High-cost heartbeat cycles → simplify HEARTBEAT.md
• Expensive sessions → identify token-heavy patterns

Active hours → HEARTBEAT.md / USER.md

• Peak usage times → optimize heartbeat schedule
• Off hours → define quiet hours
• Timezone patterns → update USER.md timezone

Multi-Session Analysis

To analyze across multiple sessions:

# Aggregate across all recent session files
cat ./agents/main/sessions/*.jsonl | jq ...

# Or process the most recent N files
ls -t ./agents/main/sessions/*.jsonl | head -50 | xargs cat | jq ...

Generating a Workspace Audit Report

Combine multiple analyses:

1. Run all jq queries from references/jq-queries.md
2. Compile findings into categories (user behavior, tool effectiveness, errors, costs)
3. Map each finding to the workspace file it should improve
4. Generate specific recommendations with proposed changes

Best Practices

1. Analyze at least 20-50 sessions for meaningful patterns
2. Focus on repeated patterns, not one-off events
3. Prioritize: user corrections > errors > tool usage > costs
4. Update workspace files based on findings, then re-analyze after 1-2 weeks
5. Run analysis monthly for ongoing optimization