session-logs

clawdbot's avatarfrom clawdbot

Search and analyze your own conversation history from session log files using jq.

⭐3.1kstars🔀474forks📁View on GitHub🕐Updated Jan 11, 2026
[Memory and Context Management]

When & Why to Use This Skill

The session-logs skill enables Claude agents to programmatically search, filter, and analyze historical conversation data stored in local JSONL files. By utilizing high-performance CLI tools like jq and ripgrep, it bridges the gap between short-term memory and long-term session history, allowing for deep context retrieval and interaction auditing.

Use Cases

  • 1. Long-term Context Retrieval: Finding specific information, past decisions, or user preferences from older or parent conversations that are no longer present in the active context window.
  • 2. Usage and Cost Auditing: Calculating total token costs and message counts for individual sessions or generating daily financial summaries to monitor API expenditure.
  • 3. Interaction Analytics: Using jq filters to extract specific message roles or tool calls to analyze agent performance and refine prompt engineering strategies.
  • 4. Global Keyword Discovery: Rapidly scanning the entire directory of session logs for specific phrases or topics using ripgrep to locate relevant historical threads.
namesession-logs
descriptionSearch and analyze your own session logs (older/parent conversations) using jq.
metadata{"clawdbot":{"emoji":"📜","requires":{"bins":["jq","rg"]}}}

session-logs

Search your complete conversation history stored in session JSONL files. Use this when a user references older/parent conversations or asks what was said before.

Trigger

Use this skill when the user asks about prior chats, parent conversations, or historical context that isn’t in memory files.

Location

Session logs live at: ~/.clawdbot/agents/<agentId>/sessions/ (use the agent=<id> value from the system prompt Runtime line).

  • sessions.json - Index mapping session keys to session IDs
  • <session-id>.jsonl - Full conversation transcript per session

Structure

Each .jsonl file contains messages with:

  • type: "session" (metadata) or "message"
  • timestamp: ISO timestamp
  • message.role: "user", "assistant", or "toolResult"
  • message.content[]: Text, thinking, or tool calls (filter type=="text" for human-readable content)
  • message.usage.cost.total: Cost per response

Common Queries

List all sessions by date and size

for f in ~/.clawdbot/agents/<agentId>/sessions/*.jsonl; do
  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
  size=$(ls -lh "$f" | awk '{print $5}')
  echo "$date $size $(basename $f)"
done | sort -r

Find sessions from a specific day

for f in ~/.clawdbot/agents/<agentId>/sessions/*.jsonl; do
  head -1 "$f" | jq -r '.timestamp' | grep -q "2026-01-06" && echo "$f"
done

Extract user messages from a session

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

Search for keyword in assistant responses

jq -r 'select(.message.role == "assistant") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl | rg -i "keyword"

Get total cost for a session

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

Daily cost summary

for f in ~/.clawdbot/agents/<agentId>/sessions/*.jsonl; do
  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
  cost=$(jq -s '[.[] | .message.usage.cost.total // 0] | add' "$f")
  echo "$date $cost"
done | awk '{a[$1]+=$2} END {for(d in a) print d, "$"a[d]}' | sort -r

Count messages and tokens in a session

jq -s '{
  messages: length,
  user: [.[] | select(.message.role == "user")] | length,
  assistant: [.[] | select(.message.role == "assistant")] | length,
  first: .[0].timestamp,
  last: .[-1].timestamp
}' <session>.jsonl

Tool usage breakdown

jq -r '.message.content[]? | select(.type == "toolCall") | .name' <session>.jsonl | sort | uniq -c | sort -rn

Search across ALL sessions for a phrase

rg -l "phrase" ~/.clawdbot/agents/<agentId>/sessions/*.jsonl

Tips

  • Sessions are append-only JSONL (one JSON object per line)
  • Large sessions can be several MB - use head/tail for sampling
  • The sessions.json index maps chat providers (discord, whatsapp, etc.) to session IDs
  • Deleted sessions have .deleted.<timestamp> suffix

Fast text-only hint (low noise)

jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' ~/.clawdbot/agents/<agentId>/sessions/<id>.jsonl | rg 'keyword'