# Session Recovery from Filesystem

When the gateway (or the container) restarts, `session_search` may appear empty because the in-memory session index has been cleared. The session files are still on disk.

## Symptom
- `session_search` returns `0 results` for queries that should match
- User says "you forgot everything"
- Gateway restart has occurred

## Cause
The gateway's session index is in-memory (SQLite `.sessions` table or in-memory cache). On restart, it rebuilds from the `.jsonl` files but may take time, or the container might not share state between restarts.

## Recovery

### 1. Read persistent memories
```bash
cat ~/.hermes/memories/USER.md
cat ~/.hermes/memories/MEMORY.md
```
These contain user profile, preferences, and durable environment state. They are unaffected by session restarts.

### 2. List raw session files
```bash
ls -lt ~/.hermes/sessions/*.jsonl | head -20
```
Each file is one session, JSONL format (one JSON object per line). Fields: `role`, `content`, `timestamp`.

### 3. Read specific sessions
The files are large; read the first 10-20 lines for metadata and the last 30 lines for the most recent exchanges:
```bash
head -n 20 ~/.hermes/sessions/20260511_094523_57fa76ca.jsonl
```

For full reconstruction, iterate over all sessions chronologically and extract `{"role":"user"}` and `{"role":"assistant"}` entries.

### 4. Check work directory
```bash
ls -la ~/.hermes/work/
```
Any files generated (3D models, documents, HTML, transcripts) persist across restarts.

### 5. Check config files
```bash
cat ~/.hermes/config.yaml          # model, provider, gateway settings
cat ~/.hermes/.env (mask secrets)  # tokens, keys
cat ~/.hermes/AGENTS.md            # custom operating rules
cat ~/.hermes/SOUL.md              # system prompt baseline
```

## ZimaOS / Docker / NAS Notes
On ZimaOS (CasaOS fork), Hermes may run inside a Docker container. The state is persisted via bind mounts:
- Host: `ZimaOS-HD/AppData/hermes`
- Container: `/DATA/AppData/hermes` or `/media/ZimaOS-HD/AppData/hermes`

If the container restarts but the directory is still mounted via the host filesystem, **all data is safe**. However:
- In-memory process state (running background tasks, active tmux sessions) is lost
- The SQLite `state.db` may need a moment to re-open
- `sessions.json` (the index) is rebuilt lazily

## Prevention
Save important session outcomes to:
1. `memory` tool → USER.md or MEMORY.md (durable, survives restarts)
2. `work/` directory for files/deliverables
3. `skills` for reusable workflows

Avoid relying solely on `session_search` for critical continuity — explicitly persist it.