Import Codex Sessions

This guide explains how to take preserved Codex session JSONL snapshots from the NEXUS object layer and append them into the canonical event store.

Use this after running the raw exporter:

dotnet fsi NEXUS-Code/scripts/export_codex_sessions.fsx

What This Does

The importer reads a preserved snapshot root such as:

  • NEXUS-Objects/providers/codex/latest/
  • NEXUS-Objects/providers/codex/archive/<timestamp>/

It then:

  • reads session_index.jsonl when present
  • reads transcript files under sessions/
  • canonicalizes user_message and agent_message records
  • writes append-only canonical events into the sibling NEXUS-EventStore/events/ repo
  • writes an import manifest into the sibling NEXUS-EventStore/imports/ repo
  • materializes an import-local graph working batch under NEXUS-EventStore/graph/working/imports/<import-id>/
  • updates the graph working catalog under NEXUS-EventStore/graph/working/catalog/import-batches.toml
  • refreshes the local SQLite working index under NEXUS-EventStore/graph/working/index/graph-working.sqlite

In v1, richer Codex runtime records such as function calls, tool outputs, reasoning, token counts, and other non-message events remain preserved only in raw JSONL.

Command

Run this from the repository root:

dotnet run --project NEXUS-Code/src/Nexus.Cli/Nexus.Cli.fsproj -- import-codex-sessions

Optional Arguments

Import from a specific snapshot or override roots:

dotnet run --project NEXUS-Code/src/Nexus.Cli/Nexus.Cli.fsproj -- import-codex-sessions \
  --snapshot-root /home/ivan/NEXUS/NEXUS-EMERGING/NEXUS-Objects/providers/codex/archive/2026-03-22T16-03-56Z \
  --objects-root /home/ivan/NEXUS/NEXUS-EMERGING/NEXUS-Objects \
  --event-store-root /home/ivan/NEXUS/NEXUS-EventStore

If you omit --event-store-root, the CLI now resolves it from NEXUS_EVENT_STORE_ROOT, an in-repo transition copy if present, or the sibling ../NEXUS-EventStore repo.

Normalization Behavior

  • conversations are keyed by Codex session ID
  • message identities are stable per transcript line, so re-imports dedupe cleanly
  • repeated imports of the same snapshot should mostly append only import-stream events
  • future parser upgrades append re-observations under a different normalization version rather than pretending the provider revised older messages

If you want the imported Codex state explicitly linked to a Git commit, prefer the higher-level checkpoint flow instead of running export and import separately:

dotnet run --project NEXUS-Code/src/Nexus.Cli/Nexus.Cli.fsproj -- capture-codex-commit-checkpoint

Otherwise, after importing, rebuild conversation projections:

dotnet run --project NEXUS-Code/src/Nexus.Cli/Nexus.Cli.fsproj -- rebuild-conversation-projections

You can also inspect or visualize the fresh graph working batch without a full durable graph rebuild:

dotnet run --project NEXUS-Code/src/Nexus.Cli/Nexus.Cli.fsproj -- report-working-graph-imports
dotnet run --project NEXUS-Code/src/Nexus.Cli/Nexus.Cli.fsproj -- report-working-graph-batch --import-id <import-id>
dotnet run --project NEXUS-Code/src/Nexus.Cli/Nexus.Cli.fsproj -- export-graphviz-dot --working-import-id <import-id>

The refreshed SQLite working index is derived local state. Keep the import batches and canonical history; rebuild the index locally when needed instead of treating it as a committed source artifact.