# Session Recovery

> >

- **Type:** Skill
- **Install:** `agentstack add skill-songhonglei-better-agent-skills-session-recovery`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Songhonglei](https://agentstack.voostack.com/s/songhonglei)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Songhonglei](https://github.com/Songhonglei)
- **Source:** https://github.com/Songhonglei/better-agent-skills/tree/main/skills/session-recovery

## Install

```sh
agentstack add skill-songhonglei-better-agent-skills-session-recovery
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# session-recovery

- **Version**: 1.0.1
- **License**: MIT
- **Author**: Evan Song · [github.com/Songhonglei](https://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

```bash
# 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:

```bash
# 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](https://github.com/Songhonglei)
- **Source:** [Songhonglei/better-agent-skills](https://github.com/Songhonglei/better-agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-songhonglei-better-agent-skills-session-recovery
- Seller: https://agentstack.voostack.com/s/songhonglei
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.