Session Recovery

session-recovery

• Version: 1.0.1
• License: MIT
• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/better-agent-skills

> Recover lost agent session content and file changes from on-disk conversation logs. > > 从本地会话日志中找回丢失的 agent 对话和文件改动。

Built for OpenClaw's on-disk session format (~/.openclaw/agents//sessions/*.jsonl). Streaming and OOM-safe for production-scale environments (5000+ sessions, 700MB+ daily JSONL).

Compatibility

| Platform | Status | |---|---| | OpenClaw | ✅ Full (primary target) | | Other agent frameworks (CC / Codex / Hermes) | 🛣️ Roadmap | | Linux | ✅ Full | | macOS | ✅ Full | | Windows (WSL) | ✅ Full | | Python | ≥ 3.8 (uses pathlib, datetime.fromisoformat) |

Quick start

# Search recent sessions for a keyword
python3 scripts/search.py "index.html" --days 2

# Search by specific date, also list write/edit ops
python3 scripts/search.py "skill logo" --date 2026-06-13 --extract-files

# Search all agents
python3 scripts/search.py "anything" --agent all

# Filter by real msg timestamp (slower, more accurate when mtime lies)
python3 scripts/search.py "stuff" --days 7 --by-content-time

# JSON output for agent consumption
python3 scripts/search.py "stuff" --json

# Once you know the session ID, extract file ops
python3 scripts/extract.py 21f68359 --file-filter index.html

# Show full content (warning: can be large)
python3 scripts/extract.py 21f68359 --file-filter index.html --show-content

# Restore to original path (non-interactive needs --yes)
python3 scripts/extract.py 21f68359 --file-filter index.html --restore --yes

# Restore to a specific path
python3 scripts/extract.py 21f68359 --restore-to ~/out/index.html --yes

# Pure-edit session (no write baseline): replay edits to rebuild
python3 scripts/extract.py 21f68359 --file-filter app.py --rebuild \
    --restore-to ~/out/app.py --yes

Custom data root

If your OpenClaw install puts agents elsewhere, override:

# Per-call
python3 scripts/search.py "foo" --root /custom/openclaw/agents

# Or environment variable
export SESSION_RECOVERY_ROOT=/custom/openclaw/agents
python3 scripts/search.py "foo"

Priority: --root > SESSION_RECOVERY_ROOT env > ~/.openclaw/agents/.

Data sources

Primary: JSONL conversations at //sessions/*.jsonl (always present). Contains full tool calls, including write content and edit deltas.

Secondary (OpenClaw-specific): QMD archive at //qmd/sessions/*.md (may not exist on all installs). Plain-text dialogue; survives session reset but does NOT contain full code — use for finding which session, then extract from JSONL.

Recovery priority: non-reset JSONL > reset+QMD > QMD only > reset only.

Safety

• Restore refuses silent overwrites in non-TTY environments. You must pass --yes

to confirm in agent / CI / script contexts.

• Target-already-exists is warned even with --yes (writes are destructive).
• --show-content prints full file content which may be huge — prefer

--restore-to for large files, or preview first.

• --max-files N is an OOM guard (default 300). When hit, output explicitly

flags "may have missed results"; narrow the time window or raise the limit.

Notes

• Session IDs support prefix match (first 8 hex chars usually enough).
• Time filter defaults to file mtime, which can lie if a session was last

modified hours after its content was written. Use --by-content-time for accurate (slower) filtering by real message timestamps.

• --limit is per agent, per source. With --agent all total results

multiply by agent count and source count.

• Field-name compatibility built in: write/edit ops accept any of

file_path|path, content|new_string|newText, oldText|old_string, arguments|input|parameters.

License

MIT (see LICENSE)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Songhonglei
• Source: Songhonglei/better-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.