Claude Code vs Codex: Deep Architectural Comparison of AI Agent Memory Systems

1. Introduction: Why Memory Systems Are Core to Agent Architecture

AI Agent competitiveness lies not in single-turn reasoning but in cross-session knowledge persistence and context coherence . Memory systems determine whether agents evolve from "one-off tools" into "continuous collaboration partners."

1.1 The Essence of the Memory Problem

In LLM contexts, memory is fundamentally an information filtering and persistence problem within bounded context windows :

Limited context window : Token limits create information bottlenecks

Cross-session information fracture : All intermediate reasoning states lost after session ends

Information redundancy and noise : Much code context obtainable via real-time reading, not needing memory storage

1.2 Fundamental Divergence Between Two Systems

Claude Code and Codex represent two fundamentally different memory design philosophies:

Memory Mode : Claude Code uses automatic + manual hybrid; Codex uses pure manual declarative

Architecture Layers : Claude Code has four-layer hierarchical; Codex has two-layer flat

Cross-Session Strategy : Claude Code uses auto memory + offline consolidation; Codex has no automatic cross-session memory

Design Philosophy : Claude Code: "Memory is Code's Complement"; Codex: "Memory is Behavior's Contract"

2. Claude Code Memory Architecture Deep Dive

Claude Code's memory system comprises Manual Contract (L1) + Auto Memory (L2) + Session Cache (L3) + Offline Consolidation (L4) forming a continuous self-optimizing loop around memory storage.

2.1 Four-Layer Hierarchical Overview

Classic layered memory model from transient to persistent:

L1 — CLAUDE.md Instruction Rules Layer : Behavioral contract layer with multi-level scope (project, user, local)

L2 — Auto Memory Automatic Learning Layer : Automatically captures, classifies, persists valuable information during interaction

L3 — Session Memory Transient Layer : Bound to single session lifecycle; receives seed memory from L1/L2 at startup

L4 — AutoDream (KAIROS) Offline Consolidation Layer : Solves long-term memory bloat via four-phase offline process

2.2 L1 — CLAUDE.md Instruction Rules Layer

Behavioral contract layer with multi-level scope: project-level (repo root), user-level (~/.claude/CLAUDE.md), local-level (current directory). Higher priority overrides lower.

2.3 L2 — Auto Memory Automatic Learning Layer

2.3.1 Four Memory Types

user : User role, preferences, knowledge background. Trigger: Identity/preference detected. Example: "User is senior Go engineer, first time with React"

feedback : Behavioral corrections & confirmations. Trigger: User corrects agent or confirms non-obvious practice. Example: "Integration tests must use real DB, no mocks"

project : Project context, goals, constraints. Trigger: Project-specific info discovered (non-code-derivable). Example: "Auth middleware rewrite due to compliance, not tech debt"

reference : External system resource pointers. Trigger: User mentions external system/source. Example: "Pipeline defects tracked in Linear project INGEST"

2.3.2 Storage Structure

All auto memories stored as Markdown files in .claude/memory/ with YAML frontmatter metadata. MEMORY.md serves as index, auto-loaded into context at session start.

2.3.3 Memory Judgment & Anti-Redundancy

Core principle: "Memory is code's complement" — only store what cannot be derived from codebase:

Don't store : Code patterns, file paths, architecture conventions (derivable from code)

Don't store : Git history, debug approaches (derivable from Git)

Don't store : Sensitive credentials, API keys (security red line)

Store : User preferences, behavioral corrections, project decision context, external resource pointers

2.4 L3 — Session Memory Layer

Transient layer bound to single session. Three core properties:

Transience : All history, intermediate reasoning, temporary context lost after session

Boundedness : Limited by context window token ceiling, faces eviction pressure

Injection : L1/L2 content injected at startup as "seed memory"

Comparison of three layers:

Lifecycle : L1/L2 cross-session persistent; L3 dies with session

Write Method : L1 manual edit; L2 automatic + manual; L3 automatic (conversation)

Role : L1 behavioral contract; L2 learning accumulation; L3 immediate reasoning context

Capacity : L1 no hard limit; L2 MEMORY.md ≤200 lines; L3 token window limited

Relationship: Persistent layers (L1/L2) provide initial context seeds to transient layer (L3); valuable info from L3 may be promoted to persistent layer via Auto Memory writes.

2.5 L4 — AutoDream (KAIROS) Offline Consolidation Layer

Solves long-term memory bloat — as Auto Memory accumulates, file count and MEMORY.md index grow, crowding context window.

2.5.1 Four-Phase Consolidation Process

Targeted Cueing : Identify task-relevant memory subset from current context → relevant memory candidates

Signal Collection : Extract decay & conflict signals from candidate memories → decay/conflict markers

Consolidation : Merge similar memories, promote high-value ones → refined memory set

Pruning & Indexing : Delete stale memories, rebuild MEMORY.md index → updated memory storage

2.5.2 Significance of Offline Consolidation

Enables closed-loop self-optimization :

Without AutoDream : Memory only grows; MEMORY.md bloats past 200-line limit; old/new memories conflict; context window wasted on stale info

With AutoDream : Memory periodically "digested"; stays lean; high-value memories consolidated; stale memories pruned; index stays current

2.6 Memory Write Timeline

Multi-step judgment chain from user input to persistence:

User Input → LLM Reasoning → Semantic Analysis → Memory Type Judgment → Redundancy Check → Write Target Layer

Semantic Analysis : Extract identity, preferences, corrections, project context, external references

Type Judgment : Map to user/feedback/project/reference types

Redundancy Check : Compare against existing memories; skip code-derivable or existing info

Write Target Layer : Write to L2 (Auto Memory) or retain only in L3 (Session Memory) based on type/persistence need

Write conditions by layer:

L1 CLAUDE.md : Explicit user request (/memory command) — Highest priority — Manual trigger

L2 Auto Memory : Semantic judgment: "worth cross-session retention" & non-redundant — High priority — Automatic

L3 Session Memory : All interaction info enters by default — Medium priority — Automatic

L4 AutoDream : Memory bloat threshold triggered — Low priority (offline) — Automatic (offline)

3. Codex Memory Architecture Deep Dive

Codex represents a "clear and restrained engineering contract" — two layers, entirely manually declared, system never oversteps.

3.1 Two-Layer Flat Architecture Overview

L1 — AGENTS.md Static Declaration Layer : Manually written behavioral contract; only persistent layer; cross-session stable; never auto-modified by system — only humans can change it

L2 — Session Context Layer : Single-session conversation history + real-time code context; created/destroyed with session. L1 content injected once at startup as behavioral baseline.

Information flow fractures at session boundary — no return path for session-incremental info. Core trade-off: "Predictability" exchanged for "Adaptivity" . Codex never silently changes behavior baseline; all changes require explicit AGENTS.md edits. Attractive for audit/compliance teams, but agent cannot auto-accumulate experience.

3.2 AGENTS.md Four-Section Structure

Project Overview : Build agent's mental model quickly. Example: "Next.js SaaS backend, monorepo, core in packages/core"

Code Conventions : Constrain code style & engineering habits. Example: "TypeScript strict mode; functional components; no default export"

Build/Test Commands : Provide executable build/test/lint instructions. Example: "Build: pnpm build; Test: pnpm test; Lint: pnpm lint --fix "

Constraints : Define inviolable behavioral red lines. Example: "No modifying migrations/; no committing .env; API changes must sync openapi.yaml"

Logical progression: "What it is" → "How to do it" → "What not to do" . Overview establishes cognition; Conventions & Commands provide positive guidance; Constraints define negative boundaries.

3.3 Agent Loop Execution Flow

Classic Perceive-Plan-Act-Observe loop. Unique aspect: AGENTS.md injected once before loop starts , serving as immutable reference frame throughout. AGENTS.md does not participate in dynamic updates — remains read-only entire session, guaranteeing behavioral consistency across iterations (unless evicted by context compression).

3.4 Context Compression Flow

No offline consolidation like Claude Code. Uses online summarization when context nears token limit:

Early Conversation History : Verbatim multi-turn Q&A retained → Summarized as "Completed X, adopted Y approach"

File Read Content : Full file content resident in window → Discard original; retain "File A key conclusions/interface signatures"

Tool Execution Logs : Full command output & stacks → Retain success/failure conclusions & key errors; discard verbose logs

Todos & Goals : Scattered across turns → Distilled into explicit goal list

Token Usage : Approaching window limit (95%+) → Significant drop (40-50%)

Critical caveat: Summarization is lossy compression — discarded details unrecoverable. If AGENTS.md key constraints injected early then "summarized away," agent may drift in late-stage long tasks. Hence Codex recommends writing critical constraints concise and prominent to survive compression.

3.5 Architecture Gaps Warning

Three key omissions from architect perspective:

Gap 1: No Auto Memory Persistence — Beyond manual AGENTS.md, Codex never auto-captures, classifies, or persists valuable interaction info. Preferences, corrections, decision context lost unless manually written to AGENTS.md.

Gap 2: No Cross-Session Learning — Every new session "starts from zero." Agent cannot auto-improve from historical successes/failures. Same errors may repeat across sessions unless developer manually distills lessons into AGENTS.md.

Gap 3: No Offline Memory Consolidation — No AutoDream-like offline consolidation, deduplication, pruning. AGENTS.md maintenance fully manual — bloat, rule conflicts, staleness all require developer cleanup. No self-optimization loop.

Essential trade-off: Codex chooses "Behavioral Determinism + Audit-Friendly" over "Adaptivity + Experience Accumulation." Suits compliance/control-focused teams but shifts memory maintenance cost entirely to developers.

4. Multi-Dimensional Comparative Analysis

4.1 Comprehensive Capability Radar (1-5 Scoring)

Persistence Capability : Cross-session retention richness & automation. Claude Code: Auto Memory auto-persistence. Codex: Manual AGENTS.md only.

Automation Degree : Memory capture, classification, consolidation without human intervention. Claude Code: Auto Memory + Offline Consolidation. Codex: Fully manual.

Controllability : Behavioral predictability & audit-friendliness. Codex: High (pure manual). Claude Code: Auto writes introduce uncertainty.

Cross-Session Memory : Auto experience accumulation from history. Claude Code: Auto Memory cross-session transfer. Codex: Each session from zero.

Context Management : Optimization/compression of limited window. Both have mechanisms; Codex online summarization vs Claude Code layered injection.

Configuration Simplicity : Onboarding cost & mental load. Codex: Two-layer flat = minimal. Claude Code: Four-layer = more complex.

Result: Claude Code leads in automation, persistence, cross-session memory. Codex wins on controllability & configuration simplicity.

4.2 System Component Package Structure (UML Package Diagrams)

Claude Code : 4 sub-packages (CLAUDE.md, AutoMemory, SessionMemory, AutoDream) with explicit dependencies & data flows forming self-optimization loop.

Codex : 2 sub-packages (AGENTS.md, SessionContext). Simple relationship — AGENTS.md injects into SessionContext at startup; no write-back, no third-party consolidator.

Component count difference (4 vs 2) maps directly to capability coverage: each extra Claude Code package corresponds to a Codex-absent capability (auto memory, offline consolidation).

4.3 Persistence Strategy Comparison

Storage Medium : Claude Code: Multiple Markdown files in .claude/memory/ + MEMORY.md index; CLAUDE.md multi-scope files. Codex: Single AGENTS.md file (multi-level placement in dir tree)

Persistence Trigger : Claude Code: Automatic (semantic judgment) + Manual ( /memory command for CLAUDE.md). Codex: Pure Manual (developer explicitly edits AGENTS.md)

Cross-Session Retention : Claude Code: Auto Memory & CLAUDE.md both persist cross-session; content grows continuously. Codex: Only AGENTS.md persists; content never auto-changes

Automation : Claude Code: High — system actively captures, classifies, deduplicates, offline consolidates, closed loop. Codex: None — all persistence actions human-dependent; system read-only

Data Structure : Claude Code: Structured: YAML frontmatter + typed (user/feedback/project/reference) + index. Codex: Semi-structured: Free Markdown, conventional four-section (Overview/Conventions/Commands/Constraints)

Core difference: Claude Code persistence is "system-driven, structured, self-growing"; Codex persistence is "human-driven, free-format, static." Former trades controllability for information richness; latter trades maintenance cost & experience loss for full predictability.

4.4 Context Compression Mechanism Comparison

Compression Timing : Claude Code: Dual-channel: In-session near-limit compression + Inter-session AutoDream offline consolidation. Codex: Single-channel: Only in-session when context nears token limit triggers online summarization

Compression Strategy : Claude Code: Layered offload — transient info compressed; high-value info promoted to Auto Memory persistent layer; offline consolidation deduplicates. Codex: Online Summarization — early history summarized into concise summary, replaced in-place

Information Retention : Claude Code: Key info can "float up" to persistent layer for permanent retention; offline consolidation ensures lean memory set without losing high-value items. Codex: Only retains summarizer-judged key decisions/interfaces/goals; other details discarded in-place

Recoverability : Claude Code: Partially recoverable — info promoted to Auto Memory reloadable in future sessions. Codex: Irrecoverable — lossy compression; summarized-away details permanently lost; no persistent layer fallback

Deep strategic difference: Claude Code treats compression as "information re-layering" — promoting retain-worthy info to persistent layer for cross-session immortality. Codex treats compression as "in-place lossy slimming" — summarization replacement within single session, no rollback once compressed. Hence Codex more prone to behavioral drift in ultra-long tasks when critical constraints get "summarized away," explaining why Codex docs advise writing critical constraints concise and prominent to maximize post-compression survival probability.

4.5 Cross-Session Information Transfer Flow (UML Activity Diagrams)

Claude Code Cross-Session Relay : Session 1 end → AutoDream offline consolidation (consolidate, deduplicate, prune) → Write to Auto Memory persistent layer. Session 2 start → Auto-load MEMORY.md index & relevant memories → Inject into new session context. Session 1 experience "seamlessly relayed" to Session 2 — user repeats no background.

Codex Session Boundary Fracture : Session 1 end → Unless developer manually updates AGENTS.md, all incremental info (preferences, corrections, decisions) lost with session context. Session 2 start → Agent only re-reads static AGENTS.md — knows nothing of Session 1; restarts from AGENTS.md baseline.

UML activity diagram shows left swimlane (Claude Code) with continuous info flow across boundary (AutoDream consolidation node + auto-injection node); right swimlane (Codex) shows explicit "Information Loss" termination node at boundary.

4.6 MCP (Model Context Protocol) Support Comparison

MCP Support : Claude Code: Native deep support — connect arbitrary MCP Servers, dynamic discovery & invocation of external tools. Codex: Limited support — ecosystem centered on built-in tools; external protocol access not core capability

External Memory Extension : Claude Code: Via MCP connect external knowledge bases/vector DBs/databases, extend persistent memory beyond system. Codex: Primarily relies on local AGENTS.md + real-time code reading; lacks standardized external memory access

Tool Ecosystem : Claude Code: Open ecosystem — third parties can publish MCP Servers; tool capabilities continuously expand. Codex: Relatively closed — toolset mainly official built-ins; extension paths limited

Extensibility : Claude Code: High — protocol standardization makes memory & tool capabilities pluggable, composable. Codex: Medium — extension depends on official iteration; lacks user-side pluggable mechanism

MCP comparison elevates divergence to macro level: Claude Code builds internal automated layered memory loop AND opens memory capability to external ecosystem via MCP, forming "endogenous memory + exogenous memory" dual-engine; Codex constrains capability boundary within local contract & built-in tools, trading openness for determinism.

5. Architect's View: Design Philosophy Comparison

5.1 Two Design Philosophies

Claude Code : "Memory is Code's Complement" — Anything readable/derivable from codebase shouldn't occupy memory. Memory should auto-capture code-external, ephemeral, unstructured knowledge → System must "Automation First," actively learn & consolidate.

Codex : "Memory is Behavior's Contract" — Memory essence is explicit human-agent contract. Every clause human-written, human-modified. System never unilaterally adds/removes → System must "Controllability First," predictability & auditability as highest principles.

No absolute right/wrong — two different value orderings: one prioritizes "Less human worry, auto-accumulate experience"; other prioritizes "Behavioral certainty, audit-friendly."

5.2 Architecture Style Comparison (Class Diagrams)

Claude Code : MemoryManager core coordinator aggregating CLAUDEmd (static rules), AutoMemory (auto memory), SessionMemory (session context) three memory carriers, plus AutoDream offline consolidator — four carriers with clear division of labor; AutoDream feeds back into AutoMemory forming loop.

Codex : Extremely flat — SessionContext depends solely on AgentsMd contract class; injected at startup, read-only throughout; no coordinator, no consolidator, no auto write-back path.

5.3 Controllability vs Automation Trade-off (Quadrant Chart)

X-axis: Automation Degree (system proactive capture/consolidation/cross-session transfer). Y-axis: Controllability (predictability & audit-friendliness). Often inversely related.

Codex : "High Controllability, Low Automation" quadrant — Certainty maximized, cost: almost no auto experience accumulation.

Claude Code : "High Automation" side, Controllability mid-upper — Maintains strong automation while using typed memory, anti-redundancy rules, offline consolidation to guard controllability floor.

Reference: "Pure Prompt Agent" in dual-low quadrant; Ideal "Contractual Auto Agent" in dual-high quadrant (yet to reach).

5.4 Information Flow Comparison (Data Flow Diagrams)

DFD conventions: Circles = processes; Arrows = data flows; Parallel lines = data stores.

Claude Code : User input → "Memory Judgment" process → One path into transient Session Context for LLM reasoning; Other path judged high-value → Written to "Memory Storage" (data store). Session end → "Offline Consolidation" process reads & rewrites Memory Storage. Next session start → Memory Storage reverse-injects into Context. Data flow forms closed loop between Storage & Context.

Codex : User input only flows to Session Context for LLM reasoning. AGENTS.md Storage only unidirectionally injects into Context at startup. Session-incremental info has NO path back to Storage — info flow is an open chain fracturing at session boundary .

Four perspectives interlock: Value ordering (5.1) → Class structure complexity (5.2) → Quadrant positioning (5.3) → Info flow closed/open (5.4). All trace back to fundamental philosophical divide: "Memory as Code's Complement / Automation First" vs "Memory as Behavior's Contract / Controllability First." Understanding this enables selection beyond feature checklists, returning to essence: "Does your team need auto-accumulated experience, or deterministic controllable behavior?"

6. Evolution Trends & Industry Implications

6.1 Hybrid Architecture Evolution Trend

Agent memory evolution ladder:

Pure Prompt Agents (no memory)

Declarative Contracts (AGENTS.md / CLAUDE.md)

Auto Memory Layer (system actively captures experience)

Offline Consolidation (counters long-term bloat)

Hybrid Intelligent Memory Architecture (fusion of all three)

Codex currently at Stage 2 (Declarative Contract) — maximizes controllability but stops before Auto Memory. Claude Code crossed Stage 3 (Auto Memory) and added AutoDream Offline Consolidation, at forefront toward Hybrid Architecture. Key insight: Pure Manual (Codex) and Pure Auto (early Auto Memory) are both transitional forms. Former shifts all memory maintenance cost to humans; latter risks memory bloat & noise uncontrolled. Future answer almost inevitably organic fusion of all three — "Declarative Contract + Auto Memory + Offline Consolidation": Human-written contract anchors immovable hard constraints; Auto Memory accumulates ephemeral soft experience; Offline Consolidation continuously consolidates/deduplicates, prevents bloat. Contract guarantees floor, Auto Memory raises ceiling, Offline Consolidation ensures long-term sustainability.

6.2 Architectural Insights Checklist

Five transferable principles from design trade-offs:

Memory Should Be Code's Complement, Not Duplicate. Anything readable/derivable from codebase (file structure, function signatures, git history) shouldn't consume precious memory capacity. True memory value: Code-external, ephemeral, unstructured knowledge — user preferences, decision context, failure lessons. Claude Code's principle draws the "what to remember" boundary.

Forgetting Mechanism Needed to Prevent Memory Bloat. Monotonically growing memory degrades into noise warehouse. Healthy memory system must build in deduplication, pruning, invalidation capabilities (like AutoDream offline consolidation) to actively evict stale, conflicting, low-value entries. Memory sustainability depends on how well forgetting works.

Declarative Contracts & Auto Memory Complement, Not Compete. Human-written contracts (AGENTS.md) excel at anchoring immovable hard constraints; Auto Memory excels at accumulating ephemeral soft experience. Not "choose one" but combine — Contract guarantees floor, Auto Memory raises ceiling. Opposing them misreads the memory problem.

Cross-Session Persistence Is Agent's Core Competitiveness. Ability to seamlessly relay one session's experience to next determines "one-off tool" vs "continuous collaboration partner." Session-boundary information fracture (Codex status quo) means starting from zero every time — the most fatal memory system capability gap.

Offline Consolidation Is Systemic Solution to Long-Term Bloat. Pure online compression only treats symptoms (lossy, in-place discard). Only introducing inter-session offline consolidation flows can systematically complete memory reorganization, deduplication, refinement without disrupting real-time tasks — the key loop for long-term memory sustainability.

6.3 Scenario Recommendation Matrix

Personal Rapid Prototyping : Volatile requirements, fast iterations, auto experience accumulation & minimal config preferred → Claude Code Strongly Recommended ; Codex: General (Manual AGENTS.md maintenance cumbersome)

Team Collaboration : Multi-person shared consistent baseline, auditable versionable explicit contract critical → Codex Strongly Recommended (AGENTS.md naturally fits Code Review & compliance); Claude Code: Recommended (Auto writes introduce uncertainty; needs extra conventions)

Long-Term Large Projects : Months-spanning, massive context, cross-session experience accumulation & offline anti-bloat essential → Claude Code Strongly Recommended (4-layer + AutoDream built for this); Codex: General (Lacks auto accumulation & consolidation; memory maintenance cost scales linearly)

One-Off Script Tasks : Short tasks, no cross-session need, simple controllable sufficient → Both Recommended (Codex minimal two-layer fits perfectly; Claude Code memory capability near-redundant but harmless)

Compliance/Audit-Sensitive : Behavior must be fully predictable & traceable; any auto-write is risk → Codex Strongly Recommended (Pure manual declarative is natural answer); Claude Code: General (Auto memory needs careful audit boundary assessment)

Selection intuition in one sentence: Seek auto experience accumulation & low-config — choose Claude Code; Seek behavioral determinism, auditability, versionability — choose Codex. Long-term large projects & personal prototypes lean former; Team collaboration & compliance-sensitive lean latter.

7. Summary

7.1 Core Conclusions

Claude Code — Layered Auto Memory System : Four-layer architecture (CLAUDE.md / Auto Memory / Session Memory / AutoDream) forms self-optimization loop. System proactively captures, classifies, deduplicates, cross-session relays experience. Automation First path — Let machine remember for you, let machine organize for you; trade slight controllability uncertainty for powerful experience accumulation.

Codex — Declarative Contract System : Two-layer flat architecture (AGENTS.md Static Declaration + Session Context). Memory entirely human-explicitly established, human-explicitly modified. System reads contract only, never unilaterally changes. Controllability First path — Sacrifice auto experience accumulation for highly predictable & audit-friendly behavior.

Two systems represent two fundamental AI Agent memory design routes — Automation First vs Controllability First . Not opposing right/wrong but different value orderings; Hybrid Architecture combining auto-learning with controllable audit is the terminal form of memory system evolution.

7.2 Architecture Comprehensive Scoring (1-5)

Persistence Capability : Claude Code 5, Codex 2 — Claude Code has Auto Memory auto-persistence; Codex only manual AGENTS.md

Automation Degree : Claude Code 5, Codex 1 — Claude Code auto-capture + offline consolidation; Codex fully human-dependent

Controllability : Claude Code 3, Codex 5 — Codex pure manual declaration highly predictable; Claude Code auto-writes introduce uncertainty

Extensibility : Claude Code 5, Codex 3 — Claude Code native deep MCP support for external ecosystem; Codex extension paths limited

Learning Capability : Claude Code 5, Codex 1 — Claude Code cross-session auto experience accumulation; Codex restarts from static baseline each time

Onboarding Cost : Claude Code 2, Codex 5 — Codex two-layer flat minimal; Claude Code four-layer higher mental load (higher score = easier onboarding)

Note: "Onboarding Cost" higher score = easier onboarding (lower cost). Claude Code stronger comprehensive capability but steeper learning curve; Codex minimal controllable but narrowed capability surface.

In summary, Claude Code lets the machine actively remember for you; Codex lets you manually contract for the machine. For auto experience accumulation & ecosystem extension, choose Claude Code; For behavioral certainty & audit control, choose Codex; Perhaps the true future belongs to the hybrid memory architecture fusing both.