back
loading skill details...
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...
---
name: session-recall
description: "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 message assumes shared context you don't have (they reference people, events, decisions, or topics not present in your current context), (2) user explicitly refers to a previous conversation ('continue where we left off', 'as we discussed', 'remember when...'), (3) you need to find a specific past discussion by keyword or time range. Key signal: if you find yourself about to reply 'I don't have context' or 'which topic are you referring to' — use this skill FIRST before asking the user to repeat themselves."
---
# 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:
```bash
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:
```bash
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:
```bash
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:
```bash
# 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
don't have the plugin yet? install it then click "run inline in claude" again.
restructured raw skill into implexa's six-part format, formalized external dependencies (agent ID, file system access), added explicit decision points for search strategy and pagination, clarified output contracts with exact formats, and added edge cases like zero results and large files.
Search OpenClaw session transcript JSONL files to locate past conversations. returns file paths and line numbers. read the relevant lines yourself to recover context.
use this skill when the current session is new or sparse and the user's message assumes shared context you don't have (they reference people, events, decisions, or topics absent from your current thread), or when they explicitly invoke a past conversation ("continue where we left off", "remember when we talked about..."). use it as a reflexive check before replying "i don't have context" or "which topic are you referring to". the skill searches transcript files by keyword, time range, or session metadata to pinpoint exactly where past discussions occurred.
agent:AGENTID:...). if unknown, run agents command to list. optional to search all agents, but filtering by agent ID is faster.search command; list works without them.--start and --end parameters in relative format (7d, 2h), absolute date (2026-03-01), or datetime (2026-03-01T14:00). defaults to all time if omitted.SKILL_DIR with the actual path where session-recall.py lives when invoking commands.detect continuity intent. user's message references context not present in current session (names, past decisions, specific topics, or explicit recall phrases like "as we discussed"). if unsure, proceed to step 2.
identify agent ID. extract your agent ID from session metadata or run python3 SKILL_DIR/scripts/session-recall.py agents to list available agents and their session counts.
choose search strategy based on clarity.
list command with time range to scan session previews.search command with those keywords.run list command (if vague):
python3 SKILL_DIR/scripts/session-recall.py list --agent AGENT_ID --start 7d --limit 10
output shows file paths, time ranges, turn counts, and first-message previews. scan previews to identify which sessions contain relevant discussions. note the file path.
run search command (if keywords exist):
python3 SKILL_DIR/scripts/session-recall.py search "keyword phrase" --agent AGENT_ID --start 7d --limit 20
output shows file paths with line numbers where keyword appears (e.g. /path/to/session.jsonl:142). note the file path and line number.
read the transcript file. use the file path and line number from steps 4 or 5. read approximately 30 lines surrounding the target line to capture context. mentally load the relevant passage(s).
continue conversation with recovered context. respond to the user's current message using the context you just loaded. reference the past discussion if helpful.
if user's message clearly references past context but you have no keywords: use list to scan session previews. pick the most likely session and read it.
if user provides specific keywords or topic names: use search directly with those keywords. skip list if you already know the approximate timeframe.
if search returns zero results: either the topic was never discussed, or it's outside the time window you specified. widen the --start parameter (e.g. 30d instead of 7d) and retry. if still empty, ask the user for more context (dates, participant names, or keywords).
if search returns many results (hitting --limit): use pagination with --offset to view the next batch, or narrow the keyword query to be more specific.
if you do not have agent ID or it's unclear: run agents command first to list available IDs and their session counts. search all agents by omitting --agent parameter if necessary, though it's slower.
if session file is very large (hundreds of lines): do not load the entire file. use --offset and --limit parameters to read selectively. focus on the line numbers returned by search results.
if time range is unknown: omit --start and --end to search all time. this is slower but guarantees you won't miss old discussions.
list command output: plain text lines formatted as /path/to/session.jsonl [MM-DD HH:MM ~ HH:MM] N turns "first message preview...". each line is one session. use file path for subsequent read calls.
search command output: plain text lines formatted as /path/to/session.jsonl:LINE_NUMBER [MM-DD HH:MM] speaker: ...context snippet.... colon separates file path from line number. use file path and line number for reading.
agents command output: plain text list of available agent IDs with session counts (e.g. agent1: 45 sessions, agent2: 12 sessions).
file location: all JSONL transcript files are stored on disk in the OpenClaw transcript directory. script accesses them directly. no external URLs or remote API calls.
data format: transcripts are newline-delimited JSON (JSONL). each line is a message object containing at least speaker, text, and timestamp fields. script searches raw text; you parse the JSON yourself if needed.
success: you locate the session file and line number(s) where the past discussion occurred. you read the relevant transcript lines and recover the missing context. your next response to the user references or incorporates that recovered context, demonstrating you now understand what they were referring to. user confirms with "yes, that's what i meant" or continues the conversation without re-explaining.
failure: search returns zero results and you have exhausted reasonable time ranges and keyword variations. you've read multiple candidate sessions and found nothing. at this point, ask the user for more specific details (dates, participant names, or exact phrases they remember) before trying again.