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

1. Detect continuity intent — user implies prior context you don't have
2. Try list first — scan session previews to narrow down candidates
3. Then search if you have keywords, or pick a session from the list
4. read the file at the returned line numbers (offset/limit) to load context
5. 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