Import AI session history

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

First time using AIWG? Begin with Install, Connect, and Verify. This guide assumes AIWG is already installed and connected to this project.

Use the session catalog when you want one privacy-aware timeline across multiple AI providers.

Install the catalog's SQLite runtime once and verify that its native module loads:

Use AIWG to complete this documented outcome: Install the catalog's SQLite runtime once and verify that its native module loads
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The installer uses a platform prebuild when one is available. On platforms without a compatible prebuild, `better-sqlite3` falls back to `node-gyp`; that requires Python 3, `make`, and a C/C++ compiler supported by your Node platform. Install those prerequisites and repeat the command if the runtime load check fails. AIWG keeps this native dependency in its user-owned optional feature root rather than adding it to every base installation.

From the project root, preview discovery first:

Use AIWG to complete this documented outcome: From the project root, preview discovery first
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Claude, Cursor, and Factory histories are discovered only below workspace-keyed provider roots. Codex keeps sessions in a shared root, so authorize it explicitly:

Use AIWG to complete this documented outcome: Claude, Cursor, and Factory histories are discovered only below workspace-keyed provider roots. Codex keeps sessions in a shared root, so authorize it explicitly
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The command reports every provider, including unavailable and manual-export providers, and saves an immutable manifest unless the dry-run option is present. Review it, preview the exact batch, then confirm:

Use AIWG to complete this documented outcome: The command reports every provider, including unavailable and manual-export providers, and saves an immutable manifest unless the dry-run option is present. Review it, preview the exact batch, then confirm
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

For non-interactive automation, the yes option is equivalent to the confirm option. Imports are resumable and idempotent:

Use AIWG to complete this documented outcome: For non-interactive automation, the yes option is equivalent to the confirm option. Imports are resumable and idempotent
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Read commands infer an unambiguous current project, so the normal follow-up is:

Use AIWG to complete this documented outcome: Read commands infer an unambiguous current project, so the normal follow-up is
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Both list and timeline report whether coverage is complete, partial, stale, or unknown. Use `the min-coverage option 0.95` when an audit should fail below a threshold. If inference reports multiple workspace candidates, rerun with the exact the workspace option shown in the diagnostic.

The catalog contains normalized AIWG copies. Discovery and import never modify provider histories, and source paths are redacted from public command output. Rejected entries in `import-discovered the json option` include an optional `detail`: resource limits report `limit`, `configured`, and `observed`; byte limits also report `setting` and `origin` (`flag`, `env`, `config`, or `default`); schema failures report `issues` containing only `path` and validator `code`. Paths use dotted field names and array indexes, with `<root>` for document-level failures. Hand-written checks use `custom`; invalid JSON uses `invalid_json`. At most 20 validator issues are included. The same detail appears in the diagnostic string and is preserved in stored batch runs and import failure receipts. For example, `{"limit":"maxBytes","configured":1024,"observed":2048}` identifies an authorized byte-limit rejection without exposing source content. Muse workspace inspection failures also retain this detail when available. Imports default to 64 MiB per record and 1 GiB (1,073,741,824 bytes) per source. Configure `sessions.import.max_record_bytes` and `sessions.import.max_source_bytes`, or pass the max-record-bytes option and the max-source-bytes option to `sessions import`, `sessions import-discovered`, or `index refresh`. You can also set `AIWG_SESSIONS_IMPORT_MAX_RECORD_BYTES` and `AIWG_SESSIONS_IMPORT_MAX_SOURCE_BYTES` to decimal byte counts, using the same integer ranges as config. Precedence is CLI flag > env var > workspace config > default. A source cap of `0` from any origin means unlimited and still streams JSONL imports. See the config reference. To skip a Codex rollout before reading it, add its native session ID or an absolute path glob to `sessions.import.exclude`. For example, either entry skips the same rollout:

{
  "sessions": {
    "import": {
      "exclude": [
        "12345678-1234-1234-1234-123456789abc",
        "~/.codex/sessions/**/rollout-*-12345678-1234-1234-1234-123456789abc.jsonl"
      ]
    }
  }
}

IDs match exactly using discovery metadata or the filename; sources are never parsed to decide exclusions. Path globs support `*`, `**` and `?`, and `~` expands to home. `AIWG_SESSIONS_IMPORT_EXCLUDE` adds comma-separated entries. Repeatable `the exclude option <id-or-glob>` adds entries for `sessions import-discovered` and `index refresh`:

Use AIWG to complete this documented outcome: IDs match exactly using discovery metadata or the filename; sources are never parsed to decide exclusions. Path globs support , and ?, and ~ expands to home. AIWG_SESSIONS_IMPORT_EXCLUDE adds comma-separated entries. Repeatable the exclude option <i
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Discovery, import and refresh report these sources as `excluded`, with the matching entry and kind (`session-id` or `path-glob`). They have their own `excluded` count and do not count as rejected or errors, cause partial-import warnings, or leave a sticky checkpoint. A previously rejected source now matching the list becomes excluded. Rediscover after removing a discovery exclusion to include that source again.

Use the agent-owned sessions operation for the complete command and JSON contracts.

Ask questions about collected history

Use the agent’s capability search and the agent’s stable-asset loader for questions such as “where did we decide this?”, “which tool kept failing?”, or “what changed between provider sessions?”. The skill covers scoped FTS5 queries, pagination, timelines, tool/HITL analytics, citations and coverage gaps.

`session-analyst` and the `session-investigation` flow collect and synthesize bounded evidence. `session-harvest` previews extraction and carries reviewed candidate versions through memory promotion. See the exploration recipes for acquisition, comparison, investigation, maintenance and handoff examples.

When rebuilding a catalog, retain its saved discovery manifest and use the agent-owned sessions operation. This rereads available sources and re-redacts history stored only in the old catalog. Keep the old copy until receipt counts, rejected sources, and redaction checks are reviewed. See the rebuild procedure.