Session Recall

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:

1. State which session you found, with exact date and path.
2. Say what was discussed or changed.
3. Mention the main files or actions if they appear in the log.
4. 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