# Import past client history

Canonical: https://hypaware.ai/docs/cli-reference/import-past-client-history

Use backfill to import local history, list providers, or preview a scan:

```text
hyp backfill [provider...] [flags]
hyp backfill list [--json]
```

```sh
hyp backfill --help
```

`hyp client history providers` remains a compatibility alias of `hyp backfill list`.
Preview a scan with `hyp backfill <provider> --dry-run`.

## `hyp backfill`

```text
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.

```sh
hyp backfill claude codex --since 2026-08-01T00:00:00Z --dry-run
```

## `hyp backfill list`

```text
hyp backfill list [--json]
```

Lists every registered backfill provider, not only providers selected as
configuration defaults.

```sh
hyp backfill list --json
```

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

```json
{ "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](https://hypaware.ai/docs/configuration/index.md#set-local-retention).

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