How Do Coding Agents Remember Anything Between Sessions?

Updated November 9, 2026 · first published September 29, 2026 · by the AQ team

Coding agents remember by loading saved context into a new session: instruction files such as AGENTS.md and CLAUDE.md that people write, plus notes some agents write for themselves. Checked-in instructions live with the repository, while agent-written notes live in a machine-local directory or a vendor account, so their defaults and sharing depend on the tool and session. AQ is a multiplayer coding harness that runs coding agents in isolated worktrees on team-controlled or AQ-managed machines, with shared live access, review, and searchable memory notes.

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 rechecked on November 9, 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. Claude Code v2.1.32 added automatic recording and recall. According to Anthropic's current memory documentation, auto memory is on by default in local sessions. Outside Claude Tag sessions, a session in a self-hosted environment runs with auto memory off by default. Its directory is derived from the git repository, so that repository's worktrees and subdirectories on one machine share ~/.claude/projects/<project>/memory/. The files do not travel across machines or cloud environments. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at launch; topic files load on demand. The four note types are user for your role and preferences, feedback for corrections and confirmed approaches, project for context the code cannot supply, and reference for external sources. Run /memory to browse and edit the plain-markdown files or disable auto memory. 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

The vendor behavior below was checked in September 2026. Claude Code's auto-memory defaults, scope, and inspection path were rechecked on November 9, 2026.

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. When an agent makes the same mistake twice, inspect what it saved, then write a durable correction into the committed instruction file so every teammate's agent receives the same context. 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 is unavailable to the teammate who picks the task up tomorrow, and to you when you switch machines. Repeatable procedures deserve a reviewable container: shared agent skills are versioned and load on demand.

When several agents write one memory page

Anthropic's November 6, 2026 agent-memory research shows why shared writers need inspection. In an acquisition-brief experiment, several agents wrote contract terms into one shared table. They overwrote each other's work and summarized terms poorly, leaving 41 of 57 graded facts in the resulting brief. Anthropic then rebuilt the wiki with one agent per contract, a separate page for each contract, and verbatim contract terms. The rebuilt brief covered 57 of 57 facts. This was not an isolated test of page layout: Anthropic changed the instructions and the layout together, so the experiment does not prove that per-contract pages alone caused the recovery.

A separate CL-Bench experiment cautions against narrowing memory to a rigid rule. When Anthropic told models to "record only failures," Opus 5 and Opus 4.7 lost much of the performance boost memory had given them. Anthropic's framing is to explain what memory is for and let the model judge what is worth saving. A useful note can hold a confirmed decision, preference, project fact, or reference as well as a correction.

Anthropic also tested a dreaming pass in Managed Agents that checked a wrong memory note against the original transcript and corrected it. That is evidence that transcript checking can repair stale notes in Anthropic's experiment. It is not a capability to assume in Claude Code auto memory or AQ, and it does not replace human review.

A practical memory inspection checklist

• List the agents and sessions that write each memory file. If facts disappear, split notes by topic or contract and give each page one writer.
• Compare important notes with the current code and original transcript. Keep exact terms verbatim where wording matters, and correct or delete stale entries.
• Check what loads at launch and what loads on demand. Keep the index short enough for its important entries to survive the loading limit.
• Review what the agent saved after a correction. Move durable team rules into the committed instruction file, and use hooks or permissions when an action must be enforced.
• Keep confirmed successes and decisions alongside failures when they would help a future session.

Keep secrets out of agent memory

When memory enters a prompt, it becomes context sent to the model provider with that 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 index that reloads into future sessions. 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 runs the real CLIs in isolated git worktrees on a team-controlled or AQ-managed machine. Where Claude auto memory is enabled, all worktrees and subdirectories of one repository on that machine share its machine-local memory directory. Separate machines do not share that directory. Self-hosted sessions outside Claude Tag start with auto memory off by default, so a team VM does not imply an always-on or cross-machine Claude memory store.

AQ also reads supported CLI memory into copies called AQ notes. Agents search these notes with the search_memory tool; AQ does not inject them into every turn. Notes are personal by default. You can explicitly share project and reference notes with the team, while notes about you stay personal. Your edits win over the CLI file and never expire, forgotten notes do not return from the file, and "Needs a look" flags moved code citations, duplicates, and notes unused for weeks. The AQ memory documentation covers the supported sources and controls.

Shared AGENTS.md rules are a separate mechanism. AQ mirrors one shared file per person per machine into supported agents' homes, and into a work item's worktree only when the repository has no AGENTS.md of its own. It never modifies a tracked repository file. AQ does not provide cross-machine Claude auto-memory sync, dreaming, or automatic transcript-checked repair.