README.md

---
license: mit
tags:
  - openclaw
  - sidecar
  - session-review
  - fastapi
---

# Session Amplifier

Lightweight OpenClaw sidecar for transcript spooling and session review.

## What it does

- **Spooler** — walks `~/.openclaw/agents/<agent>/sessions/*.jsonl`, cleans/redacts tool results, stores summaries to SQLite
- **Reviewer** — scores sessions for quality/failure patterns, detects unused tools/skills, surfaces recommendations
- **Snapshot adapter** — exposes canonical `openclaw.session.v1` session snapshots for dashboards/reviewers without gateway core patches
- **API** — FastAPI server on port 8477 with 4 endpoints

## Quick start

```bash
# Install deps
pip install -r requirements.txt

# Init DB
python main.py init

# Run once (spool or review)
python main.py spool
python main.py review

# Start API server
python main.py serve

# Watch transcript files and spool on changes
python main.py watch --interval 5
```

## Running Tests

The application uses `pytest` for testing. The tests use an in-memory SQLite database and do not require filesystem access.

```bash
# Run all tests
pytest tests/
```

## Docker / container run path

```bash
cd sidecar/session-amplifier
docker compose up -d --build
```

Manual equivalent:

```bash
docker build -t session-amplifier sidecar/session-amplifier/
docker run -p 8477:8477 \
  -v ~/.openclaw:/openclaw:ro \
  -v session_amplifier_state:/data/session-amplifier \
  -e OPENCLAW_AGENTS_ROOT=/openclaw/agents \
  -e OPENCLAW_STATE_DIR=/data/session-amplifier \
  session-amplifier serve
```

Host note: the bare host Python environment may not have `uvicorn` / `fastapi` installed. The intended live-service path is the container.

Gateway integration note: when OpenClaw runs in Docker, gateway-side scripts should target the sidecar by container hostname, not `localhost`. Default wrapper target is `SESSION_AMPLIFIER_BASE_URL=http://session-amplifier:8477`. The sidecar compose file joins the external `librechat_default` network so the gateway container can resolve it.

## API endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Container health + version |
| POST | `/spool` | Trigger incremental spooling |
| GET | `/review/report` | Fetch latest review report |
| GET | `/review/skills` | Fetch skill/MCP coverage report |
| GET | `/sessions/recent` | Recent sessions with activity/error counts |
| GET | `/sessions/snapshots` | Recent sessions as canonical `openclaw.session.v1` snapshots |
| GET | `/session/{id}/snapshot` | One canonical `openclaw.session.v1` snapshot |
| GET | `/session/{id}/activity` | Normalized per-session activity feed |

## Config (env)

| Var | Default | Description |
|-----|---------|-------------|
| `OPENCLAW_AGENTS_ROOT` | `~/.openclaw/agents` | Transcript source |
| `OPENCLAW_STATE_DIR` | `~/.openclaw/workspace/ops/state` | SQLite + artifacts output |
| `MAX_TOOLRESULT_CHARS` | `2000` | Truncate threshold |
| `SPOOLER_BATCH_SIZE` | `100` | DB insert batch size |
| `REVIEW_CONFIDENCE_THRESHOLD` | `0.5` | Min confidence for recommendations |
| `API_PORT` | `8477` | HTTP server port |

## Package layout

```
session-amplifier/
├── config.py            # Env/config loading
├── main.py              # CLI entrypoint (init/serve/serve-watch/spool/review/watch)
├── requirements.txt
├── Dockerfile
├── spooler/
│   ├── processor.py     # JSONL → spooled rows
│   ├── redaction.py     # API key / path / base64 redaction
│   ├── noise_filter.py  # Drop known-noise tool output
│   └── store.py         # SQLite read/write
├── reviewer/
│   ├── scorer.py        # Session quality scoring
│   ├── pattern_detector.py  # Recurring failure detection
│   ├── skill_analyzer.py    # MCP/skill coverage
│   └── report.py        # Report generation + persistence
├── api/
│   └── routes.py        # FastAPI route handlers
└── tests/
    └── ...              # pytest suite
```

## Architecture notes

- Reads-only from `OPENCLAW_AGENTS_ROOT`; never modifies transcripts
- Idempotent spooling via `UNIQUE(session_id, entry_idx)` constraint
- **Incremental spooling**: Uses tracked `last_entry_idx` file state to only parse lines appending to existing files, drastically reducing processing time overhead.
- Reviewer is deterministic (no LLM required in v1); recommendations scored by confidence threshold
- Watch mode is polling-based in v1 for simplicity; `python main.py watch --interval 5` or `serve-watch`
- By default `serve-watch` / `watch` only triggers spooling. To optionally trigger the reviewer append `--review-every <N>`.
- Manual trigger remains available for cron/recovery: `POST /spool` → wait → `GET /review/report`
- A simple CLI-style live monitor is available at `/home/node/.openclaw/workspace/ops/scripts/session_amplifier_live_monitor.py`
- Snapshot endpoints are read-only and sidecar-local. Rollback is removing `reviewer/session_snapshot.py`, the two route handlers/imports in `api/routes.py`, and the snapshot smoke test; no gateway config change is required unless the service was rebuilt/redeployed.

## Troubleshooting

- **API keys exposed in tool outputs?** Check `SPOOLER_REDACT_PATTERNS`.
- **Database lock errors?** Multiple cron instances might be racing. Restart with a clean volume or disable concurrent spool calls.
- **Reporting "No data"?** Ensure `OPENCLAW_AGENTS_ROOT` path exists inside the container and matches host volume bindings.