engineofperplexity/openclaw-session-amplifier

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

# 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.

# Run all tests
pytest tests/

Docker / container run path

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

Manual equivalent:

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.