| name | session-recall |
| description | Recover and summarize prior Codex conversations from local Codex history and session logs. Use when the user asks what happened in a previous chat, asks to "remember" past work, wants the last or previous session, gives a specific date or approximate time, wants to search old dialogs by keyword/topic/project, or asks to inspect Codex files/config for prior conversation context. |
Session Recall
Use local Codex logs instead of claimed model memory. Base the answer only on files found under CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}".
Primary Files
$CODEX_HOME_DIR/history.jsonl: fastest way to see recent user messages and map them to session_id$CODEX_HOME_DIR/session_index.jsonl: thread names and timestamps$CODEX_HOME_DIR/sessions/YYYY/MM/DD/*.jsonl: full session transcripts$CODEX_HOME_DIR/archived_sessions/*.jsonl: fallback for older moved sessions
Treat config.toml, state_*.sqlite, and logs_*.sqlite as fallback only. Conversation recall should usually come from history.jsonl and sessions/.../*.jsonl.
Quick Workflow
- Identify the selector the user gave:
last, previous, specific date, date plus approximate time, keyword, project path, or session id.
- Start from
history.jsonl to find candidate session_id values and the user's own wording.
- Open the matching
sessions/.../*.jsonl file to reconstruct the conversation.
- Answer with exact date and time when possible, name the session file used, and summarize only what the logs show.
- If multiple sessions match, say that and present the nearest 2-3 candidates instead of guessing.
Common Retrieval Patterns
Last or Previous Session
Use:
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
tail -n 40 "$CODEX_HOME_DIR/history.jsonl"
ls -1t "$CODEX_HOME_DIR"/sessions/*/*/*/*.jsonl 2>/dev/null | head -10
If the user asks for the previous session while already in a new chat, do not return the current session. Pick the most recent distinct earlier session_id.
Specific Day
Use the exact calendar date, not relative wording:
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
ls -1 "$CODEX_HOME_DIR/sessions/YYYY/MM/DD"/*.jsonl 2>/dev/null
rg -n 'YYYY-MM-DD|keyword|session_id' "$CODEX_HOME_DIR/history.jsonl"
If the user says "yesterday" or "that day", convert it to an absolute date in the answer.
Approximate Time on a Day
List that day's session files and choose the nearest timestamp:
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
ls -1 "$CODEX_HOME_DIR/sessions/YYYY/MM/DD"/*.jsonl
Then open the closest candidate and verify by reading nearby user messages.
Keyword, Topic, or Project Search
Search both the lightweight index and the full transcripts:
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
rg -n 'CAMvisualD|virtual camera|docker|build|mic' \
"$CODEX_HOME_DIR/history.jsonl" \
"$CODEX_HOME_DIR/sessions" \
"$CODEX_HOME_DIR/archived_sessions"
Prefer the user's own exact phrase first, then broaden the search if needed.
Session ID Search
When a session_id is already known, resolve it directly:
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
find "$CODEX_HOME_DIR/sessions" "$CODEX_HOME_DIR/archived_sessions" \
-type f -name '*session-id-fragment*.jsonl' 2>/dev/null
Interpretation Rules
- Use
history.jsonl for quick mapping, not as the sole source for a full recap.
- Use the session JSONL for the real summary, because it contains assistant actions, tool calls, and final messages.
- Prefer exact dates and times in the response.
- State clearly when an answer is inferred from nearby matches rather than directly proven.
- Do not invent missing context.
- If the logs are absent or incomplete, say what was found and why it is insufficient.
Response Pattern
Keep the answer short and concrete:
- State which session you found, with exact date and path.
- Say what was discussed or changed.
- Mention the main files or actions if they appear in the log.
- Offer to open that session deeper or continue from that point.
Useful Commands
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
tail -n 40 "$CODEX_HOME_DIR/history.jsonl"
tail -n 20 "$CODEX_HOME_DIR/session_index.jsonl"
ls -1t "$CODEX_HOME_DIR"/sessions/*/*/*/*.jsonl 2>/dev/null | head -10
rg -n 'keyword' "$CODEX_HOME_DIR/history.jsonl" "$CODEX_HOME_DIR/sessions" "$CODEX_HOME_DIR/archived_sessions"
sed -n '1,120p' /path/to/session.jsonl
tail -n 120 /path/to/session.jsonl
