Session Recall
Search OpenClaw session transcript JSONL files to locate past conversations. Returns file paths and line numbers — read the relevant lines yourself to recover context.
When to Use
- Missing context signal: Current session is new/short AND the user's message references people, events, decisions, or topics not present in your context — they clearly assume you know something you don't
- Explicit recall: User says things like "continue where we left off", "as we discussed", "remember when we talked about..."
- Self-check: You're about to reply "I don't have context" or "which topic are you referring to" — stop and use this skill first before asking the user to repeat themselves
- You need to find when/where a specific topic was discussed
Commands
List available agents
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).
List recent sessions
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.
Search by keyword
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.
Time Parameters
--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- Omit
--end to include everything up to now
- Omit both to search all time
Pagination
Use --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.
All Parameters
| 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. |
Workflow
- Detect continuity intent — user implies prior context you don't have
- Try
list first — scan session previews to narrow down candidates
- Then
search if you have keywords, or pick a session from the list
read the file at the returned line numbers (offset/limit) to load context- Continue the conversation with recovered context
Important Notes
- Replace
SKILL_DIR with the actual skill directory path when calling
- Only search your own agent's sessions by default
- The tool does NOT use LLM — it's pure text search, fast and free
- For vague queries with no keywords: use
list, scan previews, then read promising sessions
- Large sessions may have hundreds of lines — read selectively, don't load entire files
- Use
--offset to paginate when --limit doesn't cover all results
