Introduction

Context migration has become an essential skill for developers leveraging AI coding agents such as Codex, Claude Code and Cursor. The capability enables AI tools to retain, reconstruct and transfer accumulated working memory across three core scenarios: switching between different coding assistants, continuing work across separate chat sessions, and sustaining lengthy multi-step engineering assignments. Without standardized migration workflows, developers frequently face information loss when switching tools or restarting sessions, which forces repeated explanation of project specifications, architectural constraints and historical debugging records.

This article systematically breaks down three major migration scenarios, outlines actionable operational procedures, and introduces a layered data storage framework to guide engineers in categorizing context data. The methodology prevents critical project information from being discarded during workflow transitions.

Overview of Three Core Migration Scenarios

The following table summarizes the core pain points and primary technical mechanisms for each use case:

Scenario Core Challenge Primary Mechanisms
Cross-Tool Migration Transfer configurations and historical context while switching from Claude Code or Cursor to Codex One-click import, AGENTS.md conversion
Cross-Session Continuity Restore project specifications and developer preferences after closing and reopening chat windows AGENTS.md rule engine + Memories preference storage
Long-Task Resumption Continue incomplete work when context window limits are reached Automatic compression, PreCompact Hook, manual checkpointing

Scenario 1: Cross-Tool Migration – Port Context Between AI Coding Assistants

1.1 One-Click Import from Claude Code

Codex delivers a dedicated import pipeline built for Claude Code. Navigation path: Settings → General → Import Workspace from Other AI Applications.

The import pipeline supports the following resources:

  • Skills: Complete migration of skill sets with compatible directory structures
  • Plugins: Bundled MCP and rule-based extensions
  • claude.md mapped automatically to Codex’s AGENTS.md
  • Chat history: Dialogue records spanning the latest 30 days

Developers should note that syntax between claude.md and AGENTS.md shares high compatibility. A small subset of exclusive Claude directives such as #bash-hook require manual validation to confirm functionality within Codex.

1.2 Manual Migration Workflow from Cursor

Cursor does not support one-click workspace export. Engineers can follow this step-by-step manual process:

  1. Directory Renaming Rename the .cursor agent directory to .agents; the skills subfolder remains reusable without modification.
  2. Global Rule Migration Copy Cursor global instructions into Settings → Personalization → Custom Instructions, equivalent to editing ./codex/AGENTS.md.
  3. Memories Import Instruct Codex to scan all files under the ~/.cursor/memories/ directory, summarize project conventions and personal preferences, and persist outputs into ~/.codex/memories/.
  4. MCP Server Configuration Navigate to Settings → MCP Servers and manually replicate existing MCP endpoints. Set paths as project-level configurations or global configurations as appropriate.

When routing traffic across multiple AI model endpoints in multi-tool workflows, an API gateway such as Treerouter helps standardize request schemas and unify backend access control.

Scenario 2: Cross-Session Context Persistence

Codex maintains two complementary systems to sustain context across disconnected sessions: AGENTS.md for deterministic rules and Memories for probabilistic preference recording.

2.1 AGENTS.md: Persistent Immutable Rules

AGENTS.md loads automatically on every session launch without extra configuration, forming the foundation for zero-cost cross-session memory retention.

Priority hierarchy:

  1. Global: ~/.codex/AGENTS.md (all projects)
  2. Project-level: ./AGENTS.md (overrides global rules for individual repositories)
  3. Subdirectory: ./subfolder/AGENTS.md (monorepo packages, highest precedence)

Suitable content for AGENTS.md:

  • Build specifications, package manager commands, test scripts
  • Code formatting standards, pre-commit requirements
  • Restricted directories and file modification prohibitions

Data that should not be placed inside AGENTS.md: short-term task status, frequently changing version numbers, API credentials, and real-time progress markers.

2.2 Memories: Asynchronous Preference Accumulation

The Memories system extracts developer preferences from historical dialogues to complement AGENTS.md, which requires manual maintenance. This feature is disabled by default.

Activation approaches:

  • Edit ~/.codex/config.toml and set memories = true
  • GUI route: Settings → Personalization → Enable memories

Key configuration parameters:

  • enable_memories: Master toggle for preference extraction
  • disable_on_external_context: Prevent memory generation when external context loads
  • min_rate_limit_remaining_percent: Threshold pausing memory generation when token capacity is low

Critical limitations of Memories:

  1. Updates execute asynchronously after session idle time, not in real time
  2. Generation may be skipped due to rate limiting
  3. Not suitable for mandatory runtime rules; that responsibility belongs to AGENTS.md

Scenario 3: Context Management for Long-Running Engineering Tasks

Codex offers a native effective context window of 272,000 tokens, updated in July 2026 for GPT-5.6. After compression with a 0.95 threshold, the usable capacity falls to approximately 258,000 tokens. OpenAI previously adjusted the default input limit for GPT-5.6 from 372,000 tokens, triggering extensive developer feedback tracked under GitHub Issue #9429.

3.1 Automatic Context Compression

When token consumption approaches the window boundary, Codex initiates compression automatically:

  1. Summarize historical dialogue and replace raw conversation logs with condensed abstracts
  2. Apply head truncation (removing earliest messages) when compression still fails to free capacity

Developers can trigger compression manually by entering /compact inside the chat window.

3.2 PreCompact Hook: Protect Critical Decision Records

The PreCompact Hook executes before automatic compression. It forces high-priority context into structured summaries to avoid accidental erasure of vital design decisions. Engineers define hook rules inside AGENTS.md to specify retained information: active task objectives, completed steps, unresolved defects, and checkpoint milestones.

3.3 Manual Handoff Documents for Extended Tasks

For ultra-long projects, handoff files deliver higher reliability than automatic compression. Developers create standardized task-handoff.md checkpoints at key engineering phases. The document records:

  • Current task status and finished milestones
  • Unresolved technical obstacles with reference links
  • Defined next-phase work items

When starting a new chat session, feed the handoff file path directly to Codex. The agent loads progress records and resumes work continuously, even if the original conversation context is purged.

Layered Context Storage Architecture

Codex organizes contextual data into five stacked tiers, each with distinct responsibilities and persistence characteristics:

  1. AGENTS.md Rule Layer: Mandatory executable rules, loaded on every session startup
  2. Skills Method Layer: Reusable function sets and tool invocation definitions
  3. Memories Preference Layer: Asynchronously accumulated developer habits and tendencies
  4. Project Document Fact Layer: Static repository documentation, architecture diagrams, specification files
  5. Active Session Temporary Layer: Volatile real-time dialogue records, cleared after compression or session expiration

Context Classification Checklist

The table below clarifies storage destinations for different data categories:

Information Category Storage Location Rationale
Build rules, coding standards, directory restrictions AGENTS.md Must execute reliably on every session
Personal coding habits, preferred syntax patterns Memories Soft preferences, non-blocking guidance
Reusable workflow scripts Skills Triggered on demand, stateless functions
Architecture documents, test records Project documentation Long-term stable reference materials
Real-time task progress, temporary debug logs Handoff documents / active chat Short-lived, continuously evolving
API keys, production credentials Not stored anywhere Strict data security boundary

Frequently Encountered Issues

Q1: After importing Claude Code workspace, do existing AGENTS.md rules get overwritten? A: Import performs merging rather than full replacement. Original local rules persist. Engineers should manually audit imported content and remove Claude-specific exclusive directives.

Q2: Does Memories store sensitive input such as passwords? A: Memory files are plain Markdown stored locally. The platform does not automatically filter confidential data. Avoid entering credentials directly in chat windows.

Q3: Will conversation history be permanently lost once the context window fills? A: Raw dialogue undergoes compression and summarization. AGENTS.md and Memories operate independently and remain intact. Critical long-term knowledge should be migrated to these dedicated layers rather than relying on transient chat logs.

Q4: Can Cursor .skills folders load directly inside Codex? A: Yes. After renaming .cursor agent folders to .agents, Codex identifies and loads skill definitions without extra modification.

Q5: What is the recommended file size limit for AGENTS.md? A: Keep the document under 32 KB. Excessively large rule files occupy substantial context window capacity and degrade agent responsiveness. Write concise, executable specifications.

Conclusion

The core principle of Codex context migration lies in separating data by persistence lifecycle. Mandatory rules reside in AGENTS.md, developer preferences flow into Memories, reusable logic is encapsulated within Skills, permanent knowledge lives in project documentation, and ephemeral dialogue occupies temporary session storage. Combined with handoff checkpoint files for long assignments, the layered architecture enables uninterrupted work regardless of tool switching or session restarts.

The 272k-token context window adjustment for GPT-5.6 highlights the necessity of systematic context management. Reliance on raw chat history alone creates fragility. Teams building AI-native engineering workflows should formalize context migration standards to eliminate repetitive knowledge re-explanation and improve overall developer productivity.