| name | session-logs |
| description | Search and analyze session logs (older/parent conversations) using jq. |
| requiredBins | ["jq","rg"] |
| version | 1.0.0 |
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 under the active state directory:
$STATE_DIR/agents/<agentId>/sessions/.
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
AGENT_ID="<agentId>"
SESSION_DIR="$HOME/.state/agents/$AGENT_ID/sessions"
for f in "$SESSION_DIR"/*.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
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
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
AGENT_ID="<agentId>"
SESSION_DIR="$HOME/.state/agents/$AGENT_ID/sessions"
rg -l "phrase" "$SESSION_DIR"/*.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