Search past session transcripts to recover lost conversation context. MUST use when: (1) the current session is new or has very few messages AND the user's m...
Search OpenClaw session transcript JSONL files to locate past conversations. Returns file paths and line numbers — read the relevant lines yourself to recover context.
Discover which agent IDs exist and how many sessions each has:
python3 SKILL_DIR/scripts/session-recall.py agents
Use this to find valid agent IDs before searching. Your own agent ID is typically visible in your session key (e.g. agent:myagent:... → agent ID is myagent).
Show sessions with time range, turn count, and first message preview:
python3 SKILL_DIR/scripts/session-recall.py list --agent AGENT_ID --start 48h --limit 10
Output example:
/path/to/session.jsonl [03-08 02:15 ~ 03:35] 32 turns "Can you look into the impact of..."
Use this when the user's query is vague — scan previews to identify the right session, then read into it.
Find specific mentions across transcripts:
python3 SKILL_DIR/scripts/session-recall.py search "keyword" --agent AGENT_ID --start 7d --limit 20
Output example:
/path/to/session.jsonl:142 [03-08 02:15] user: ...the keyword appears here in context...
The number after : is the line number. Use read --offset LINE --limit 30 to read surrounding context.
--start and --end define the time window for filtering sessions.
| Format | Example | Meaning |
|---|---|---|
| Relative duration | 30m, 6h, 2d, 1w, 3mo | Minutes/hours/days/weeks/months ago |
| Absolute date | 2026-03-01, 03-01 | Specific date (midnight) |
| Absolute datetime | 2026-03-01T14:00 | Specific date and time |
| Keyword | today, yesterday | Start of today/yesterday |
--start 7d → sessions from the last 7 days--start 2026-02-01 --end 2026-02-28 → sessions within February--end yesterday → sessions before today--end to include everything up to nowUse --offset and --limit to paginate through results:
# First page
session-recall list --start 30d --limit 10
# Second page
session-recall list --start 30d --limit 10 --offset 10
# Third page
session-recall list --start 30d --limit 10 --offset 20
The tool prints Showing X-Y of Z when there are more results beyond the current page.
| Parameter | Description |
|---|---|
--agent | Agent ID. Run session-recall agents to list available IDs. Omit to search all. |
--start | Start of time window. Accepts durations, dates, datetimes, or keywords. |
--end | End of time window. Same formats as --start. Omit for "up to now". |
--limit | Max results per page. Default: 20 for list, 30 for search. |
--offset | Skip N results for pagination. Default: 0. |
list first — scan session previews to narrow down candidatessearch if you have keywords, or pick a session from the listread the file at the returned line numbers (offset/limit) to load contextSKILL_DIR with the actual skill directory path when callinglist, scan previews, then read promising sessions--offset to paginate when --limit doesn't cover all resultsZIP package — ready to use