search-event-history

name	search-event-history
description	Search through past events in the event log files. Use when you need to look up something that happened previously but didn't store in memory.

Searching event history

Event logs are stored as JSONL files under $MNGR_AGENT_STATE_DIR/events/<source>/events.jsonl. You can search them using standard tools like grep and jq.

Be careful about how much data you load into context. Event files can be very large, and individual events can contain large payloads. Always inspect the shape and size of the data before loading full content.

You should generally prefer to use sub-agents or your delegate-task-to-agent skill for larger or more complex explorations of event history, but for quick lookups or simple queries, see below for some tips on how to search event logs directly.

Step 1: Find which sources exist

( cd $MNGR_AGENT_STATE_DIR/events/ && find -name events.jsonl -printf '%h\n' | sed 's|^\./||' )

Step 2: Understand the data before loading it

Before reading event content, check how large the fields are to avoid pulling huge payloads into context:

# See the size (in characters) of each field for each event
cat "$MNGR_AGENT_STATE_DIR/events/<source>/events.jsonl" | tail -20 | jq -c '[to_entries[] | .value = (.value | tojson | length)] | from_entries'

This tells you which fields are small (IDs, timestamps) and which are large (content, data payloads). Only load the fields you actually need.

Step 3: Search with targeted queries

Find events matching a pattern

grep '<pattern>' "$MNGR_AGENT_STATE_DIR/events/<source>/events.jsonl" | jq -c '[to_entries[] | .value = (.value | tojson | length)] | from_entries'

Extract specific fields only

When you know which fields you need, use jq to select only those fields:

# Get just timestamps and event types from recent events
tail -50 "$MNGR_AGENT_STATE_DIR/events/<source>/events.jsonl" | jq -c '{timestamp, type, event_id}'

# Get message metadata without loading content
tail -50 "$MNGR_AGENT_STATE_DIR/events/messages/events.jsonl" | jq -c '{timestamp, conversation_id, role, event_id}'

# Get content only for a specific conversation
grep '<conversation-id>' "$MNGR_AGENT_STATE_DIR/events/messages/events.jsonl" | jq -c '{role, content}'

Find events for a specific agent

grep '"<agent-id>"' "$MNGR_AGENT_STATE_DIR/events/mngr/agent_states/events.jsonl" | jq -c '{timestamp, state, event_id, agent_id}'

Find events in a time range

# Events after a specific timestamp
cat "$MNGR_AGENT_STATE_DIR/events/<source>/events.jsonl" | jq -c 'select(.timestamp > "2026-03-15T00:00:00")' | jq -c '[to_entries[] | .value = (.value | tojson | length)] | from_entries'

Guidelines

• Always limit output. Use tail, head, or jq select() to avoid loading entire log files into context, and use | jq -c '[to_entries[] | .value = (.value | tojson | length)] | from_entries' to restrict to just field sizes.
• Inspect field sizes first. Use the field-size query (step 2) before deciding which fields to load. A content field might be thousands of characters or more.
• Load only the fields you need. Use jq to project specific fields rather than loading full events.
• For aggregate event files (referenced by aggregate_events paths in aggregate events), be especially cautious -- always inspect field sizes before loading content.