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