Context and Memory

Context and Memory

Codex runs against a large context window and keeps its session in a process you control. ChatGPT Web does neither: the window is smaller than most real tasks, and when it fills — or when you open a new chat — the plan and everything learned along the way are gone, with no sign to the model they ever existed. Codex Free attacks both halves.

---

Spend the window on less

Every tool that could return an unbounded amount of text stops at a budget and says so on its last line, naming the argument that continues from where it stopped:

(showing lines 1-1000 of 4820 — call again with offset=1000 for the rest)

That line matters as much as the cap. Silent truncation reads as "that was the whole file", which is worse than no cap at all. read_file has a byte ceiling as well as a line one, because a minified bundle is a single line several megabytes long that a line cap alone would hand back in full. exec_command and grep are bounded too, ported that way from Codex. The caps live in the output block — see Configuration.

Keep what would be expensive to rediscover

• remember writes one keyed note.
• recall hands back the notes and the current plan.
• update_plan persists the plan too, so it survives the conversation that made it.

Writing to a key that exists replaces it, and an empty value deletes it — a keyed store stays current where an append log accumulates contradictions until it's worthless.

Where state lives

Task state lives in:

~/.codex-free/projects/<name>-<hash>/memory.json

keyed by the absolute active project root. Nothing is written into the repository you pointed the server at, and two checkouts of the same repo do not share notes. Multi-project conversations share task state only when they select the same canonical project root.

Configure it with the memory block:

Key	Default
enabled	true	false turns persistence off entirely.
dir	~/.codex-free/projects/<name>-<hash>	Outside the repo by default. In multi-project mode an explicit dir becomes a base directory with a hashed child per project.
maxBytes	16384	Budget for all notes together. A note over it is rejected, not silently evicted.

ChatGPT project bindings (multi-project)

Separate from task state, project bindings live under:

~/.codex-free/conversation-projects/<access-root-hash>/<conversation-hash>.json

The raw openai/session value is never written — only its SHA-256-derived key is used as the filename. Each small record holds the canonical access root and selected project root. Delete this directory to forget all conversation bindings. A missing or stale project fails closed rather than silently rebinding the conversation elsewhere. Bindings stay enabled even when memory.enabled is false.

How saved state reaches a new chat

• Single-project mode: instructions is rebuilt for every MCP session, so a new conversation opens with the saved plan and notes already in front of it, under a ## Saved state heading between the environment and AGENTS.md.
• Multi-project mode: initialize-time instructions stay project-neutral (the conversation identifier arrives on tool calls, after initialize). Calling get_agent_brief restores an existing binding automatically; for a new conversation it says set_project_root is required. After binding, get_agent_brief returns the environment, saved state, skills, and AGENTS.md for the selected project.

If the client ignores instructions, one recall gets the same saved state after selection.

The division of labour

Keep this straight:

AGENTS.md is what is true of the project — it belongs in the repo. Notes are what is true of the task in flight — they belong here.

See AGENTS and Skills for the project side.

---

See also

• How It Works — where bounding and persistence sit in the request lifecycle.
• Tools Reference — remember, recall, update_plan.
• Configuration — the memory and output blocks.