Import past client history
Use backfill to import local history, list providers, or preview a scan:
hyp backfill [provider...] [flags]
hyp backfill list [--json]hyp backfill --helphyp client history providers remains a compatibility alias of hyp backfill list.
Preview a scan with hyp backfill <provider> --dry-run.
hyp backfill
hyp backfill [provider...] [--since <iso>] [--until <iso>] [--retention-days <n>] [--dry-run] [--json]Scans selected providers, materializes records into live datasets, appends
rows, and flushes the cache. Provider failures don't stop sibling providers.
--dry-run runs the same full scan and projection and writes no row, so it
reports what an import would take at nearly the cost of one: only
materialization, the row write, and the cache flush are skipped.
Choose providers shown by hyp backfill list. The example below requires
both Claude and Codex capture to be enabled.
hyp backfill claude codex --since 2026-08-01T00:00:00Z --dry-runhyp backfill list
hyp backfill list [--json]Lists every registered backfill provider, not only providers selected as configuration defaults.
hyp backfill list --jsonScheduled recovery sweeps and backfill.window_days
Some adapters import history on a schedule to recover sessions missed by live capture:
| Plugin | Default interval | Does backfill.on_join: false stop scheduled recovery? |
|---|---|---|
@hypaware/codex (transcript mode) |
One minute | No (it is Codex's only capture lane) |
@hypaware/pi |
Five minutes | Yes |
@hypaware/droid |
Five minutes | Yes |
@hypaware/claude (also Claude Desktop) |
Five minutes | Yes |
@hypaware/cursor |
Five minutes | Yes |
@hypaware/openclaw |
Five minutes | Yes |
@hypaware/nanoclaw |
Five minutes | Yes (this is NanoClaw's only capture route) |
hyp client detach <client> stops every client's scheduled recovery, whatever
on_join says; hyp client attach <client> resumes it.
A positive backfill.window_days bounds both the join-time import and scheduled
recovery. Older sessions remain on disk but are not imported. Widening the
window makes older history eligible on the next run.
{ "name": "@hypaware/openclaw", "config": {
"backfill": { "window_days": 30 }
} }Without an explicit window, recovery uses query.cache.retention.default_days,
or 90 days if that setting is absent. A retention value of 0 means no age
limit. See retention configuration.
sweep_cron changes the recovery cadence and has no "never" value. For the
adapters marked Yes above, backfill.on_join: false stops automatic history
import: any separate live capture continues, and an explicit
hyp backfill <provider> still imports on demand. NanoClaw has no separate
live capture route, so disabling its schedule stops automatic capture entirely.
Detach when you want to stop all capture for a client.