How Do Coding Agents Remember Anything Between Sessions?

Published September 29, 2026 · by the AQ team

Coding agents start every session with an empty context window, so anything they appear to remember is really a file reloaded at launch. As of September 2026 that memory takes two forms: instruction files you write and check into the repository (AGENTS.md, CLAUDE.md, Cursor rules), and automatic memory the agent writes for itself (Claude Code's auto memory directory, Cursor's Memories). Claude Code, Codex, Cursor, and OpenCode each persist different things in different places, and only some of it is shared with your team: instruction files travel with the git repository, while auto memory usually stays on one machine, invisible to everyone else.

The two kinds of coding agent memory

An instruction file is a markdown file a human writes and the agent reloads at the start of every session: build commands, conventions, architecture notes, "always do X" rules. Auto memory is the newer mechanism: notes the agent writes for itself as it works, based on your corrections and preferences, without you editing anything. Both are plain context, not enforced configuration: the agent reads them and tries to comply, but nothing guarantees it. The distinction that matters for a team is location: instruction files are versioned with the code, so everyone gets the same ones, while auto memory is written per person and stored per machine or per account, never in the repository.

Instruction files: AGENTS.md is the shared standard

AGENTS.md is the cross-tool instruction file format, published as an open specification in August 2025 by OpenAI with input from Google, Cursor, and Factory, and donated to the Linux Foundation in December 2025. A plain AGENTS.md at the repository root is read natively by Codex, Cursor, OpenCode, and (since v2.1.277, verified on Anthropic's documentation as of September 2026) Claude Code, which loads AGENTS.md when the project has no CLAUDE.md. Most tools also read nested AGENTS.md files in subdirectories. If your team runs more than one CLI against the same repo, one AGENTS.md beats maintaining per-tool copies; keeping AGENTS.md and CLAUDE.md in sync covers the patterns, including the one-line import that lets a CLAUDE.md wrap an AGENTS.md.

Claude Code: CLAUDE.md files plus auto memory

Claude Code has the most layered memory system of the four, per Anthropic's documentation as of September 2026. Instruction files load in scope order: a managed policy file IT can deploy machine-wide, your personal ~/.claude/CLAUDE.md, the project's CLAUDE.md (or .claude/CLAUDE.md), and a gitignored CLAUDE.local.md for personal per-project notes. Files from parent directories load at launch; files in subdirectories load when Claude reads code there. A .claude/rules/ directory holds topic files that can be scoped to glob patterns, so a rule about API handlers only enters context when matching files are touched. Anthropic recommends keeping each file under 200 lines, since instruction files spend context window tokens every session.

Auto memory is the part Claude writes itself. It is on by default, and stores notes at ~/.claude/projects/<project>/memory/: a MEMORY.md index whose first 200 lines (or 25KB) load into every session, plus topic files Claude reads on demand. It records four kinds of notes (your preferences, corrections you give, project context it cannot derive from the code, and external references) and deliberately skips anything the codebase or your CLAUDE.md already says. Everything is plain markdown you can read, edit, or delete via the /memory command, and one setting turns the feature off. For teams: all worktrees of one repository share the memory directory, and it is machine-local, never synced to another computer. Separately, Claude Code Projects (beta since September 17, 2026) adds a shared, cloud-side project memory that multiple threads read and write; our Claude Code Projects guide covers it in depth.

Codex: instruction files only, concatenated top-down

OpenAI's Codex CLI keeps memory simple: AGENTS.md files, nothing self-written. Per OpenAI's documentation as of September 2026, Codex reads a global ~/.codex/AGENTS.md for personal defaults, then walks from the git root down to your working directory, concatenating each level's AGENTS.md (an AGENTS.override.md at any level replaces its sibling). Files closer to where you work appear later in the prompt, so they win conflicts. Combined instructions are capped at 32 KiB by default (the project_doc_max_bytes setting raises it), and the chain is rebuilt at every session start. There is no automatic memory: if you correct Codex twice, the fix is to write the correction into AGENTS.md yourself. Teams switching between tools mid-task should read carrying context between Claude Code and Codex, because nothing carries over on its own.

Cursor: rules, team rules, and per-person Memories

Cursor persists instructions three ways as of September 2026, per its documentation. Project rules live in .cursor/rules/ as .mdc files with frontmatter that can scope each rule to glob patterns, version-controlled with the repo (the old single .cursorrules file is legacy). Cursor also reads a root AGENTS.md and nested AGENTS.md files in subdirectories. User rules apply globally to your own Cursor environment, and Team rules are managed centrally from the Cursor dashboard on Team and Enterprise plans: the only org-level instruction surface among these four tools. Cursor additionally has Memories, introduced in v1.0 in June 2025: a background model proposes facts worth saving from your chats, you approve them, and they persist per project, per person, managed from Settings and never shared with teammates.

OpenCode: AGENTS.md with Claude Code fallbacks

OpenCode reads a project AGENTS.md (walking up parent directories) and a global ~/.config/opencode/AGENTS.md, per its documentation as of September 2026. Where neither exists it falls back to a project CLAUDE.md and ~/.claude/CLAUDE.md globally, so a repo set up for Claude Code works unmodified. An instructions array in opencode.json can pull in additional files by path, glob, or URL. Like Codex, OpenCode writes no memory of its own.

What persists where

What your team shares and what stays on one laptop

The rule of thumb: anything in the repository is team memory, anything under a home directory is one person's memory. A committed AGENTS.md, CLAUDE.md, or .cursor/rules/ directory reaches every teammate on the next pull, which is why the highest-leverage habit is promoting lessons upward: when an agent makes the same mistake twice, write the correction into the committed instruction file so the whole team's agents stop making it. Auto memory does not travel: Claude Code's memory directory is explicitly machine-local and Cursor's Memories are per person, so the insight your agent accumulated on your laptop evaporates for the teammate who picks the task up tomorrow, and for you when you switch machines. Repeatable procedures deserve a stronger container than memory: shared agent skills are versioned, reviewable, and load on demand.

Keep secrets out of agent memory

Memory files are context, and context goes to the model provider on every request. Never put credentials in an instruction file, and remember that auto memory is the agent deciding what to write down: paste a database URL into chat and nothing stops that fact landing in a memory file that reloads into every future session. Audit what was saved (/memory in Claude Code, Settings in Cursor), keep personal scratch context in a gitignored CLAUDE.local.md, and follow the patterns in keeping secrets out of coding agent prompts: scoped tokens, short-lived credentials, and secrets injected at use time rather than written anywhere an agent rereads.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. Memory is one of the quiet reasons a persistent team workspace beats a fleet of laptops. AQ runs the real CLIs, unmodified, in persistent tmux sessions on your team's VM, so everything this guide describes works exactly as the vendors document it: each workspace gets its own isolated git worktree, so every task starts from the committed AGENTS.md and CLAUDE.md your team maintains, and machine-local stores like Claude Code's auto memory accumulate on the VM where future sessions actually run, not on whichever laptop happened to run the task. Sessions survive a closed laptop, teammates can open the same workspace and watch the same live session, and each engineer signs into the CLIs with their own Claude or OpenAI account. The Free plan is a personal sandbox AQ creates for you with nothing to install and no time limit; the Team plan is $50 per user per month in early access (standard $200, billed monthly), covering VMs you connect from your own cloud or a dedicated always-on AQ-managed VM, with the rate locked for your first 12 months.